extensions/source/propctrlr/cellbindinghelper.hxx

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