Difference between revisions of "Documentation/DevGuide/OfficeDev/Filter"

Latest revision as of 12:09, 3 January 2021

As described in the previous chapter, filters are objects that can be used to import or export content into or from Apache OpenOffice documents. The API defines the two services com.sun.star.document.ImportFilter and com.sun.star.document.ExportFilter. A filter implementation can support one or both of them. If a particular filter that only supports import is used, the imported document is modified by the user and then the user presses the "Save" button, a "Save As" operation will be carried out instead as Apache OpenOffice must assume that the filter component is "import only" and so storing must be done in a different format. It doesn't help to have a different export filter for the same content. If a direct "Save" operation should be possible, both filter services must be supported at the same filter object.

A filter is created from the factory service com.sun.star.document.FilterFactory. This service also provides a low-level access to the configuration that knows all registered filters of Apache OpenOffice and their properties, supports search and query functionality, and creates and initializes filter components. As an example, if the type name of a content is known, a query at the FilterFactory can be used to retrieve one or more internal filter names of possible filters and after choosing one of them the filter can be created using this name.

Many existing filters are legacy filters. The component loader or XStorable implementation does not use the FilterFactory to create them, but triggers filtering by internal C++ calls. So asking the FilterFactory to create such filter is not possible.

Filters can be initialized if they implement the interface com.sun.star.lang.XInitialization. The method initialize() is used by the filter factory service directly after creation of the filter object, before the filter is returned to the code that requested the filter. It passes the configuration data of the filter and all parameters and options that have been specified by the creation request to the factory. These properties usually originate from the "FilterOptions" property of the MediaDescriptor and have been put there either by the code requesting the loading or storing or by user input in a filter options dialog. How such filter dialog can be implemented is explained in the chapter about filter options.

The parameter list of initialize() uses the following protocol:

• The first item in the list is a sequence of com.sun.star.beans.PropertyValue structs, that describe the configuration properties of the filter.
• All other items are directly copied from the parameter Arguments of the factory interface method createInstanceWithArguments().

The interface provides functionality for reading and writing of this name. It is not allowed to change an internal filter name during runtime of Apache OpenOffice, because all filter names must be unique, and it is not possible for a filter instance to alter its name. Calls to setName() should be ignored or forwarded to the FilterFactory service, which knows all unique names and can solve ambiguities!

The fact that a filter gets its own name passed as an argument can be used to use one filter implementation to act as several filters in the configuration. This is shown in the following code snippet of the implementation of a filter initialization:

  private String m_sInternalName;
  public void initialize( Object[] lArguments )  
          throws com.sun.star.uno.Exception 
  {  
          // no arguments - no initialization  
          if (lArguments.length<1)
                  return;
          // Arguments[0] = own configuration data
          com.sun.star.beans.PropertyValue[] lConfig =
                  (com.sun.star.beans.PropertyValue[])lArguments[0];
 
          // Arguments[1..n] = optional arguments of create request 
          for (int n=1; n<lArguments.length; ++n)
          {
                  ...
          }  
 
          // analyze own configuration data for our own internal  
          // filter name! Important for generic filter services,  
          // which are registered more then once. They can use this  
          // information to find out, which specialization of it  
          // is required.  
          for (int i=0; i<lConfig.length; ++i)  
          {   
                  if (lConfig[i].Name.equals("Name"))   
                  {    
                          m_sInternalName =     
                                  AnyConverter.toString(lConfig[i].Value);
 
                          // Tip: A generic filter implementation can use this internal    
                          // name at runtime, to detect which specialization of it is required.
                          if (m_sInternalName=="filter_format_1")     
                                  m_eHandle = E_FORMAT_1;    
                          else     
                          if (m_sInternalName=="filter_format_2")
                                  ...   
                  }  
          } 
  }

In one single workflow filters can act as an import or an export filter. If content is loaded, the creator of the filter will use the com.sun.star.document.XImporter interface and its method setTargetDocument() to bind the filter to the document it should import into. If content is stored, the interface com.sun.star.document.XExporter and its method setSourceDocument() will bind the filter to the document it shall get data from. The filtering process is done by the same method in both cases: it's the filter() method of the com.sun.star.document.XFilter interface that both kinds of filters must support. Here the MediaDescriptor is passed to the filter.

In an object that implements both import and export it is necessary to decide whether importing or exporting is asked for when the filter() method is called. The differentiator is whether setTargetDocument or setSourceDocument has been called before (see sample code below). The user of a filter is responsible to make this call in a valid order.

This example code shows how the required filter operation can be tracked inside the filter implementation easily:

  private boolean m_bImport;
 
  // used to tell us: "you will be used for import" 
  public void setTargetDocument( 
    com.sun.star.lang.XComponent xDocument ) 
      throws com.sun.star.lang.IllegalArgumentException 
  { 
      m_bImport = true;
  }
 
  // used to tell us: "you will be used for export" 
  public void setSourceDocument( 
    com.sun.star.lang.XComponent xDocument ) 
      throws com.sun.star.lang.IllegalArgumentException 
  { 
      m_bImport = false; 
  }  
 
  // detect required type of filter operation 
  public boolean filter( 
    com.sun.star.beans.PropertyValue[] lDescriptor ) 
  { 
       boolean bState; 
       if (m_bImport) 
         bState = impl_import( lDescriptor ); 
       else 
         bState = impl_export( lDescriptor ); 
       return bState; 
  }