INTEGRATION: CWS dba23b (1.11.28); FILE MERGED

2007/07/08 20:34:27 fs 1.11.28.2: document the property introducing with fixing#i78987#
2007/06/25 08:46:23 fs 1.11.28.1: work around idlc limitation, which does not allow to refer unpublished interfaces as optional entities in published services

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

@@ -4,9 +4,9 @@
  *
  *  $RCSfile: FormController.idl,v $
  *
- *  $Revision: 1.11 $
+ *  $Revision: 1.12 $
  *
- *  last change: $Author: kz $ $Date: 2007-05-10 10:01:34 $
+ *  last change: $Author: rt $ $Date: 2007-07-24 11:57:16 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -79,14 +79,14 @@
 #include <com/sun/star/form/FormControllerDispatcher.idl>
 #endif
 
-#ifndef __com_sun_star_form_runtime_XFormOperations_idl__
-#include <com/sun/star/form/runtime/XFormOperations.idl>
-#endif
-
 //=============================================================================
 
  module com {  module sun {  module star {  module form {
 
+module runtime {
+    published interface XFormOperations;
+};
+
 //=============================================================================
 
 /** specifies a component controlling the interaction between the user and form functionality.
@@ -100,12 +100,37 @@
     contain one or more other <type>FormController</type>s, so the form model structure or hierarchy
     is reflected in the structure of <type>FormController</type>s.</p>
 
+    <h3>Responsibilities</h3>
     <p>A <type>FormController</type> is responsible for a <type scope="com::sun::star::awt">UnoControlContainer</type>,
     and all controls therein.</p>
 
+    <p>Furthermore, a form controller is responsible for preventing invalid user input. That is, if the form
+    contains controls bound to a database, or to an external validator, then the form controller will
+    check their current value when the current record is to be saved to the database.</p>
+
+    <p>First, it will check whether any controls with an external validator exist. If so, those validators
+    will be asked to validate the current control content. If this fails, the message provided by the validator
+    is displayed to the user, the control is focused, and the update of the record is vetoed.</p>
+
+    <p>Second, the controls are examined for NULL values. If a control is bound to a database field which
+    is declared to be <code>NOT NULL</code>, no auto-increment field, but still <NULL/>, then an error
+    message is shown to the user saying that input is required, the respective control is focused, and
+    the update of the record is vetoed.</p>
+
+    <p>Note that you can precent the second check - for database fields containing <NULL/> values - on
+    a per-form and a per-database basis.<br/>
+    For the former, you need to add a boolean property <code>FormsCheckRequiredFields</code> to the form
+    (aka the <code>FormController</code>'s model), using its
+    <member scope="com::sun::star::beans">XPropertyContainer::addProperty</member> method, with a value
+    of <FALSE/>.<br/>
+    For the latter, you need to set the respective property of the data source's <code>Settings</code>
+    (also named <code>FormsCheckRequiredFields</code>) to <FALSE/>.</p>
+
     @see com::sun::star::form::component:Form
     @see com::sun::star::awt::XTabController
- */
+    @see com::sun::star::form::binding::BindableControlModel
+    @see com::sun::star::sdb::DataSource::Settings
+*/
 published service FormController
 {
     /** allows delegating form controller functionality to the component
@@ -121,7 +146,7 @@ published service FormController
 
         <p>This instance can be used, for instance, to determine the current state of certain form features.</p>
     */
-//    [optional, property] ::com::sun::star::form::runtime::XFormOperations FormOperations;
+    [optional, property] ::com::sun::star::form::runtime::XFormOperations FormOperations;
 
     /** is used for notifying the (de)activation of the controller.
      */