merged tag ooo/OOO330_m14
[LibreOffice.git] / extensions / source / propctrlr / cellbindinghelper.hxx
blob30bc94c106f0c715fff7e55fe1c081bd9ede289b
1 /*************************************************************************
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
7 * OpenOffice.org - a multi-platform office productivity suite
9 * This file is part of OpenOffice.org.
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.
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).
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.
26 ************************************************************************/
28 #ifndef EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
29 #define EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
31 /** === begin UNO includes === **/
32 #include <com/sun/star/frame/XModel.hpp>
33 #include <com/sun/star/beans/XPropertySet.hpp>
34 #include <com/sun/star/sheet/XSpreadsheetDocument.hpp>
35 #include <com/sun/star/table/CellAddress.hpp>
36 #include <com/sun/star/table/CellRangeAddress.hpp>
37 #include <com/sun/star/form/binding/XValueBinding.hpp>
38 #include <com/sun/star/form/binding/XListEntrySource.hpp>
39 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
40 #include <com/sun/star/sheet/XSpreadsheet.hpp>
41 /** === end UNO includes === **/
43 //............................................................................
44 namespace pcr
46 //............................................................................
48 //========================================================================
49 //= CellBindingHelper
50 //========================================================================
51 /** encapsulates functionality related to binding a form control to a spreadsheet cell
53 class CellBindingHelper
55 protected:
56 ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
57 m_xControlModel; // the model we work for
58 ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheetDocument >
59 m_xDocument; // the document where the model lives
61 public:
62 /** ctor
63 @param _rxControlModel
64 the control model which is or will be bound
66 CellBindingHelper(
67 const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel,
68 const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
71 public:
72 /** determines whether the given model is a spreadsheet document model
74 <p>If this method returns <FALSE/>, you cannot instantiate a CellBindingHelper with
75 the document, since then no of it's functionality will be available.</p>
77 static sal_Bool isSpreadsheetDocument(
78 const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
81 /** gets a cell binding for the given address
82 @precond
83 isCellBindingAllowed returns <TRUE/>
85 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
86 createCellBindingFromStringAddress(
87 const ::rtl::OUString& _rAddress,
88 bool _bSupportIntegerExchange = false
89 ) const;
91 /** creates a cell binding (supporting integer exchange, if requested) for
92 the given address object
94 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
95 createCellBindingFromAddress(
96 const ::com::sun::star::table::CellAddress& _rAddress,
97 bool _bSupportIntegerExchange = false
98 ) const;
100 /** gets a cell range list source binding for the given address
102 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
103 createCellListSourceFromStringAddress( const ::rtl::OUString& _rAddress ) const;
105 /** creates a string representation for the given value binding's address
107 <p>If the sheet of the bound cell is the same as the sheet which our control belongs
108 to, then the sheet name is omitted in the resulting string representation.</p>
110 @precond
111 The binding is a valid cell binding, or <NULL/>
112 @see isCellBinding
114 ::rtl::OUString getStringAddressFromCellBinding(
115 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
116 ) const;
118 /** creates an address object for the given value binding's address
120 @precond
121 The binding is a valid cell binding, or <NULL/>
122 @return
123 <FALSE/> if and only if an error occured and no valid address could be obtained
124 @see isCellBinding
126 bool getAddressFromCellBinding(
127 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding,
128 ::com::sun::star::table::CellAddress& _rAddress
129 ) const;
131 /** creates a string representation for the given list source's range address
133 <p>If the sheet of the cell range which acts as list source is the same as the
134 sheet which our control belongs to, then the sheet name is omitted in the
135 resulting string representation.</p>
137 @precond
138 The object is a valid cell range list source, or <NULL/>
139 @see isCellRangeListSource
141 ::rtl::OUString getStringAddressFromCellListSource(
142 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
143 ) const;
145 /** returns the current binding of our control model, if any.
147 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
148 getCurrentBinding( ) const;
150 /** returns the current external list source of the control model, if any
152 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
153 getCurrentListSource( ) const;
155 /** sets a new binding for our control model
156 @precond
157 the control model is bindable (which is implied by <member>isCellBindingAllowed</member>
158 returning <TRUE/>)
160 void setBinding(
161 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
164 /** sets a list source for our control model
165 @precond
166 the control model is a list sink (which is implied by <member>isListCellRangeAllowed</member>
167 returning <TRUE/>)
169 void setListSource(
170 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
173 /** checks whether it's possible to bind the control model to a spreadsheet cell
175 bool isCellBindingAllowed( ) const;
177 /** checks whether it's possible to bind the control model to a spreadsheet cell,
178 with exchanging integer values
180 bool isCellIntegerBindingAllowed( ) const;
182 /** checks whether it's possible to bind the control model to range of spreadsheet cells
183 supplying the list entries
185 bool isListCellRangeAllowed( ) const;
187 /** checks whether a given binding is a spreadsheet cell binding
189 bool isCellBinding(
190 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
191 ) const;
193 /** checks whether a given binding is a spreadsheet cell binding, exchanging
194 integer values
196 bool isCellIntegerBinding(
197 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
198 ) const;
200 /** checks whether a given list source is a spreadsheet cell list source
202 bool isCellRangeListSource(
203 const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
204 ) const;
206 /** retrieves the index of the sheet which our control belongs to
207 @return the index of the sheet which our control belongs to or -1, if an error occured
209 sal_Int16 getControlSheetIndex(
210 ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheet >& _out_rxSheet
211 ) const;
213 protected:
214 /** creates an address object from a string representation of a cell address
216 bool convertStringAddress(
217 const ::rtl::OUString& _rAddressDescription,
218 ::com::sun::star::table::CellAddress& /* [out] */ _rAddress
219 ) const;
221 /** creates an address range object from a string representation of a cell range address
223 bool convertStringAddress(
224 const ::rtl::OUString& _rAddressDescription,
225 ::com::sun::star::table::CellRangeAddress& /* [out] */ _rAddress
226 ) const;
228 /** determines if our document is a spreadsheet document, *and* can supply
229 the given service
231 bool isSpreadsheetDocumentWhichSupplies( const ::rtl::OUString& _rService ) const;
233 /** checkes whether a given component supports a given servive
235 bool doesComponentSupport(
236 const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
237 const ::rtl::OUString& _rService
238 ) const;
240 /** uses the document (it's factory interface, respectively) to create a component instance
241 @param _rService
242 the service name
243 @param _rArgumentName
244 the name of the single argument to pass during creation. May be empty, in this case
245 no arguments are passed
246 @param _rArgumentValue
247 the value of the instantiation argument. Not evaluated if <arg>_rArgumentName</arg>
248 is empty.
250 ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
251 createDocumentDependentInstance(
252 const ::rtl::OUString& _rService,
253 const ::rtl::OUString& _rArgumentName,
254 const ::com::sun::star::uno::Any& _rArgumentValue
255 ) const;
257 /** converts an address representation into another one
259 @param _rInputProperty
260 the input property name for the conversion service
261 @param _rInputValue
262 the input property value for the conversion service
263 @param _rOutputProperty
264 the output property name for the conversion service
265 @param _rOutputValue
266 the output property value for the conversion service
267 @param _bIsRange
268 if <TRUE/>, the RangeAddressConversion service will be used, else
269 the AddressConversion service
271 @return
272 <TRUE/> if any only if the conversion was successfull
274 @see com::sun::star::table::CellAddressConversion
275 @see com::sun::star::table::CellRangeAddressConversion
277 bool doConvertAddressRepresentations(
278 const ::rtl::OUString& _rInputProperty,
279 const ::com::sun::star::uno::Any& _rInputValue,
280 const ::rtl::OUString& _rOutputProperty,
281 ::com::sun::star::uno::Any& _rOutputValue,
282 bool _bIsRange
283 ) const SAL_THROW(());
286 //............................................................................
287 } // namespace pcr
288 //............................................................................
290 #endif // EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX