tdf#130857 qt weld: Implement QtInstanceWidget::strip_mnemonic
[LibreOffice.git] / offapi / com / sun / star / form / component / DataForm.idl
blobed0ff3eb7d1768cd24499d5dacde20aa6ace07c0
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
21 module com { module sun { module star { module form {
23 published interface XReset;
24 published interface XDatabaseParameterBroadcaster;
26 module component {
27 /** This service specifies a form which is connected to a database and
28 displays the results of SQL queries. It provides the possibility of
29 adding new data records, modifying existing ones, or deleting them.
31 <p>A database form is a special kind of enhanced database row set
32 which provides all information for displaying the data and has more
33 possibilities for configuring the data manipulation.</p>
36 published service DataForm
38 service com::sun::star::sdb::RowSet;
39 service com::sun::star::form::component::Form;
41 /** is used to reset controls belonging to the form, and to reset database fields to which the
42 controls are bound
44 <p>A DataForm is reset either on explicit request, or after it is moved
45 to the insertion row.</p>
47 <p>The insertion row is a virtual row which is used to insert new records. It is reached
48 by calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow().
49 The com::sun::star::sdb::RowSet service specifies exactly which notifications
50 happen in which order when calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow(),
51 and a DataForm implementation extends this with the following contract:
52 <ul><li>After all notifications as defined in the com::sun::star::sdb::RowSet
53 service have been sent, the DataForm resets itself, if all
54 com::sun::star::form::XResetListeners approve this.</li>
55 <li>After the reset happened, the com::sun::star::sdb::RowSet::IsModified
56 property is reset to `FALSE`. This property might have been switched to `TRUE` during listener
57 notifications, since listeners are allowed to change field values. Also, the
58 com::sun::star::form::XReset::reset() implementations of bound control
59 models might have modified the fields they're bound to (by filling them with default values).</li>
60 <li>The reset listeners are notified of the completed reset operation.</li>
61 </ul></p>
63 interface com::sun::star::form::XReset;
65 /** used to load/unload the form
66 <p>Loading a form is basically the same as executing the underlying row set. In fact, all the
67 functionality of this interface could be simulated by using setting some properties manually,
68 com::sun::star::sdbc::XRowSet::execute(), moving the row set cursor and so on.</p>
70 <p>One main difference between XLoadable::load() and com::sun::star::sdbc::XRowSet::execute()
71 is that if you use the former, the row set is positioned on the first record, while in the latter case
72 it is position <em>before</em> the it.</p>
74 interface com::sun::star::form::XLoadable;
76 /** can be used to allow an interaction handler to supply missing data during a load process.
78 <p>If data is needed during loading a form, then this is usually obtained via broadcaster-listener
79 mechanisms. An example for this (and currently the only one) are parameter values.</p>
80 <p>However, if you use this method, you can pass an interaction handler which should supply these
81 additional data.</p>
83 @see com::sun::star::sdb::InteractionHandler
85 interface com::sun::star::sdb::XCompletedExecution;
87 /** can be used for filling parameters.
89 <p>You can add your component as
90 com::sun::star::form::XDatabaseParameterListener
91 to a form to get notified whenever the form needs parameter values to be filled in<br/>
92 In a first approach, the form tries to fill any parameters from its master-detail relation
93 (if any). All values which can't be filled are then passed to all listeners, which can
94 fill them by their own choice.</p>
96 <p>This is slightly changed if the form is loaded using the
97 com::sun::star::sdb::XCompletedExecution::connectWithCompletion() method. In this case, the parameters
98 are obtained from the interaction handler, not from the listeners</p>
100 @see XCompletedExecution
101 @see MasterFields
102 @see DetailFields
104 interface com::sun::star::form::XDatabaseParameterBroadcaster;
106 /** is used for subforms and contains the names of columns of the parent form.
108 <p> These columns are typically the foreign key fields of the parent form.
109 The values of these columns are used to identify the data for the subform.
110 Each time the parent form changes its current row, the subform requeries
111 it's data based on the values of the master fields.</p>
113 <p>If the form is no sub form (e.g. its parent is not a form itself), this
114 property is not evaluated.</p>
116 [property] sequence<string> MasterFields;
118 /** is used for subforms and contains the names of the columns of the subform
119 which are related to the master fields of the parent form.
121 <p>Entries in this sequence can either denote column names in the sub form,
122 or parameter names.<br/>
123 For instance, you could base the form on the SQL statement
124 <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code>
125 to the DetailFields property. In this case, the parameter will be filled from
126 the corresponding master field.<br/>
127 Alternatively, you could simply base your form on the table <code>invoices</code>,
128 and add the column name <code>cust_ref</code> to the DetailFields. In this case,
129 and implicit filter clause <code>WHERE cust_ref = :&lt;new_param_name&gt;</code> will
130 be created, and the artificial parameter will be filled from the corresponding
131 master field.<br/>
132 If a string in this property denotes both a column name and a parameter name, it
133 is undefined which way it is interpreted, but implementations of the service are required
134 to either decide for the parameter or the column, and proceed as usual.
135 </p>
137 <p>The columns specified herein typically represent a part of the primary key
138 fields or their aliases of the detail form.</p>
140 <p>If the form is no sub form (e.g. its parent is not a form itself), this
141 property is not evaluated.</p>
143 [property] sequence<string> DetailFields;
145 /** returns the kind of tabulator controlling.
147 [property] com::sun::star::form::TabulatorCycle Cycle;
149 /** determines how a navigation bar for this form should act.
151 [property] com::sun::star::form::NavigationBarMode NavigationBarMode;
153 /** determines if insertions into the form's row set are allowed.
155 <p>Note that this is a recommendation for user interface components displaying the
156 form. Form implementations may decide to allow for insertions done via the API, even
157 if the property is set to `FALSE`, but the user interface should respect the property
158 value.</p>
160 [property] boolean AllowInserts;
162 /** determines if modifications of the current record of the form are allowed.
164 <p>Note that this is a recommendation for user interface components displaying the
165 form. Form implementations may decide to allow for updates done via the API, even
166 if the property is set to `FALSE`, but the user interface should respect the property
167 value.</p>
169 [property] boolean AllowUpdates;
171 /** determines if deletions of records of the form are allowed.
173 <p>Note that this is a recommendation for user interface components displaying the
174 form. Form implementations may decide to allow for deletions done via the API, even
175 if the property is set to `FALSE`, but the user interface should respect the property
176 value.</p>
178 [property] boolean AllowDeletes;
182 }; }; }; }; };
184 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */