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