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)
 266         throw (css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 267
 268     // @see css::beans::XPropertySet::getPropertySetInfo
 269     virtual css::uno::Reference< css::beans::XPropertySetInfo > SAL_CALL getPropertySetInfo()
 270         throw (css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 271
 272     // @see css::beans::XPropertySet::setPropertyValue
 273     virtual void SAL_CALL setPropertyValue(
 274         rtl::OUString const & propertyName,
 275         css::uno::Any const & value)
 276         throw (
 277             css::beans::UnknownPropertyException,
 278             css::beans::PropertyVetoException,
 279             css::lang::IllegalArgumentException,
 280             css::lang::WrappedTargetException,
 281             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 282
 283     // @see css::beans::XPropertySet::getPropertyValue
 284     virtual css::uno::Any SAL_CALL getPropertyValue(
 285         rtl::OUString const & propertyName)
 286         throw (
 287             css::beans::UnknownPropertyException,
 288             css::lang::WrappedTargetException,
 289             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 290
 291     /**
 292        @short Adds a
 293        <code>css::beans::XPropertyChangeListener</code>.
 294
 295        If a listener is added more than once, it will receive all
 296        relevant notifications multiple times.
 297
 298        @see css::beans::XPropertySet::addPropertyChangeListener
 299     */
 300     virtual void SAL_CALL addPropertyChangeListener(
 301         rtl::OUString const & propertyName,
 302         css::uno::Reference<
 303         css::beans::XPropertyChangeListener > const & listener)
 304         throw (
 305             css::beans::UnknownPropertyException,
 306             css::lang::WrappedTargetException,
 307             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 308
 309     // @see css::beans::XPropertySet::removePropertyChangeListener
 310     virtual void SAL_CALL removePropertyChangeListener(
 311         rtl::OUString const & propertyName,
 312         css::uno::Reference<
 313         css::beans::XPropertyChangeListener > const & listener)
 314         throw (
 315             css::beans::UnknownPropertyException,
 316             css::lang::WrappedTargetException,
 317             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 318
 319     /**
 320        @short Adds a
 321        <code>css::beans::XVetoableChangeListener</code>.
 322
 323        If a listener is added more than once, it will receive all
 324        relevant notifications multiple times.
 325
 326        @see css::beans::XPropertySet::addVetoableChangeListener
 327     */
 328     virtual void SAL_CALL addVetoableChangeListener(
 329         rtl::OUString const & propertyName,
 330         css::uno::Reference<
 331         css::beans::XVetoableChangeListener > const & listener)
 332         throw (
 333             css::beans::UnknownPropertyException,
 334             css::lang::WrappedTargetException,
 335             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 336
 337     // @see css::beans::XPropertySet::removeVetoableChangeListener
 338     virtual void SAL_CALL removeVetoableChangeListener(
 339         rtl::OUString const & propertyName,
 340         css::uno::Reference<
 341         css::beans::XVetoableChangeListener > const & listener)
 342         throw (
 343             css::beans::UnknownPropertyException,
 344             css::lang::WrappedTargetException,
 345             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 346
 347     // @see css::beans::XFastPropertySet::setFastPropertyValue
 348     virtual void SAL_CALL setFastPropertyValue(
 349         sal_Int32 handle, css::uno::Any const & value)
 350         throw (
 351             css::beans::UnknownPropertyException,
 352             css::beans::PropertyVetoException,
 353             css::lang::IllegalArgumentException,
 354             css::lang::WrappedTargetException,
 355             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 356
 357     // @see css::beans::XFastPropertySet::getFastPropertyValue
 358     virtual css::uno::Any SAL_CALL getFastPropertyValue(
 359         sal_Int32 handle)
 360         throw (
 361             css::beans::UnknownPropertyException,
 362             css::lang::WrappedTargetException,
 363             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 364
 365     // @see css::beans::XPropertyAccess::getPropertyValues
 366     virtual css::uno::Sequence< css::beans::PropertyValue > SAL_CALL getPropertyValues()
 367         throw (css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 368
 369     // @see css::beans::XPropertyAccess::setPropertyValues
 370     virtual void SAL_CALL setPropertyValues(
 371         css::uno::Sequence< css::beans::PropertyValue > const & props)
 372         throw (
 373             css::beans::UnknownPropertyException,
 374             css::beans::PropertyVetoException,
 375             css::lang::IllegalArgumentException,
 376             css::lang::WrappedTargetException,
 377             css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 378
 379 private:
 380     PropertySetMixinImpl( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
 381     void operator=( const PropertySetMixinImpl&) SAL_DELETED_FUNCTION;
 382
 383     PropertySetMixinImpl(
 384         css::uno::Reference< css::uno::XComponentContext > const & context,
 385         Implements implements,
 386         css::uno::Sequence< rtl::OUString > const & absentOptional,
 387         css::uno::Type const & type);
 388
 389     class Impl;
 390     Impl * m_impl;
 391
 392     friend class Impl;
 393     template< typename T > friend class PropertySetMixin;
 394
 395     ~PropertySetMixinImpl();
 396
 397     void checkUnknown(rtl::OUString const & propertyName);
 398 };
 399
 400 /**
 401    @short A helper mixin to implement certain UNO interfaces related to property
 402    set handling on top of the attributes of a given UNO interface type.
 403
 404    The UNO interface type is specified by the type parameter
 405    <code>T</code> (which must correspond to a UNO interface type).
 406
 407    No specializations of this class template should be added by client
 408    code.
 409
 410    @since UDK 3.2.1
 411 */
 412 template< typename T > class PropertySetMixin: public PropertySetMixinImpl {
 413 protected:
 414     /**
 415        @short The constructor.
 416
 417        May throw <code>css::uno::RuntimeException</code> and
 418        <code>std::bad_alloc</code>.
 419
 420        @param context  the component context used by this class template; must
 421        not be null, and must supply the
 422        <code>com.sun.star.reflection.theCoreReflection</code> and
 423        <code>com.sun.star.reflection.theTypeDescriptionManager</code> singletons
 424
 425        @param implements  a combination of zero or more flags specifying what
 426        UNO interface types shall be supported
 427
 428        @param absentOptional  a list of optional properties that are not
 429        present, and should thus not be visible via
 430        <code>css::beans::XPropertySet::getPropertySetInfo</code>,
 431        <code>css::beans::XPropertySet::addPropertyChangeListener<!--
 432        --></code>, <code>css::beans::XPropertySet::<!--
 433        -->removePropertyChangeListener</code>,
 434        <code>css::beans::XPropertySet::addVetoableChangeListener<!--
 435        --></code>, and <code>css::beans::XPropertySet::<!--
 436        -->removeVetoableChangeListener</code>.  For consistency reasons, the
 437        given <code>absentOptional</code> should only contain the names of
 438        attributes that represent optional properties that are not present (that
 439        is, the attribute getters and setters always throw a
 440        <code>css::beans::UnknownPropertyException</code>), and should
 441        contain each such name only once.  If an optional property is not present
 442        (that is, the corresponding attribute getter and setter always throw a
 443        <code>css::beans::UnknownPropertyException</code>) but is not
 444        contained in the given <code>absentOptional</code>, then it will be
 445        visible via
 446        <code>css::beans::XPropertySet::getPropertySetInfo</code> as a
 447        <code>css::beans::Property</code> with a set
 448        <code>css::beans::PropertyAttribute::OPTIONAL</code>.  If the
 449        given <code>implements</code> specifies that
 450        <code>css::beans::XPropertySet</code> is not supported, then
 451        the given <code>absentOptional</code> is effectively ignored and can be
 452        empty.
 453     */
 454     PropertySetMixin(
 455         css::uno::Reference< css::uno::XComponentContext > const & context,
 456         Implements implements,
 457         css::uno::Sequence< rtl::OUString > const & absentOptional):
 458         PropertySetMixinImpl(
 459             context, implements, absentOptional, T::static_type())
 460     {}
 461
 462     /**
 463        @short The destructor.
 464
 465        Does not throw.
 466     */
 467     ~PropertySetMixin() {}
 468
 469 private:
 470     PropertySetMixin( const PropertySetMixin&) SAL_DELETED_FUNCTION;
 471     void operator=( const PropertySetMixin&) SAL_DELETED_FUNCTION;
 472 };
 473 #if defined __GNUC__ && !defined __clang__
 474 #pragma GCC diagnostic pop
 475 #endif
 476
 477 #if defined _MSC_VER
 478 #pragma warning(pop)
 479 #endif
 480
 481 }
 482
 483 #endif
 484
 485 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */