Difference between revisions of "Documentation/DevGuide/OfficeDev/Filter Options"
m (1 revision(s)) |
m |
||
| Line 14: | Line 14: | ||
A generic UI that uses a filter as one part of a load request does not know about special parameters. Normally, the <code>FilterData</code> 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 <idl>com.sun.star.ui.dialogs.FilterOptionsDialog</idl>. 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 {{PRODUCTNAME}} 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 <code>filter()</code> request returning false. | A generic UI that uses a filter as one part of a load request does not know about special parameters. Normally, the <code>FilterData</code> 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 <idl>com.sun.star.ui.dialogs.FilterOptionsDialog</idl>. 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 {{PRODUCTNAME}} 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 <code>filter()</code> request returning false. | ||
| − | The UIComponent provides an interface <idl>com.sun.star.beans.XPropertyAccess</idl> used to set the whole <code>MediaDescriptor</code> before executing the dialog using the <code>FilterOptionsDialog</code> interface | + | The UIComponent provides an interface <idl>com.sun.star.beans.XPropertyAccess</idl> used to set the whole <code>MediaDescriptor</code> before executing the dialog using the <code>FilterOptionsDialog</code> interface <idl>com.sun.star.ui.dialogs.XExecutableDialog</idl> 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 <code>FilterData</code> or <code>FilterOptions</code> are part of the descriptor, so that they are added. In the case where they exist, it is necessary to change it. |
{{Documentation/Tip|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 <tt>MediaDescriptor</tt>, called <tt>FilterName</tt>. 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.}} | {{Documentation/Tip|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 <tt>MediaDescriptor</tt>, called <tt>FilterName</tt>. 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.}} | ||
Revision as of 14:37, 30 March 2008
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.
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). |
