Filter Options
From OpenOffice.org Wiki
It is possible to parameterize a filter component. For example, the OpenOffice.org filter "Text - txt - csv (StarCalc)" needs a separator used to detect columns. This information is transported inside the MediaDescriptor. A special property named FilterData of type any exists. The value depends on the filter implementation and is not specified.
 | There is another string property named FilterOptions. It should be used if the flexibility of an any is not required. For historical reasons, a third-string property FilterFlags exists. It is deprecated, so it is not recommend for use. |
A generic UI that uses a filter as one part of a load request does not know about special parameters. Normally, the FilterData are not set inside the media descriptor, therefore a filter should use default values. It should be possible to prompt the user for better values by registering another component that implements the service com.sun.star.ui.dialogs.FilterOptionsDialog. It is called UIComponent. It enables a filter developer to query for user options before the filter operation is performed. It does not show this dialog inside the filter, because any UI can be suppressed, for example, an external application uses the API of OpenOffice.org for scripting running in a hidden mode. The code that uses the filter decides if it is necessary and allowed to use the dialog. If not, the filter lives with missing parameters and uses default values. If it is not possible to have defaults, it aborts the filter() request returning false.
The UIComponent provides an interface com.sun.star.beans.XPropertyAccess used to set the whole MediaDescriptor before executing the dialog using the FilterOptionsDialog interface com.sun.star.ui.dialogs.XExecutableDialog and retrieves the changes. The user of the dialog decides if the changes are merged with the original ones or replaced. Using the whole descriptor provides the information about the environment in which the filter works, for example, the URL or information about preview mode. The parameters of a filter depend on it. Normally a UIComponent is shown if no FilterData or FilterOptions are part of the descriptor, so that they are added. In the case where they exist, it is necessary to change it.
 | If the filter programmer wants to implement a generic dialog for different filters, then he must know which of these filters the UIComponent is shown. This information exists inside the MediaDescriptor, called FilterName. The outside code which uses the dialog knows this filter also and should set it in the descriptor, because the implementation name of the component must be known to create the dialog. This information exists inside the configuration where it is registered for a filter. |
| Content on this page is licensed under the Public Documentation License (PDL). |
