extensions/source/propctrlr/cellbindinghelper.hxx

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