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