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 
24 #ifndef EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
25 #define EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
26 
27 /** === begin UNO includes === **/
28 #include <com/sun/star/frame/XModel.hpp>
29 #include <com/sun/star/beans/XPropertySet.hpp>
30 #include <com/sun/star/sheet/XSpreadsheetDocument.hpp>
31 #include <com/sun/star/table/CellAddress.hpp>
32 #include <com/sun/star/table/CellRangeAddress.hpp>
33 #include <com/sun/star/form/binding/XValueBinding.hpp>
34 #include <com/sun/star/form/binding/XListEntrySource.hpp>
35 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
36 #include <com/sun/star/sheet/XSpreadsheet.hpp>
37 /** === end UNO includes === **/
38 
39 //............................................................................
40 namespace pcr
41 {
42 //............................................................................
43 
44     //========================================================================
45     //= CellBindingHelper
46     //========================================================================
47     /** encapsulates functionality related to binding a form control to a spreadsheet cell
48     */
49     class CellBindingHelper
50     {
51     protected:
52         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
53                     m_xControlModel;    // the model we work for
54         ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheetDocument >
55                     m_xDocument;        // the document where the model lives
56 
57     public:
58         /** ctor
59             @param _rxControlModel
60                 the control model which is or will be bound
61         */
62         CellBindingHelper(
63             const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel,
64             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
65         );
66 
67     public:
68         /** determines whether the given model is a spreadsheet document model
69 
70             <p>If this method returns <FALSE/>, you cannot instantiate a CellBindingHelper with
71             the document, since then no of it's functionality will be available.</p>
72         */
73         static  sal_Bool    isSpreadsheetDocument(
74                                 const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
75                             );
76 
77         /** gets a cell binding for the given address
78             @precond
79                 isCellBindingAllowed returns <TRUE/>
80         */
81         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
82                         createCellBindingFromStringAddress(
83                             const ::rtl::OUString& _rAddress,
84                             bool _bSupportIntegerExchange = false
85                         ) const;
86 
87         /** creates a cell binding (supporting integer exchange, if requested) for
88             the given address object
89         */
90         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
91                         createCellBindingFromAddress(
92                             const ::com::sun::star::table::CellAddress& _rAddress,
93                             bool _bSupportIntegerExchange = false
94                         ) const;
95 
96         /** gets a cell range list source binding for the given address
97         */
98         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
99                         createCellListSourceFromStringAddress( const ::rtl::OUString& _rAddress ) const;
100 
101         /** creates a string representation for the given value binding's address
102 
103             <p>If the sheet of the bound cell is the same as the sheet which our control belongs
104             to, then the sheet name is omitted in the resulting string representation.</p>
105 
106             @precond
107                 The binding is a valid cell binding, or <NULL/>
108             @see isCellBinding
109         */
110         ::rtl::OUString getStringAddressFromCellBinding(
111                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
112                         ) const;
113 
114         /** creates an address object for the given value binding's address
115 
116             @precond
117                 The binding is a valid cell binding, or <NULL/>
118             @return
119                 <FALSE/> if and only if an error occurred and no valid address could be obtained
120             @see isCellBinding
121         */
122         bool            getAddressFromCellBinding(
123                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding,
124                             ::com::sun::star::table::CellAddress& _rAddress
125                         ) const;
126 
127         /** creates a string representation for the given list source's range address
128 
129             <p>If the sheet of the cell range which acts as list source is the same as the
130             sheet which our control belongs to, then the sheet name is omitted in the
131             resulting string representation.</p>
132 
133             @precond
134                 The object is a valid cell range list source, or <NULL/>
135             @see isCellRangeListSource
136         */
137         ::rtl::OUString getStringAddressFromCellListSource(
138                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
139                         ) const;
140 
141         /** returns the current binding of our control model, if any.
142         */
143         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
144                         getCurrentBinding( ) const;
145 
146         /** returns the current external list source of the control model, if any
147         */
148         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
149                         getCurrentListSource( ) const;
150 
151         /** sets a new binding for our control model
152             @precond
153                 the control model is bindable (which is implied by <member>isCellBindingAllowed</member>
154                 returning <TRUE/>)
155         */
156         void            setBinding(
157                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
158                         );
159 
160         /** sets a list source for our control model
161             @precond
162                 the control model is a list sink (which is implied by <member>isListCellRangeAllowed</member>
163                 returning <TRUE/>)
164         */
165         void            setListSource(
166                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
167                         );
168 
169         /** checks whether it's possible to bind the control model to a spreadsheet cell
170         */
171         bool            isCellBindingAllowed( ) const;
172 
173         /** checks whether it's possible to bind the control model to a spreadsheet cell,
174             with exchanging integer values
175         */
176         bool            isCellIntegerBindingAllowed( ) const;
177 
178         /** checks whether it's possible to bind the control model to range of spreadsheet cells
179             supplying the list entries
180         */
181         bool            isListCellRangeAllowed( ) const;
182 
183         /** checks whether a given binding is a spreadsheet cell binding
184         */
185         bool            isCellBinding(
186                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
187                         ) const;
188 
189         /** checks whether a given binding is a spreadsheet cell binding, exchanging
190             integer values
191         */
192         bool            isCellIntegerBinding(
193                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
194                         ) const;
195 
196         /** checks whether a given list source is a spreadsheet cell list source
197         */
198         bool            isCellRangeListSource(
199                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
200                         ) const;
201 
202         /** retrieves the index of the sheet which our control belongs to
203             @return the index of the sheet which our control belongs to or -1, if an error occurred
204         */
205         sal_Int16       getControlSheetIndex(
206                             ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheet >& _out_rxSheet
207                         ) const;
208 
209     protected:
210         /** creates an address object from a string representation of a cell address
211         */
212         bool            convertStringAddress(
213                             const ::rtl::OUString& _rAddressDescription,
214                             ::com::sun::star::table::CellAddress& /* [out] */ _rAddress
215                         ) const;
216 
217         /** creates an address range object from a string representation of a cell range address
218         */
219         bool            convertStringAddress(
220                             const ::rtl::OUString& _rAddressDescription,
221                             ::com::sun::star::table::CellRangeAddress& /* [out] */ _rAddress
222                         ) const;
223 
224         /** determines if our document is a spreadsheet document, *and* can supply
225             the given service
226         */
227         bool            isSpreadsheetDocumentWhichSupplies( const ::rtl::OUString& _rService ) const;
228 
229         /** checkes whether a given component supports a given servive
230         */
231         bool            doesComponentSupport(
232                             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
233                             const ::rtl::OUString& _rService
234                         ) const;
235 
236         /** uses the document (it's factory interface, respectively) to create a component instance
237             @param _rService
238                 the service name
239             @param _rArgumentName
240                 the name of the single argument to pass during creation. May be empty, in this case
241                 no arguments are passed
242             @param _rArgumentValue
243                 the value of the instantiation argument. Not evaluated if <arg>_rArgumentName</arg>
244                 is empty.
245         */
246         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
247                         createDocumentDependentInstance(
248                             const ::rtl::OUString& _rService,
249                             const ::rtl::OUString& _rArgumentName,
250                             const ::com::sun::star::uno::Any& _rArgumentValue
251                         ) const;
252 
253         /** converts an address representation into another one
254 
255             @param _rInputProperty
256                 the input property name for the conversion service
257             @param _rInputValue
258                 the input property value for the conversion service
259             @param _rOutputProperty
260                 the output property name for the conversion service
261             @param _rOutputValue
262                 the output property value for the conversion service
263             @param _bIsRange
264                 if <TRUE/>, the RangeAddressConversion service will be used, else
265                 the AddressConversion service
266 
267             @return
268                 <TRUE/> if any only if the conversion was successful
269 
270             @see com::sun::star::table::CellAddressConversion
271             @see com::sun::star::table::CellRangeAddressConversion
272         */
273         bool            doConvertAddressRepresentations(
274                             const ::rtl::OUString& _rInputProperty,
275                             const ::com::sun::star::uno::Any& _rInputValue,
276                             const ::rtl::OUString& _rOutputProperty,
277                                   ::com::sun::star::uno::Any& _rOutputValue,
278                             bool _bIsRange
279                         ) const SAL_THROW(());
280     };
281 
282 //............................................................................
283 }   // namespace pcr
284 //............................................................................
285 
286 #endif // EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
287