xref: /aoo41x/main/svx/source/inc/formcontrolling.hxx (revision 3334a7e6)
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 SVX_FORMCONTROLLING_HXX
25 #define SVX_FORMCONTROLLING_HXX
26 
27 #include <com/sun/star/form/runtime/XFormController.hpp>
28 #include <com/sun/star/form/XForm.hpp>
29 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
30 #include <com/sun/star/form/runtime/FeatureState.hpp>
31 #include <com/sun/star/form/runtime/XFormOperations.hpp>
32 #include <com/sun/star/sdb/XSQLErrorListener.hpp>
33 
34 #include <cppuhelper/implbase2.hxx>
35 #include <comphelper/componentcontext.hxx>
36 
37 #include <vector>
38 
39 //........................................................................
40 namespace svx
41 {
42 //........................................................................
43 
44     //====================================================================
45     //= FeatureSlotTranslation
46     //====================================================================
47     class FeatureSlotTranslation
48     {
49     public:
50         /// retrieves the feature id for a given feature URL
51         static  sal_Int32       getControllerFeatureSlotIdForURL( const ::rtl::OUString& _rMainURL );
52 
53         /// retrieves the feature URL for a given feature id
54         static ::rtl::OUString  getControllerFeatureURLForSlotId( sal_Int32 _nSlotId );
55 
56         /// determines whether the given URL is a controller feature URL
57         static sal_Bool         isFeatureURL( const ::rtl::OUString& _rMainURL );
58 
59         /// retrieves the css.form.runtime.FormFeature ID for a given slot ID
60         static  sal_Int16       getFormFeatureForSlotId( sal_Int32 _nSlotId );
61 
62         /// retrieves the slot id for a given css.form.runtime.FormFeature ID
63         static  sal_Int32       getSlotIdForFormFeature( sal_Int16 _nFormFeature );
64     };
65 
66     //====================================================================
67     //= IControllerFeatureInvalidation
68     //====================================================================
69     class IControllerFeatureInvalidation
70     {
71     public:
72         /** invalidates the given features
73 
74             Invalidation means that any user interface representation (such as toolbox buttons), or
75             any dispatches associated with the features in question are potentially out-of-date, and
76             need to be updated
77 
78             @param _rFeatures
79                 Ids of the features to be invalidated.
80         */
81         virtual void invalidateFeatures( const ::std::vector< sal_Int32 >& _rFeatures ) = 0;
82     };
83 
84     //====================================================================
85     //= ControllerFeatures
86     //====================================================================
87     class FormControllerHelper;
88     /** easier access to an FormControllerHelper instance
89     */
90     class ControllerFeatures
91     {
92     protected:
93         ::comphelper::ComponentContext  m_aContext;
94         IControllerFeatureInvalidation* m_pInvalidationCallback;    // necessary as long as m_pImpl is not yet constructed
95         FormControllerHelper*           m_pImpl;
96 
97     public:
98         /** standard ctor
99 
100             The instance is not functional until <method>assign</method> is used.
101 
102             @param _rxORB
103                 a multi service factory for creating various needed components
104 
105             @param _pInvalidationCallback
106                 the callback for invalidating feature states
107         */
108         ControllerFeatures(
109             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
110             IControllerFeatureInvalidation* _pInvalidationCallback
111         );
112 
113         /** constructs the instance from a <type scope="com::sun::star::form::runtime">XFormController<type> instance
114 
115             @param _rxORB
116                 a multi service factory for creating various needed components
117 
118             @param _rxController
119                 The form controller which the helper should be responsible for. Must not
120                 be <NULL/>, and must have a valid model (form).
121 
122             @param _pInvalidationCallback
123                 the callback for invalidating feature states
124         */
125         ControllerFeatures(
126             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
127             const ::com::sun::star::uno::Reference< ::com::sun::star::form::runtime::XFormController >& _rxController,
128             IControllerFeatureInvalidation* _pInvalidationCallback
129         );
130 
131         /** constructs the helper form a <type scope="com::sun::star::form">XForm<type> instance
132 
133             Any functionality which depends on a controller will not be available.
134 
135             @param _rxORB
136                 a multi service factory for creating various needed components
137 
138             @param _rxForm
139                 The form which the helper should be responsible for. Must not be <NULL/>.
140 
141             @param _pInvalidationCallback
142                 the callback for invalidating feature states
143         */
144         ControllerFeatures(
145             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
146             const ::com::sun::star::uno::Reference< ::com::sun::star::form::XForm >& _rxForm,
147             IControllerFeatureInvalidation* _pInvalidationCallback
148         );
149 
150         /// dtor
151         ~ControllerFeatures();
152 
153         /// checks whether the instance is properly assigned to a form and/or controller
isAssigned() const154         inline bool isAssigned( ) const { return m_pImpl != NULL; }
155 
156         /** assign to a controller
157         */
158         void assign(
159             const ::com::sun::star::uno::Reference< ::com::sun::star::form::runtime::XFormController >& _rxController
160         );
161 
162         /** assign to a controller
163         */
164         void assign(
165             const ::com::sun::star::uno::Reference< ::com::sun::star::form::XForm >& _rxForm
166         );
167 
168         /// clears the instance so that it cannot be used afterwards
169         void dispose();
170 
171         // access to the instance which implements the functionality. Not to be used when not assigned
operator ->() const172         inline const FormControllerHelper* operator->() const { return m_pImpl; }
operator ->()173         inline       FormControllerHelper* operator->()       { return m_pImpl; }
operator *() const174         inline const FormControllerHelper& operator*() const  { return *m_pImpl; }
operator *()175         inline       FormControllerHelper& operator*()        { return *m_pImpl; }
176     };
177 
178     //====================================================================
179     //= FormControllerHelper
180     //====================================================================
181     typedef ::cppu::WeakImplHelper2 <   ::com::sun::star::form::runtime::XFeatureInvalidation
182                                     ,   ::com::sun::star::sdb::XSQLErrorListener
183                                     >   FormControllerHelper_Base;
184     /** is a helper class which manages form controller functionality (such as moveNext etc.).
185 
186         <p>The class helps implementing form controller functionality, by providing
187         methods to determine the state of, and execute, various common form features.<br/>
188         A <em>feature</em> is for instance moving the form associated with the controller
189         to a certain position, or reloading the form, and so on.</p>
190     */
191     class FormControllerHelper : public FormControllerHelper_Base
192     {
193     protected:
194         ::comphelper::ComponentContext  m_aContext;
195         IControllerFeatureInvalidation* m_pInvalidationCallback;
196         ::com::sun::star::uno::Reference< ::com::sun::star::form::runtime::XFormOperations >
197                                         m_xFormOperations;
198 
199         ::com::sun::star::uno::Any      m_aOperationError;
200 
201     public:
202         /** constructs the helper from a <type scope="com::sun::star::form::runtime">XFormController<type> instance
203 
204             @param _rContext
205                 the context the component lives in
206             @param _rxController
207                 The form controller which the helper should be responsible for. Must not
208                 be <NULL/>, and must have a valid model (form).
209             @param _pInvalidationCallback
210                 the callback for invalidating feature states
211         */
212         FormControllerHelper(
213             const ::comphelper::ComponentContext& _rContext,
214             const ::com::sun::star::uno::Reference< ::com::sun::star::form::runtime::XFormController >& _rxController,
215             IControllerFeatureInvalidation* _pInvalidationCallback
216         );
217 
218         /** constructs the helper form a <type scope="com::sun::star::form">XForm<type> instance
219 
220             Any functionality which depends on a controller will not be available.
221 
222             @param _rContext
223                 the context the component lives in
224             @param _rxForm
225                 The form which the helper should be responsible for. Must not be <NULL/>.
226             @param _pInvalidationCallback
227                 the callback for invalidating feature states
228         */
229         FormControllerHelper(
230             const ::comphelper::ComponentContext& _rContext,
231             const ::com::sun::star::uno::Reference< ::com::sun::star::form::XForm >& _rxForm,
232             IControllerFeatureInvalidation* _pInvalidationCallback
233         );
234 
235         // forwards to the XFormOperations implementation
236         ::com::sun::star::uno::Reference< ::com::sun::star::sdbc::XRowSet >
237                     getCursor() const;
238         void        getState(
239                         sal_Int32 _nSlotId,
240                         ::com::sun::star::form::runtime::FeatureState& _out_rState
241                     ) const;
242         sal_Bool    isEnabled( sal_Int32 _nSlotId ) const;
243         void        execute( sal_Int32 _nSlotId ) const;
244         void        execute( sal_Int32 _nSlotId, const ::rtl::OUString& _rParamName, const ::com::sun::star::uno::Any& _rParamValue ) const;
245         sal_Bool    commitCurrentRecord() const;
246         sal_Bool    commitCurrentControl( ) const;
247         sal_Bool    isInsertionRow() const;
248         sal_Bool    isModifiedRow() const;
249 
250         bool        moveLeft( ) const;
251         bool        moveRight( ) const;
252 
253         bool        canDoFormFilter() const;
254 
255         /** disposes this instance.
256 
257             After this method has been called, the instance is not functional anymore
258         */
259         void        dispose();
260 
261         const ::com::sun::star::uno::Reference< ::com::sun::star::form::runtime::XFormOperations >&
getFormOperations() const262                     getFormOperations() const { return m_xFormOperations; }
263     protected:
264         /// dtor
265         ~FormControllerHelper();
266 
267         // XFeatureInvalidation
268         virtual void SAL_CALL invalidateFeatures( const ::com::sun::star::uno::Sequence< ::sal_Int16 >& Features ) throw (::com::sun::star::uno::RuntimeException);
269         virtual void SAL_CALL invalidateAllFeatures() throw (::com::sun::star::uno::RuntimeException);
270 
271         // XSQLErrorListener
272         virtual void SAL_CALL errorOccured( const ::com::sun::star::sdb::SQLErrorEvent& _Event ) throw (::com::sun::star::uno::RuntimeException);
273 
274         // XEventListener
275         virtual void SAL_CALL disposing( const ::com::sun::star::lang::EventObject& Source ) throw (::com::sun::star::uno::RuntimeException);
276 
277     private:
278         enum FormOperation { EXECUTE, EXECUTE_ARGS, COMMIT_CONTROL, COMMIT_RECORD };
279 
280         bool    impl_operateForm_nothrow(
281                     const FormOperation _eWhat,
282                     const sal_Int16 _nFeature,  /* ignore for COMMIT_* */
283                     const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& _rArguments /* ignore except for EXECUTE_ARGS */
284                 ) const;
impl_operateForm_nothrow(const FormOperation _eWhat) const285         bool    impl_operateForm_nothrow( const FormOperation _eWhat ) const
286         {
287             return impl_operateForm_nothrow( _eWhat, 0, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >() );
288         }
impl_operateForm_nothrow(const sal_Int16 _nFeature) const289         bool    impl_operateForm_nothrow( const sal_Int16 _nFeature ) const
290         {
291             return impl_operateForm_nothrow( EXECUTE, _nFeature, ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >() );
292         }
293 
294     private:
295         FormControllerHelper();                                         // never implemented
296         FormControllerHelper( const FormControllerHelper& );            // never implemented
297         FormControllerHelper& operator=( const FormControllerHelper& ); // never implemented
298     };
299 
300 //........................................................................
301 }   // namespace svx
302 //........................................................................
303 
304 #endif // SVX_FORMCONTROLLING_HXX
305