offapi/com/sun/star/form/component/DataForm.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_form_component_DataForm_idl__
  20 #define __com_sun_star_form_component_DataForm_idl__
  21
  22 #include <com/sun/star/form/component/Form.idl>
  23 #include <com/sun/star/sdb/RowSet.idl>
  24 #include <com/sun/star/form/TabulatorCycle.idl>
  25 #include <com/sun/star/form/NavigationBarMode.idl>
  26 #include <com/sun/star/form/XLoadable.idl>
  27 #include <com/sun/star/sdb/XCompletedExecution.idl>
  28 #include <com/sun/star/awt/TabControllerModel.idl>
  29
  30
  31 module com { module sun { module star { module form {
  32
  33  published interface XReset;
  34  published interface XDatabaseParameterBroadcaster;
  35
  36 module component {
  37 /** This service specifies a form which is connected to a database and
  38     displays the results of SQL queries. It provides the possibility of
  39     adding new data records, modifying existing ones, or deleting them.
  40
  41     <p>A database form is a special kind of enhanced database row set
  42     which provides all information for displaying the data and has more
  43     possibilities for configuring the data manipulation.</p>
  44
  45 */
  46 published service DataForm
  47 {
  48     service com::sun::star::sdb::RowSet;
  49     service com::sun::star::form::component::Form;
  50
  51     /** is used to reset controls belonging to the form, and to reset database fields to which the
  52         controls are bound
  53
  54         <p>A DataForm is reset either on explicit request, or after it is moved
  55         to the insertion row.</p>
  56
  57         <p>The insertion row is a virtual row which is used to insert new records. It is reached
  58         by calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow().
  59         The com::sun::star::sdb::RowSet service specifies exactly which notifications
  60         happen in which order when calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow(),
  61         and a DataForm implementation extends this with the following contract:
  62         <ul><li>After all notifications as defined in the com::sun::star::sdb::RowSet
  63                 service have been sent, the DataForm resets itself, if all
  64                 com::sun::star::form::XResetListeners approve this.</li>
  65             <li>After the reset happened, the com::sun::star::sdb::RowSet::IsModified
  66                 property is reset to `FALSE`. This property might have been switched to `TRUE` during listener
  67                 notifications, since listeners are allowed to change field values. Also, the
  68                 com::sun::star::form::XReset::reset() implementations of bound control
  69                 models might have modified the fields they're bound to (by filling them with default values).</li>
  70             <li>The reset listeners are notified of the completed reset operation.</li>
  71         </ul></p>
  72     */
  73     interface com::sun::star::form::XReset;
  74
  75     /** used to load/unload the form
  76         <p>Loading a form is basically the same as executing the underlying row set. In fact, all the
  77         functionality of this interface could be simulated by using setting some properties manually,
  78         com::sun::star::sdbc::XRowSet::execute(), moving the row set cursor and so on.</p>
  79
  80         <p>One main difference between XLoadable::load() and com::sun::star::sdbc::XRowSet::execute()
  81         is that if you use the former, the row set is positioned on the first record, while in the latter case
  82         it is position <em>before</em> the it.</p>
  83     */
  84     interface com::sun::star::form::XLoadable;
  85
  86     /** can be used to allow an interaction handler to supply missing data during a load process.
  87
  88         <p>If data is needed during loading a form, then this is usually obtained via broadcaster-listener
  89         mechanisms. An example for this (and currently the only one) are parameter values.</p>
  90         <p>However, if you use this method, you can pass an interaction handler which should supply these
  91         additional data.</p>
  92
  93         @see com::sun::star::sdb::InteractionHandler
  94     */
  95     interface com::sun::star::sdb::XCompletedExecution;
  96
  97     /** can be used for filling parameters.
  98
  99         <p>You can add your component as
 100         com::sun::star::form::XDatabaseParameterListener
 101         to a form to get notified whenever the form needs parameter values to be filled in<br/>
 102         In a first approach, the form tries to fill any parameters from its master-detail relation
 103         (if any). All values which can't be filled are then passed to all listeners, which can
 104         fill them by their own choice.</p>
 105
 106         <p>This is slightly changed if the form is loaded using the
 107         com::sun::star::sdb::XCompletedExecution::connectWithCompletion() method. In this case, the parameters
 108         are obtained from the interaction handler, not from the listeners</p>
 109
 110         @see XCompletedExecution
 111         @see MasterFields
 112         @see DetailFields
 113     */
 114     interface com::sun::star::form::XDatabaseParameterBroadcaster;
 115
 116     /** is used for subforms and contains the names of columns of the parent form.
 117
 118         <p> These columns are typically the foreign key fields of the parent form.
 119         The values of theses columns are used to identify the data for the subform.
 120         Each time the parent form changes its current row, the subform requeries
 121         it's data based on the values of the master fields.</p>
 122
 123         <p>If the form is no sub form (e.g. its parent is not a form itself), this
 124         property is not evaluated.</p>
 125     */
 126     [property] sequence<string> MasterFields;
 127
 128     /** is used for subforms and contains the names of the columns of the subform
 129         which are related to the master fields of the parent form.
 130
 131         <p>Entries in this sequence can either denote column names in the sub form,
 132         or parameter names.<br/>
 133         For instance, you could base the form on the SQL statement
 134         <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code>
 135         to the DetailFields property. In this case, the parameter will be filled from
 136         the corresponding master field.<br/>
 137         Alternatively, you could simply base your form on the table <code>invoices</code>,
 138         and add the column name <code>cust_ref</code> to the DetailFields. In this case,
 139         and implicit filter clause <code>WHERE cust_ref = :&lt;new_param_name&gt;</code> will
 140         be created, and the artificial parameter will be filled from the corresponding
 141         master field.<br/>
 142         If a string in this property denotes both a column name and a parameter name, it
 143         is undefined which way it is interpreted, but implementations of the service are required
 144         to either decide for the parameter or the column, and proceed as usual.
 145         </p>
 146
 147         <p>The columns specified herein typically represent a part of the primary key
 148         fields or their aliases of the detail form.</p>
 149
 150         <p>If the form is no sub form (e.g. its parent is not a form itself), this
 151         property is not evaluated.</p>
 152     */
 153     [property] sequence<string> DetailFields;
 154
 155     /** returns the kind of tabulator controlling.
 156     */
 157     [property] com::sun::star::form::TabulatorCycle Cycle;
 158
 159     /** determines how an navigation bar for this form should act.
 160     */
 161     [property] com::sun::star::form::NavigationBarMode NavigationBarMode;
 162
 163     /** determines if insertions into the form's row set are allowed.
 164
 165         <p>Note that this is a recommendation for user interface components displaying the
 166         form. Form implementations may decide to allow for insertions done via the API, even
 167         if the property is set to `FALSE`, but the user interface should respect the property
 168         value.</p>
 169     */
 170     [property] boolean AllowInserts;
 171
 172     /** determines if modifications of the current record of the form are allowed.
 173
 174         <p>Note that this is a recommendation for user interface components displaying the
 175         form. Form implementations may decide to allow for updates done via the API, even
 176         if the property is set to `FALSE`, but the user interface should respect the property
 177         value.</p>
 178     */
 179     [property] boolean AllowUpdates;
 180
 181     /** determines if deletions of records of the form are allowed.
 182
 183         <p>Note that this is a recommendation for user interface components displaying the
 184         form. Form implementations may decide to allow for deletions done via the API, even
 185         if the property is set to `FALSE`, but the user interface should respect the property
 186         value.</p>
 187     */
 188     [property] boolean AllowDeletes;
 189 };
 190
 191
 192 }; }; }; }; };
 193
 194 #endif
 195
 196 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */