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