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