Export filter framework

From Apache OpenOffice Wiki
Revision as of 13:18, 3 May 2007 by Kohei (Talk | contribs)

Jump to: navigation, search

Where to Start

The best thing to do in order to have a good understanding of what OO.o does when you save or export a file is to read the relevant code. A good place to start would be the SfxObjectShell::SaveTo_Impl(...) method in sfx2/source/doc/objstor.cxx. This method depicts the overall flow of the file save / file export operation, so reading that code will give you a good overview of the process. Beware, though, that the SaveTo_Impl method has roughly 600-lines of code in it. So, tracing the code there will probably drain a lot of your energy. Take a lot of vitamin before you start! :-)

The basic export framework is set by class SfxObjectShell, which is sub-classed by the document shell class of each application (Writer, Calc and Draw/Impress) to implement several virtual functions of SfxObjectShell. Class SfxMedium represents the document to be saved, and class SfxFilter represents the filter that saves the document.

The export process also makes the following distinction.

  • Native OO.o format (such as ODF) - call SfxObjectShell::SaveAsOwnFormat(...)
  • Non-native, "alien" format - call SfxObjectShell::ExportTo(...) or SfxObjectShell::ConvertTo(...), the latter being a virtual function that is overwritten by each application.

SfxFilter - The Filter Class

This method SfxFilterContainer::ReadSingleFilter_Impl() (located in sfx2/source/bastyp/fltfnc.cxx) reads each filter from the XML filter configuration files, and creates an instance of SfxFilter for each filter defined therein.

Filter configuration files

The filter configuration files are found in filter/source/config/fragments/filters, and all have an extension of .xcu. When the module is built, those fragment configuration files get merged into a single configuration file named fcfg_*_filters.xcu. These files eventually wind up in the installation tree. Look under

 <root installation directory>/share/registry/modules/org/openoffice/TypeDetection/Filter

in your OO.o installation directory.

Properties

Flags

Filter flags affect the run-time behavior of the filter. A combination of any number of the following values can be used.

  • 3RDPARTYFILTER
  • ALIEN
  • ASYNCHRON
  • DEFAULT
  • EXPORT
  • IMPORT
  • INTERNAL
  • NOTINCHOOSER
  • NOTINFILEDIALOG
  • OWN
  • PACKED
  • PREFERRED
  • READONLY
  • SILENTEXPORT
  • SUPPORTSSELECTION
  • TEMPLATE
  • TEMPLATEPATH
  • USESOPTIONS
UIComponent
FilterService
UIName
Type
DocumentService

The name of the document service that this filter belongs to. For instance, if it's a Calc-related filter, the value of this property will be com.sun.star.sheet.SpreadsheetDocument.

Export to external (alien) format

This probably covers the vast majority of the export filters. The main flow moves to either ExportTo(...) in SfxObjectShell, or ConvertTo(...) in the same class. ConvertTo(...) is a virtual function overwritten by the current application's document shell class; ScDocShell for Calc, SwDocShell for Writer, and sd::DrawDocShell for Draw/Impress. The distinction between these two calls is unclear; it is differentiated based on whether or not the filter has flag SFX_FILTER_STARONEFILTER, but it's not clear what that flag means.

Zip-based package format

There is a UNO API for creating a zip-based package format - com.sun.star.packages.zip. There is also an internal UNO API called com.sun.star.packages.comp.ZipPackage, which is used when

  • saving to ODF, or
  • exporting XML filters as package (Tools > XML Filter Settings > Save as Package).

The code for ODF export is pretty complex, so a good code to look at to see how it works is the XML filter package export code. Have a look at filter/source/xsltdialog/xmlfilterjar.cxx and see how it creates a jar package and stuff folders and files therein.

The aforementioned com.sun.star.packages.comp.ZipPackage service is implemented in package/source/zippackage/*. The name of the implementation classes and their relationship suggest that this framework was modeled after Java's corresponding zip framework java.util.zip.

ZipPackage implementation class relationship.

UNO Component Filter

Export Filter Code Organization (by module)

filter

The filter module contains code for export filters such as PDF, SVG, and Flash, and the code that implements the export of XML filter settings as a jar package.

oox

The oox module contains some initial code for Office Open XML export which is still under development. Class ::oox::core::XmlStorage has a hook for export operation.

sc

The sc (Calc) module contains code for export filters such as CSV, HTML, RTF, and DIF all in this one class ScImportExport (sc/source/ui/docshell/impex.cxx). The method for each export type is named Doc2Text, Doc2HTML and so on. Method ScDocShell::ConvertTo(...) creates an instance of ScImportExport and calls its method ExportStream(...), which detects the desired export format, and calls appropriate Doc2.... function.

sd

The definition of the sd::DrawDocShell::ConvertTo(...) function is found in sd/source/ui/docshell/docshel4.cxx. This function is fairly short compared to the ones for Writer and Calc.

Similar to the arrangement of the sw module, the sd module also uses separate classes for each individual filter that are all derived from class SdFilter. The following filter classes are found:

  • SdCGMFilter
  • SdGRFFilter
  • SdHTMLFilter
  • SdPPTFilter
  • SdXMLFilter

The ConvertTo() method instantiates the correct filter class based on the filter type, and does the export operation.

sw

The sw (Writer) module implements export filters as individual classes, each one representing a single filter, that are sub-classes of class Writer. The following classes are found:

  • SwASCWriter - for ASCII text export
  • SwHTMLWriter - for HTML export
  • SwRTFWriter - for RTF export
  • SwW4WWriter - ?

All of Writer's export filters are found in sw/source/filter/. Now, when SwDocShell::ConvertTo(...) is called, this method instantiates the correct Sw...Writer class based on the user input, and executes the export operation.

Strategy for OOXML Export

TODO: Fill it.

Personal tools