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 COMPHELPER_PROPERTYCONTAINERHELPER_HXX
  21 #define 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 LocationType
  39     {
  40         ltDerivedClassRealType,     // within the derived class, it's a "real" (non-Any) type
  41         ltDerivedClassAnyType,      // within the derived class, it's a <type scope="com.sun.star.uno">Any</type>
  42         ltHoldMyself                // 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     ::com::sun::star::beans::Property
  52                         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, ::com::sun::star::uno::Type(), 0 )
  58         ,eLocated( ltHoldMyself )
  59     {
  60         aLocation.nOwnClassVectorIndex = -1;
  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.services.openoffice.org/wiki/Development/Cpp/Helper/PropertyContainerHelper.
  73 */
  74 class COMPHELPER_DLLPUBLIC OPropertyContainerHelper
  75 {
  76     typedef ::std::vector< ::com::sun::star::uno::Any > PropertyContainer;
  77     typedef PropertyContainer::iterator                 PropertyContainerIterator;
  78     typedef PropertyContainer::const_iterator           ConstPropertyContainerIterator;
  79     PropertyContainer   m_aHoldProperties;
  80         // the properties which are hold by this class' instance, not the derived one's
  81
  82 private:
  83     typedef ::std::vector< PropertyDescription >    Properties;
  84     typedef Properties::iterator                    PropertiesIterator;
  85     typedef Properties::const_iterator              ConstPropertiesIterator;
  86     Properties      m_aProperties;
  87
  88     sal_Bool        m_bUnused;
  89
  90 protected:
  91     OPropertyContainerHelper();
  92     ~OPropertyContainerHelper();
  93
  94     /** register a property. The property is represented through a member of the derived class which calls
  95         this methdod.
  96         @param      _rName              the name of the property
  97         @param      _nHandle            the handle of the property
  98         @param      _nAttributes        the attributes of the property
  99         @param      _pPointerToMember   the pointer to the member representing the property
 100                                         within the derived class.
 101         @param      _rMemberType        the cppu type of the property represented by the object
 102                                         to which _pPointerToMember points.
 103     */
 104     void    registerProperty(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 105         void* _pPointerToMember, const ::com::sun::star::uno::Type& _rMemberType);
 106
 107
 108     /** register a property. The property is represented through a ::com::sun::star::uno::Any member of the
 109         derived class which calls this methdod.
 110         @param      _rName              the name of the property
 111         @param      _nHandle            the handle of the property
 112         @param      _nAttributes        the attributes of the property
 113         @param      _pPointerToMember   the pointer to the member representing the property
 114                                         within the derived class, which has to be a ::com::sun::star::uno::Any.
 115         @param      _rExpectedType      the expected type of the property. NOT the type of the object to which
 116                                         _pPointerToMember points (this is always an Any).
 117     */
 118     void    registerMayBeVoidProperty(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 119         ::com::sun::star::uno::Any* _pPointerToMember, const ::com::sun::star::uno::Type& _rExpectedType);
 120
 121     /** register a property. The repository will create an own object holding this property, so there is no
 122         need to declare an extra member in your derived class
 123         @param      _rName              the name of the property
 124         @param      _nHandle            the handle of the property
 125         @param      _nAttributes        the attributes of the property
 126         @param      _rType              the type of the property
 127         @param      _pInitialValue      the initial value of the property. May be null if _nAttributes includes
 128                                         the ::com::sun::star::beans::PropertyAttribute::MAYBEVOID flag.
 129                                         Else it must be a pointer to an object of the type described by _rType.
 130     */
 131     void    registerPropertyNoMember(const OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes,
 132         const ::com::sun::star::uno::Type& _rType, const void* _pInitialValue);
 133
 134     /** revokes a previously registered property
 135         @throw  com::sun::star::beans::UnknownPropertyException
 136             if no property with the given handle is registered
 137     */
 138     void    revokeProperty( sal_Int32 _nHandle );
 139
 140
 141     /// checkes whether a property with the given handle has been registered
 142     sal_Bool    isRegisteredProperty( sal_Int32 _nHandle ) const;
 143
 144     /// checkes whether a property with the given name has been registered
 145     sal_Bool    isRegisteredProperty( const OUString& _rName ) const;
 146
 147
 148     // helper for implementing OPropertySetHelper overridables
 149     sal_Bool    convertFastPropertyValue(
 150                     ::com::sun::star::uno::Any & rConvertedValue,
 151                     ::com::sun::star::uno::Any & rOldValue,
 152                     sal_Int32 nHandle,
 153                     const ::com::sun::star::uno::Any& rValue
 154                 )
 155                 SAL_THROW((::com::sun::star::lang::IllegalArgumentException));
 156
 157     void        setFastPropertyValue(
 158                         sal_Int32 nHandle,
 159                         const ::com::sun::star::uno::Any& rValue
 160                     )
 161                     SAL_THROW((::com::sun::star::uno::Exception));
 162
 163     void        getFastPropertyValue(
 164                         ::com::sun::star::uno::Any& rValue,
 165                         sal_Int32 nHandle
 166                     ) const;
 167
 168 // helper
 169     /** appends the descriptions of all properties which were registered 'til that moment to the given sequence,
 170         keeping the array sorted (by name)
 171         @precond
 172             the given sequence is already sorted by name
 173         @param  _rProps
 174             initial property sequence which is to be extended
 175     */
 176     void    describeProperties(::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& /* [out] */ _rProps) const;
 177
 178     /** retrieves the description for a registered property
 179         @throw  com::sun::star::beans::UnknownPropertyException
 180             if no property with the given name is registered
 181     */
 182     const ::com::sun::star::beans::Property&
 183             getProperty( const OUString& _rName ) const;
 184
 185 private:
 186     /// insertion of _rProp into m_aProperties, keeping the sort order
 187     COMPHELPER_DLLPRIVATE void  implPushBackProperty(const PropertyDescription& _rProp);
 188
 189     /// search the PropertyDescription for the given handle (within m_aProperties)
 190     COMPHELPER_DLLPRIVATE PropertiesIterator    searchHandle(sal_Int32 _nHandle);
 191
 192 private:
 193     COMPHELPER_DLLPRIVATE OPropertyContainerHelper( const OPropertyContainerHelper& );            // never implemented
 194     COMPHELPER_DLLPRIVATE OPropertyContainerHelper& operator=( const OPropertyContainerHelper& ); // never implemented
 195 };
 196
 197 //.........................................................................
 198 }   // namespace comphelper
 199 //.........................................................................
 200
 201 #endif // COMPHELPER_PROPERTYCONTAINERHELPER_HXX
 202
 203 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */