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