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