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