xmloff/source/forms/propertyexport.hxx

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