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_PROPERTYBAG_HXX
25 #define COMPHELPER_PROPERTYBAG_HXX
26 
27 #include "comphelper/comphelperdllapi.h"
28 #include <comphelper/propertycontainerhelper.hxx>
29 
30 /** === begin UNO includes === **/
31 /** === end UNO includes === **/
32 
33 #include <memory>
34 
35 //........................................................................
36 namespace comphelper
37 {
38 //........................................................................
39 
40     struct PropertyBag_Impl;
41 	//====================================================================
42 	//= PropertyBag
43 	//====================================================================
44     /** provides a bag of properties associated with their values
45 
46         This class can, for instance, be used for components which need to implement
47         the com.sun.star.beans.PropertyBag service.
48     */
49     class COMPHELPER_DLLPUBLIC PropertyBag : protected OPropertyContainerHelper
50 	{
51     private:
52         ::std::auto_ptr< PropertyBag_Impl > m_pImpl;
53 
54     public:
55         PropertyBag();
56         virtual ~PropertyBag();
57 
58         /** allow adding property with empty string as name
59             (by default, such names are rejected with IllegalActionException).
60             @param i_isAllowed
61                 iff true, empty property name will be allowed
62          */
63         void setAllowEmptyPropertyName(bool i_isAllowed = true);
64 
65         /** adds a property to the bag
66 
67             The type of the property is determined from its initial value (<code>_rInitialValue</code>).
68 
69             @param _rName
70                 the name of the new property. Must not be empty unless
71                 explicitly allowed with setAllowEmptyPropertyName.
72             @param _nHandle
73                 the handle of the new property
74             @param _nAttributes
75                 the attributes of the property
76             @param _rInitialValue
77                 the initial value of the property. Must not be <NULL/>, to allow
78                 determining the property type.
79 
80             @throws ::com::sun::star::beans::IllegalTypeException
81                 if the initial value is <NULL/>
82             @throws ::com::sun::star::beans::PropertyExistException
83                 if the name or the handle are already used
84             @throws ::com::sun::star::beans::IllegalArgumentException
85                 if the name is empty
86         */
87         void    addProperty(
88                     const ::rtl::OUString& _rName,
89                     sal_Int32 _nHandle,
90                     sal_Int32 _nAttributes,
91 		            const ::com::sun::star::uno::Any& _rInitialValue
92                 );
93 
94         /** adds a property to the bag
95 
96             The initial value of the property is <NULL/>.
97 
98             @param _rName
99                 the name of the new property. Must not be empty unless
100                 explicitly allowed with setAllowEmptyPropertyName.
101             @param _rType
102                 the type of the new property
103             @param _nHandle
104                 the handle of the new property
105             @param _nAttributes
106                 the attributes of the property
107 
108             @throws ::com::sun::star::beans::IllegalTypeException
109                 if the initial value is <NULL/>
110             @throws ::com::sun::star::beans::PropertyExistException
111                 if the name or the handle are already used
112             @throws ::com::sun::star::beans::IllegalArgumentException
113                 if the name is empty
114         */
115         void    addVoidProperty(
116                     const ::rtl::OUString& _rName,
117                     const ::com::sun::star::uno::Type& _rType,
118                     sal_Int32 _nHandle,
119                     sal_Int32 _nAttributes
120                 );
121 
122         /** removes a property from the bag
123             @param _rName
124                 the name of the to-be-removed property.
125             @throws UnknownPropertyException
126                 if the bag does not contain a property with the given name
127             @throws NotRemoveableException
128                 if the property with the given name is not removeable, as indicated
129                 by the property attributes used in a previous <code>addProperty</code>
130                 call.
131         */
132         void    removeProperty(
133                     const ::rtl::OUString& _rName
134                 );
135 
136         /** describes all properties in the bag
137             @param _out_rProps
138                 takes, upon return, the descriptions of all properties in the bag
139         */
describeProperties(::com::sun::star::uno::Sequence<::com::sun::star::beans::Property> & _out_rProps) const140         inline void describeProperties(
141                     ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& _out_rProps
142                 ) const
143         {
144             OPropertyContainerHelper::describeProperties( _out_rProps );
145         }
146 
147         /** retrieves the value of a property given by handle
148             @param _nHandle
149                 the handle of the property whose value is to be retrieved
150             @param _out_rValue
151                 output parameter taking the property value
152             @throws UnknownPropertyException
153                 if the given handle does not denote a property in the bag
154         */
155         void    getFastPropertyValue(
156                     sal_Int32 _nHandle,
157                     ::com::sun::star::uno::Any& _out_rValue
158                 ) const;
159 
160         /** converts a to-be-set value of a property (given by handle) so that it can
161             be used in subsequent calls to setFastPropertyValue
162             @param _nHandle
163                 the handle of the property
164             @param _rNewValue
165                 the new value, which should be converted
166             @param _out_rConvertedValue
167                 output parameter taking the converted value
168             @param _out_rCurrentValue
169                 output parameter taking the current value of the
170                 property
171             @throws UnknownPropertyException
172                 if the given handle does not denote a property in the bag
173             @throws IllegalArgumentException
174                 if the given value cannot be lossless converted into a value
175                 for the given property.
176         */
177 	    bool    convertFastPropertyValue(
178 				        sal_Int32 _nHandle,
179 				        const ::com::sun::star::uno::Any& _rNewValue,
180 				        ::com::sun::star::uno::Any& _out_rConvertedValue,
181 				        ::com::sun::star::uno::Any& _out_rCurrentValue
182                     ) const;
183 
184         /** sets a new value for a property given by handle
185             @throws UnknownPropertyException
186                 if the given handle does not denote a property in the bag
187         */
188         void    setFastPropertyValue(
189                         sal_Int32 _nHandle,
190                         const ::com::sun::star::uno::Any& _rValue
191                     );
192 
193         /** returns the default value for a property given by handle
194 
195             The default value of a property is its initial value, as passed
196             to ->addProperty.
197 
198             @param _nHandle
199                 handle of the property whose default value is to be obtained
200             @param _out_rValue
201                 the default value
202             @throws UnknownPropertyException
203                 if the given handle does not denote a property in the bag
204         */
205         void    getPropertyDefaultByHandle(
206                         sal_Int32 _nHandle,
207                         ::com::sun::star::uno::Any& _out_rValue
208                     ) const;
209 
210         /** determines whether a property with a given name is part of the bag
211         */
hasPropertyByName(const::rtl::OUString & _rName) const212         inline  bool    hasPropertyByName( const ::rtl::OUString& _rName ) const
213         {
214             return isRegisteredProperty( _rName );
215         }
216 
217         /** determines whether a property with a given handle is part of the bag
218         */
hasPropertyByHandle(sal_Int32 _nHandle) const219         inline  bool    hasPropertyByHandle( sal_Int32 _nHandle ) const
220         {
221             return isRegisteredProperty( _nHandle );
222         }
223     protected:
224         using OPropertyContainerHelper::convertFastPropertyValue;
225         using OPropertyContainerHelper::getFastPropertyValue;
226 	};
227 
228 //........................................................................
229 } // namespace comphelper
230 //........................................................................
231 
232 #endif // COMPHELPER_PROPERTYBAG_HXX
233 
234