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