extensions/source/propctrlr/cellbindinghelper.hxx

   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 EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
  29 #define EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX
  30
  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 === **/
  42
  43 //............................................................................
  44 namespace pcr
  45 {
  46 //............................................................................
  47
  48     //========================================================================
  49     //= CellBindingHelper
  50     //========================================================================
  51     /** encapsulates functionality related to binding a form control to a spreadsheet cell
  52     */
  53     class CellBindingHelper
  54     {
  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
  60
  61     public:
  62         /** ctor
  63             @param _rxControlModel
  64                 the control model which is or will be bound
  65         */
  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
  69         );
  70
  71     public:
  72         /** determines whether the given model is a spreadsheet document model
  73
  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>
  76         */
  77         static  sal_Bool    isSpreadsheetDocument(
  78                                 const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
  79                             );
  80
  81         /** gets a cell binding for the given address
  82             @precond
  83                 isCellBindingAllowed returns <TRUE/>
  84         */
  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;
  90
  91         /** creates a cell binding (supporting integer exchange, if requested) for
  92             the given address object
  93         */
  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;
  99
 100         /** gets a cell range list source binding for the given address
 101         */
 102         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
 103                         createCellListSourceFromStringAddress( const ::rtl::OUString& _rAddress ) const;
 104
 105         /** creates a string representation for the given value binding's address
 106
 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>
 109
 110             @precond
 111                 The binding is a valid cell binding, or <NULL/>
 112             @see isCellBinding
 113         */
 114         ::rtl::OUString getStringAddressFromCellBinding(
 115                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 116                         ) const;
 117
 118         /** creates an address object for the given value binding's address
 119
 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
 125         */
 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;
 130
 131         /** creates a string representation for the given list source's range address
 132
 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>
 136
 137             @precond
 138                 The object is a valid cell range list source, or <NULL/>
 139             @see isCellRangeListSource
 140         */
 141         ::rtl::OUString getStringAddressFromCellListSource(
 142                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 143                         ) const;
 144
 145         /** returns the current binding of our control model, if any.
 146         */
 147         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
 148                         getCurrentBinding( ) const;
 149
 150         /** returns the current external list source of the control model, if any
 151         */
 152         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
 153                         getCurrentListSource( ) const;
 154
 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/>)
 159         */
 160         void            setBinding(
 161                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 162                         );
 163
 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/>)
 168         */
 169         void            setListSource(
 170                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 171                         );
 172
 173         /** checks whether it's possible to bind the control model to a spreadsheet cell
 174         */
 175         bool            isCellBindingAllowed( ) const;
 176
 177         /** checks whether it's possible to bind the control model to a spreadsheet cell,
 178             with exchanging integer values
 179         */
 180         bool            isCellIntegerBindingAllowed( ) const;
 181
 182         /** checks whether it's possible to bind the control model to range of spreadsheet cells
 183             supplying the list entries
 184         */
 185         bool            isListCellRangeAllowed( ) const;
 186
 187         /** checks whether a given binding is a spreadsheet cell binding
 188         */
 189         bool            isCellBinding(
 190                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 191                         ) const;
 192
 193         /** checks whether a given binding is a spreadsheet cell binding, exchanging
 194             integer values
 195         */
 196         bool            isCellIntegerBinding(
 197                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 198                         ) const;
 199
 200         /** checks whether a given list source is a spreadsheet cell list source
 201         */
 202         bool            isCellRangeListSource(
 203                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 204                         ) const;
 205
 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
 208         */
 209         sal_Int16       getControlSheetIndex(
 210                             ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheet >& _out_rxSheet
 211                         ) const;
 212
 213     protected:
 214         /** creates an address object from a string representation of a cell address
 215         */
 216         bool            convertStringAddress(
 217                             const ::rtl::OUString& _rAddressDescription,
 218                             ::com::sun::star::table::CellAddress& /* [out] */ _rAddress
 219                         ) const;
 220
 221         /** creates an address range object from a string representation of a cell range address
 222         */
 223         bool            convertStringAddress(
 224                             const ::rtl::OUString& _rAddressDescription,
 225                             ::com::sun::star::table::CellRangeAddress& /* [out] */ _rAddress
 226                         ) const;
 227
 228         /** determines if our document is a spreadsheet document, *and* can supply
 229             the given service
 230         */
 231         bool            isSpreadsheetDocumentWhichSupplies( const ::rtl::OUString& _rService ) const;
 232
 233         /** checkes whether a given component supports a given servive
 234         */
 235         bool            doesComponentSupport(
 236                             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
 237                             const ::rtl::OUString& _rService
 238                         ) const;
 239
 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.
 249         */
 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;
 256
 257         /** converts an address representation into another one
 258
 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
 270
 271             @return
 272                 <TRUE/> if any only if the conversion was successfull
 273
 274             @see com::sun::star::table::CellAddressConversion
 275             @see com::sun::star::table::CellRangeAddressConversion
 276         */
 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(());
 284     };
 285
 286 //............................................................................
 287 }   // namespace pcr
 288 //............................................................................
 289
 290 #endif // EXTENSIONS_PROPCTRLR_CELLBINDINGHELPER_HXX