xmloff/source/forms/formcellbinding.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: formcellbinding.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef XMLOFF_FORMS_FORMCELLBINDING
  32 #define XMLOFF_FORMS_FORMCELLBINDING
  33
  34 #include <com/sun/star/beans/XPropertySet.hpp>
  35 #include <com/sun/star/sheet/XSpreadsheetDocument.hpp>
  36 #include <com/sun/star/table/CellAddress.hpp>
  37 #include <com/sun/star/table/CellRangeAddress.hpp>
  38 #include <com/sun/star/form/binding/XValueBinding.hpp>
  39 #include <com/sun/star/form/binding/XListEntrySource.hpp>
  40 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  41 #include <com/sun/star/frame/XModel.hpp>
  42
  43 //............................................................................
  44 namespace xmloff
  45 {
  46 //............................................................................
  47
  48     //========================================================================
  49     //= FormCellBindingHelper
  50     //========================================================================
  51     /** encapsulates functionality related to binding a form control to a spreadsheet cell
  52     */
  53     class FormCellBindingHelper
  54     {
  55     protected:
  56         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
  57                     m_xControlModel;    // the model we work for
  58         ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheetDocument >
  59                     m_xDocument;        // the document where the model lives
  60
  61     public:
  62         /** determines whether the given control model lives in a spreadsheet document
  63             <p>If this method returns <FALSE/>, you cannot instantiate a CellBindingHelper with
  64             this model, since then no of it's functionality will be available.</p>
  65         */
  66         static  sal_Bool    livesInSpreadsheetDocument(
  67                                 const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel
  68                             );
  69
  70         /** ctor
  71             @param _rxControlModel
  72                 the control model which is or will be bound
  73             @param _rxDocument
  74                 the document. If this is <NULL/>, the document will be obtained from the model
  75                 itself by walkong up the chain of its ancestors.<br/>
  76                 This parameter can be used if the control model is not (yet) part of a document
  77                 model.
  78         */
  79         FormCellBindingHelper(
  80             const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel,
  81             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocument
  82         );
  83
  84     public:
  85         /** gets a cell binding for the given address
  86             @precond
  87                 isCellBindingAllowed returns <TRUE/>
  88         */
  89         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
  90                         createCellBindingFromStringAddress(
  91                             const ::rtl::OUString& _rAddress,
  92                             bool _bUseIntegerBinding
  93                         ) const;
  94
  95         /** gets a cell range list source binding for the given address
  96         */
  97         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
  98                         createCellListSourceFromStringAddress( const ::rtl::OUString& _rAddress ) const;
  99
 100         /** creates a string representation for the given value binding's address
 101
 102             <p>If the sheet of the bound cell is the same as the sheet which our control belongs
 103             to, then the sheet name is omitted in the resulting string representation.</p>
 104
 105             @precond
 106                 The binding is a valid cell binding, or <NULL/>
 107             @see isCellBinding
 108         */
 109         ::rtl::OUString getStringAddressFromCellBinding(
 110                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 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         ::rtl::OUString getStringAddressFromCellListSource(
 124                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 125                         ) const;
 126
 127         /** returns the current binding of our control model, if any.
 128         */
 129         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >
 130                         getCurrentBinding( ) const;
 131
 132         /** returns the current external list source of the control model, if any
 133         */
 134         ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 ::com::sun::star::uno::Reference< ::com::sun::star::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 within the given document, it's possible to bind control models to spreadsheet cells
 160         */
 161         static bool     isCellBindingAllowed(
 162                             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocument
 163                         );
 164
 165         /** checks whether it's possible to bind the control model to a range of spreadsheet cells
 166             supplying the list entries
 167         */
 168         bool            isListCellRangeAllowed( ) const;
 169
 170         /** checks whether within the given document, it's possible to bind the control model to a range of
 171             spreadsheet cells supplying the list entries
 172         */
 173         static bool     isListCellRangeAllowed(
 174                             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxDocument
 175                         );
 176
 177         /** checks whether a given binding is a spreadsheet cell binding
 178         */
 179         bool            isCellBinding(
 180                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 181                         ) const;
 182
 183         /** checks whether a given binding is a spreadsheet cell binding, exchanging
 184             integer values
 185         */
 186         bool            isCellIntegerBinding(
 187                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XValueBinding >& _rxBinding
 188                         ) const;
 189
 190         /** checks whether a given list source is a spreadsheet cell list source
 191         */
 192         bool            isCellRangeListSource(
 193                             const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxSource
 194                         ) const;
 195
 196     protected:
 197         /** creates an address object from a string representation of a cell address
 198         */
 199         bool            convertStringAddress(
 200                             const ::rtl::OUString& _rAddressDescription,
 201                             ::com::sun::star::table::CellAddress& /* [out] */ _rAddress,
 202                             sal_Int16 _nAssumeSheet = -1
 203                         ) const;
 204
 205         /** creates an address range object from a string representation of a cell range address
 206         */
 207         bool            convertStringAddress(
 208                             const ::rtl::OUString& _rAddressDescription,
 209                             ::com::sun::star::table::CellRangeAddress& /* [out] */ _rAddress
 210                         ) const;
 211
 212         /** determines if our document is a spreadsheet document, *and* can supply
 213             the given service
 214         */
 215         bool            isSpreadsheetDocumentWhichSupplies( const ::rtl::OUString& _rService ) const  SAL_THROW(());
 216
 217         /** determines if our document is a spreadsheet document, *and* can supply
 218             the given service
 219         */
 220         static bool     isSpreadsheetDocumentWhichSupplies(
 221                             const ::com::sun::star::uno::Reference< ::com::sun::star::sheet::XSpreadsheetDocument >& _rxDocument,
 222                             const ::rtl::OUString& _rService
 223                         ) SAL_THROW(());
 224
 225         /** checkes whether a given component supports a given servive
 226         */
 227         bool            doesComponentSupport(
 228                             const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxComponent,
 229                             const ::rtl::OUString& _rService
 230                         ) const;
 231
 232         /** uses the document (it's factory interface, respectively) to create a component instance
 233             @param _rService
 234                 the service name
 235             @param _rArgumentName
 236                 the name of the single argument to pass during creation. May be empty, in this case
 237                 no arguments are passed
 238             @param _rArgumentValue
 239                 the value of the instantiation argument. Not evaluated if <arg>_rArgumentName</arg>
 240                 is empty.
 241         */
 242         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 243                         createDocumentDependentInstance(
 244                             const ::rtl::OUString& _rService,
 245                             const ::rtl::OUString& _rArgumentName,
 246                             const ::com::sun::star::uno::Any& _rArgumentValue
 247                         ) const;
 248
 249         /** converts an address representation into another one
 250
 251             @param _rInputProperty
 252                 the input property name for the conversion service
 253             @param _rInputValue
 254                 the input property value for the conversion service
 255             @param _rOutputProperty
 256                 the output property name for the conversion service
 257             @param _rOutputValue
 258                 the output property value for the conversion service
 259             @param _bIsRange
 260                 if <TRUE/>, the RangeAddressConversion service will be used, else
 261                 the AddressConversion service
 262
 263             @return
 264                 <TRUE/> if any only if the conversion was successfull
 265
 266             @see com::sun::star::table::CellAddressConversion
 267             @see com::sun::star::table::CellRangeAddressConversion
 268         */
 269         bool            doConvertAddressRepresentations(
 270                             const ::rtl::OUString& _rInputProperty,
 271                             const ::com::sun::star::uno::Any& _rInputValue,
 272                             const ::rtl::OUString& _rOutputProperty,
 273                                   ::com::sun::star::uno::Any& _rOutputValue,
 274                             bool _bIsRange
 275                         ) const SAL_THROW(());
 276     };
 277
 278 //............................................................................
 279 }   // namespace xmloff
 280 //............................................................................
 281
 282 #endif // XMLOFF_FORMS_FORMCELLBINDING