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 __offapi_com_sun_star_form_runtime_XFormController_idl__
25#define __offapi_com_sun_star_form_runtime_XFormController_idl__
26
27#include <com/sun/star/awt/XTabController.idl>
28#include <com/sun/star/container/XChild.idl>
29#include <com/sun/star/lang/XComponent.idl>
30#include <com/sun/star/container/XIndexAccess.idl>
31#include <com/sun/star/container/XEnumerationAccess.idl>
32#include <com/sun/star/util/XModifyBroadcaster.idl>
33#include <com/sun/star/util/XModeSelector.idl>
34#include <com/sun/star/form/XConfirmDeleteBroadcaster.idl>
35#include <com/sun/star/sdb/XSQLErrorBroadcaster.idl>
36#include <com/sun/star/sdb/XRowSetApproveBroadcaster.idl>
37#include <com/sun/star/form/XDatabaseParameterBroadcaster2.idl>
38#include <com/sun/star/form/XFormControllerListener.idl>
39#include <com/sun/star/task/XInteractionHandler.idl>
40#include <com/sun/star/lang/IllegalArgumentException.idl>
41#include <com/sun/star/form/runtime/XFilterController.idl>
42
43//=============================================================================
44
45module com { module sun { module star { module form { module runtime {
46
47interface XFormOperations;
48interface XFormControllerContext;
49
50//=============================================================================
51
52/** specifies a component controlling the interaction between the user and form functionality.
53
54	<p>As soon as a form (containing controls) is to be presented to the user,
55	there is a need for an instance controlling the user interaction.<br/>
56	Such a <code>FormController</code> is responsible for dialog processing,
57	like controlling the tab order and the grouping of controls.</p>
58
59	<p>As a form may contain one or many subforms, a <type>FormController</type> may
60	contain one or more other <type>FormController</type>s, so the form model structure or hierarchy
61	is reflected in the structure of <type>FormController</type>s. That is, retrieving the parent of
62    the model of a controller will give you the same object as retrieving the model of the parent of
63    the controller. Similarly, retrieving the model of the <code>n</code><sup>th</sup> child of
64    a controller gives you the same object as retrieving the <code>n</code><sup>th</sup> child of
65    the model of the controller.</p>
66
67	<p>A controller is called <em>active</em> if one of the controls it is responsible for has the focus,
68	else inactive. To be notified whenever this activation state of a given controller changes, you can
69	add listeners.</p>
70
71    <p>This interface supersedes the <type scope="com::sun::star::form">FormController</type>.</p>
72
73	<h3>Responsibilities</h3>
74    <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>,
75    and all controls therein.</p>
76
77    <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form
78    contains controls bound to a database, or to an external validator, then the form controller will
79    check their current value when the current record is to be saved to the database.</p>
80
81    <p>First, it will check whether any controls with an external validator exist. If so, those validators
82    will be asked to validate the current control content. If this fails, the message provided by the validator
83    is displayed to the user, the control is focused, and the update of the record is vetoed.</p>
84
85    <p>Second, the controls are examined for NULL values. If a control is bound to a database field which
86    is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error
87    message is shown to the user saying that input is required, the respective control is focused, and
88    the update of the record is vetoed.</p>
89
90    <p>Note that you can precent the second check - for database fields containing <NULL/> values - on
91    a per-form and a per-database basis.<br/>
92    For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form
93    (aka the <code>FormController</code>'s model), using its
94    <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value
95    of <FALSE/>.<br/>
96    For the latter, you need to set the respective property of the data source's <code>Settings</code>
97    (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p>
98
99    <p>Alternatively, you can prevent the check on a per-control basis, using the
100    <member>DataAwareControlModel::InputRequired</member> property of a single control model.</p>
101
102    <p>If a control which the controller is responsible for supports the <type scope="com::sun::star::frame">XDispatchProviderInterception</type>
103    interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its
104    functionality to the controller by querying the dispatch interceptor for it.</p>
105
106    <p>Below, there's a list of URLs which have a defined meaning - if an implementation supports one of them,
107    there must be a guaranteed semantices. However, concrete implementations may support an arbitrary sub or super
108    set of these URLs.</p>
109
110    <p>In general, all URLs start with the same prefix, namely <em>.uno:FormController/</em>. To this, a suffix is
111    appended which describes the requested functionality.<br/>
112    Example: The URL suffix for deleting the current record is <em>deleteRecord</em>, so the complete URL for
113    requesting a dispatcher for this functionality is <em>.uno:FormController/deleteRecord</em>.</p>
114
115    <p>Some URLs may require parameters. For this, the sequence of <type scope="com::sun::star::beans">PropertyValue</type>s
116    passed to the <member scope="com::sun::star::frame">XDispatch::dispatch</member> call is used - every property value is
117    used as one named parameter.</p>
118
119    <p>For all URLs, interested parties can register as status listeners (<type scope="com::sun::star::frame">XStatusListener</type>)
120    at the dispatchers, and be notified whenever the functionality associated with the URL becomes enabled or
121    disabled.<br/>
122    For instance, the URL with the suffix <em>moveToFirst</em> is associated with moving the form to the first
123    record, and it will be disabled in case the form is already positioned on the first record.</p>
124
125    <table style="width:100%;" border="0" cellpadding="2" cellspacing="2"><tbody>
126
127      <tr style="vertical-align: top;">
128        <td><b>URL suffix</b></td>
129        <td><b>functionality</b></td>
130      </tr>
131
132      <tr style="vertical-align: top;">
133        <td><em>positionForm</em></td>
134        <td>positions the form on a record given by absolute number.<br/>
135        There's one parameter for this functionality, named <em>Position</em>, which must be a long
136        value specifying the absolute position to which the form should be moved</td>
137      </tr>
138
139      <tr style="vertical-align: top;">
140        <td><em>RecordCount</em></td>
141        <td>This is a passive functionality: It cannot be dispatched, instead, interested parties may
142        use the dispatcher to add as <type scope="com::sun::star::frame">XStatusListener</type>, and be
143        notified when the record count changes.<br/>
144        The status value which is being notified (<member scope="com::sun::star::frame">FeatureStateEvent::State</member>)
145        is a string which can be used to display the record count. In particular, if the record count is not yet known
146        (<member scope="com::sun::star::sdb">RowSet::IsRowCountFinal</member> is <FALSE/>), this is indicated in the
147        string, too.</td>
148      </tr>
149
150      <tr style="vertical-align: top;">
151        <td><em>moveToFirst</em></td>
152        <td>moves the form to the first record</td>
153      </tr>
154
155      <tr style="vertical-align: top;">
156        <td><em>moveToPrev</em></td>
157        <td>moves the form to the record preceding the current one</td>
158      </tr>
159
160      <tr style="vertical-align: top;">
161        <td><em>moveToNext</em></td>
162        <td>moves the form to the record after the current one</td>
163      </tr>
164
165      <tr style="vertical-align: top;">
166        <td><em>moveToLast</em></td>
167        <td>moves the form to the last record</td>
168      </tr>
169
170      <tr style="vertical-align: top;">
171        <td><em>moveToNew</em></td>
172        <td>moves the form to the virtual "insert row", where new records can be inserted</td>
173      </tr>
174
175      <tr style="vertical-align: top;">
176        <td><em>saveRecord</em></td>
177        <td>Commits any potentially pending changes in the current control, and saves the current record to
178        the database, or inserts a new record if the form is currently positioned on the virtual insertion row.</td>
179      </tr>
180
181      <tr style="vertical-align: top;">
182        <td><em>undoRecord</em></td>
183        <td>reverts the changes done to the current record. Basically, this means refreshing the
184        current row from the database, and updating all controls with the new content.</td>
185      </tr>
186
187      <tr style="vertical-align: top;">
188        <td><em>deleteRecord</em></td>
189        <td>deletes the current record, after asking the user for confirmation.</td>
190      </tr>
191
192      <tr style="vertical-align: top;">
193        <td><em>refreshForm</em></td>
194        <td>reloads the complete form. After this, the form is positioned on the first record</td>
195      </tr>
196
197      <tr style="vertical-align: top;">
198        <td><em>sortUp</em></td>
199        <td>Adds an order clause to the form, to sort it ascending by the field which the current control is bound to,
200        and then reloads the form.</td>
201      </tr>
202
203      <tr style="vertical-align: top;">
204        <td><em>sortDown</em></td>
205        <td>Adds an order clause to the form, to sort it descending by the field which the current control is bound to,
206        and then reloads the form.</td>
207      </tr>
208
209      <tr style="vertical-align: top;">
210        <td><em>sort</em></td>
211        <td>opens an dialog, which allows the user to manipulate the current sorting order of the form. If the dialog
212        is closed with OK, the form is reloaded after setting the new sorting order.</td>
213      </tr>
214
215      <tr style="vertical-align: top;">
216        <td><em>autoFilter</em></td>
217        <td>creates, from the current control, a filter for the form. This is, if the current control is bound to
218        the field, say, "customer", and contains the value "Furs, Inc.", then a filter "customer = 'Furs, Inc.'"
219        is created and set at the form. After this, the form is reloaded.</td>
220      </tr>
221
222      <tr style="vertical-align: top;">
223        <td><em>filter</em></td>
224        <td>opens an dialog, which allows the user to manipulate the current filter of the form. If the dialog
225        is closed with OK, the form is reloaded after setting the new filter.</td>
226      </tr>
227
228      <tr style="vertical-align: top;">
229        <td><em>applyFilter</em></td>
230        <td><p>Toggles the <member scope="com::sun::star::sdb">RowSet::ApplyFilter</member> property
231        of the form.</p>
232        <p>Additionally, status listeners will be provided with the current (boolean) state of this property
233        in the <member scope="com::sun::star::frame">FeatureStateEvent::State</member> member of the event
234        notified by the dispatcher.</p></td>
235      </tr>
236
237      <tr style="vertical-align: top;">
238        <td><em>removeFilterOrder</em></td>
239        <td>completely removes any filter and sorting order from the form, and reloads it.</td>
240      </tr>
241
242    </tbody></table>
243
244    @see ::com::sun::star::form::component:Form
245    @see ::com::sun::star::form::binding::BindableControlModel
246    @see ::com::sun::star::sdb::DataSource::Settings
247
248    @since OpenOffice 3.3
249 */
250interface XFormController
251{
252	/** is used for tab controlling and grouping of the controls.
253
254        <p>The model obtained via <member scope="com::sun::star::awt">XTabController::getModel</member> is the form for which the
255        controller is responsible.</p>
256	 */
257	interface ::com::sun::star::awt::XTabController;
258
259    /** allows access to the parent controller.
260	 */
261	interface ::com::sun::star::container::XChild;
262
263	/** allows access to the sub controllers.
264	 */
265	interface ::com::sun::star::container::XIndexAccess;
266
267    /** allows enumerating sub controllers
268     */
269    interface ::com::sun::star::container::XEnumerationAccess;
270
271    /** allows life time control of the controller.
272	 */
273	interface ::com::sun::star::lang::XComponent;
274
275    /** allows to register as listener for modifications in the controls which the controller is responsible
276        for.
277     */
278    interface ::com::sun::star::util::XModifyBroadcaster;
279
280    /** used to notify deletions of data in the form before they happen.
281
282		<p>A form controller listens for deletion events at the form it is responsible for. If and only if no
283        <type scope="com::sun::star::form">XConfirmDeleteListener</type> is registered at
284		the controller, it uses an own dialog to ask the user for confirmation.</p>
285	*/
286    interface ::com::sun::star::form::XConfirmDeleteBroadcaster;
287
288	/** is used to notify errors which happen in the form the controller is responsible for.
289
290		<p>A form controller listens for error events at the form it is responsible for. If and only if no
291        <type scope="com::sun::star::sdb">XSQLErrorListener</type> is registered at the controller, it
292		uses an own dialog to notify the user of the error.</p>
293
294	*/
295	interface ::com::sun::star::sdb::XSQLErrorBroadcaster;
296
297    /** is used for multiplexing row set events happening on the form which the controller is responsible for.
298	*/
299	interface ::com::sun::star::sdb::XRowSetApproveBroadcaster;
300
301    /** is used broadcasting parameter events in the form.
302
303		<p>A form controller listens for parameter events at the form it is responsible for. If and only if no
304        <type scope="com::sun::star::form">XDatabaseParameterListener</type> is registered at the controller, it
305        uses an own dialog to ask the user for parameter values.</p>
306	*/
307	interface ::com::sun::star::form::XDatabaseParameterBroadcaster2;
308
309    /** allows switching the form controller to different operation modes.
310
311        <a name="mode_selector"></a>
312        <p>The two modes usually (but not necessarily) supported by a form controller are the <code>DataMode</code>
313        and the <code>FilterMode</code>, where the former is the usual modus operandi for displaying and modifying
314        data, and the latter is a special mode to enter a filter for the database form which the controller is
315        responsible for.</p>
316    */
317    interface ::com::sun::star::util::XModeSelector;
318
319    /** allows controlling the filter mode.
320
321        <p>If the form controller supports a <a href="#mode_selector">form based filter mode</a>, then it shall also
322        support the <type>XFilterController</type> interface, which allows controlling this mode.</p>
323    */
324    [optional] interface XFilterController;
325
326    /** denotes the instance which is used to implement operations on the form which the controller
327        works for.
328
329        <p>This instance can be used, for instance, to determine the current state of certain form features.</p>
330    */
331    [attribute, readonly] XFormOperations FormOperations;
332
333	/** provicdes access to the currently active control
334      */
335    [attribute, readonly] ::com::sun::star::awt::XControl CurrentControl;
336
337    /** allows to delegate certain tasks to the context of the form controller
338    */
339    [attribute] XFormControllerContext  Context;
340
341    /** used (if not <NULL/>) for user interactions triggered by the form controller.
342    */
343    [attribute] ::com::sun::star::task::XInteractionHandler InteractionHandler;
344
345    /** adds the specified listener to receive notifications whenever the activation state of
346		the controller changes.
347	 */
348    void addActivateListener( [in] ::com::sun::star::form::XFormControllerListener _Listener );
349
350    /** removes the specified listener from the list of components to receive notifications whenever the activation
351        state of the controller changes.
352	 */
353    void removeActivateListener( [in] ::com::sun::star::form::XFormControllerListener _Listener );
354
355    /** adds a controller to the list of child controllers
356        @throws ::com::sun::star::lang::IllegalArgumentException
357            if the given controller is <NULL/>, or cannot rightfully be a child controller. Since controllers
358            mirror the hierarchy of the forms the are responsible for, this means that the form of the given
359            child controller must be a child of the controller at which the method is invoked.
360    */
361    void addChildController( [in] XFormController _ChildController )
362        raises ( ::com::sun::star::lang::IllegalArgumentException );
363};
364
365//=============================================================================
366
367}; }; }; }; };
368
369//=============================================================================
370
371#endif
372