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