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