CXCFilter

alpha version, October 2000

<<<sorry, this document is slightly out of date. Temporarily, check it please against the header file; we shall soon provide a documentation upgrade>>>

There is always exactly one instance of the filter object for each filter. It is made as soon as the appropriate DLL is loaded, and is deleted just before the DLL is unloaded (in principle, it should be shared between all tasks, but the C++ rot do not support remote objects). Thence, the init/dealloc are relatively unimportant, and it is quite probable you will not need to reimplement them. The destructor should delete all the embedded objects (unless they are shared).

Since the filter DLL exports a filter instance (not a class), you will have to create the instance manually; therefore the constructor class methods are documented here as well.

+CXCFilter *filter;

The most primitive constructor: just makes a filter object with a minimal initialization. You will use this constructor in case you reimplement all the relevant methods yourself.

See the name, version, company, info, helpFileName, inputTypes, and outputTypes methods below for more information.

+CXCFilter *filterWith(id iTypes,id oTypes);

In practice, you would hardly need to reimplement the inputTypes and outputTypes methods; instead, this constructor can be used to fill a standard CXCFilter properties with values given.

The object will properly set the values; you can use directly a CXCDataType object for both the arguments in case there is just one input or output type, or you can specify more of them by using a CXArray of CXCDataTypes. See the inputTypes and outputTypes methods below.

The name, version, company, info, and helpFileName methods will still have to be reimplemented; see them below for more information.

+CXCFilter *filterWith(id iTypes,id oTypes,CXCConversionClassClass *cnvClass,CXString *name,CXString *version,CXString *company,CXString *info);

This constructor (or the one below) will probably be most frequently used. It allows you to fill a standard CXCFilter properties with values given; this way you do not need to reimplement any CXCFilter method but the conversionFor one.

In an extremely simple case the filter has just one conversion, used for any combination of its input/output data, you do not need to reimplement any method, and you even do not need to subclass the CXCFilter! Just make a CXCFilter instance using this constructor method, and set the cnvClass to the appropriate conversion class. The filter will make automatically a conversion object of the class given for any input and output data.

Note: since it is possible thus to make use of the CXCFilter class directly (not using a subclass), there is one special service to support it: the implementationDllPath service (see CXObject) is re-implemented so that for a plain CXCFilter it would return the DLL where its conversion class is defined. For CXCFilter subclasses it will normally return the receiver's DLL. This way, for each filter the implementationDllPath service returns the appropriate filter DLL, regardless it defines its own filter class, or it uses the plain filter class and defines just the conversion.

+CXCFilter *filterWith(id iTypes,id oTypes,CXCConversionClassClass *cnvClass,CXString *name,CXString *version,CXString *company,CXString *info,CXString *helpFName);

The same as above, but you can specify the help file name as well. See the helpFileName method below for more information.

-CXString *name; -CXString *version; -CXString *company; -CXString *info;

These methods just give information of the filter. The meaning of them should be clear enough: name is a short filter name, whilst info is a more detailed description. The version can be any string, like "Development" or "Beta"; for release the standard format of "N.NN" is recommended. For filters featuring more different conversion the version can be more complicated, like "1.01 (RTF), 2.00 (HTML), Beta (PDF)". The company is just the name of the company which created the filter.

Note the name is used to distinguish the filter. Thence, you should use a distinctive filter names; the framework might not support more filters with same names well. In future versions there will quite probably be another method distinctiveName, which will be used to distinguish the fiters, whilst the name will be just shown to the user.

The default implementations of all the methods just return values of a CXCFilter property variables, which can be set by the third and fourth constructors. Thence, unless you need to construct the information some way dynamically, it is easiest (and recommended) not to reimplement these methods, but just to specify the appropriate values in the constructor, and let the default implementations to use them.

-CXString *helpFileName;

Just like the information methods above, the default implementation returns a value of a property variable, which can be set using the last constructor method. Only in case you need to construct the help name dynamically you might need to reimplement this method.

The framework automatically searches for the given file; in case full file name is not given, it is searched for in the same folder the filter DLL is placed. If there is no extension, the "hlp" is added automatically. In case the file is found, it is presumed it has the Epoc Help format (the very same one as of the Data application), and the user is given opportunity to open it.

-CXArray *inputTypes; -CXArray *outputTypes;

This is the list of all input and output data types (represented by a CXCDataType instances). The first method returns an array of input types (ie. data formats which can be read in), and the second one an array of output output types (ie. data formats, which can be produced by converting the input ones). Note that any of the input types must be convertable to any of the output types. Other cases (when different input types can be converted to different output ones) should be represented by more filter objects (which, if needed, may easily share some conversion classes).

Note: actually, you can make 'non-ortogonal' set of input/output types, if really needed. The conversionFor method can refuse to make a conversion for the non-supported input/output data type combinations. Though, this should be used carefully, for the framework will offer to user even the unsupported data types this way, informing him only afterwards that the selected combination is not available (which is naturally an undesired behaviour).

-CXCConversion *conversionFor(CXCGeneralData *in,CXCGeneralData *out);

The conversionFor service creates an appropriate conversion object for the input data, and the desired output data. It is called only in case the input data type is one of the data types from the inputTypes array, and the output data types is one of the outputTypes array.

The default implementation just instantiates an object of the class set by the third or fourth constructor. The behaviour of the conversion object--including how and when it is released--is described in the CXCConversion class. The input and output data representation is described in the CXCGeneralData class.

In case there are more different conversion classes, appropriate to different combinations of input and output data types (which is presumed to be the typical case for more sophisticated filters), you must reimplement at least this one method, more or less this way:

@interface Text2EpocWordFilter:CXCFilter -CXCConversion *conversionFor(CXCGeneralData *in,CXCGeneralData *out); @end @implementation Text2EpocWordFilter -CXCConversion *conversionFor(CXCGeneralData *in,CXCGeneralData *out) { CXString *subType=[[in dataType] mimeSubtype]; _cnvClass=[subType isEqual:@"rtf"]?RtfEpocWordConversionClass: [subType isEqual:@"html"]?HtmlEpocWordConversionClass: TextEpocWordConversionClass; CXCConversion* cnv=[_cnvClass conversionWith:in,this]; // see CXCConversion [cnv setOutput:out]; // see CXCConversion return cnv; } @end

If so, you still use the third or fourth constructor to set all the values for the information methods; the cnvClass argument just can be set to Nil:

id filter=[Text2EpocWordFilterClass filterWith: [CXArray arrayWithObjects:rtfDatatype,htmlDataType,txtDataType,nil], // input types epocWordDataType, // output types Nil, // the cnvClass will not be used @"OCS: Text to Epoc Word", // name, using the OCS prefix to keep it distinctive @"1.01 (rtf,txt), Beta (html)", // version @"OCSoftware", // company @"Rich, html, or plain text to Epoc Word conversion"]; // info

-CXUserDefaults *filterDefaults; -CXUserDefaults *globalDefaults;

These two service methods are never to be reimplemented, but rather to be used from the filter (or, rather, conversion) code. They return a CXUserDefaults objects, representing the filter's local defaults and the whole XConversion system defaults respectively.

The filter local defaults are automatically placed to a INI file named by the filter DLL, and placed either to the same folder the DLL lays in (in case it is writeable), or to the appropriate folder on the drive C:. Thence, it is local for all the filters in one DLL.

The global defaults are shared by all the filters; thence, they should be read only and never written to. There are a few standard values there: <<<description forthcoming>>>