chart2/source/controller/inc/ItemConverter.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ItemConverter.hxx,v $
  10  * $Revision: 1.10.44.1 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef CHART_ITEMCONVERTER_HXX
  31 #define CHART_ITEMCONVERTER_HXX
  32
  33 #include <unotools/eventlisteneradapter.hxx>
  34 #include <svtools/itempool.hxx>
  35 #include <svtools/itemset.hxx>
  36 #include <com/sun/star/beans/XPropertySet.hpp>
  37
  38 // for pair
  39 #include <utility>
  40
  41 namespace comphelper
  42 {
  43
  44 /** This class serves for conversion between properties of an XPropertySet and
  45     SfxItems in SfxItemSets.
  46
  47     With this helper classes, you can feed dialogs with XPropertySets and let
  48     those modify by the dialogs.
  49
  50     You must implement GetWhichPairs() such that an SfxItemSet created with
  51     CreateEmptyItemSet() is able to hold all items that may be mapped.
  52
  53     You also have to implement GetItemProperty(), in order to return the
  54     property name for a given which-id together with the corresponding member-id
  55     that has to be used for conversion in QueryValue/PutValue.
  56
  57     FillSpecialItem and ApplySpecialItem may be used for special handling of
  58     individual item, e.g. if you need member-ids in QueryValue/PutValue
  59
  60     A typical use could be the following:
  61
  62     ::comphelper::ChartTypeItemConverter aItemConverter( xPropertySet, GetItemPool() );
  63     SfxItemSet aItemSet = aItemConverter.CreateEmptyItemSet();
  64     aItemConverter.FillItemSet( aItemSet );
  65     bool bChanged = false;
  66
  67     MyDialog aDlg( aItemSet );
  68     if( aDlg.Execute() == RET_OK )
  69     {
  70         const SfxItemSet* pOutItemSet = aDlg.GetOutputItemSet();
  71         if( pOutItemSet )
  72             bChanged = aItemConverter.ApplyItemSet( *pOutItemSet );
  73     }
  74
  75     if( bChanged )
  76     {
  77         [ apply model changes to view ]
  78     }
  79  */
  80 class ItemConverter :
  81         public ::utl::OEventListenerAdapter
  82 {
  83 public:
  84     /** Construct an item converter that uses the given property set for
  85         reading/writing converted items
  86      */
  87     ItemConverter(
  88         const ::com::sun::star::uno::Reference<
  89             ::com::sun::star::beans::XPropertySet > & rPropertySet ,
  90             SfxItemPool& rItemPool );
  91     virtual ~ItemConverter();
  92
  93     // typedefs -------------------------------
  94
  95     typedef USHORT          tWhichIdType;
  96     typedef ::rtl::OUString tPropertyNameType;
  97     typedef BYTE            tMemberIdType;
  98
  99     typedef ::std::pair< tPropertyNameType, tMemberIdType > tPropertyNameWithMemberId;
 100
 101     // ----------------------------------------
 102
 103     /** applies all properties that can be mapped to items into the given item
 104         set.
 105
 106         Call this method before opening a dialog.
 107
 108         @param rOutItemSet
 109             the SfxItemSet is filled with all items that are a result of a
 110             conversion from a property of the internal XPropertySet.
 111      */
 112     virtual void FillItemSet( SfxItemSet & rOutItemSet ) const;
 113
 114     /** applies all properties that are results of a conversion from all items
 115         in rItemSet to the internal XPropertySet.
 116
 117         Call this method after a dialog was closed with OK
 118
 119         @return true, if any properties have been changed, false otherwise.
 120      */
 121     virtual bool ApplyItemSet( const SfxItemSet & rItemSet );
 122
 123     /** creates an empty item set using the given pool or a common pool if empty
 124         (see GetItemPool) and allowing all items given in the ranges returned by
 125         GetWhichPairs.
 126      */
 127     SfxItemSet CreateEmptyItemSet() const;
 128
 129     /** Invalidates all items in rDestSet, that are set (state SFX_ITEM_SET) in
 130         both item sets (rDestSet and rSourceSet) and have differing content.
 131      */
 132     static void InvalidateUnequalItems( SfxItemSet &rDestSet, const SfxItemSet &rSourceSet );
 133
 134 protected:
 135     // ________
 136
 137     /** implement this method to provide an array of which-ranges of the form:
 138
 139         const USHORT aMyPairs[] =
 140         {
 141             from_1, to_1,
 142             from_2, to_2,
 143             ...
 144             from_n, to_n,
 145             0
 146         };
 147     */
 148     virtual const USHORT * GetWhichPairs() const = 0;
 149
 150     /** implement this method to return a Property object for a given which id.
 151
 152         @param rOutProperty
 153             If true is returned, this contains the property name and the
 154             corresponding Member-Id.
 155
 156         @return true, if the item can be mapped to a property.
 157      */
 158     virtual bool GetItemProperty( tWhichIdType nWhichId, tPropertyNameWithMemberId & rOutProperty ) const = 0;
 159
 160     /** for items that can not be mapped directly to a property.
 161
 162         This method is called from FillItemSet(), if GetItemProperty() returns
 163         false.
 164
 165         The default implementation does nothing except showing an assertion
 166      */
 167     virtual void FillSpecialItem( USHORT nWhichId, SfxItemSet & rOutItemSet ) const
 168         throw( ::com::sun::star::uno::Exception );
 169
 170     /** for items that can not be mapped directly to a property.
 171
 172         This method is called from ApplyItemSet(), if GetItemProperty() returns
 173         false.
 174
 175         The default implementation returns just false and shows an assertion
 176
 177         @return true if the item changed a property, false otherwise.
 178      */
 179     virtual bool ApplySpecialItem( USHORT nWhichId, const SfxItemSet & rItemSet )
 180         throw( ::com::sun::star::uno::Exception );
 181
 182     // ________
 183
 184     /// Returns the pool
 185     SfxItemPool & GetItemPool() const;
 186
 187     /** Returns the XPropertySet that was given in the CTOR and is used to apply
 188         items in ApplyItemSet().
 189      */
 190     ::com::sun::star::uno::Reference<
 191         ::com::sun::star::beans::XPropertySet >  GetPropertySet() const;
 192
 193     // ____ ::utl::OEventListenerAdapter ____
 194     virtual void _disposing( const ::com::sun::star::lang::EventObject& rSource );
 195
 196 protected:
 197     /** sets a new property set, that you get with GetPropertySet().  It should
 198         not be necessary to use this method.  It is introduced to allow changing
 199         the regression type of a regression curve which changes the object
 200         identity.
 201      */
 202     void resetPropertySet( const ::com::sun::star::uno::Reference<
 203                            ::com::sun::star::beans::XPropertySet > & xPropSet );
 204
 205 private:
 206     ::com::sun::star::uno::Reference<
 207         ::com::sun::star::beans::XPropertySet >     m_xPropertySet;
 208     ::com::sun::star::uno::Reference<
 209         ::com::sun::star::beans::XPropertySetInfo > m_xPropertySetInfo;
 210
 211     SfxItemPool&                                    m_rItemPool;
 212     bool                                            m_bIsValid;
 213 };
 214
 215 } //  namespace comphelper
 216
 217 // CHART_ITEMCONVERTER_HXX
 218 #endif