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