LCOV - code coverage report
Current view: top level - include/cppuhelper - propertysetmixin.hxx (source / functions) Hit Total Coverage
Test: commit 10e77ab3ff6f4314137acd6e2702a6e5c1ce1fae Lines: 4 4 100.0 %
Date: 2014-11-03 Functions: 18 28 64.3 %
Legend: Lines: hit not hit

          Line data    Source code
       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&); // not defined
     162             :         void operator=( const BoundListeners&); // not defined
     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&); // not defined
     386             :     void operator=( const PropertySetMixinImpl&); // not defined
     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       17514 :     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       17514 :             context, implements, absentOptional, T::static_type())
     467       17514 :     {}
     468             : 
     469             :     /**
     470             :        @short The destructor.
     471             : 
     472             :        Does not throw.
     473             :     */
     474       17511 :     ~PropertySetMixin() {}
     475             : 
     476             : private:
     477             :     PropertySetMixin( const PropertySetMixin&); // not defined
     478             :     void operator=( const PropertySetMixin&); // not defined
     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: */

Generated by: LCOV version 1.10