extensions/source/propctrlr/eformshelper.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: eformshelper.hxx,v $
  10  * $Revision: 1.7 $
  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 EXTENSIONS_SOURCE_PROPCTRLR_EFORMSHELPER_HXX
  32 #define EXTENSIONS_SOURCE_PROPCTRLR_EFORMSHELPER_HXX
  33
  34 #include "pcrcommon.hxx"
  35
  36 /** === begin UNO includes === **/
  37 #include <com/sun/star/frame/XModel.hpp>
  38 #include <com/sun/star/beans/XPropertySet.hpp>
  39 #include <com/sun/star/xforms/XModel.hpp>
  40 #include <com/sun/star/xforms/XFormsSupplier.hpp>
  41 #include <com/sun/star/form/binding/XBindableValue.hpp>
  42 #include <com/sun/star/form/binding/XListEntrySource.hpp>
  43 /** === end UNO includes === **/
  44 #include <osl/mutex.hxx>
  45 #include <tools/string.hxx>
  46 #include <comphelper/listenernotification.hxx>
  47
  48 #include <vector>
  49 #include <set>
  50 #include <map>
  51
  52 //........................................................................
  53 namespace pcr
  54 {
  55 //........................................................................
  56
  57     typedef ::std::map< ::rtl::OUString, ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >, ::std::less< ::rtl::OUString > >
  58             MapStringToPropertySet;
  59
  60     //====================================================================
  61     //= EFormsHelper
  62     //====================================================================
  63     class EFormsHelper
  64     {
  65     protected:
  66         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
  67                         m_xControlModel;
  68         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XBindableValue >
  69                         m_xBindableControl;
  70         ::com::sun::star::uno::Reference< ::com::sun::star::xforms::XFormsSupplier >
  71                         m_xDocument;
  72         PropertyChangeListeners
  73                         m_aPropertyListeners;
  74         MapStringToPropertySet
  75                         m_aSubmissionUINames;   // only filled upon request
  76         MapStringToPropertySet
  77                         m_aBindingUINames;      // only filled upon request
  78
  79     public:
  80         EFormsHelper(
  81             ::osl::Mutex& _rMutex,
  82             const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxControlModel,
  83             const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
  84         );
  85
  86         /** determines whether the given document is an eForm
  87
  88             If this method returns <FALSE/>, you cannot instantiate a EFormsHelper with
  89             this document, since then no of it's functionality will be available.
  90         */
  91         static  bool
  92                 isEForm(
  93                     const ::com::sun::star::uno::Reference< ::com::sun::star::frame::XModel >& _rxContextDocument
  94                 ) SAL_THROW(());
  95
  96         /** registers a listener to be notified when any aspect of the binding changes.
  97
  98             The listener will be registered at the current binding of the control model. If the binding
  99             changes (see <method>setBinding</method>), the listener will be revoked from the old binding,
 100             registered at the new binding, and for all properties which differ between both bindings,
 101             the listener will be notified.
 102             @see revokeBindingListener
 103         */
 104         void    registerBindingListener(
 105                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxBindingListener
 106                 );
 107
 108         /** revokes the binding listener which has previously been registered
 109             @see registerBindingListener
 110         */
 111         void    revokeBindingListener(
 112                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxBindingListener
 113                 );
 114
 115         /** checks whether it's possible to bind the control model to a given XSD data type
 116
 117             @param _nDataType
 118                 the data type which should be bound. If this is -1, <TRUE/> is returned if the control model
 119                 can be bound to <em>any</em> data type.
 120         */
 121         bool    canBindToDataType( sal_Int32 _nDataType = -1 ) const SAL_THROW(());
 122
 123         /** checks whether the control model cna be bound to any XSD data type
 124         */
 125         bool    canBindToAnyDataType() const SAL_THROW(()) { return canBindToDataType( -1 ); }
 126
 127         /** checks whether the control model is a source for list entries, as supplied by XML data bindings
 128         */
 129         bool    isListEntrySink() const SAL_THROW(());
 130
 131         /** retrieves the names of all XForms models in the document the control lives in
 132         */
 133         void    getFormModelNames( ::std::vector< ::rtl::OUString >& /* [out] */ _rModelNames ) const SAL_THROW(());
 134
 135         /** retrieves the names of all bindings for a given model
 136             @see getFormModelNames
 137         */
 138         void    getBindingNames( const ::rtl::OUString& _rModelName, ::std::vector< ::rtl::OUString >& /* [out] */ _rBindingNames ) const SAL_THROW(());
 139
 140         /// retrieves the XForms model (within the control model's document) with the given name
 141         ::com::sun::star::uno::Reference< ::com::sun::star::xforms::XModel >
 142                 getFormModelByName( const ::rtl::OUString& _rModelName ) const SAL_THROW(());
 143
 144         /** retrieves the model which the active binding of the control model belongs to
 145         */
 146         ::com::sun::star::uno::Reference< ::com::sun::star::xforms::XModel >
 147                 getCurrentFormModel() const SAL_THROW(());
 148
 149         /** retrieves the name of the model which the active binding of the control model belongs to
 150         */
 151         ::rtl::OUString
 152                 getCurrentFormModelName() const SAL_THROW(());
 153
 154         /** retrieves the binding instance which is currently attached to the control model
 155         */
 156         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
 157                 getCurrentBinding() const SAL_THROW(());
 158
 159         /** retrieves the name of the binding instance which is currently attached to the control model
 160         */
 161         ::rtl::OUString
 162                 getCurrentBindingName() const SAL_THROW(());
 163
 164         /** sets a new binding at the control model
 165         */
 166         void    setBinding( const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxBinding ) SAL_THROW(());
 167
 168         /** retrieves the binding instance which is currently used as list source for the control model
 169             @see isListEntrySink
 170         */
 171         ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >
 172                 getCurrentListSourceBinding() const SAL_THROW(());
 173
 174         /** sets a new list source at the control model
 175             @see isListEntrySink
 176         */
 177         void    setListSourceBinding( const ::com::sun::star::uno::Reference< ::com::sun::star::form::binding::XListEntrySource >& _rxListSource ) SAL_THROW(());
 178
 179         /** retrieves a given binding for a given model, or creates a new one
 180
 181             @param _rTargetModel
 182                 the name of the model to create a binding for. Must not be empty
 183             @param _rBindingName
 184                 the name of the binding to retrieve. If the model denoted by <arg>_rTargetModel</arg> does not
 185                 have a binding with this name, a new binding is created and returned.
 186         */
 187         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
 188             getOrCreateBindingForModel( const ::rtl::OUString& _rTargetModel, const ::rtl::OUString& _rBindingName ) const SAL_THROW(());
 189
 190         /** types of sub-elements of a model
 191         */
 192         enum ModelElementType
 193         {
 194             Submission,
 195             Binding
 196         };
 197
 198         /** retrieves the name of a model's sub-element, as to be shown in the UI
 199             @see getModelElementFromUIName
 200             @see getAllElementUINames
 201         */
 202         ::rtl::OUString
 203                 getModelElementUIName(
 204                     const ModelElementType _eType,
 205                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxElement
 206                 ) const SAL_THROW(());
 207
 208         /** retrieves the submission object for an UI name
 209
 210             Note that <member>getAllElementUINames</member> must have been called before, for the given element type
 211
 212             @see getModelElementUIName
 213             @see getAllElementUINames
 214         */
 215         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
 216                 getModelElementFromUIName(
 217                     const ModelElementType _eType,
 218                     const ::rtl::OUString& _rUIName
 219                 ) const SAL_THROW(());
 220
 221         /** retrieves the UI names of all elements of all models in our document
 222             @param _eType
 223                 the type of elements for which the names should be retrieved
 224             @param _rElementNames
 225                 the array of element names
 226             @see getModelElementUIName
 227             @see getModelElementFromUIName
 228         */
 229         void    getAllElementUINames(
 230                     const ModelElementType _eType,
 231                     ::std::vector< ::rtl::OUString >& /* [out] */ _rElementNames,
 232                     bool _bPrepentEmptyEntry
 233                 );
 234
 235     protected:
 236         void    firePropertyChanges(
 237                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxOldProps,
 238                     const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >& _rxNewProps,
 239                     ::std::set< ::rtl::OUString >& _rFilter
 240                 ) const;
 241
 242         /** fires a change in a single property, if the property value changed, and if we have a listener
 243             interested in property changes
 244         */
 245         void    firePropertyChange(
 246                     const ::rtl::OUString& _rName,
 247                     const ::com::sun::star::uno::Any& _rOldValue,
 248                     const ::com::sun::star::uno::Any& _rNewValue
 249                 ) const;
 250
 251     private:
 252         void impl_switchBindingListening_throw( bool _bDoListening, const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxListener );
 253
 254         /// implementation for both <member>getOrCreateBindingForModel</member>
 255         ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySet >
 256             implGetOrCreateBinding( const ::rtl::OUString& _rTargetModel, const ::rtl::OUString& _rBindingName ) const SAL_THROW(());
 257
 258         void
 259             impl_toggleBindingPropertyListening_throw( bool _bDoListen, const ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertyChangeListener >& _rxConcreteListenerOrNull );
 260
 261     private:
 262         EFormsHelper();                                 // never implemented
 263         EFormsHelper( const EFormsHelper& );            // never implemented
 264         EFormsHelper& operator=( const EFormsHelper& ); // never implemented
 265     };
 266
 267 //........................................................................
 268 } // namespace pcr
 269 //........................................................................
 270
 271 #endif // EXTENSIONS_SOURCE_PROPCTRLR_EFORMSHELPER_HXX
 272