include/comphelper/propertycontainerhelper.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_COMPHELPER_PROPERTYCONTAINERHELPER_HXX
  21 #define INCLUDED_COMPHELPER_PROPERTYCONTAINERHELPER_HXX
  22
  23 #include <com/sun/star/uno/Type.hxx>
  24 #include <com/sun/star/beans/Property.hpp>
  25 #include <cstddef>
  26 #include <limits>
  27 #include <vector>
  28 #include <comphelper/comphelperdllapi.h>
  29
  30
  31 namespace comphelper
  32 {
  33
  34
  35 // infos about one single property
  36 struct COMPHELPER_DLLPUBLIC PropertyDescription
  37 {
  38     // the possibilities where a property holding object may be located
  39     enum class LocationType
  40     {
  41         DerivedClassRealType,     // within the derived class, it's a "real" (non-Any) type
  42         DerivedClassAnyType,      // within the derived class, it's a com.sun.star.uno::Any
  43         HoldMyself                // within m_aHoldProperties
  44     };
  45     // the location of an object holding a property value :
  46     union LocationAccess
  47     {
  48         void*       pDerivedClassMember;        // a pointer to a member of an object of a derived class
  49         std::size_t nOwnClassVectorIndex;       // an index within m_aHoldProperties
  50     };
  51
  52     css::beans::Property aProperty;
  53     LocationType         eLocated;       // where is the object containing the value located ?
  54     LocationAccess       aLocation;      // access to the property value
  55
  56     PropertyDescription()
  57         :aProperty( OUString(), -1, css::uno::Type(), 0 )
  58         ,eLocated( LocationType::HoldMyself )
  59     {
  60         aLocation.nOwnClassVectorIndex = std::numeric_limits<std::size_t>::max();
  61     }
  62 };
  63
  64
  65 //= OPropertyContainerHelper
  66
  67 /** helper class for managing property values, and implementing most of the X*Property* interfaces
  68
  69     The property values are usually held in derived classes, but can also be given to the
  70     responsibility of this class here.
  71
  72     For more information, see http://wiki.openoffice.org/wiki/Development/Cpp/Helper/PropertyContainerHelper.
  73 */
  74 class COMPHELPER_DLLPUBLIC OPropertyContainerHelper
  75 {
  76     typedef ::std::vector< css::uno::Any >              PropertyContainer;
  77     PropertyContainer   m_aHoldProperties;
  78         // the properties which are hold by this class' instance, not the derived one's
  79
  80 private:
  81     typedef ::std::vector< PropertyDescription >    Properties;
  82     typedef Properties::iterator                    PropertiesIterator;
  83     typedef Properties::const_iterator              ConstPropertiesIterator;
  84     Properties      m_aProperties;
  85
  86 protected:
  87     OPropertyContainerHelper();
  88     ~OPropertyContainerHelper();
  89
  90     /** register a property. The property is represented through a member of the derived class which calls
  91         this method.
  92         @param      _rName              the name of the property
  93         @param      _nHandle            the handle of the property
  94         @param      _nAttributes        the attributes of the property
  95         @param      _pPointerToMember   the pointer to the member representing the property
  96                                         within the derived class.
  97         @param      _rMemberType        the cppu type of the property represented by the object
  98                                         to which _pPointerToMember points.
  99     */
 100     void    registerProperty(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 101         void* _pPointerToMember, const css::uno::Type& _rMemberType);
 102
 103
 104     /** register a property. The property is represented through a css::uno::Any member of the
 105         derived class which calls this method.
 106         @param      _rName              the name of the property
 107         @param      _nHandle            the handle of the property
 108         @param      _nAttributes        the attributes of the property
 109         @param      _pPointerToMember   the pointer to the member representing the property
 110                                         within the derived class, which has to be a css::uno::Any.
 111         @param      _rExpectedType      the expected type of the property. NOT the type of the object to which
 112                                         _pPointerToMember points (this is always an Any).
 113     */
 114     void    registerMayBeVoidProperty(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 115         css::uno::Any* _pPointerToMember, const css::uno::Type& _rExpectedType);
 116
 117     /** register a property. The repository will create an own object holding this property, so there is no
 118         need to declare an extra member in your derived class
 119         @param      _rName              the name of the property
 120         @param      _nHandle            the handle of the property
 121         @param      _nAttributes        the attributes of the property
 122         @param      _rType              the type of the property
 123         @param      _pInitialValue      the initial value of the property. May be void if _nAttributes includes
 124                                         the css::beans::PropertyAttribute::MAYBEVOID flag.
 125                                         Else it must contain a value compatible with the type described by _rType.
 126     */
 127     void    registerPropertyNoMember(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 128         const css::uno::Type& _rType, css::uno::Any const & _pInitialValue);
 129
 130     /** revokes a previously registered property
 131         @throw  css::beans::UnknownPropertyException
 132             if no property with the given handle is registered
 133     */
 134     void    revokeProperty( sal_Int32 _nHandle );
 135
 136
 137     /// checks whether a property with the given handle has been registered
 138     bool    isRegisteredProperty( sal_Int32 _nHandle ) const;
 139
 140     /// checks whether a property with the given name has been registered
 141     bool    isRegisteredProperty( const OUString& _rName ) const;
 142
 143
 144     // helper for implementing OPropertySetHelper overridables
 145     bool    convertFastPropertyValue(
 146                     css::uno::Any & rConvertedValue,
 147                     css::uno::Any & rOldValue,
 148                     sal_Int32 nHandle,
 149                     const css::uno::Any& rValue
 150                 );
 151
 152     void        setFastPropertyValue(
 153                         sal_Int32 nHandle,
 154                         const css::uno::Any& rValue
 155                     );
 156
 157     void        getFastPropertyValue(
 158                         css::uno::Any& rValue,
 159                         sal_Int32 nHandle
 160                     ) const;
 161
 162 // helper
 163     /** appends the descriptions of all properties which were registered 'til that moment to the given sequence,
 164         keeping the array sorted (by name)
 165         @precond
 166             the given sequence is already sorted by name
 167         @param  _rProps
 168             initial property sequence which is to be extended
 169     */
 170     void    describeProperties(css::uno::Sequence< css::beans::Property >& /* [out] */ _rProps) const;
 171
 172     /** retrieves the description for a registered property
 173         @throw  css::beans::UnknownPropertyException
 174             if no property with the given name is registered
 175     */
 176     const css::beans::Property&
 177             getProperty( const OUString& _rName ) const;
 178
 179 private:
 180     /// insertion of _rProp into m_aProperties, keeping the sort order
 181     COMPHELPER_DLLPRIVATE void  implPushBackProperty(const PropertyDescription& _rProp);
 182
 183     /// search the PropertyDescription for the given handle (within m_aProperties)
 184     COMPHELPER_DLLPRIVATE PropertiesIterator    searchHandle(sal_Int32 _nHandle);
 185
 186 private:
 187     OPropertyContainerHelper( const OPropertyContainerHelper& ) = delete;
 188     OPropertyContainerHelper& operator=( const OPropertyContainerHelper& ) = delete;
 189 };
 190
 191
 192 }   // namespace comphelper
 193
 194
 195 #endif // INCLUDED_COMPHELPER_PROPERTYCONTAINERHELPER_HXX
 196
 197 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */