Branch data 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 COMPHELPER_PROPERTYBAG_HXX
21 : : #define 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 ::rtl::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 ::rtl::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 removeable, as indicated
122 : : by the property attributes used in a previous <code>addProperty</code>
123 : : call.
124 : : */
125 : : void removeProperty(
126 : : const ::rtl::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 : 2747 : inline void describeProperties(
134 : : ::com::sun::star::uno::Sequence< ::com::sun::star::beans::Property >& _out_rProps
135 : : ) const
136 : : {
137 : 2747 : OPropertyContainerHelper::describeProperties( _out_rProps );
138 : 2747 : }
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 : 11781 : inline bool hasPropertyByName( const ::rtl::OUString& _rName ) const
206 : : {
207 : 11781 : return isRegisteredProperty( _rName );
208 : : }
209 : :
210 : : /** determines whether a property with a given handle is part of the bag
211 : : */
212 : 444098 : inline bool hasPropertyByHandle( sal_Int32 _nHandle ) const
213 : : {
214 : 444098 : return isRegisteredProperty( _nHandle );
215 : : }
216 : : protected:
217 : : using OPropertyContainerHelper::convertFastPropertyValue;
218 : : using OPropertyContainerHelper::getFastPropertyValue;
219 : : };
220 : :
221 : : //........................................................................
222 : : } // namespace comphelper
223 : : //........................................................................
224 : :
225 : : #endif // COMPHELPER_PROPERTYBAG_HXX
226 : :
227 : : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
