INTEGRATION: CWS formdesign01 (1.8.228); FILE MERGED

2004/01/09 12:31:20 fs 1.8.228.1: slightly enhanced documentation for sub form functionality

1 files changed, 35 insertions, 12 deletions

diff --git a/offapi/com/sun/star/form/component/DataForm.idl b/offapi/com/sun/star/form/component/DataForm.idl
index 0ee7947ecd62..da2a3a1ea9ca 100644
--- a/offapi/com/sun/star/form/component/DataForm.idl
+++ b/offapi/com/sun/star/form/component/DataForm.idl
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: DataForm.idl,v $
  *
- *  $Revision: 1.8 $
+ *  $Revision: 1.9 $
  *
- *  last change: $Author: hr $ $Date: 2003-03-26 13:54:05 $
+ *  last change: $Author: obo $ $Date: 2004-03-19 12:24:52 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -160,20 +160,43 @@ service DataForm
     interface com::sun::star::form::XDatabaseParameterBroadcaster;
 
     //-------------------------------------------------------------------------
-    /**is used for subforms and contains the names of columns of the parent form.
-       <p> These columns are typically the foreign key fields of the parent form.
-       The values of theses columns are used to identify the data for the subform.
-       Each time the parent form changes it's current row, the subform requeries
-       it's data based on the values of the master fields.
+    /** is used for subforms and contains the names of columns of the parent form.
+
+        <p> These columns are typically the foreign key fields of the parent form.
+        The values of theses columns are used to identify the data for the subform.
+        Each time the parent form changes it's current row, the subform requeries
+        it's data based on the values of the master fields.</p>
+
+        <p>If the form is no sub form (e.g. it's parent is not a form itself), this
+        property is not evaluated.</p>
     */
     [property] sequence<string> MasterFields;
 
     //-------------------------------------------------------------------------
-    /**is used for subforms and contains the names of the columns of the subform
-       which are related to the master fields of the parent form.
-       <p> These columns represent typically a part of the primary key fields or their aliases
-       of the detail form and are used as parameters in a database query to retrieve
-       the details for an according master form.
+    /** is used for subforms and contains the names of the columns of the subform
+        which are related to the master fields of the parent form.
+
+        <p>Entries in this sequence can either denote column names in the sub form,
+        or paramater names.<br/>
+        For instance, you could base the form on the SQL statement
+        <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code>
+        to the DetailFields property. In this case, the parameter will be filled from
+        the corresponding master field.<br/>
+        Alternatively, you could simply base your form on the table <code>invoices</code>,
+        and add the column name <code>cust_ref</code> to the DetailFields. In this case,
+        and implicit filter clause <code>WHERE cust_ref = :&lt;new_param_name&gt;</code> will
+        be created, and the artificial parameter will be filled from the corresponding
+        master field.<br/>
+        If a string in this property denotes both a column name and a parameter name, it
+        is undefined which way it is interpreted, but implementations of the service are required
+        to either decide for the paramter or the column, and proceed as usual.
+        </p>
+
+        <p>The columns specified herein typically represent a part of the primary key
+        fields or their aliases of the detail form.</p>
+
+        <p>If the form is no sub form (e.g. it's parent is not a form itself), this
+        property is not evaluated.</p>
     */
     [property] sequence<string> DetailFields;