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         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
  42                     m_xControlModel;    // the model we work for
  43         ::com::sun::star::uno::Reference< ::com::sun::star::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 it's functionality will be available.</p>
  50         */
  51         static  bool    livesInSpreadsheetDocument(
  52                                 const ::com::sun::star::uno::Reference< ::com::sun::star::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 walkong 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 ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel,
  66             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocument
  67         );
  68
  69     public:
  70         /** gets a cell binding for the given address
  71             @precond
  72                 isCellBindingAllowed returns <TRUE/>
  73         */
  74         ::com::sun::star::uno::Reference< ::com::sun::star::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         ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 110                         ) const;
 111
 112         /** returns the current binding of our control model, if any.
 113         */
 114         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
 115                         getCurrentBinding( ) const;
 116
 117         /** returns the current external list source of the control model, if any
 118         */
 119         ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocument
 160                         );
 161
 162         /** checks whether a given binding is a spreadsheet cell binding
 163         */
 164         static bool     isCellBinding(
 165                             const ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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                             ::com::sun::star::table::CellAddress& /* [out] */ _rAddress,
 187                             sal_Int16 _nAssumeSheet = -1
 188                         ) const;
 189
 190         /** creates an address range object from a string representation of a cell range address
 191         */
 192         bool            convertStringAddress(
 193                             const OUString& _rAddressDescription,
 194                             ::com::sun::star::table::CellRangeAddress& /* [out] */ _rAddress
 195                         ) const;
 196
 197         /** determines if our document is a spreadsheet document, *and* can supply
 198             the given service
 199         */
 200         bool            isSpreadsheetDocumentWhichSupplies( const OUString& _rService ) const;
 201
 202         /** determines if our document is a spreadsheet document, *and* can supply
 203             the given service
 204         */
 205         static bool     isSpreadsheetDocumentWhichSupplies(
 206                             const ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheetDocument >& _rxDocument,
 207                             const OUString& _rService
 208                         );
 209
 210         /** checkes whether a given component supports a given servive
 211         */
 212         static bool     doesComponentSupport(
 213                             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
 214                             const OUString& _rService
 215                         );
 216
 217         /** uses the document (it's factory interface, respectively) to create a component instance
 218             @param _rService
 219                 the service name
 220             @param _rArgumentName
 221                 the name of the single argument to pass during creation. May be empty, in this case
 222                 no arguments are passed
 223             @param _rArgumentValue
 224                 the value of the instantiation argument. Not evaluated if <arg>_rArgumentName</arg>
 225                 is empty.
 226         */
 227         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 228                         createDocumentDependentInstance(
 229                             const OUString& _rService,
 230                             const OUString& _rArgumentName,
 231                             const ::com::sun::star::uno::Any& _rArgumentValue
 232                         ) const;
 233
 234         /** converts an address representation into another one
 235
 236             @param _rInputProperty
 237                 the input property name for the conversion service
 238             @param _rInputValue
 239                 the input property value for the conversion service
 240             @param _rOutputProperty
 241                 the output property name for the conversion service
 242             @param _rOutputValue
 243                 the output property value for the conversion service
 244             @param _bIsRange
 245                 if <TRUE/>, the RangeAddressConversion service will be used, else
 246                 the AddressConversion service
 247
 248             @return
 249                 <TRUE/> if any only if the conversion was successful
 250
 251             @see com::sun::star::table::CellAddressConversion
 252             @see com::sun::star::table::CellRangeAddressConversion
 253         */
 254         bool            doConvertAddressRepresentations(
 255                             const OUString& _rInputProperty,
 256                             const ::com::sun::star::uno::Any& _rInputValue,
 257                             const OUString& _rOutputProperty,
 258                                   ::com::sun::star::uno::Any& _rOutputValue,
 259                             bool _bIsRange
 260                         ) const;
 261     };
 262
 263 }   // namespace xmloff
 264
 265 #endif // INCLUDED_XMLOFF_SOURCE_FORMS_FORMCELLBINDING_HXX
 266
 267 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */