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