A filter may need some additional information before it can import or export properly. As an example, the OpenOffice.org filter "
Text - txt - csv (StarCalc)" needs a separator used to detect columns. This information is transported as a property
FilterData inside the
MediaDescriptor. The value depends on the filter implementation and is not specified (type
any). It's up to the filter to deal with it and handle it properly. The MediaDescriptor may contain another property of type string named
FilterOptions. It can be used if the flexibility of an any is not required and the small overhead to retrieve the string from the any is unwanted. The filter must document which of these properties it uses and how the information transported by it must be shaped.
|For historical reasons, a third string property |
There are two possible origins of the FilterData or FilterOptions property:
- The loading or storing process is triggered from code that has the necessary information and provides it in the code.
- A user has entered the data into a dialog that OpenOffice.org has presented to him and retrieved it from the dialog after the user closed it. The dialog is shown by a UNO service that is specified by the
UIComponentproperty of the filter configuration. OpenOffice.org will not show the dialog if the MediaDescriptor already contains one of the named properties.
The service specified by the
UIComponent property is the only way how a filter can retrieve parameters interactively. The filter code itself must not do that because it may be used in an environment that does not allow to show any UI elements, especially modal ones. Here providing filter options by API calls is the only way to provide them to the filter.
The UIComponent is an object implementing the com.sun.star.ui.dialogs.FilterOptionsDialog. It will be called in a modal way, means with an
execute() call that must guarantee that when it returns, all parameters can be retrieved from the UIComponent by its interface com.sun.star.beans.XPropertyAccess. The same interface is used to transfer the current
MediaDescriptor to the UIComponent before executing it. In the
execute() call the implementer can use any UI elements, usually a dialog will be used here. The UIComponent must provide the filter options with the correct property names and the value of the property must be as the filter implementation understands it. The framework code will copy the retrieved properties to the
MediaDescriptor without any change.
If a filter doesn't get any FilterOptions or FilterData though it needs some, it may use default values for them, if possible. Usually this is always possible for export filters, but not always for import filters. The filter implementation should use a configuration file to retrieve default values instead of providing them in the code, so that they can be changed easily. Whether the filter updates the configuration values to the last recently used values passed by
MediaDescriptor or if it never changes them itself is up to the filter developer.
|Content on this page is licensed under the Public Documentation License (PDL).|