offapi/com/sun/star/form/FormController.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: FormController.idl,v $
  10  * $Revision: 1.13 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_form_FormController_idl__
  31 #define __com_sun_star_form_FormController_idl__
  32
  33 #ifndef __com_sun_star_form_XFormController_idl__
  34 #include <com/sun/star/form/XFormController.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_awt_XTabController_idl__
  38 #include <com/sun/star/awt/XTabController.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_container_XChild_idl__
  42 #include <com/sun/star/container/XChild.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_lang_XComponent_idl__
  46 #include <com/sun/star/lang/XComponent.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_container_XEnumerationAccess_idl__
  50 #include <com/sun/star/container/XEnumerationAccess.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_util_XModifyBroadcaster_idl__
  54 #include <com/sun/star/util/XModifyBroadcaster.idl>
  55 #endif
  56
  57 #ifndef __com_sun_star_form_XConfirmDeleteBroadcaster_idl__
  58 #include <com/sun/star/form/XConfirmDeleteBroadcaster.idl>
  59 #endif
  60
  61 #ifndef __com_sun_star_sdb_XSQLErrorBroadcaster_idl__
  62 #include <com/sun/star/sdb/XSQLErrorBroadcaster.idl>
  63 #endif
  64
  65 #ifndef __com_sun_star_sdb_XRowSetApproveBroadcaster_idl__
  66 #include <com/sun/star/sdb/XRowSetApproveBroadcaster.idl>
  67 #endif
  68
  69 #ifndef __com_sun_star_form_XDatabaseParameterBroadcaster_idl__
  70 #include <com/sun/star/form/XDatabaseParameterBroadcaster.idl>
  71 #endif
  72
  73 #ifndef __com_sun_star_form_FormControllerDispatcher_idl__
  74 #include <com/sun/star/form/FormControllerDispatcher.idl>
  75 #endif
  76
  77 //=============================================================================
  78
  79  module com {  module sun {  module star {  module form {
  80
  81 module runtime {
  82     published interface XFormOperations;
  83 };
  84
  85 //=============================================================================
  86
  87 /** specifies a component controlling the interaction between the user and form functionality.
  88
  89     <p>As soon as a form (containing controls) is to be presented to the user,
  90     there is a need for an instance controlling the user interaction.<br/>
  91     Such a <type>FormController</type> is responsible for dialog processing,
  92     like controlling the tab order and the grouping of controls.</p>
  93
  94     <p>As a form may contain one or many subforms, a <type>FormController</type> may
  95     contain one or more other <type>FormController</type>s, so the form model structure or hierarchy
  96     is reflected in the structure of <type>FormController</type>s.</p>
  97
  98     <h3>Responsibilities</h3>
  99     <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>,
 100     and all controls therein.</p>
 101
 102     <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form
 103     contains controls bound to a database, or to an external validator, then the form controller will
 104     check their current value when the current record is to be saved to the database.</p>
 105
 106     <p>First, it will check whether any controls with an external validator exist. If so, those validators
 107     will be asked to validate the current control content. If this fails, the message provided by the validator
 108     is displayed to the user, the control is focused, and the update of the record is vetoed.</p>
 109
 110     <p>Second, the controls are examined for NULL values. If a control is bound to a database field which
 111     is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error
 112     message is shown to the user saying that input is required, the respective control is focused, and
 113     the update of the record is vetoed.</p>
 114
 115     <p>Note that you can precent the second check - for database fields containing <NULL/> values - on
 116     a per-form and a per-database basis.<br/>
 117     For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form
 118     (aka the <code>FormController</code>'s model), using its
 119     <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value
 120     of <FALSE/>.<br/>
 121     For the latter, you need to set the respective property of the data source's <code>Settings</code>
 122     (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p>
 123
 124     <p>Alternatively, you can prevent the check on a per-control basis, using the
 125     <member>DataAwareControlModel::InputRequired</member> property of a single control model.</p>
 126
 127     @see com::sun::star::form::component:Form
 128     @see com::sun::star::awt::XTabController
 129     @see com::sun::star::form::binding::BindableControlModel
 130     @see com::sun::star::sdb::DataSource::Settings
 131 */
 132 published service FormController
 133 {
 134     /** allows delegating form controller functionality to the component
 135
 136         <p>If a control which the controller is responsible for supports the <type scope="com::sun::star::frame">XDispatchProviderInterception</type>
 137         interface, the controller registers a dispatch interceptor. Then, the control can try to delegate part of its
 138         functionality to the controller by querying the dispatch interceptor for it.</p>
 139     */
 140     [optional] service FormControllerDispatcher;
 141
 142     /** denotes the instance which is used to implement operations on the form which the controller
 143         works for.
 144
 145         <p>This instance can be used, for instance, to determine the current state of certain form features.</p>
 146     */
 147     [optional, property] ::com::sun::star::form::runtime::XFormOperations FormOperations;
 148
 149     /** is used for notifying the (de)activation of the controller.
 150      */
 151     interface com::sun::star::form::XFormController;
 152
 153
 154     /** is used for tab controlling and grouping of the controls.
 155      */
 156     interface com::sun::star::awt::XTabController;
 157
 158
 159     /** A FormController may have a parent controller, such as when the related form is a subform.
 160      */
 161     interface com::sun::star::container::XChild;
 162
 163
 164     /** A FormController must be disposable.
 165      */
 166     interface com::sun::star::lang::XComponent;
 167
 168
 169     /** A FormController must provide access to its sub controllers.
 170      */
 171     interface com::sun::star::container::XEnumerationAccess;
 172
 173
 174     /** A FormController must communicate if any of its children (means sub controllers) or contained
 175         controls have been modified.
 176      */
 177     interface com::sun::star::util::XModifyBroadcaster;
 178
 179     /** used to notify deletions of data in the form before they happen.
 180
 181         <p>A form controller listens for deletion events at the form it is responsible for.<br/>
 182         If and only if no <type>XConfirmDeleteListener</type> is registered at
 183         the controller, it uses an own dialog to ask the user for confirmation.</p>
 184
 185         <p>You may use this interface to integrate your own confirmation dialogs.</p>
 186     */
 187     interface com::sun::star::form::XConfirmDeleteBroadcaster;
 188
 189     /** used to notify errors which happen in the form the controller is responsible for.
 190
 191         <p>A form controller listens for error events at the form it is responsible for.<br/>
 192         If and only if no <type scope="com::sun::star::sdb">XSQLErrorListener</type> is registered at the controller, it
 193         uses an own dialog to notify the user of the error.</p>
 194
 195     */
 196     interface com::sun::star::sdb::XSQLErrorBroadcaster;
 197
 198     /** is used for multiplexing row set events happening on the form which the controller is responsible for.
 199     */
 200     interface com::sun::star::sdb::XRowSetApproveBroadcaster;
 201
 202     /** is used broadcasting parameter events in the form.
 203
 204         <p>A form controller listens for parameter events at the form it is responsible for.<br/>
 205         If and only if no <type>XDatabaseParameterListener</type> is registered at the controller, it
 206         uses an own dialog to ask the user for parameter values.</p>
 207     */
 208     interface com::sun::star::form::XDatabaseParameterBroadcaster;
 209 };
 210
 211 //=============================================================================
 212
 213 }; }; }; };
 214
 215 /*=============================================================================
 216
 217 =============================================================================*/
 218 #endif