Difference between revisions of "Documentation/DevGuide/OfficeDev/Properties of a Filter"
From Apache OpenOffice Wiki
< Documentation | DevGuide
| Line 39: | Line 39: | ||
|- | |- | ||
|<code>Flags</code> | |<code>Flags</code> | ||
| − | |string list. Some boolean attributes of a filter, see | + | |string list. Some boolean attributes of a filter. |
| + | : ''3RDPARTYFILTER'' | ||
| + | : The filter is a UNO component filter, as opposed to the internal C++ filters. This is an artefact that will vanish over time. | ||
| + | : ''ALIEN'' | ||
| + | : The filter may lose some information upon saving. | ||
| + | : ''DEFAULT'' | ||
| + | : This is the "best" filter for the document type it works on that is guaranteed not so lose any data on export. By default this filter will be used or suggested for every storing process unless the user has chosen a different default filter in the options dialog. | ||
| + | : ''EXPORT'' | ||
| + | : The filter supports the service com.sun.star.document.ExportFilter. It will be shown in the dialog "File-Export". If the filter also has the "IMPORT" flag set, it will be shown in the dialog "File-Save". This makes sure that a format that a user chooses in the save dialog can be loaded again. The same is not guaranteed for a format chosen in "File-Export". | ||
| + | : ''IMPORT'' | ||
| + | : The filter supports service com.sun.star.document.ImportFilter. The filter will be shown in the dialog "File-Open". | ||
| + | : ''INTERNAL'' | ||
| + | : This filter is used only for internal purposes, users won't see it ever. | ||
| + | : ''NOTINCHOOSER'' | ||
| + | : This filter will not be shown in the dialog box for chosing a filter in case OOo was not able to detect one | ||
| + | : ''NOTINFILEDIALOG'' | ||
| + | : This filter will not be shown in the file dialog's filter list | ||
| + | : ''OWN'' | ||
| + | : The filter is a native OO.o format (ODF or otherwise). | ||
| + | : ''PREFERRED'' | ||
| + | : The filter is preferred in case of multiple filters for the same file type exist in the configuration | ||
| + | : ''READONLY'' | ||
| + | : All documents imported by this filter will automatically be in read-only state | ||
| + | : ''SUPPORTSSELECTION'' | ||
| + | : Filter can export only the selected part of a document. This information enables {{PRODUCTNAME}} to enable a corresponding check box in the "File-Export" dialog. | ||
| + | : ''TEMPLATE'' | ||
| + | : Filter denotes a template filter (means, by default all documents opened by it become an "untitled" one) | ||
| + | : ''TEMPLATEPATH'' | ||
| + | : Must always be set together with "TEMPLATE" to make this feature flag work; soon becoming deprecated | ||
| + | : ''USESOPTIONS'' | ||
| + | : The filter must get some parameters to work properly; this can be done by API or using a UNO component as explained above for the "UIComponent" property of filters. | ||
|- | |- | ||
|<code>UserData</code> | |<code>UserData</code> | ||
| Line 50: | Line 80: | ||
|string. The name of a template file for styles the target document of an import filter shall use. If this property is set, the document merges the styles of this template with its default styles before the import starts. | |string. The name of a template file for styles the target document of an import filter shall use. If this property is set, the document merges the styles of this template with its default styles before the import starts. | ||
|} | |} | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
{{Documentation/Caution|Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only. | {{Documentation/Caution|Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only. | ||
Revision as of 09:05, 1 October 2008
Every filter inside OpenOffice.org is specified by the properties shown in the table below. These values are accessible at the previously mentioned service com.sun.star.document.FilterFactory using the interface com.sun.star.container.XNameAccess. Write access is not available here. All types are addressed by their internal names. The property names are identical to the configuration property names.
 |
The documentation of the FilterFactory service currently is outdated. In case of conflicting information about the properties this page is right. An update will follow soon. |
A filter always is registered for only one type. A single filter implementation can handle several types but then must be registered multiple times. One type may handled by more than one filter.
| Property Name | Description |
|---|---|
Name
|
string. The internal name of the filter. This is only an API property, not a configuration property. In the configuration this is the name of the configuration node containing all the other properties. To avoid name clashes with other node names it should follow the rules outlined for extension identifiers. |
UIName
|
string. User friendly name of the type. It may be localized using the localization support of the configuration. All Unicode characters are permitted here. Currently this UI name is not used in OOo itself but it is available for e.g. extensions. |
Type
|
string. A filter is registered for the type it can handle. Multiple assignments are not allowed. Use multiple configuration entries to support more than one type with a single filter implementation. |
DocumentService
|
string. UNO service name describing the component on which the filter can operate. As an example, "com.sun.star.text.TextDocument" specifies the filter as workin with text documents. An object of this type will be passed to the filter in its setTargetDocument() or setSourceDocument() methods.
|
FilterService
|
string. This is the UNO service or implementation name of the filter. Of course a service name can be used only if it is not the generic com.sun.star.document.ImportFilter or com.sun.star.document.ExportFilter. |
UIComponent
|
string. UNO service or implementation name of a UI component (usually a dialog) where users can parameterize the filtering process. As an example, the "Text - txt - csv (StarCalc)" filter needs information about the used column separators to load data. More about that in the chapter about filter options.
|
Flags
|
string list. Some boolean attributes of a filter.
|
UserData
|
sequence<string>. Some filters need to store more configuration to work properly. The format of the string list is not restricted. |
FileFormatVersion
|
int. Indicates that a filter handles only a particular format version of the content type. If a filter implementation can handle several versions of a filter, several configuration entries have to be created. This is not necessary if the filter handles all possible versions and the different versions don't need to appear in the user interface. |
TemplateName
|
string. The name of a template file for styles the target document of an import filter shall use. If this property is set, the document merges the styles of this template with its default styles before the import starts. |
|
Besides these filter flags there are other flags existing that are used currently, but are not documented here. Use documented flags only. |
The service com.sun.star.document.FilterFactory provides these data. It supports read access by using the interface com.sun.star.container.XNameAccess. All items are addressed by their internal names. The return value is represented as a list of type com.sun.star.beans.PropertyValue structures. It uses the filter properties shown above.
Another aspect of this service is the factory interface com.sun.star.lang.XMultiServiceFactory. It creates filter instances using an internal type, or an internal filter name directly. Using a type name searches for a suitable filter and creates, initializes and returns it. Using a filter name directly follows the algorithm shown in the box below. Note that creation of filters is possible for external ones only that have set the FilterService property. Most of the current filters of OpenOffice.org are internal filters, implemented as local code, but not as a UNO service. They can not be created by this FilterFactory. It is possible to ask only for their properties.
|
Direct creation of a filter instance is only possible using a special argument in the createInstanceWithArguments() call of the interface XMultiServiceFactory. To do so, a com.sun.star.beans.PropertyValue FilterName with the internal name of the requested filter as value must be used. Otherwise, the service specifier, that is, the first argument of the create call, is interpreted as an internal type name. It will be used to search a suitable, preferred filter that will be created. It is a combination of searching and creation. Future implementations will split that to make it clearer. In future implementations, a registered filter must be searched through the provided query mechanism and created by using this factory interface. |
| Content on this page is licensed under the Public Documentation License (PDL). |
