include/comphelper/propertybag.hxx

   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::unique_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);
  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 css::beans::IllegalTypeException
  74                 if the initial value is <NULL/>
  75             @throws css::beans::PropertyExistException
  76                 if the name or the handle are already used
  77             @throws css::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 css::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 css::beans::IllegalTypeException
 102                 if the initial value is <NULL/>
 103             @throws css::beans::PropertyExistException
 104                 if the name or the handle are already used
 105             @throws css::beans::IllegalArgumentException
 106                 if the name is empty
 107         */
 108         void    addVoidProperty(
 109                     const OUString& _rName,
 110                     const css::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         void describeProperties(
 134                     css::uno::Sequence< css::beans::Property >& _out_rProps
 135                 ) const
 136         {
 137             OPropertyContainerHelper::describeProperties( _out_rProps );
 138         }
 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                     css::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 css::uno::Any& _rNewValue,
 173                         css::uno::Any& _out_rConvertedValue,
 174                         css::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 css::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                         css::uno::Any& _out_rValue
 201                     ) const;
 202
 203         /** determines whether a property with a given name is part of the bag
 204         */
 205         bool    hasPropertyByName( const OUString& _rName ) const
 206         {
 207             return isRegisteredProperty( _rName );
 208         }
 209
 210         /** determines whether a property with a given handle is part of the bag
 211         */
 212         bool    hasPropertyByHandle( sal_Int32 _nHandle ) const
 213         {
 214             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: */