offapi/com/sun/star/form/component/DataForm.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: DataForm.idl,v $
  10  * $Revision: 1.14 $
  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_component_DataForm_idl__
  31 #define __com_sun_star_form_component_DataForm_idl__
  32
  33 #ifndef __com_sun_star_form_component_Form_idl__
  34 #include <com/sun/star/form/component/Form.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_sdb_RowSet_idl__
  38 #include <com/sun/star/sdb/RowSet.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_form_TabulatorCycle_idl__
  42 #include <com/sun/star/form/TabulatorCycle.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_form_NavigationBarMode_idl__
  46 #include <com/sun/star/form/NavigationBarMode.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_form_XLoadable_idl__
  50 #include <com/sun/star/form/XLoadable.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_sdb_XCompletedExecution_idl__
  54 #include <com/sun/star/sdb/XCompletedExecution.idl>
  55 #endif
  56
  57 #ifndef __com_sun_star_awt_TabControllerModel_idl__
  58 #include <com/sun/star/awt/TabControllerModel.idl>
  59 #endif
  60
  61 //=============================================================================
  62
  63 module com { module sun { module star { module form {
  64
  65  published interface XReset;
  66  published interface XDatabaseParameterBroadcaster;
  67
  68 module component {
  69 //=============================================================================
  70 /** This service specifies a form which is connected to a database and
  71     displays the results of SQL queries. It provides the possiblity of
  72     adding new data records, modifying existing ones, or deleting them.
  73
  74     <p>A database form is a special kind of enhanced database row set
  75     which provides all information for displaying the data and has more
  76     possibilities for configuring the data manipulation.</p>
  77
  78 */
  79 published service DataForm
  80 {
  81     service com::sun::star::sdb::RowSet;
  82     service com::sun::star::form::component::Form;
  83
  84     /** is used to reset controls belonging to the form, and to reset database fields to which the
  85         controls are bound
  86
  87         <p>A <type>DataForm</type> is reset either on explicit request, or after it is moved
  88         to the insertion row.</p>
  89
  90         <p>The insertion row is a virtual row which is used to insert new records. It is reached
  91         by calling <member scope="com::sun::star::sdbc">XResultSetUpdate::moveToInsertRow</member>.
  92         The <type scope="com::sun::star::sdb">RowSet</type> service specifies exactly which notifications
  93         happen in which order when calling <member scope="com::sun::star::sdbc">XResultSetUpdate::moveToInsertRow</member>,
  94         and a <type>DataForm</type> implementation extends this with the following contract:
  95         <ul><li>After all notifications as defined in the <type scope="com::sun::star::sdb">RowSet</type>
  96                 service have been sent, the <type>DataForm</type> resets itself, if all
  97                 <type scope="com::sun::star::form">XResetListeners</type> approve this.</li>
  98             <li>After the reset happened, the <member scope="com::sun::star::sdb">RowSet::IsModified</member>
  99                 property is reset to <FALSE/>. This property might have been switched to <TRUE/> during listener
 100                 notifications, since listeners are allowed to change field values. Also, the
 101                 <member scope="com::sun::star::form">XReset::reset</member> implementations of bound control
 102                 models might have modified the fields they're bound to (by filling them with default values).</li>
 103             <li>The reset listeners are notified of the completed reset operation.</li>
 104         </ul></p>
 105     */
 106     interface com::sun::star::form::XReset;
 107
 108     /** used to load/unload the form
 109         <p>Loading a form is basically the same as executing the underlying row set. In fact, all the
 110         functionality of this interface could be simulated by using setting some properties manually,
 111         <member scope="com::sun::star::sdbc">XRowSet::execute</member>, moving the row set cursor and so on.</p>
 112
 113         <p>One main difference between <member>XLoadable::load</member> and <member scope="com::sun::star::sdbc">XRowSet::execute</member>
 114         is that if you use the former, the row set is positioned on the first record, while in the latter case
 115         it is position <em>before</em> the it.</p>
 116     */
 117     interface com::sun::star::form::XLoadable;
 118
 119     /** can be used to allow an interaction handler to supply missing data during a load process.
 120
 121         <p>If data is needed during loading a form, then this is usually obtained via broadcaster-listener
 122         mechanisms. An example for this (and currently the only one) are parameter values.</p>
 123         <p>However, if you use this method, you can pass an interaction handler which should supply these
 124         additional data.</p>
 125
 126         @see com::sun::star::sdb::InteractionHandler
 127     */
 128     interface com::sun::star::sdb::XCompletedExecution;
 129
 130     /** can be used for filling parameters.
 131
 132         <p>You can add your component as
 133         <type scope="com::sun::star::form">XDatabaseParameterListener</type>
 134         to a form to get notified whenever the form needs parameter values to be filled in<br/>
 135         In a first approach, the form tries to fill any parameters from it's master-detail relation
 136         (if any). All values which can't be filled are then passed to all listeners, which can
 137         fill them by their own choice.</p>
 138
 139         <p>This is sligtly changed if the form is loaded using the
 140         <member scope="com::sun::star::sdb">XCompletedExecution::connectWithCompletion</member> method. In this case, the parameters
 141         are obtained from the interaction handler, not from the listeners</p>
 142
 143         @see XCompletedExecution
 144         @see MasterFields
 145         @see DetailFields
 146     */
 147     interface com::sun::star::form::XDatabaseParameterBroadcaster;
 148
 149     //-------------------------------------------------------------------------
 150     /** is used for subforms and contains the names of columns of the parent form.
 151
 152         <p> These columns are typically the foreign key fields of the parent form.
 153         The values of theses columns are used to identify the data for the subform.
 154         Each time the parent form changes it's current row, the subform requeries
 155         it's data based on the values of the master fields.</p>
 156
 157         <p>If the form is no sub form (e.g. it's parent is not a form itself), this
 158         property is not evaluated.</p>
 159     */
 160     [property] sequence<string> MasterFields;
 161
 162     //-------------------------------------------------------------------------
 163     /** is used for subforms and contains the names of the columns of the subform
 164         which are related to the master fields of the parent form.
 165
 166         <p>Entries in this sequence can either denote column names in the sub form,
 167         or paramater names.<br/>
 168         For instance, you could base the form on the SQL statement
 169         <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code>
 170         to the DetailFields property. In this case, the parameter will be filled from
 171         the corresponding master field.<br/>
 172         Alternatively, you could simply base your form on the table <code>invoices</code>,
 173         and add the column name <code>cust_ref</code> to the DetailFields. In this case,
 174         and implicit filter clause <code>WHERE cust_ref = :&lt;new_param_name&gt;</code> will
 175         be created, and the artificial parameter will be filled from the corresponding
 176         master field.<br/>
 177         If a string in this property denotes both a column name and a parameter name, it
 178         is undefined which way it is interpreted, but implementations of the service are required
 179         to either decide for the paramter or the column, and proceed as usual.
 180         </p>
 181
 182         <p>The columns specified herein typically represent a part of the primary key
 183         fields or their aliases of the detail form.</p>
 184
 185         <p>If the form is no sub form (e.g. it's parent is not a form itself), this
 186         property is not evaluated.</p>
 187     */
 188     [property] sequence<string> DetailFields;
 189
 190     //-------------------------------------------------------------------------
 191     /** returns the kind of tabulator controlling.
 192     */
 193     [property] com::sun::star::form::TabulatorCycle Cycle;
 194
 195     //-------------------------------------------------------------------------
 196     /** determines how an navigation bar for this form should act.
 197     */
 198     [property] com::sun::star::form::NavigationBarMode NavigationBarMode;
 199
 200     //-------------------------------------------------------------------------
 201     /** determines if insertions into the form's row set are allowed.
 202
 203         <p>Note that this is a recommendation for user interface components displaying the
 204         form. Form implementations may decide to allow for insertions done via the API, even
 205         if the property is set to <FALSE/>, but the user interface should respect the property
 206         value.</p>
 207     */
 208     [property] boolean AllowInserts;
 209
 210     //-------------------------------------------------------------------------
 211     /** determines if modifications of the current record of the form are allowed.
 212
 213         <p>Note that this is a recommendation for user interface components displaying the
 214         form. Form implementations may decide to allow for updates done via the API, even
 215         if the property is set to <FALSE/>, but the user interface should respect the property
 216         value.</p>
 217     */
 218     [property] boolean AllowUpdates;
 219
 220     //-------------------------------------------------------------------------
 221     /** determines if deletions of records of the form are allowed.
 222
 223         <p>Note that this is a recommendation for user interface components displaying the
 224         form. Form implementations may decide to allow for deletions done via the API, even
 225         if the property is set to <FALSE/>, but the user interface should respect the property
 226         value.</p>
 227     */
 228     [property] boolean AllowDeletes;
 229 };
 230
 231 //=============================================================================
 232
 233 }; }; }; }; };
 234
 235 #endif