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