xmloff/source/forms/propertyexport.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_XMLOFF_SOURCE_FORMS_PROPERTYEXPORT_HXX
  21 #define INCLUDED_XMLOFF_SOURCE_FORMS_PROPERTYEXPORT_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <set>
  26
  27 #include "formattributes.hxx"
  28 #include <com/sun/star/beans/XPropertySet.hpp>
  29 #include <com/sun/star/beans/XPropertyState.hpp>
  30 #include <xmloff/xmlexp.hxx>
  31 #include "callbacks.hxx"
  32 #include "strings.hxx"
  33
  34 namespace xmloff
  35 {
  36
  37 #define BOOLATTR_DEFAULT_FALSE          0x00
  38 #define BOOLATTR_DEFAULT_TRUE           0x01
  39 #define BOOLATTR_DEFAULT_VOID           0x02
  40 #define BOOLATTR_DEFAULT_MASK           0x03
  41
  42 #define BOOLATTR_INVERSE_SEMANTICS      0x04
  43     // if sal_True, indicates that the semantic of the property referred by <arg>_pPropertyName</arg>
  44     // is inverse to the semantic of the XML attribute.<br/>
  45     // I.e. if the property value is <TRUE/>, <FALSE/> has to be written and vice versa.
  46     // <p>Be careful with <arg>_bDefault</arg> and <arg>_bInverseSemantics</arg>: if <arg>_bInverseSemantics</arg>
  47     // is <TRUE/>, the current property value is inverted <em>before</em> comparing it to the default.</p>
  48
  49     class IFormsExportContext;
  50     //= OPropertyExport
  51     /** provides export related tools for attribute handling
  52
  53         <p>(The name is somewhat misleading. It's not only a PropertyExport, but in real a ElementExport.
  54         Anyway.)</p>
  55     */
  56     class OPropertyExport
  57     {
  58     private:
  59         typedef std::set<OUString> StringSet;
  60         StringSet       m_aRemainingProps;
  61             // see examinePersistence
  62
  63         void exportRelativeTargetLocation(const OUString& _sPropertyName,sal_Int32 _nProperty,bool _bAddType);
  64
  65     protected:
  66         IFormsExportContext&    m_rContext;
  67
  68         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
  69                                 m_xProps;
  70         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySetInfo >
  71                                 m_xPropertyInfo;
  72         const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyState >
  73                                 m_xPropertyState;
  74
  75         // caching
  76         OUString     m_sValueTrue;
  77         OUString     m_sValueFalse;
  78
  79     public:
  80         /** constructs an object capable of handling attributes for export
  81             @param  _rContext
  82                 the export context to which's attribute list the property translation should be added
  83             @param  m_xControl
  84                 the property set to be exported
  85         */
  86         OPropertyExport(IFormsExportContext& _rContext,
  87             const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxProps);
  88
  89     protected:
  90         /** examines a property set given for all properties which's value are to made persistent
  91
  92             <p>upon return the <method>m_aRemainingProps</method> will be filled with the names of all properties
  93             which need to be stored</p>
  94         */
  95         void examinePersistence();
  96
  97         template< typename T > void exportRemainingPropertiesSequence(
  98             com::sun::star::uno::Any const & value,
  99             token::XMLTokenEnum eValueAttName);
 100
 101         void exportRemainingProperties();
 102
 103         /** indicates that a property has been handled by a derived class, without using the helper methods of this
 104             class.
 105
 106             <p>Calling this method is necessary in case you use the suggested mechanism for the generic export of
 107             properties. This means that you want to use <method>exportRemainingProperties</method>, which exports
 108             all properties which need to ('cause they haven't been exported with one of the other type-specific
 109             methods).</p>
 110
 111             <p>In this case you should call exportedProperty for every property you export yourself, so the property
 112             will be flagged as <em>already handled</em></p>
 113         */
 114         void exportedProperty(const OUString& _rPropertyName)
 115             { m_aRemainingProps.erase(_rPropertyName); }
 116
 117         /** add an attribute which is represented by a string property to the export context
 118
 119             @param _nNamespaceKey
 120                 the key of the namespace to use for the attribute name. Is used with the namespace map
 121                 provided by the export context.
 122             @param _pAttributeName
 123                 the name of the attribute to add. Must not contain any namespace
 124             @param _pPropertyName
 125                 the name of the property to ask the control for
 126         */
 127         void exportStringPropertyAttribute(
 128             const sal_uInt16 _nNamespaceKey,
 129             const sal_Char* _pAttributeName,
 130             const OUString& _rPropertyName
 131         );
 132
 133         /** add an attribute which is represented by a boolean property to the export context
 134
 135             @param _nNamespaceKey
 136                 the key of the namespace to use for the attribute name. Is used with the namespace map
 137                 provided by the export context.
 138             @param _pAttributeName
 139                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 140             @param _pPropertyName
 141                 the name of the property to ask the control for
 142             @param _nBooleanAttributeFlags
 143                 specifies the default and the "alignment" (inverse semantics) of the boolean property
 144         */
 145         void exportBooleanPropertyAttribute(
 146             const sal_uInt16 _nNamespaceKey,
 147             const sal_Char* _pAttributeName,
 148             const OUString& _rPropertyName,
 149             const sal_Int8 _nBooleanAttributeFlags);
 150
 151         /** add an attribute which is represented by a sal_Int16 property to the export context
 152
 153             @param _nNamespaceKey
 154                 the key of the namespace to use for the attribute name. Is used with the namespace map
 155                 provided by the export context.
 156             @param _pAttributeName
 157                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 158             @param _pPropertyName
 159                 the name of the property to ask the control for
 160             @param _nDefault
 161                 the default of the attribute. See force parameter.
 162             @param force
 163                 if true and the property is not set or does not contain a sal_Int16,
 164                 then _nDefault is written out.
 165                 if false and the current property value equals _nDefault,
 166                 then no attribute is added.
 167         */
 168         void exportInt16PropertyAttribute(
 169             const sal_uInt16 _nNamespaceKey,
 170             const sal_Char* _pAttributeName,
 171             const OUString& _rPropertyName,
 172             const sal_Int16 _nDefault,
 173             const bool force = false);
 174
 175         /** add an attribute which is represented by a sal_Int32 property to the export context
 176
 177             @param _nNamespaceKey
 178                 the key of the namespace to use for the attribute name. Is used with the namespace map
 179                 provided by the export context.
 180             @param _pAttributeName
 181                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 182             @param _pPropertyName
 183                 the name of the property to ask the control for
 184             @param _nDefault
 185                 the default of the attribute. If the current property value equals this default, no
 186                 attribute is added.
 187         */
 188         void exportInt32PropertyAttribute(
 189             const sal_uInt16 _nNamespaceKey,
 190             const sal_Char* _pAttributeName,
 191             const OUString& _rPropertyName,
 192             const sal_Int32 _nDefault);
 193
 194         /** add an attribute which is represented by a enum property to the export context
 195
 196             @param _nNamespaceKey
 197                 the key of the namespace to use for the attribute name. Is used with the namespace map
 198                 provided by the export context.
 199             @param _pAttributeName
 200                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 201             @param _pPropertyName
 202                 the name of the property to ask the control for
 203             @param _pValueMap
 204                 the map to use when converting the property value to an attribute value
 205             @param _nDefault
 206                 the default of the attribute. If the current property value equals this default, no
 207                 attribute is added.
 208         */
 209         void exportEnumPropertyAttribute(
 210             const sal_uInt16 _nNamespaceKey,
 211             const sal_Char* _pAttributeName,
 212             const OUString& _rPropertyName,
 213             const SvXMLEnumMapEntry* _pValueMap,
 214             const sal_Int32 _nDefault,
 215             const bool _bVoidDefault = false);
 216
 217         // some very special methods for some very special attribute/property pairs
 218
 219         /** add the hlink:target-frame attribute to the export context.
 220
 221             <p>The value of this attribute is extracted from the TargetFrame property of the object given.</p>
 222
 223             <p>The property needs a special handling because conflicts between the default values for the attribute
 224             and the property.</p>
 225         */
 226         void exportTargetFrameAttribute();
 227
 228         /** add the form:href attribute to the export context.
 229
 230             <p>The value of this attribute is extracted from the TargetURL property of the object given.</p>
 231
 232             <p>The property needs a special handling because the URL's need to be made relative</p>
 233
 234             <p>If _bAddType is set, an additional xlink:type="simple" attribute is also added.</p>
 235         */
 236         inline void exportTargetLocationAttribute(bool _bAddType) { exportRelativeTargetLocation(PROPERTY_TARGETURL,CCA_TARGET_LOCATION,_bAddType); }
 237
 238         /** add the form:image attribute to the export context.
 239
 240             <p>The value of this attribute is extracted from the ImageURL property of the object given.</p>
 241
 242             <p>The property needs a special handling because the URL's need to be made relative</p>
 243         */
 244         inline void exportImageDataAttribute() { exportRelativeTargetLocation(PROPERTY_IMAGEURL,CCA_IMAGE_DATA,false); }
 245
 246         /** flag the style properties as 'already exported'
 247
 248             <p>We don't have style support right now, so the only thing the method does is removing the style-relevant
 249             properties from the list of yet-to-be-exported properties (<member>m_aRemainingProps</member>)</p>
 250         */
 251         void flagStyleProperties();
 252
 253         /** add an arbitrary attribute extracted from an arbitrary property to the export context
 254
 255             <p>The current value of the property specified with <arg>_pPropertyName</arg> is taken and converted
 256             into a string, no matter what type it has. (Okay, there are the usual limitations: We know Date, Datetime,
 257             double, integer ... to name just a few).</p>
 258
 259             <p>In case the property value is <NULL/> (void), no attribute is added</p>
 260
 261             <p>In case the property value is an empty string, and the property is a not allowed to be <NULL/> (void),
 262             no attribute is added</p>
 263
 264             <p>In case the property value is a sequence of any type, no attribute is added, 'cause sequences can't be
 265             transported as attribute. In the debug version, an additional assertion will occur if you nonetheless try
 266             to do this.</p>
 267
 268             @param _nNamespaceKey
 269                 the key of the namespace to use for the attribute name. Is used with the namespace map
 270                 provided by the export context.
 271             @param _pAttributeName
 272                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 273             @param _pPropertyName
 274                 the name of the property to ask the object for
 275         */
 276         void exportGenericPropertyAttribute(
 277             const sal_uInt16 _nAttributeNamespaceKey,
 278             const sal_Char* _pAttributeName,
 279             const sal_Char* _pPropertyName);
 280
 281         /** exports a property value, which is a string sequence, as attribute
 282
 283             <p>The elements of the string sequence given are quoted and concatenated, with the characters used for
 284             this to be chosen by the caller</p>
 285
 286             <p>If you use the quote character, no check (except assertions) is made if one of the list items
 287             contains the quote character</p>
 288
 289             <p>If you don't use the quote character, no check (except assertions) is made if one of the list items
 290             contains the separator character (which would be deadly when reimporting the string)</p>
 291
 292             @param _nNamespaceKey
 293                 the key of the namespace to use for the attribute name. Is used with the namespace map
 294                 provided by the export context.
 295             @param _pAttributeName
 296                 the name of the attribute to add. Must not contain any namespace (it's added automatically)
 297             @param _pPropertyName
 298                 the name of the property to ask the object for
 299             @param _aQuoteCharacter
 300                 the character to use to quote the sequence elements with. May be 0, in this case no quoting happens
 301             @param _aListSeparator
 302                 the character to use to separate the list entries
 303         */
 304         void exportStringSequenceAttribute(
 305             const sal_uInt16 _nAttributeNamespaceKey,
 306             const sal_Char* _pAttributeName,
 307             const OUString& _rPropertyName,
 308             const sal_Unicode _aQuoteCharacter = '"',
 309             const sal_Unicode _aListSeparator = ',');
 310
 311         /** determines whether the given property is to be exported
 312
 313             <p>Currently, the method simply checks whether the property's state is <em>not</em> PropertyState.DEFAULT,
 314             or whether the property is a dynamic property (i.e. added via an <code>XPropertyContainer</code>).
 315             So, take care when using the method - the heuristics is not applicable for all properties.</p>
 316         */
 317         bool shouldExportProperty( const OUString& i_propertyName ) const;
 318
 319         /** tries to convert an arbitrary <type scope="com.sun:star.uno">Any</type> into an string
 320
 321             <p>If the type contained in the Any is not supported, the returned string will be empty. In the
 322             debug version, an additional assertion occurs.</p>
 323
 324             @param  _rValue
 325                 the value to convert
 326         */
 327         OUString implConvertAny(
 328             const ::com::sun::star::uno::Any& _rValue);
 329
 330         /**
 331             @return
 332                 token which can be used in the <code>form:property</code> element's <code>type</code> attribute
 333                 to describe the type of a value.<br/>
 334                 Possible types returned are
 335                 <ul>
 336                     <li><b>boolean</b>: <arg>_rValue</arg> was interpreted as boolean value before converting
 337                         it into a string</li>
 338                     <li><b>float</b>: <arg>_rValue</arg> was interpreted as 64 bit floating point 16bit integer, 32bit integer or 64 bit integer value before
 339                         converting it into a string</li>
 340                     <li><b>string</b>: <arg>_rValue</arg> did not need any conversion as it already was a string</li>
 341                 </ul>
 342                 If the type is not convertible, float is returned
 343         */
 344         static ::xmloff::token::XMLTokenEnum implGetPropertyXMLType(const ::com::sun::star::uno::Type& _rType);
 345
 346 #ifdef DBG_UTIL
 347                 void AddAttribute(sal_uInt16 _nPrefix, const sal_Char* _pName, const OUString& _rValue);
 348                 void AddAttribute( sal_uInt16 _nPrefix, const OUString& _rName, const OUString& _rValue );
 349                 void AddAttributeASCII( sal_uInt16 nPrefix, const sal_Char *pName, const sal_Char *pValue );
 350                 void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, const OUString& _rValue);
 351                 void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, ::xmloff::token::XMLTokenEnum _eValue );
 352 #else
 353         //  in the product version, inline this, so it does not cost us extra time calling into our method
 354         inline  void AddAttribute(sal_uInt16 _nPrefix, const sal_Char* _pName, const OUString& _rValue)
 355             { m_rContext.getGlobalContext().AddAttribute(_nPrefix, _pName, _rValue); }
 356         inline void AddAttribute( sal_uInt16 _nPrefix, const OUString& _rName, const OUString& _rValue )
 357             { m_rContext.getGlobalContext().AddAttribute( _nPrefix, _rName, _rValue ); }
 358         inline  void AddAttributeASCII( sal_uInt16 _nPrefix, const sal_Char* _pName, const sal_Char *pValue )
 359             { m_rContext.getGlobalContext().AddAttributeASCII(_nPrefix, _pName, pValue); }
 360         inline void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, const OUString& _rValue)
 361             { m_rContext.getGlobalContext().AddAttribute(_nPrefix, _eName, _rValue); }
 362         inline void AddAttribute(sal_uInt16 _nPrefix, ::xmloff::token::XMLTokenEnum _eName, ::xmloff::token::XMLTokenEnum _eValue )
 363             { m_rContext.getGlobalContext().AddAttribute(_nPrefix, _eName, _eValue); }
 364 #endif
 365
 366 #ifdef DBG_UTIL
 367     protected:
 368         /** check a given property set for the existence and type correctness of a given property
 369
 370             <p>This method is available in the non-product version only.</p>
 371
 372             @param _rPropertyName
 373                 the name of the property to ask the control model for
 374             @param _pType
 375                 the expected type of the property. May be NULL, in this case no type check is made.
 376             @return sal_True, if the property exists and is of the correct type
 377         */
 378         void dbg_implCheckProperty(
 379             const OUString& _rPropertyName,
 380             const ::com::sun::star::uno::Type* _pType);
 381
 382 //      void dbg_implCheckProperty(
 383 //          const sal_Char* _rPropertyName,
 384 //          const ::com::sun::star::uno::Type* _pType)
 385 //      {
 386 //          dbg_implCheckProperty(OUString::createFromAscii(_rPropertyName), _pType);
 387 //      }
 388 #endif
 389     };
 390
 391     //= helper
 392 #ifdef DBG_UTIL
 393     #define DBG_CHECK_PROPERTY(name, type)  \
 394         dbg_implCheckProperty(name, &cppu::UnoType<type>::get())
 395
 396     #define DBG_CHECK_PROPERTY_NO_TYPE(name)    \
 397         dbg_implCheckProperty(name, NULL)
 398
 399     #define DBG_CHECK_PROPERTY_ASCII_NO_TYPE( name ) \
 400         dbg_implCheckProperty( OUString::createFromAscii( name ), NULL )
 401 #else
 402     #define DBG_CHECK_PROPERTY(name, type)
 403     #define DBG_CHECK_PROPERTY_NO_TYPE(name)
 404     #define DBG_CHECK_PROPERTY_ASCII_NO_TYPE( name )
 405 #endif
 406
 407 }   // namespace xmloff
 408
 409 #endif // INCLUDED_XMLOFF_SOURCE_FORMS_PROPERTYEXPORT_HXX
 410
 411 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */