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