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 http://wiki.services.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 methdod. 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 methdod. 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 /// checkes whether a property with the given handle has been registered 148 sal_Bool isRegisteredProperty( sal_Int32 _nHandle ) const; 149 150 /// checkes 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 SAL_THROW((::com::sun::star::lang::IllegalArgumentException)); 162 163 void setFastPropertyValue( 164 sal_Int32 nHandle, 165 const ::com::sun::star::uno::Any& rValue 166 ) 167 SAL_THROW((::com::sun::star::uno::Exception)); 168 169 void getFastPropertyValue( 170 ::com::sun::star::uno::Any& rValue, 171 sal_Int32 nHandle 172 ) const; 173 174 // helper 175 /** appends the descriptions of all properties which were registered 'til that moment to the given sequence, 176 keeping the array sorted (by name) 177 @precond 178 the given sequence is already sorted by name 179 @param _rProps 180 initial property sequence which is to be extended 181 */ 182 void describeProperties(::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& /* [out] */ _rProps) const; 183 184 /** modify the attributes of an already registered property. 185 186 You may want to use this if you're a derived from OPropertyContainer indirectly and want to override 187 some settings your base class did. 188 */ 189 void modifyAttributes(sal_Int32 _nHandle, sal_Int32 _nAddAttrib, sal_Int32 _nRemoveAttrib); 190 191 /** retrieves the description for a registered property 192 @throw com::sun::star::beans::UnknownPropertyException 193 if no property with the given name is registered 194 */ 195 const ::com::sun::star::beans::Property& 196 getProperty( const ::rtl::OUString& _rName ) const; 197 198 private: 199 /// insertion of _rProp into m_aProperties, keeping the sort order 200 COMPHELPER_DLLPRIVATE void implPushBackProperty(const PropertyDescription& _rProp); 201 202 /// search the PropertyDescription for the given handle (within m_aProperties) 203 COMPHELPER_DLLPRIVATE PropertiesIterator searchHandle(sal_Int32 _nHandle); 204 205 private: 206 COMPHELPER_DLLPRIVATE OPropertyContainerHelper( const OPropertyContainerHelper& ); // never implemented 207 COMPHELPER_DLLPRIVATE OPropertyContainerHelper& operator=( const OPropertyContainerHelper& ); // never implemented 208 }; 209 210 //......................................................................... 211 } // namespace comphelper 212 //......................................................................... 213 214 #endif // COMPHELPER_PROPERTYCONTAINERHELPER_HXX 215