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