1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 #ifndef COMPHELPER_PROPERTYBAG_HXX 29 #define COMPHELPER_PROPERTYBAG_HXX 30 31 #include "comphelper/comphelperdllapi.h" 32 #include <comphelper/propertycontainerhelper.hxx> 33 34 /** === begin UNO includes === **/ 35 /** === end UNO includes === **/ 36 37 #include <memory> 38 39 //........................................................................ 40 namespace comphelper 41 { 42 //........................................................................ 43 44 struct PropertyBag_Impl; 45 //==================================================================== 46 //= PropertyBag 47 //==================================================================== 48 /** provides a bag of properties associated with their values 49 50 This class can, for instance, be used for components which need to implement 51 the com.sun.star.beans.PropertyBag service. 52 */ 53 class COMPHELPER_DLLPUBLIC PropertyBag : protected OPropertyContainerHelper 54 { 55 private: 56 ::std::auto_ptr< PropertyBag_Impl > m_pImpl; 57 58 public: 59 PropertyBag(); 60 virtual ~PropertyBag(); 61 62 /** allow adding property with empty string as name 63 (by default, such names are rejected with IllegalActionException). 64 @param i_isAllowed 65 iff true, empty property name will be allowed 66 */ 67 void setAllowEmptyPropertyName(bool i_isAllowed = true); 68 69 /** adds a property to the bag 70 71 The type of the property is determined from its initial value (<code>_rInitialValue</code>). 72 73 @param _rName 74 the name of the new property. Must not be empty unless 75 explicitly allowed with setAllowEmptyPropertyName. 76 @param _nHandle 77 the handle of the new property 78 @param _nAttributes 79 the attributes of the property 80 @param _rInitialValue 81 the initial value of the property. Must not be <NULL/>, to allow 82 determining the property type. 83 84 @throws ::com::sun::star::beans::IllegalTypeException 85 if the initial value is <NULL/> 86 @throws ::com::sun::star::beans::PropertyExistException 87 if the name or the handle are already used 88 @throws ::com::sun::star::beans::IllegalArgumentException 89 if the name is empty 90 */ 91 void addProperty( 92 const ::rtl::OUString& _rName, 93 sal_Int32 _nHandle, 94 sal_Int32 _nAttributes, 95 const ::com::sun::star::uno::Any& _rInitialValue 96 ); 97 98 /** adds a property to the bag 99 100 The initial value of the property is <NULL/>. 101 102 @param _rName 103 the name of the new property. Must not be empty unless 104 explicitly allowed with setAllowEmptyPropertyName. 105 @param _rType 106 the type of the new property 107 @param _nHandle 108 the handle of the new property 109 @param _nAttributes 110 the attributes of the property 111 112 @throws ::com::sun::star::beans::IllegalTypeException 113 if the initial value is <NULL/> 114 @throws ::com::sun::star::beans::PropertyExistException 115 if the name or the handle are already used 116 @throws ::com::sun::star::beans::IllegalArgumentException 117 if the name is empty 118 */ 119 void addVoidProperty( 120 const ::rtl::OUString& _rName, 121 const ::com::sun::star::uno::Type& _rType, 122 sal_Int32 _nHandle, 123 sal_Int32 _nAttributes 124 ); 125 126 /** removes a property from the bag 127 @param _rName 128 the name of the to-be-removed property. 129 @throws UnknownPropertyException 130 if the bag does not contain a property with the given name 131 @throws NotRemoveableException 132 if the property with the given name is not removeable, as indicated 133 by the property attributes used in a previous <code>addProperty</code> 134 call. 135 */ 136 void removeProperty( 137 const ::rtl::OUString& _rName 138 ); 139 140 /** describes all properties in the bag 141 @param _out_rProps 142 takes, upon return, the descriptions of all properties in the bag 143 */ 144 inline void describeProperties( 145 ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& _out_rProps 146 ) const 147 { 148 OPropertyContainerHelper::describeProperties( _out_rProps ); 149 } 150 151 /** retrieves the value of a property given by handle 152 @param _nHandle 153 the handle of the property whose value is to be retrieved 154 @param _out_rValue 155 output parameter taking the property value 156 @throws UnknownPropertyException 157 if the given handle does not denote a property in the bag 158 */ 159 void getFastPropertyValue( 160 sal_Int32 _nHandle, 161 ::com::sun::star::uno::Any& _out_rValue 162 ) const; 163 164 /** converts a to-be-set value of a property (given by handle) so that it can 165 be used in subsequent calls to setFastPropertyValue 166 @param _nHandle 167 the handle of the property 168 @param _rNewValue 169 the new value, which should be converted 170 @param _out_rConvertedValue 171 output parameter taking the converted value 172 @param _out_rCurrentValue 173 output parameter taking the current value of the 174 property 175 @throws UnknownPropertyException 176 if the given handle does not denote a property in the bag 177 @throws IllegalArgumentException 178 if the given value cannot be lossless converted into a value 179 for the given property. 180 */ 181 bool convertFastPropertyValue( 182 sal_Int32 _nHandle, 183 const ::com::sun::star::uno::Any& _rNewValue, 184 ::com::sun::star::uno::Any& _out_rConvertedValue, 185 ::com::sun::star::uno::Any& _out_rCurrentValue 186 ) const; 187 188 /** sets a new value for a property given by handle 189 @throws UnknownPropertyException 190 if the given handle does not denote a property in the bag 191 */ 192 void setFastPropertyValue( 193 sal_Int32 _nHandle, 194 const ::com::sun::star::uno::Any& _rValue 195 ); 196 197 /** returns the default value for a property given by handle 198 199 The default value of a property is its initial value, as passed 200 to ->addProperty. 201 202 @param _nHandle 203 handle of the property whose default value is to be obtained 204 @param _out_rValue 205 the default value 206 @throws UnknownPropertyException 207 if the given handle does not denote a property in the bag 208 */ 209 void getPropertyDefaultByHandle( 210 sal_Int32 _nHandle, 211 ::com::sun::star::uno::Any& _out_rValue 212 ) const; 213 214 /** determines whether a property with a given name is part of the bag 215 */ 216 inline bool hasPropertyByName( const ::rtl::OUString& _rName ) const 217 { 218 return isRegisteredProperty( _rName ); 219 } 220 221 /** determines whether a property with a given handle is part of the bag 222 */ 223 inline bool hasPropertyByHandle( sal_Int32 _nHandle ) const 224 { 225 return isRegisteredProperty( _nHandle ); 226 } 227 protected: 228 using OPropertyContainerHelper::convertFastPropertyValue; 229 using OPropertyContainerHelper::getFastPropertyValue; 230 }; 231 232 //........................................................................ 233 } // namespace comphelper 234 //........................................................................ 235 236 #endif // COMPHELPER_PROPERTYBAG_HXX 237 238