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