Difference between revisions of "Calc/Implementation/Calc styles export"

Revision as of 11:54, 8 August 2012

Basic concept of Styles

In the OpenDocument format, formatting properties, which influences the visual representation of objects, are stored in styles. Using styles to store formatting properties has advantages such as, format information is separated from document content, and styles enable consistent formatting and changing of formatting for objects subject to styles. Following picture is a sample of OpenDocument styles.xml file. This file is the main file for styles storage.

As styles.xml shows, both <style:default-style> and <style:style> in <office:styles> have a “style:name” attribute. In fact, styles and font face declarations are referenced by their style:name attribute[1]. A referenced style or font face declaration should be defined in the same file as the reference, or in styles.xml. Styles built in the stylist (can be used by click menu "Format"--"Styles and formatting") or ones that you create there, will have names like “Heading 1” or Custom Citation. Automatic styles <office:automatic-styles> will have names consisting of style-family abbreviation followed by a number; a style name such as T1 is the first automatic style for style:family="text"; P3 would be the third style for paragraphs, ta2 would be the second style for a table, ro4 would be the fourth style for a table row, etc(please refer content.xml for OpenDocument). The other attribute of interest is the optional parent-style-name, which you will find in styles that have been derived from other styles. <style:font-face> element represents a font face declaration which documents the properties of a font used in a document. OpenDocument font face declarations may have an unique name. This name can be used inside styles (as an attribute of <style:text-properties> element) as value of the style:font-name attribute to select a font face declaration. <style:style> element represents styles,and <style:default-style> element represents default styles. A default style specifies default formatting properties for a style family. These defaults are used if a formatting property is neither specified by an automatic nor a common style. Default styles exist for all style families that are represented by the <style:style> element specified by the style:family attribute. An OpenDocument document should contain the default styles of the style families for which are used in common or automatic styles in the document.<office:master-styles> <style:master-page> defines page styles which is in stylist.

File:Styles font face.xml .jpg

Attributes for elements defined by OpenDocument are divided between those used by structural elements[2] versus those used by <style:*-properties> elements. Attributes have default values defined by reference[2] standard, and when any element appears in a document instance without such an attribute, consumers should behave as if the attribute is present with the defined default value. <style:*-properties> elements is commonly used to aggregate attributes of one type for specific style. Formatting definitions are expressed as attributes on the <style:*-properties> elements or as child elements of these elements. From code perspective, these <office:styles> , <office:automatic-styles> etc elements in styles.xml is written by SvXMLExport::exportDoc( enum ::xmloff::token::XMLTokenEnum eClass ), when export ods, eClass is XML_SPREADSHEET. For example, ImplExportStyles() inside SvXMLExport::exportDoc() is for writing <office:styles> elements, _ExportFontDecls(); is for <office:font-face-decls>, and ImplExportAutoStyles() is for <office:automatic-styles>. Inside ImplExportStyles() , ScXMLExport::_ExportStyles will call exportDefaultStyle(), exportDataStyles(), exportStyleFamily() etc, in turn to export <style:default-style> <number:number-style>, <style:style> etc. ScXMLImportWrapper::ExportToComponent() is called with different parameters to export each file inside ods, such as styles.xml, content.xml.

Styles export sequence diagrams overview

<style:font-face> elements export is mainly in following sequence, <style: default style> elements is exported generally as following sequece,

Automatic styles export is mainly as below,

Main class for export, SvXMLExport and ScXMLExport

SvXMLExport is the main class for XML file export. It implements several UNO interfaces such as ::com::sun::star::document::Xfilter, which is used by service ImportFilter or ExportFilter to support loading/saving of documents in different formats, and ::com::sun::star::xml::sax::XDocumentHandler plus ::com::sun::star::xml::sax::XEntendedDocumentHandler, which is interfaces for calling SAX(an event-based sequential access parser API ). It also holds ::com::sun::star::frame::XModel to access document data model. And it use XMLFontAutoStylePool, SvXMLAutoStylePoolP to manage font declarations and automatic styles store plus export. Member UniReference< XMLPageExport > mxPageExport is used as child exporter, which export page styles; and UniReference< XMLShapeExport > mxShapeExport for exporting shape styles. It has function ImplExportStyles( ) for <office:styles> export, _ImplExportMasterStyles() for <style:master-styles> export, etc.

   ScXMLExport is derived from SvXMLExport and it holds specific SvXMLExportPropertyMapper for SC module, such as xCellStylesExportPropertySetMapper, xRowStylesExportPropertySetMapper. And  ScColumnStyles, ScRowStyles etc for corresponding automatic styles export. It implements _ExportFontDecls(),  _ExportStyles(), _ExportAutoStyles() etc to actually export styles. ScXMLExport will be constructed once writing a XML file such as styles.xml, content.xml.

class XMLOFF_DLLPUBLIC SvXMLExport { … SvXMLNamespaceMap *mpNamespaceMap; // the namepspace map SvXMLUnitConverter *mpUnitConv; // the unit converter

UniReference< SvXMLAutoStylePoolP > mxAutoStylePool;

UniReference< XMLFontAutoStylePool > mxFontAutoStylePool;

SAL_DLLPRIVATE void ImplExportMeta(); // <office:meta> SAL_DLLPRIVATE void ImplExportSettings(); // <office:settings> SAL_DLLPRIVATE void ImplExportStyles( sal_Bool bUsed ); // <office:styles> SAL_DLLPRIVATE void ImplExportAutoStyles( sal_Bool bUsed );// <office:automatic-styles> SAL_DLLPRIVATE void ImplExportMasterStyles( sal_Bool bUsed ); // <office:master-styles> SAL_DLLPRIVATE void ImplExportContent(); // <office:body>

// This method can be overloaded to export the font declarations // The default implementation will export the contents of the // XMLFontAutoStylePool if it has been created. virtual void _ExportFontDecls();

// This method should be overloaded to export the content of <style:styles>. // If bUsed is set, used styles should be exported only. // Overloaded Methods must call this method ! virtual void _ExportStyles( sal_Bool bUsed ) ;

   // methods for accessing the document handler and handling SAX errors

void StartElement(sal_uInt16 nPrefix,

                       enum ::xmloff::token::XMLTokenEnum eName,

sal_Bool bIgnWSOutside ); … }

   SvXMLElementExport is helper class to export an element, its constructors prints a start tag with the common attributes. For example, SvXMLElementExport aElement( GetExport(), XML_NAMESPACE_STYLE, XML_FONT_FACE,  sal_True, sal_True )  could print tag <style:font-face style:name="Arial" svg:font-family="Arial" style:font-pitch="variable" /> .  Constructor of SvXMLElementExport will indirectly call SvXMLExport::StartElement() to write XML. And the destructor ~SvXMLElementExport() prints an end tag.
   For different properties, process of writing XML is quite differently. Handling color will use XMLColorPropHdl for writing XML and string using XMLStringProHdl; meanwhile XMLPropertyHandler is abstract base-class for different XML-types. Derivations of XMLPropertyHandler  knows how to compare, im/export a special XML-type. 
    Some property types need SvXMLUnitConverter converts values  from their internal represantation to the textual form used in xml and back.Most of the methods are static but the SvXMLUnitConverter can also store default units for both numerical and textual measures.  For example, when XMLFontPitchPropHdl writing FontPitch property to XML, it use SvXMLUnitConverter::convertEnum() to convert enum FontPitch to textual form, by searching SvXMLEnumMapEntry aFontPitchMapping[] it will get mapped XMLTokenEnum and finally get corresponding text in xmltoken.cxx. Sample code is as below.

static SvXMLEnumMapEntry __READONLY_DATA aFontPitchMapping[] = { { XML_FIXED, PITCH_FIXED }, { XML_VARIABLE, PITCH_VARIABLE }, { XML_TOKEN_INVALID, 0 } }; sal_Bool XMLFontPitchPropHdl::exportXML( OUString& rStrExpValue, const uno::Any& rValue, const SvXMLUnitConverter& ) const { sal_Bool bRet = sal_False; sal_Int16 nPitch = sal_Int16(); OUStringBuffer aOut;

FontPitch ePitch = PITCH_DONTKNOW; if( rValue >>= nPitch ) ePitch = (FontPitch)nPitch;

if( PITCH_DONTKNOW != ePitch ) { bRet = SvXMLUnitConverter::convertEnum( aOut, ePitch, aFontPitchMapping, XML_FIXED ); rStrExpValue = aOut.makeStringAndClear(); }

return bRet; }