include/cppuhelper/propertysetmixin.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_CPPUHELPER_PROPERTYSETMIXIN_HXX
  21 #define INCLUDED_CPPUHELPER_PROPERTYSETMIXIN_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <exception>
  26
  27 #include <com/sun/star/beans/PropertyVetoException.hpp>
  28 #include <com/sun/star/beans/UnknownPropertyException.hpp>
  29 #include <com/sun/star/beans/XFastPropertySet.hpp>
  30 #include <com/sun/star/beans/XPropertyAccess.hpp>
  31 #include <com/sun/star/beans/XPropertySet.hpp>
  32 #include <com/sun/star/lang/IllegalArgumentException.hpp>
  33 #include <com/sun/star/lang/WrappedTargetException.hpp>
  34 #include <com/sun/star/uno/Reference.hxx>
  35 #include <com/sun/star/uno/RuntimeException.hpp>
  36 #include <com/sun/star/uno/Sequence.hxx>
  37 #include <sal/types.h>
  38 #include <cppuhelper/cppuhelperdllapi.h>
  39
  40 namespace com { namespace sun { namespace star {
  41     namespace beans {
  42         class XPropertyChangeListener;
  43         class XPropertySetInfo;
  44         class XVetoableChangeListener;
  45         struct PropertyValue;
  46     }
  47     namespace uno {
  48         class Any;
  49         class Type;
  50         class XComponentContext;
  51     }
  52 } } }
  53 namespace rtl { class OUString; }
  54
  55 namespace cppu {
  56
  57 template< typename T > class PropertySetMixin;
  58
  59 // Suppress warnings about virtual functions but non-virtual destructor:
  60 #if defined _MSC_VER
  61 #pragma warning(push)
  62 #pragma warning(disable: 4265)
  63 #endif
  64
  65 /**
  66    @short A helper base class for <code>cppu::PropertySetMixin</code>.
  67
  68    See the documentation of <code>cppu::PropertySetMixin</code> for
  69    further details.
  70
  71    That <code>cppu::PropertySetMixin</code> is derived from this
  72    base class should be considered an implementation detail.  The functionality
  73    of <code>cppu::PropertySetMixin</code> that is inherited from this base
  74    class and is visible to subclasses of
  75    <code>cppu::PropertySetMixin</code> should be treated by such
  76    subclasses as being provided by <code>cppu::PropertySetMixin</code>
  77    directly (e.g., in such subclasses, use
  78    &ldquo;<code>PropertySetMixin::Implements</code>&rdquo; instead of
  79    &ldquo;<code>PropertySetMixinImpl::Implements</code>&rdquo;).
  80
  81    @since UDK 3.2.1
  82 */
  83 #if defined __GNUC__ && !defined __clang__
  84 #pragma GCC diagnostic push
  85 #pragma GCC diagnostic ignored "-Wnon-virtual-dtor"
  86 #endif
  87 class CPPUHELPER_DLLPUBLIC PropertySetMixinImpl:
  88     public css::beans::XPropertySet,
  89     public css::beans::XFastPropertySet,
  90     public css::beans::XPropertyAccess
  91 {
  92 protected:
  93     /**
  94        @short Flags used by subclasses of
  95        <code>cppu::PropertySetMixin</code> to specify what UNO interface
  96        types shall be supported.
  97     */
  98     enum Implements {
  99         /**
 100            @short Flag specifying that the UNO interface type
 101            <code>css::beans::XPropertySet</code> shall be supported.
 102         */
 103         IMPLEMENTS_PROPERTY_SET = 1,
 104
 105         /**
 106            @short Flag specifying that the UNO interface type
 107            <code>css::beans::XFastPropertySet</code> shall be
 108            supported.
 109         */
 110         IMPLEMENTS_FAST_PROPERTY_SET = 2,
 111
 112         /**
 113            @short Flag specifying that the UNO interface type
 114            <code>css::beans::XPropertyAccess</code> shall be
 115            supported.
 116         */
 117         IMPLEMENTS_PROPERTY_ACCESS = 4
 118     };
 119
 120     /**
 121        @short A class used by subclasses of
 122        <code>cppu::PropertySetMixin</code> when implementing UNO interface
 123        type attribute setter functions.
 124
 125        This class is not thread safe; that is, the constructor,
 126        <code>notify</code>, and the destructor must be called from the same
 127        thread.
 128
 129        See <code>cppu::PropertySetMixinImpl::prepareSet</code> for
 130        further details.
 131     */
 132     class CPPUHELPER_DLLPUBLIC BoundListeners {
 133     public:
 134         /**
 135            @short The constructor.
 136
 137            May throw <code>std::bad_alloc</code>.
 138         */
 139         BoundListeners();
 140
 141         /**
 142            @short The destructor.
 143
 144            Does not throw.
 145         */
 146         ~BoundListeners();
 147
 148         /**
 149            @short Notifies any
 150            <code>css::beans::XPropertyChangeListener</code>s.
 151
 152            May throw <code>css::uno::RuntimeException</code>
 153            and <code>std::bad_alloc</code>.
 154
 155            See <code>cppu::PropertySetMixinImpl::prepareSet</code>
 156            for further details.
 157          */
 158         void notify() const;
 159
 160     private:
 161         BoundListeners( const BoundListeners&) SAL_DELETED_FUNCTION;
 162         void operator=( const BoundListeners&) SAL_DELETED_FUNCTION;
 163
 164         class Impl;
 165         Impl * m_impl;
 166
 167         friend class PropertySetMixinImpl;
 168     };
 169
 170     /**
 171        @short A function used by subclasses of
 172        <code>cppu::PropertySetMixin</code> when implementing UNO interface
 173        type attribute setter functions.
 174
 175        First, this function checks whether this instance has already been
 176        disposed (see <code>cppu::PropertySetMixinImpl::dispose</code>),
 177        and throws a <code>css::lang::DisposedException</code> if
 178        applicable.  For a constrained attribute (whose setter can explicitly
 179        raise <code>css::beans::PropertyVetoException</code>), this
 180        function notifies any
 181        <code>css::beans::XVetoableChangeListener</code>s.  For a
 182        bound attribute, this function modifies the passed-in
 183        <code>boundListeners</code> so that it can afterwards be used to notify
 184        any <code>css::beans::XPropertyChangeListener</code>s.  This
 185        function should be called before storing the new attribute value, and
 186        <code>boundListeners->notify()</code> should be called exactly once after
 187        storing the new attribute value (in case the attribute is bound;
 188        otherwise, calling <code>boundListeners->notify()</code> is ignored).
 189        Furthermore, <code>boundListeners->notify()</code> and this function have
 190        to be called from the same thread.
 191
 192        May throw
 193        <code>css::beans::PropertyVetoException</code>,
 194        <code>css::uno::RuntimeException</code> (and
 195        <code>css::lang::DisposedException</code> in particular), and
 196        <code>std::bad_alloc</code>.
 197
 198        @param propertyName  the name of the property (which is the same as the
 199        name of the attribute that is going to be set)
 200
 201        @param oldValue the property value corresponding to the old attribute
 202        value.  This is only used as
 203        <code>css::beans::PropertyChangeEvent::OldValue</code>, which
 204        is rather useless, anyway (see &ldquo;Using the Observer Pattern&rdquo;
 205        in <a href="http://tools.openoffice.org/CodingGuidelines.sxw">
 206        OpenOffice.org Coding Guidelines</a>).  If the attribute
 207        that is going to be set is neither bound nor constrained, or if
 208        <code>css::beans::PropertyChangeEvent::OldValue</code> should
 209        not be set, a <code>VOID</code> <code>Any</code> can be used instead.
 210
 211        @param newValue the property value corresponding to the new
 212        attribute value.  This is only used as
 213        <code>css::beans::PropertyChangeEvent::NewValue</code>, which
 214        is rather useless, anyway (see &ldquo;Using the Observer Pattern&rdquo;
 215        in <a href="http://tools.openoffice.org/CodingGuidelines.sxw">
 216        OpenOffice.org Coding Guidelines</a>), <em>unless</em> the
 217        attribute that is going to be set is constrained.  If the attribute
 218        that is going to be set is neither bound nor constrained, or if it is
 219        only bound but
 220        <code>css::beans::PropertyChangeEvent::NewValue</code> should
 221        not be set, a <code>VOID</code> <code>Any</code> can be used instead.
 222
 223        @param boundListeners  a pointer to a fresh
 224        <code>cppu::PropertySetMixinImpl::BoundListeners</code> instance
 225        (which has not been passed to this function before, and on which
 226        <code>notify</code> has not yet been called); may only be null if the
 227        attribute that is going to be set is not bound
 228     */
 229     void prepareSet(
 230         rtl::OUString const & propertyName,
 231         css::uno::Any const & oldValue,
 232         css::uno::Any const & newValue,
 233         BoundListeners * boundListeners);
 234
 235     /**
 236        @short Mark this instance as being disposed.
 237
 238        See <code>css::lang::XComponent</code> for the general
 239        concept of disposing UNO objects.  On the first call to this function,
 240        all registered listeners
 241        (<code>css::beans::XPropertyChangeListener</code>s and
 242        <code>css::beans::XVetoableChangeListener</code>s) are
 243        notified of the disposing source.  Any subsequent calls to this function
 244        are ignored.
 245
 246        May throw <code>css::uno::RuntimeException</code> and
 247        <code>std::bad_alloc</code>.
 248      */
 249     void dispose();
 250
 251     /**
 252        @short A function used by subclasses of
 253        <code>cppu::PropertySetMixin</code> when implementing
 254        <code>css::uno::XInterface::queryInterface</code>.
 255
 256        This function checks for support of any of the UNO interface types
 257        specified in the call of the <code>cppu::PropertySetMixin</code>
 258        constructor.  It does not check for any other UNO interface types (not
 259        even for <code>css::uno::XInterface</code>), and should not
 260        be used directly as the implementation of
 261        <code>css::uno::XInterface::queryInterface</code> of this UNO
 262        object.
 263     */
 264     virtual css::uno::Any SAL_CALL queryInterface(
 265         css::uno::Type const & type) SAL_OVERRIDE;
 266
 267     // @see css::beans::XPropertySet::getPropertySetInfo
 268     virtual css::uno::Reference< css::beans::XPropertySetInfo > SAL_CALL getPropertySetInfo() SAL_OVERRIDE;
 269
 270     // @see css::beans::XPropertySet::setPropertyValue
 271     virtual void SAL_CALL setPropertyValue(
 272         rtl::OUString const & propertyName,
 273         css::uno::Any const & value) SAL_OVERRIDE;
 274
 275     // @see css::beans::XPropertySet::getPropertyValue
 276     virtual css::uno::Any SAL_CALL getPropertyValue(
 277         rtl::OUString const & propertyName) SAL_OVERRIDE;
 278
 279     /**
 280        @short Adds a
 281        <code>css::beans::XPropertyChangeListener</code>.
 282
 283        If a listener is added more than once, it will receive all
 284        relevant notifications multiple times.
 285
 286        @see css::beans::XPropertySet::addPropertyChangeListener
 287     */
 288     virtual void SAL_CALL addPropertyChangeListener(
 289         rtl::OUString const & propertyName,
 290         css::uno::Reference<
 291         css::beans::XPropertyChangeListener > const & listener) SAL_OVERRIDE;
 292
 293     // @see css::beans::XPropertySet::removePropertyChangeListener
 294     virtual void SAL_CALL removePropertyChangeListener(
 295         rtl::OUString const & propertyName,
 296         css::uno::Reference<
 297         css::beans::XPropertyChangeListener > const & listener) SAL_OVERRIDE;
 298
 299     /**
 300        @short Adds a
 301        <code>css::beans::XVetoableChangeListener</code>.
 302
 303        If a listener is added more than once, it will receive all
 304        relevant notifications multiple times.
 305
 306        @see css::beans::XPropertySet::addVetoableChangeListener
 307     */
 308     virtual void SAL_CALL addVetoableChangeListener(
 309         rtl::OUString const & propertyName,
 310         css::uno::Reference<
 311         css::beans::XVetoableChangeListener > const & listener) SAL_OVERRIDE;
 312
 313     // @see css::beans::XPropertySet::removeVetoableChangeListener
 314     virtual void SAL_CALL removeVetoableChangeListener(
 315         rtl::OUString const & propertyName,
 316         css::uno::Reference<
 317         css::beans::XVetoableChangeListener > const & listener) SAL_OVERRIDE;
 318
 319     // @see css::beans::XFastPropertySet::setFastPropertyValue
 320     virtual void SAL_CALL setFastPropertyValue(
 321         sal_Int32 handle, css::uno::Any const & value) SAL_OVERRIDE;
 322
 323     // @see css::beans::XFastPropertySet::getFastPropertyValue
 324     virtual css::uno::Any SAL_CALL getFastPropertyValue(
 325         sal_Int32 handle) SAL_OVERRIDE;
 326
 327     // @see css::beans::XPropertyAccess::getPropertyValues
 328     virtual css::uno::Sequence< css::beans::PropertyValue > SAL_CALL getPropertyValues() SAL_OVERRIDE;
 329
 330     // @see css::beans::XPropertyAccess::setPropertyValues
 331     virtual void SAL_CALL setPropertyValues(
 332         css::uno::Sequence< css::beans::PropertyValue > const & props) SAL_OVERRIDE;
 333
 334 private:
 335     PropertySetMixinImpl( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
 336     void operator=( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
 337
 338     PropertySetMixinImpl(
 339         css::uno::Reference< css::uno::XComponentContext > const & context,
 340         Implements implements,
 341         css::uno::Sequence< rtl::OUString > const & absentOptional,
 342         css::uno::Type const & type);
 343
 344     class Impl;
 345     Impl * m_impl;
 346
 347     friend class Impl;
 348     template< typename T > friend class PropertySetMixin;
 349
 350     ~PropertySetMixinImpl();
 351
 352     void checkUnknown(rtl::OUString const & propertyName);
 353 };
 354
 355 /**
 356    @short A helper mixin to implement certain UNO interfaces related to property
 357    set handling on top of the attributes of a given UNO interface type.
 358
 359    The UNO interface type is specified by the type parameter
 360    <code>T</code> (which must correspond to a UNO interface type).
 361
 362    No specializations of this class template should be added by client
 363    code.
 364
 365    @since UDK 3.2.1
 366 */
 367 template< typename T > class PropertySetMixin: public PropertySetMixinImpl {
 368 protected:
 369     /**
 370        @short The constructor.
 371
 372        May throw <code>css::uno::RuntimeException</code> and
 373        <code>std::bad_alloc</code>.
 374
 375        @param context  the component context used by this class template; must
 376        not be null, and must supply the
 377        <code>com.sun.star.reflection.theCoreReflection</code> and
 378        <code>com.sun.star.reflection.theTypeDescriptionManager</code> singletons
 379
 380        @param implements  a combination of zero or more flags specifying what
 381        UNO interface types shall be supported
 382
 383        @param absentOptional  a list of optional properties that are not
 384        present, and should thus not be visible via
 385        <code>css::beans::XPropertySet::getPropertySetInfo</code>,
 386        <code>css::beans::XPropertySet::addPropertyChangeListener<!--
 387        --></code>, <code>css::beans::XPropertySet::<!--
 388        -->removePropertyChangeListener</code>,
 389        <code>css::beans::XPropertySet::addVetoableChangeListener<!--
 390        --></code>, and <code>css::beans::XPropertySet::<!--
 391        -->removeVetoableChangeListener</code>.  For consistency reasons, the
 392        given <code>absentOptional</code> should only contain the names of
 393        attributes that represent optional properties that are not present (that
 394        is, the attribute getters and setters always throw a
 395        <code>css::beans::UnknownPropertyException</code>), and should
 396        contain each such name only once.  If an optional property is not present
 397        (that is, the corresponding attribute getter and setter always throw a
 398        <code>css::beans::UnknownPropertyException</code>) but is not
 399        contained in the given <code>absentOptional</code>, then it will be
 400        visible via
 401        <code>css::beans::XPropertySet::getPropertySetInfo</code> as a
 402        <code>css::beans::Property</code> with a set
 403        <code>css::beans::PropertyAttribute::OPTIONAL</code>.  If the
 404        given <code>implements</code> specifies that
 405        <code>css::beans::XPropertySet</code> is not supported, then
 406        the given <code>absentOptional</code> is effectively ignored and can be
 407        empty.
 408     */
 409     PropertySetMixin(
 410         css::uno::Reference< css::uno::XComponentContext > const & context,
 411         Implements implements,
 412         css::uno::Sequence< rtl::OUString > const & absentOptional):
 413         PropertySetMixinImpl(
 414             context, implements, absentOptional, T::static_type())
 415     {}
 416
 417     /**
 418        @short The destructor.
 419
 420        Does not throw.
 421     */
 422     ~PropertySetMixin() {}
 423
 424 private:
 425     PropertySetMixin( const PropertySetMixin&) SAL_DELETED_FUNCTION;
 426     void operator=( const PropertySetMixin&) SAL_DELETED_FUNCTION;
 427 };
 428 #if defined __GNUC__ && !defined __clang__
 429 #pragma GCC diagnostic pop
 430 #endif
 431
 432 #if defined _MSC_VER
 433 #pragma warning(pop)
 434 #endif
 435
 436 }
 437
 438 #endif
 439
 440 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */