alpha version, October 2000
The data type (or format) is fully qualified by a CXCDataType object, described below. Though, the principal type specification is the type name; the CXCDataType is more or less just a convenient wrapper around the name (with a few other unimportant auxiliary attributes, like a human readable type name). Each format (like Epoc Word, MBM Epoc Multi Bitmap file, TIFF image, plain text file, WK1 spreadsheet, TAR archive, WAV sound file, RTF text...) has a distinctive name. The data type name is always a plain ASCII text string, which can contain:
The distinctive UID for the proprietary names is generated the standard Epoc way: a UID from the temporary UID range can be used for in-house products and for development; published filters' proprietary data types should have a UID owned by the company, which made the filter.
Just like the filters, the types can be built-in or can be loaded from the filter DLLs. Just like the filter objects, the data type objects are created as soon as the DLL is loaded (and should be shared between all tasks had the C++ support it), and exist until the task finishes.
+CXCDataType *dataTypeWith(CXString *type,CXString *name,CXString *ver,CXString *comp,CXString *inf,int qualify,CXArray *extensions);
The dataTypeWith constructor just initializes private variables, which are then accessed by the default implementation of type, name, version, company, info, qualify, and extensions methods. See them below for more information on the respective values.
Should you ever need to reimplement the class, you can use the private properties (then just don't reimplement these methods), or do it your way: all the conveniency methods use the accessor methods (not the private variables), so they will work properly anyway. For the case you do it your way, there is the dataType constructor without arguments:
+CXCDataType *dataType;
In practice, though, you would hardly ever use these constructors, for they always make a new CXCDataType instance. Generally the following ones, which support data type sharing, are more convenient:
+CXCDataType *dataTypeWith(CXString *type);
Use this constructor to get a shared data type with the type name given. The type must exist (or you'll get a nil result). This service is best for the builtin data types, or to reference to a data type which you have already prepared.
+CXCDataType *dataTypeWith(CXString *type,CXString *suggestedName,int suggestedQualify,CXArray *suggestedExtensions);
This construcotr tries to find and return a shared data type with the type name given. In case no such data type exists, it creates a new data type, with the suggested... properties.
+CXCDataType *dataTypeForEpocData;
+CXCDataType *dataTypeForEpocAgenda;
+CXCDataType *dataTypeForEpocWord;
+CXCDataType *dataTypeForEpocSheet;
+CXCDataType *dataTypeForEpocPaint;
+CXCDataType *dataTypeForEpocComms;
+CXCDataType *dataTypeForEpocTextEd;
+CXCDataType *dataTypeForEpocJotter;
+CXCDataType *dataTypeForEpocContacts;
+CXCDataType *dataTypeForEpocRecord;
Predefined constructors for all the Epoc application data types. The qualification is maximum, there are no extensions. Nota also that the Paint application is now called Sketch (or at least was in the time of writing this documentation!).
-CXString *name;
A human readable data type name, like "Epoc Word" or "Windoze Word Mess".
-int qualify;
The qualify value contains the type priority: the higher the number, the better is the filter equipped to deal with the type.
The framework known two boundaries in qualification numbers: types with qualify below 100 are considered to fit poorly; types with qualify of 1000 are considered to fit perfectly. Normally, when there is at least one type for a data given which fits perfectly, no other data types than those with perfect fit will be given. Analogically, if at least one data type has qualify grater or equal to 100, no of the poor ones will be used. See the matching methods below for a more detailed description.
-CXString *type;
The type contains the data type name, described above (like "text/html" or "*<uid>*<anything>"). All the conveniency methods just decode the data type name; thence, even should you subclass the CXCDataType, they would not need to be reimplemented.
-CXString *version;
-CXString *company;
-CXString *info;
<<<documentation forthcoming (but it's clear, isn't it?)>>>
-CXArray *extensions;
The extension list--an array of strings, given by the extensions method--is a hint for any application which uses files: in case the file has no extension from the list, it won't be checked further as convertable. Should you want to be able to convert all files regardless the extension (recommended particularly for the Epoc types, which have UIDs), just supply nil.
The first extension (if any) is automatically used for newly created files.
Each of the strings can contain any pattern, using asterisk for a wildcard. Particularly, an extension of "*" matches any file name, regardless its extension is. Besides, the string might have a leading zero byte, which means that the extension will be checked case-insensitively.
Finally, in place of each the extension string there can be an array of two items: the first one is the extension, and the second one's intValue will be used for qualification, in case it matched the extension. Thus, you can supply, say, the following extension list:
@(@"\0txt",@(@"*",@"20"))
to ensure that when a file with a "txt" extension (regardless its case) is found, the default qualification will be used, whatever it is (presumably some number over 100). Though, in case a file with any other extension is matched, the qualification will be only 20.
-void setExtensions(CXArray *exts);
-void addExtensions(CXArray *exts);
<<<documentation forthcoming>>>
-BOOL isMime;
-BOOL isEpoc;
-BOOL isProprietary;
These methods just determine (by parsing the type string) the type of the data.
-CXString *mimeType;
-CXString *mimeSubtype;
In case the type isMime, these methods parse the type andreturn the MIME type (the text up to the slash) and subtype (the text after the slash).
-unsigned epocUid1; // Uid1, if any, from Epoc type (zero if none)
-unsigned epocUid2; // Uid2, if any, from Epoc type (zero if none)
-unsigned epocUid3; // Uid3, if any, from Epoc type (zero if none)
-unsigned epocUid(int index); // 0..2
-CXString *epocAppName;
In case the type isEpoc, these methods parse the type and return the appropriate information from there.
-unsigned proprietaryUid;
-CXString *proprietaryName;
In case the type isProprietary, these methods parse the type and return the appropriate information from there.
-BOOL canReadStream; // means also file, YES by default, will be NO for special ones only
-int matchesExtension(CXString *ext); // no need to reimplement, uses extensions
-int matchesName(CXString *name); // finds extension and calls the previous one
-int matchesUid(unsigned ui1,unsigned uid2,unsigned uid3); // 0 can be used as a wildcard
-int matchesEpocApp(unsigned uid3); // calls the above one
-int matchesContents(CXData *bytes); // to be reimplemented; first called with nil to get the length, the with data!!!
-int matchesClipboard(CClipboard *clipboard); // to be reimplemented; text clipboard is given as a stream!!!
-id specialOpenNames; // nil none, all non-nil names presented to the user, might be CXString or CXArray with more names
-int matchesSpecial(CXString *name); // name is all right for sure, but might check conditions. By deflt rets qualify (!)
<<<documentation forthcoming>>>
-BOOL canWriteToStream; // which means also file; YES for all standard types (EPOC embeds store... etc)
-BOOL canWriteToClipboard; // to be reimplemented, of std types only text/* can do so
-id specialWriteNames; // nil none, all non-nil names presented to the user, might be CXString or CXArray with more names
-BOOL canWriteSpecial(CXString *name); // name is all right for sure, but might check conditions. By deflt rest YES (!)
<<<documentation forthcoming>>>
-CXCGeneralData *inputDataForFile(CXString *fname,RFile *rf=NULL); // if rf!=nil, takes ownership of already existent file; by default opens stream for MIME/proprietary, DictStore for EPOC
-CXString *suggestedOutputFileNameFor(CXString *ofname); // might add extension or whatever
-CXCGeneralData *outputDataForFile(CXString *fname,RFile *rf=NULL); // ditto, output
-CXCGeneralData *inputDataForStream(RReadStream *stream,CStreamStore *store=NULL,unsigned knownSize=XCUnknownSize); // stream for MIME/prop, embedded store for EPOC
-CXCGeneralData *outputDataForStream(RWriteStream *stream,CStreamStore *store=NULL); // ditto
-CXCGeneralData *inputDataForClipboard(CClipboard *clipboard); // stream for MIME/prop, not supported for EPOC
-CXCGeneralData *outputDataForClipboard(CClipboard *clipboard); // ditto
-CXCGeneralData *inputDataForSpecial(CXString *name);
-CXCGeneralData *outputDataForSpecial(CXString *name);
<<<documentation forthcoming>>>
-CXArray *detailsForDataconversion(CXCGeneralData *data,CXCConversion *conversion,CXCGeneralData *inherited=nil); // construct and use a dialog with the details
-void dialogueLineChangedforDataconversion(CXString *itemLabel,int line,id value,XDialogueAccess *access,CXCGeneralData *data,CXCConversion *conversion);
-id validateDetailsForDataconversion(CXCGeneralData *data,CXCConversion *conversion); // validate the detail values, nil==OK
-void dialogueCancelledForDataconversion(CXCGeneralData *data,CXCConversion *conversion);
-void setDetailsForDataconversion(CXCGeneralData *data,CXCConversion *conversion); // apply the values from the dialogue
<<<description forthcoming>>>
+CXArray *allTypes; // all active types, ie. only the default one of each array!!!
+CXArray *alternativesForType(id type); // type migth be CXString with type or CXCDataType, returns all alts if>1, or nil
+void setDefaultType(CXCDataType *dt); // in his own group
<<<documentation forthcoming>>>
Copyright © 1999-2000 X.soft, all rights reserved