Filter Options
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.
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.
Content on this page is licensed under the Public Documentation License (PDL). |