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