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