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