1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef COMPHELPER_PROPERTYCONTAINERHELPER_HXX 25 #define COMPHELPER_PROPERTYCONTAINERHELPER_HXX 26 27 #include <cppuhelper/propshlp.hxx> 28 #include <com/sun/star/uno/Type.hxx> 29 #include <com/sun/star/beans/Property.hpp> 30 #ifndef __SGI_STL_VECTOR 31 #include <vector> 32 #endif 33 #include "comphelper/comphelperdllapi.h" 34 35 //......................................................................... 36 namespace comphelper 37 { 38 //......................................................................... 39 40 // infos about one single property 41 struct COMPHELPER_DLLPUBLIC PropertyDescription 42 { 43 // the possibilities where a property holding object may be located 44 enum LocationType 45 { 46 ltDerivedClassRealType, // within the derived class, it's a "real" (non-Any) type 47 ltDerivedClassAnyType, // within the derived class, it's a <type scope="com.sun.star.uno">Any</type> 48 ltHoldMyself // within m_aHoldProperties 49 }; 50 // the location of an object holding a property value : 51 union LocationAccess 52 { 53 void* pDerivedClassMember; // a pointer to a member of an object of a derived class 54 sal_Int32 nOwnClassVectorIndex; // an index within m_aHoldProperties 55 }; 56 57 ::com::sun::star::beans::Property 58 aProperty; 59 LocationType eLocated; // where is the object containing the value located ? 60 LocationAccess aLocation; // access to the property value 61 PropertyDescriptioncomphelper::PropertyDescription62 PropertyDescription() 63 :aProperty( ::rtl::OUString(), -1, ::com::sun::star::uno::Type(), 0 ) 64 ,eLocated( ltHoldMyself ) 65 { 66 aLocation.nOwnClassVectorIndex = -1; 67 } 68 }; 69 70 //========================================================================== 71 //= OPropertyContainerHelper 72 //========================================================================== 73 /** helper class for managing property values, and implementing most of the X*Property* interfaces 74 75 The property values are usually held in derived classes, but can also be given to the 76 responsibility of this class here. 77 78 For more information, see https://wiki.openoffice.org/wiki/Development/Cpp/Helper/PropertyContainerHelper. 79 */ 80 class COMPHELPER_DLLPUBLIC OPropertyContainerHelper 81 { 82 typedef ::std::vector< ::com::sun::star::uno::Any > PropertyContainer; 83 typedef PropertyContainer::iterator PropertyContainerIterator; 84 typedef PropertyContainer::const_iterator ConstPropertyContainerIterator; 85 PropertyContainer m_aHoldProperties; 86 // the properties which are hold by this class' instance, not the derived one's 87 88 private: 89 typedef ::std::vector< PropertyDescription > Properties; 90 typedef Properties::iterator PropertiesIterator; 91 typedef Properties::const_iterator ConstPropertiesIterator; 92 Properties m_aProperties; 93 94 sal_Bool m_bUnused; 95 96 protected: 97 OPropertyContainerHelper(); 98 ~OPropertyContainerHelper(); 99 100 /** register a property. The property is represented through a member of the derived class which calls 101 this method. 102 @param _rName the name of the property 103 @param _nHandle the handle of the property 104 @param _nAttributes the attributes of the property 105 @param _pPointerToMember the pointer to the member representing the property 106 within the derived class. 107 @param _rMemberType the cppu type of the property represented by the object 108 to which _pPointerToMember points. 109 */ 110 void registerProperty(const ::rtl::OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes, 111 void* _pPointerToMember, const ::com::sun::star::uno::Type& _rMemberType); 112 113 114 /** register a property. The property is represented through a ::com::sun::star::uno::Any member of the 115 derived class which calls this method. 116 @param _rName the name of the property 117 @param _nHandle the handle of the property 118 @param _nAttributes the attributes of the property 119 @param _pPointerToMember the pointer to the member representing the property 120 within the derived class, which has to be a ::com::sun::star::uno::Any. 121 @param _rExpectedType the expected type of the property. NOT the type of the object to which 122 _pPointerToMember points (this is always an Any). 123 */ 124 void registerMayBeVoidProperty(const ::rtl::OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes, 125 ::com::sun::star::uno::Any* _pPointerToMember, const ::com::sun::star::uno::Type& _rExpectedType); 126 127 /** register a property. The repository will create an own object holding this property, so there is no 128 need to declare an extra member in your derived class 129 @param _rName the name of the property 130 @param _nHandle the handle of the property 131 @param _nAttributes the attributes of the property 132 @param _rType the type of the property 133 @param _pInitialValue the initial value of the property. May be null if _nAttributes includes 134 the ::com::sun::star::beans::PropertyAttribute::MAYBEVOID flag. 135 Else it must be a pointer to an object of the type described by _rType. 136 */ 137 void registerPropertyNoMember(const ::rtl::OUString& _rName, sal_Int32 _nHandle, sal_Int32 _nAttributes, 138 const ::com::sun::star::uno::Type& _rType, const void* _pInitialValue); 139 140 /** revokes a previously registered property 141 @throw com::sun::star::beans::UnknownPropertyException 142 if no property with the given handle is registered 143 */ 144 void revokeProperty( sal_Int32 _nHandle ); 145 146 147 /// checks whether a property with the given handle has been registered 148 sal_Bool isRegisteredProperty( sal_Int32 _nHandle ) const; 149 150 /// checks whether a property with the given name has been registered 151 sal_Bool isRegisteredProperty( const ::rtl::OUString& _rName ) const; 152 153 154 // helper for implementing OPropertySetHelper overridables 155 sal_Bool convertFastPropertyValue( 156 ::com::sun::star::uno::Any & rConvertedValue, 157 ::com::sun::star::uno::Any & rOldValue, 158 sal_Int32 nHandle, 159 const ::com::sun::star::uno::Any& rValue 160 ); 161 162 void setFastPropertyValue( 163 sal_Int32 nHandle, 164 const ::com::sun::star::uno::Any& rValue 165 ); 166 167 void getFastPropertyValue( 168 ::com::sun::star::uno::Any& rValue, 169 sal_Int32 nHandle 170 ) const; 171 172 // helper 173 /** appends the descriptions of all properties which were registered 'til that moment to the given sequence, 174 keeping the array sorted (by name) 175 @precond 176 the given sequence is already sorted by name 177 @param _rProps 178 initial property sequence which is to be extended 179 */ 180 void describeProperties(::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& /* [out] */ _rProps) const; 181 182 /** modify the attributes of an already registered property. 183 184 You may want to use this if you're a derived from OPropertyContainer indirectly and want to override 185 some settings your base class did. 186 */ 187 void modifyAttributes(sal_Int32 _nHandle, sal_Int32 _nAddAttrib, sal_Int32 _nRemoveAttrib); 188 189 /** retrieves the description for a registered property 190 @throw com::sun::star::beans::UnknownPropertyException 191 if no property with the given name is registered 192 */ 193 const ::com::sun::star::beans::Property& 194 getProperty( const ::rtl::OUString& _rName ) const; 195 196 private: 197 /// insertion of _rProp into m_aProperties, keeping the sort order 198 COMPHELPER_DLLPRIVATE void implPushBackProperty(const PropertyDescription& _rProp); 199 200 /// search the PropertyDescription for the given handle (within m_aProperties) 201 COMPHELPER_DLLPRIVATE PropertiesIterator searchHandle(sal_Int32 _nHandle); 202 203 private: 204 COMPHELPER_DLLPRIVATE OPropertyContainerHelper( const OPropertyContainerHelper& ); // never implemented 205 COMPHELPER_DLLPRIVATE OPropertyContainerHelper& operator=( const OPropertyContainerHelper& ); // never implemented 206 }; 207 208 //......................................................................... 209 } // namespace comphelper 210 //......................................................................... 211 212 #endif // COMPHELPER_PROPERTYCONTAINERHELPER_HXX 213