Filter Options

From Apache OpenOffice Wiki
Jump to: navigation, search



A filter may need some additional information before it can import or export properly. As an example, the Apache OpenOffice 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.

Documentation caution.png For historical reasons, a third string property FilterFlags exists. It is deprecated, so don't use it.

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 Apache OpenOffice 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 UIComponent property of the filter configuration. Apache OpenOffice 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).
Personal tools
In other languages