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