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