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 final
  40     {
  41         css::uno::Reference< css::beans::XPropertySet >
  42                     m_xControlModel;    // the model we work for
  43         css::uno::Reference< css::sheet::XSpreadsheetDocument >
  44                     m_xDocument;        // the document where the model lives
  45
  46     public:
  47         /** ctor
  48             @param _rxControlModel
  49                 the control model which is or will be bound
  50         */
  51         CellBindingHelper(
  52             const css::uno::Reference< css::beans::XPropertySet >& _rxControlModel,
  53             const css::uno::Reference< css::frame::XModel >& _rxContextDocument
  54         );
  55
  56         /** determines whether the given model is a spreadsheet document model
  57
  58             <p>If this method returns <FALSE/>, you cannot instantiate a CellBindingHelper with
  59             the document, since then no of its functionality will be available.</p>
  60         */
  61         static  bool    isSpreadsheetDocument(
  62                                 const css::uno::Reference< css::frame::XModel >& _rxContextDocument
  63                             );
  64
  65         /** gets a cell binding for the given address
  66             @precond
  67                 isCellBindingAllowed returns <TRUE/>
  68         */
  69         css::uno::Reference< css::form::binding::XValueBinding >
  70                         createCellBindingFromStringAddress(
  71                             const OUString& _rAddress,
  72                             bool _bSupportIntegerExchange
  73                         ) const;
  74
  75         /** creates a cell binding (supporting integer exchange, if requested) for
  76             the given address object
  77         */
  78         css::uno::Reference< css::form::binding::XValueBinding >
  79                         createCellBindingFromAddress(
  80                             const css::table::CellAddress& _rAddress,
  81                             bool _bSupportIntegerExchange
  82                         ) const;
  83
  84         /** gets a cell range list source binding for the given address
  85         */
  86         css::uno::Reference< css::form::binding::XListEntrySource >
  87                         createCellListSourceFromStringAddress( const OUString& _rAddress ) const;
  88
  89         /** creates a string representation for the given value binding's address
  90
  91             <p>If the sheet of the bound cell is the same as the sheet which our control belongs
  92             to, then the sheet name is omitted in the resulting string representation.</p>
  93
  94             @precond
  95                 The binding is a valid cell binding, or <NULL/>
  96             @see isCellBinding
  97         */
  98         OUString getStringAddressFromCellBinding(
  99                             const css::uno::Reference< css::form::binding::XValueBinding >& _rxBinding
 100                         ) const;
 101
 102         /** creates an address object for the given value binding's address
 103
 104             @precond
 105                 The binding is a valid cell binding, or <NULL/>
 106             @return
 107                 <FALSE/> if and only if an error occurred and no valid address could be obtained
 108             @see isCellBinding
 109         */
 110         bool            getAddressFromCellBinding(
 111                             const css::uno::Reference< css::form::binding::XValueBinding >& _rxBinding,
 112                             css::table::CellAddress& _rAddress
 113                         ) const;
 114
 115         /** creates a string representation for the given list source's range address
 116
 117             <p>If the sheet of the cell range which acts as list source is the same as the
 118             sheet which our control belongs to, then the sheet name is omitted in the
 119             resulting string representation.</p>
 120
 121             @precond
 122                 The object is a valid cell range list source, or <NULL/>
 123             @see isCellRangeListSource
 124         */
 125         OUString getStringAddressFromCellListSource(
 126                             const css::uno::Reference< css::form::binding::XListEntrySource >& _rxSource
 127                         ) const;
 128
 129         /** returns the current binding of our control model, if any.
 130         */
 131         css::uno::Reference< css::form::binding::XValueBinding >
 132                         getCurrentBinding( ) const;
 133
 134         /** returns the current external list source of the control model, if any
 135         */
 136         css::uno::Reference< css::form::binding::XListEntrySource >
 137                         getCurrentListSource( ) const;
 138
 139         /** sets a new binding for our control model
 140             @precond
 141                 the control model is bindable (which is implied by <member>isCellBindingAllowed</member>
 142                 returning <TRUE/>)
 143         */
 144         void            setBinding(
 145                             const css::uno::Reference< css::form::binding::XValueBinding >& _rxBinding
 146                         );
 147
 148         /** sets a list source for our control model
 149             @precond
 150                 the control model is a list sink (which is implied by <member>isListCellRangeAllowed</member>
 151                 returning <TRUE/>)
 152         */
 153         void            setListSource(
 154                             const css::uno::Reference< css::form::binding::XListEntrySource >& _rxSource
 155                         );
 156
 157         /** checks whether it's possible to bind the control model to a spreadsheet cell
 158         */
 159         bool            isCellBindingAllowed( ) const;
 160
 161         /** checks whether it's possible to bind the control model to a spreadsheet cell,
 162             with exchanging integer values
 163         */
 164         bool            isCellIntegerBindingAllowed( ) const;
 165
 166         /** checks whether it's possible to bind the control model to range of spreadsheet cells
 167             supplying the list entries
 168         */
 169         bool            isListCellRangeAllowed( ) const;
 170
 171         /** checks whether a given binding is a spreadsheet cell binding
 172         */
 173         static bool     isCellBinding(
 174                             const css::uno::Reference< css::form::binding::XValueBinding >& _rxBinding
 175                         );
 176
 177         /** checks whether a given binding is a spreadsheet cell binding, exchanging
 178             integer values
 179         */
 180         static bool    isCellIntegerBinding(
 181                             const css::uno::Reference< css::form::binding::XValueBinding >& _rxBinding
 182                         );
 183
 184         /** checks whether a given list source is a spreadsheet cell list source
 185         */
 186         static bool     isCellRangeListSource(
 187                             const css::uno::Reference< css::form::binding::XListEntrySource >& _rxSource
 188                         );
 189
 190         /** retrieves the index of the sheet which our control belongs to
 191             @return the index of the sheet which our control belongs to or -1, if an error occurred
 192         */
 193         sal_Int16       getControlSheetIndex(
 194                             css::uno::Reference< css::sheet::XSpreadsheet >& _out_rxSheet
 195                         ) const;
 196
 197     private:
 198         /** creates an address object from a string representation of a cell address
 199         */
 200         bool            convertStringAddress(
 201                             const OUString& _rAddressDescription,
 202                             css::table::CellAddress& /* [out] */ _rAddress
 203                         ) const;
 204
 205         /** creates an address range object from a string representation of a cell range address
 206         */
 207         bool            convertStringAddress(
 208                             const OUString& _rAddressDescription,
 209                             css::table::CellRangeAddress& /* [out] */ _rAddress
 210                         ) const;
 211
 212         /** determines if our document is a spreadsheet document, *and* can supply
 213             the given service
 214         */
 215         bool            isSpreadsheetDocumentWhichSupplies( const OUString& _rService ) const;
 216
 217         /** checks whether a given component supports a given servive
 218         */
 219         static bool     doesComponentSupport(
 220                             const css::uno::Reference< css::uno::XInterface >& _rxComponent,
 221                             const OUString& _rService
 222                         );
 223
 224         /** uses the document (it's factory interface, respectively) to create a component instance
 225             @param _rService
 226                 the service name
 227             @param _rArgumentName
 228                 the name of the single argument to pass during creation. May be empty, in this case
 229                 no arguments are passed
 230             @param _rArgumentValue
 231                 the value of the instantiation argument. Not evaluated if <arg>_rArgumentName</arg>
 232                 is empty.
 233         */
 234         css::uno::Reference< css::uno::XInterface >
 235                         createDocumentDependentInstance(
 236                             const OUString& _rService,
 237                             const OUString& _rArgumentName,
 238                             const css::uno::Any& _rArgumentValue
 239                         ) const;
 240
 241         /** converts an address representation into another one
 242
 243             @param _rInputProperty
 244                 the input property name for the conversion service
 245             @param _rInputValue
 246                 the input property value for the conversion service
 247             @param _rOutputProperty
 248                 the output property name for the conversion service
 249             @param _rOutputValue
 250                 the output property value for the conversion service
 251             @param _bIsRange
 252                 if <TRUE/>, the RangeAddressConversion service will be used, else
 253                 the AddressConversion service
 254
 255             @return
 256                 <TRUE/> if any only if the conversion was successful
 257
 258             @see css::table::CellAddressConversion
 259             @see css::table::CellRangeAddressConversion
 260         */
 261         bool            doConvertAddressRepresentations(
 262                             const OUString& _rInputProperty,
 263                             const css::uno::Any& _rInputValue,
 264                             const OUString& _rOutputProperty,
 265                                   css::uno::Any& _rOutputValue,
 266                             bool _bIsRange
 267                         ) const;
 268     };
 269
 270
 271 }   // namespace pcr
 272
 273
 274 #endif // INCLUDED_EXTENSIONS_SOURCE_PROPCTRLR_CELLBINDINGHELPER_HXX
 275
 276 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */