Difference between revisions of "Documentation/DevGuide/OfficeDev/Filter Options"
| Line 15: | Line 15: | ||
There are two possible origins of the FilterData or FilterOptions property: | There are two possible origins of the FilterData or FilterOptions property: | ||
| − | * The loading or storing process is triggered from code that | + | * 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 {{PRODUCTNAME}} has presented to him and retrieved it from the dialog after the user closed it. {{PRODUCTNAME}} will not show the dialog if the MediaDescriptor already contains one of the named properties before. The dialog is shown by a UNO service that is specified by the "UIComponent" property of the filter configuration. | * A user has entered the data into a dialog that {{PRODUCTNAME}} has presented to him and retrieved it from the dialog after the user closed it. {{PRODUCTNAME}} will not show the dialog if the MediaDescriptor already contains one of the named properties before. The dialog is shown by a UNO service that is specified by the "UIComponent" property of the filter configuration. | ||
Revision as of 10:38, 1 October 2008
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.
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. OpenOffice.org will not show the dialog if the MediaDescriptor already contains one of the named properties before. The dialog is shown by a UNO service that is specified by the "UIComponent" property of the filter configuration.
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. 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 <code>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.
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). |
