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 __com_sun_star_form_runtime_XFormOperations_idl__
25#define __com_sun_star_form_runtime_XFormOperations_idl__
26
27#ifndef __com_sun_star_form_runtime_FeatureState_idl__
28#include <com/sun/star/form/runtime/FeatureState.idl>
29#endif
30
31#ifndef __com_sun_star_lang_XComponent_idl__
32#include <com/sun/star/lang/XComponent.idl>
33#endif
34#ifndef __com_sun_star_sdbc_XRowSet_idl__
35#include <com/sun/star/sdbc/XRowSet.idl>
36#endif
37#ifndef __com_sun_star_sdbc_XResultSetUpdate_idl__
38#include <com/sun/star/sdbc/XResultSetUpdate.idl>
39#endif
40#ifndef __com_sun_star_form_runtime_XFormController_idl__
41#include <com/sun/star/form/runtime/XFormController.idl>
42#endif
43#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
44#include <com/sun/star/lang/IllegalArgumentException.idl>
45#endif
46#ifndef __com_sun_star_lang_WrappedTargetException_idl__
47#include <com/sun/star/lang/WrappedTargetException.idl>
48#endif
49#ifndef __com_sun_star_beans_NamedValue_idl__
50#include <com/sun/star/beans/NamedValue.idl>
51#endif
52
53//=============================================================================
54
55module com { module sun { module star { module form { module runtime {
56
57interface XFeatureInvalidation;
58
59//=============================================================================
60
61/** encapsulates operations on a database form.
62
63    <p>This instance allows for operations on a user interface form, by saving its clients
64    from various tedious and error-prone operations.</p>
65
66    <p>As an example, imagine you have a database form, displayed in some user
67    interface, which you want to move to the next record.<br/>
68    It is as easy as calling <member scope="com:::sun::star::sdbc">XResultSet::next</member>
69    on this form, right? Wrong. First, you need to care for saving the current
70    record, so the user doesn't lose her input. So you need to call
71    <member scope="com::sun::star::sdbc">XResultSetUpdate::updateRow</member> or
72    <member scope="com::sun::star::sdbc">XResultSetUpdate::insertRow</member>, depending
73    on the form's <member scope="com::sun::star::sdb">RowSet::IsNew</member> property.<br/>
74    But then you're done, right? Wrong, again.<br/>
75    When the user just entered some data into one of the form fields, but did not yet
76    leave this field, then the data is not yet committed to the form, not to talk
77    about being committed to the underlying database. So, before everything else,
78    you would nee to obtain the active control of the form, and commit it.<br/>
79    <em>Now</em> you're done ...</p>
80
81    <p>As another example, consider that you want to delete the current record from the
82    form. You have to take into account any <type scope="com::sun::star::form">XConfirmDeleteListener</type>s
83    registered at the <type scope="com::sun::star::form">FormController</type> or the
84    <type scope="com::sun::star::form::component">DataForm</type>.</p>
85
86    <p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code>
87    is for you. It provides a <member>execute</member> method, which will do all of the above
88    for you; plus some similar convenient wrappers for similar functionality.</p>
89
90    @see FormFeature
91
92    @since OpenOffice 2.2
93 */
94interface XFormOperations : ::com::sun::star::lang::XComponent
95{
96    /** provides access to the cursor of the form the instance is operating on.
97    */
98    [attribute, readonly]   ::com::sun::star::sdbc::XRowSet             Cursor;
99
100    /** provides access to the update cursor of the form the instance is operating on.
101    */
102    [attribute, readonly]   ::com::sun::star::sdbc::XResultSetUpdate    UpdateCursor;
103
104    /** provides access to the form controller which the instance is operating on.
105
106        <p>Note that it is possible to operate on a user interface form without
107        actually having access to the form controller instance. However, in this
108        case some functionality will not be available. In particular, every feature
109        which relies on the active control of the controller might be of limited use.</p>
110    */
111    [attribute, readonly]   ::com::sun::star::form::runtime::XFormController    Controller;
112
113    /** retrieves the current state of the given feature
114
115        <p>You would usually use this to update some user interface to reflect this state.
116        For instance, you could imagine a toolbar button which is associated with a given feature.
117        This button would be enabled if and only if the respective feature is currently
118        available, and be checked if and only if the feature state is a <code>boolean</code>
119        evaluating to <TRUE/>.<p>
120
121        @param Feature
122            the feature whose state is to be determimed. Must be one of the <type>FormFeature</type>
123            constants.<br/>
124            An invalid value here will be silently ignored, and simply return a <type>FeatureState</type>
125            indicating <em>disabled</em> with a <NULL/> state.</p>
126    */
127    FeatureState    getState(
128                        [in] short Feature
129                    );
130
131    /** determines whether a feature is currently enabled.
132
133        <p>Calling this is equivalent to calling <member>getState</member>, and evaluating the
134        <member>FeatureState::Enabled</member> member.</p>
135
136        @param Feature
137            the feature whose state is to be determimed. Must be one of the <type>FormFeature</type>
138            constants.<br/>
139            An invalid value here will be silently ignored, and simply return <FALSE/>.
140    */
141    boolean         isEnabled(
142                        [in] short Feature
143                    );
144
145    /** executes the operation associated with the given feature
146
147        @param Feature
148            the feature which is to be executed. Must be one of the <type>FormFeature</type>
149            constants.
150
151        @throws ::com::sun::star::lang::IllegalArgumentException
152            if the given Feature is unknown, not executable, or striclty requires arguments
153            to be executed.
154
155        @throws ::com::sun::star::sdbc::SQLException
156            if a database access erorr occurs
157
158        @throws ::com::sun::star::lang::WrappedTargetException
159            if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type>
160            and no <type scope="com::sun::star::sdbc">SQLException</type>.
161
162        @see executeWithArguments
163    */
164    void            execute(
165                        [in] short Feature
166                    )
167                    raises  (   ::com::sun::star::lang::IllegalArgumentException
168                            ,   ::com::sun::star::sdbc::SQLException
169                            ,   ::com::sun::star::lang::WrappedTargetException
170                            );
171
172    /** executes the operation associated with the given feature, with passing arguments for execution
173
174        @param Feature
175            the feature which is to be executed. Must be one of the <type>FormFeature</type>
176            constants.
177
178        @param Arguments
179            the named arguments for the feature to execute. See the <type>FormFeature</type> list
180            for features which require arguments.
181
182        @throws ::com::sun::star::lang::IllegalArgumentException
183            if the given feature is unknown, or not executable
184
185        @throws ::com::sun::star::lang::IllegalArgumentException
186            if the given arguments are not sufficient to execute the feature
187
188        @throws ::com::sun::star::sdbc::SQLException
189            if a database access erorr occurs
190
191        @throws ::com::sun::star::lang::WrappedTargetException
192            if an exception is caught which is no <type scope="com::sun::star::uno">RuntimeException</type>
193            and no <type scope="com::sun::star::sdbc">SQLException</type>.
194    */
195    void            executeWithArguments(
196                        [in] short Feature,
197                        [in] sequence< ::com::sun::star::beans::NamedValue > Arguments
198                    )
199                    raises  (   ::com::sun::star::lang::IllegalArgumentException
200                            ,   ::com::sun::star::sdbc::SQLException
201                            ,   ::com::sun::star::lang::WrappedTargetException
202                            );
203
204    /** commits the current record of the form
205
206        @param RecordInserted
207            will be <TRUE/> if a record has been inserted, i.e. the form was positioned
208            on the insertion row.
209
210        @return
211            <TRUE/> if and only if the current record needed being committed. That's the
212            case if the record or the active control of the form were modified.
213
214        @throws ::com::sun::star::sdbc::SQLException
215            if a database access erorr occurs
216    */
217    boolean         commitCurrentRecord(
218                        [out] boolean RecordInserted
219                    )
220                    raises ( ::com::sun::star::sdbc::SQLException );
221
222    /** commits the current control of our controller
223
224        @throws ::com::sun::star::sdbc::SQLException
225            if a database access erorr occurs
226    */
227    boolean         commitCurrentControl(
228                    )
229                    raises ( ::com::sun::star::sdbc::SQLException );
230
231    /** determines whether the form is currently positioned on the insertion row
232
233        <p>This is a convenience method only. Calling it es equivalent to examing the
234        <member scope="com::sun::star::sdb">RowSet::IsNew</member> property of the form.</p>
235
236        @throws ::com::sun::star::lang::WrappedTargetException
237            if an error occurs obtaining the form property
238    */
239    boolean         isInsertionRow(
240                    )
241                    raises ( ::com::sun::star::lang::WrappedTargetException );
242
243    /** determines whether the current row of the form is modified
244
245        <p>This is a convenience method only. Calling it es equivalent to examing the
246        <member scope="com::sun::star::sdb">RowSet::IsModified</member> property of the form.</p>
247
248        @throws ::com::sun::star::lang::WrappedTargetException
249            if an error occurs obtaining the form property
250    */
251    boolean         isModifiedRow(
252                    )
253                    raises ( ::com::sun::star::lang::WrappedTargetException );
254
255    /** denotes the instance which should be notified about features whose state might have changed.
256
257        <p>If this attribute is not <NULL/>, the instance which it denotes will be notified
258        whenever the state of any supported feature might have changed.</p>
259
260        <p>For instance, imagine a form whose current row has just been moved to another
261        record, using the <member>execute</member> method. This means that potentially, the state
262        of all movement-related features might have changed.</p>
263
264        <p>Note that the instance does not actually notify changes in the feature states, but only
265        <em>potential</em> changes: It's up to the callee to react on this appropriately. This is
266        since OpenOffice.org's application framework features own mechanisms to cache and invalidate
267        feature states, so we do not burden this implementation here with such mechanisms.</p>
268
269        @see FormFeature
270    */
271    [attribute] XFeatureInvalidation    FeatureInvalidation;
272};
273
274//=============================================================================
275
276}; }; }; }; };
277
278//=============================================================================
279
280#endif
281