Difference between revisions of "Documentation/DevGuide/OfficeDev/Properties of a Filter"
Line 5: | Line 5: | ||
|ShowPrevNext=block | |ShowPrevNext=block | ||
|PrevPage=Documentation/DevGuide/OfficeDev/Properties of a Type | |PrevPage=Documentation/DevGuide/OfficeDev/Properties of a Type | ||
− | |NextPage=Documentation/DevGuide/OfficeDev/ | + | |NextPage=Documentation/DevGuide/OfficeDev/Filter Options |
}} | }} | ||
{{DISPLAYTITLE:Properties of a Filter}} | {{DISPLAYTITLE:Properties of a Filter}} |
Revision as of 22:01, 30 September 2008
Every filter is registered for only one type . Multiple registrations are to be done by multiple configuration entries. One type is handled by more than one filter. Flags also regulate the use of the preferred filter. A filter is described by the following properties:
Property Name | Description |
---|---|
Name
|
string. The internal name of a filter must be unique and is also used as list entry. It contains special characters, but they must be encoded. |
UIName
|
string. A filter should be able to show a localized name in selection dialogs. You must assign a value for a language, thus supporting CJK versions. All Unicode characters are permitted here. |
Installed
|
boolean. This flag indicates the installation status of a filter. A filter is generally registered equally for all users. In a network installation you should deactivate this for certain groups or single users.
Note: A filter works only if the component library has already been registered in OpenOffice.org. |
Order
|
int. This number shows filters in a user defined order. Valid values are greater then 0. If the number is set to 0, sorting is done alphabetically by the UIName property of the filter. The same applies to filters that have the same Order value.
|
Type
|
string. A filter must register itself for the type it can handle. Multiple assignments are not allowed. Multiple configuration entries must be created, one for every supported type. |
DocumentService
|
string. Describes the component for which the filter operates,For example, "com.sun.star.text.TextDocument ", depending upon the use., This is considered the output or goal of the filter process. A UNO service name is expected.
Note: The implementation name cannot be used here, the generic type of the document is needed. |
FilterService
|
string. This is the UNO implementation name of the filter. It should be clear that this field can not contain the service name of a filter, otherwise OpenOffice.org could not distinguish more then one registered filter. |
UIComponent
|
string. Describes an implementation of a UI dialog used by the filter to let the user modify certain properties for filtering. For example, the "Text - txt - csv (StarCalc) " needs information about the used column separators to load data. To distinguish between different implementations, it must be the real UNO implementation name, not a service name.
|
Flags
|
int. Describes the filter, as shown in the table below. This is where, the organization into import and export filters takes place. Note that external filters must set the ThirdParty flag to be detected.
|
UserData
|
sequence<string>. Some filters need to store more configuration data than usual. This is realized through this entry. The format of the string list is not restricted. |
FileFormatVersion
|
int. Indicates a version number of a document that can be edited by this filter. |
TemplateName
|
string. The name of a template file for importing styles. It is a special feature for importing documents only and not useable for export. Every OpenOffice.org document service knows default styles. If this TemplateName is set, it merges these default styles with the styles of the template, and the template styles are merged with all styles of a document that is imported by this filter.
|
Most functionality of a Filter is listed by its flags. They are necessary to prevent a filter from being displayed in a UI, and to classify import and export, or internal a nd external filters, and prefer some filters to others. Currently supported flags are:
Name | Value | Description |
---|---|---|
Import
|
0x00000001 h
|
This filter supports the specification of a com.sun.star.document.ImportFilter and is used for loading content. |
Export
|
0x00000002 h
|
This filter supports the specification of a com.sun.star.document.ExportFilter and is used for saving content. |
Template
|
0x00000004 h
|
These filters are specialized to handle template formats. By default, a filtered document is used as a template to create a new document . |
Internal
|
0x00000008 h
|
This filter should never be shown on any UI and not be available. |
OwnTemplate
|
0x00000010 h
|
Templates used with the template API of OpenOffice.org and it supports the internal template features. For older versions, it is usable for internal content formats only. |
Own
|
0x00000020 h
|
Tag the intrinsic content formats of OpenOffice.org based on OLE storage or zip packages. |
Alien
|
0x00000040 h
|
A filter with this flag is not fully compatible with the current document format. It is unclear what document features will be lost during saving. This flag decides if a warning box on saving has to be shown. |
UsesOptions (deprecated)
|
0x00000080 h
|
This filter could be customized during processing. Older versions of OpenOffice.org used it to customize the "SaveAs" dialog. Newer versions uses the filter property "UIComponent" to tell if a filter provides filter options. |
Default
|
0x00000100 h
|
Mark a filter as the default filter for saving. Only one filter in an application module, distinguished through the DocumentService property, has this flag set.
|
NotInFileDialog
|
0x00001000 h
|
Suppress display of a filter in file open and save dialogs. |
NotInChooser
|
0x00002000 h
|
Suppress display of a filter in UI elements for choosing filters. |
ThirdParty
|
0x00080000 h
|
These filters are developed by external parties. For historical reasons, the filter detection of OpenOffice.org differentiates between old internal and new external ones, because the former are not UNO based and are used differently. |
Preferred
|
0x10000000 h
|
If more than one filter is registered for the same type, this flag prefers one of them at loading time if the user does not select a specific filter. In contrast to the Default flag, it does not depend on the application module, but there can only be one preferred filter for a type. |
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). |