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 occured 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 occured 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 successfull 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