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