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