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