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