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