diff options
Diffstat (limited to 'offapi/com/sun/star/form/component/DataForm.idl')
-rw-r--r-- | offapi/com/sun/star/form/component/DataForm.idl | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/offapi/com/sun/star/form/component/DataForm.idl b/offapi/com/sun/star/form/component/DataForm.idl new file mode 100644 index 0000000000..ed0ff3eb7d --- /dev/null +++ b/offapi/com/sun/star/form/component/DataForm.idl @@ -0,0 +1,184 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ + + +module com { module sun { module star { module form { + + published interface XReset; + published interface XDatabaseParameterBroadcaster; + +module component { +/** This service specifies a form which is connected to a database and + displays the results of SQL queries. It provides the possibility of + adding new data records, modifying existing ones, or deleting them. + + <p>A database form is a special kind of enhanced database row set + which provides all information for displaying the data and has more + possibilities for configuring the data manipulation.</p> + +*/ +published service DataForm +{ + service com::sun::star::sdb::RowSet; + service com::sun::star::form::component::Form; + + /** is used to reset controls belonging to the form, and to reset database fields to which the + controls are bound + + <p>A DataForm is reset either on explicit request, or after it is moved + to the insertion row.</p> + + <p>The insertion row is a virtual row which is used to insert new records. It is reached + by calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow(). + The com::sun::star::sdb::RowSet service specifies exactly which notifications + happen in which order when calling com::sun::star::sdbc::XResultSetUpdate::moveToInsertRow(), + and a DataForm implementation extends this with the following contract: + <ul><li>After all notifications as defined in the com::sun::star::sdb::RowSet + service have been sent, the DataForm resets itself, if all + com::sun::star::form::XResetListeners approve this.</li> + <li>After the reset happened, the com::sun::star::sdb::RowSet::IsModified + property is reset to `FALSE`. This property might have been switched to `TRUE` during listener + notifications, since listeners are allowed to change field values. Also, the + com::sun::star::form::XReset::reset() implementations of bound control + models might have modified the fields they're bound to (by filling them with default values).</li> + <li>The reset listeners are notified of the completed reset operation.</li> + </ul></p> + */ + interface com::sun::star::form::XReset; + + /** used to load/unload the form + <p>Loading a form is basically the same as executing the underlying row set. In fact, all the + functionality of this interface could be simulated by using setting some properties manually, + com::sun::star::sdbc::XRowSet::execute(), moving the row set cursor and so on.</p> + + <p>One main difference between XLoadable::load() and com::sun::star::sdbc::XRowSet::execute() + is that if you use the former, the row set is positioned on the first record, while in the latter case + it is position <em>before</em> the it.</p> + */ + interface com::sun::star::form::XLoadable; + + /** can be used to allow an interaction handler to supply missing data during a load process. + + <p>If data is needed during loading a form, then this is usually obtained via broadcaster-listener + mechanisms. An example for this (and currently the only one) are parameter values.</p> + <p>However, if you use this method, you can pass an interaction handler which should supply these + additional data.</p> + + @see com::sun::star::sdb::InteractionHandler + */ + interface com::sun::star::sdb::XCompletedExecution; + + /** can be used for filling parameters. + + <p>You can add your component as + com::sun::star::form::XDatabaseParameterListener + to a form to get notified whenever the form needs parameter values to be filled in<br/> + In a first approach, the form tries to fill any parameters from its master-detail relation + (if any). All values which can't be filled are then passed to all listeners, which can + fill them by their own choice.</p> + + <p>This is slightly changed if the form is loaded using the + com::sun::star::sdb::XCompletedExecution::connectWithCompletion() method. In this case, the parameters + are obtained from the interaction handler, not from the listeners</p> + + @see XCompletedExecution + @see MasterFields + @see DetailFields + */ + interface com::sun::star::form::XDatabaseParameterBroadcaster; + + /** is used for subforms and contains the names of columns of the parent form. + + <p> These columns are typically the foreign key fields of the parent form. + The values of these columns are used to identify the data for the subform. + Each time the parent form changes its current row, the subform requeries + it's data based on the values of the master fields.</p> + + <p>If the form is no sub form (e.g. its parent is not a form itself), this + property is not evaluated.</p> + */ + [property] sequence<string> MasterFields; + + /** is used for subforms and contains the names of the columns of the subform + which are related to the master fields of the parent form. + + <p>Entries in this sequence can either denote column names in the sub form, + or parameter names.<br/> + For instance, you could base the form on the SQL statement + <code>SELECT * FROM invoices WHERE cust_ref = :cid</code>, and add <code>cid</code> + to the DetailFields property. In this case, the parameter will be filled from + the corresponding master field.<br/> + Alternatively, you could simply base your form on the table <code>invoices</code>, + and add the column name <code>cust_ref</code> to the DetailFields. In this case, + and implicit filter clause <code>WHERE cust_ref = :<new_param_name></code> will + be created, and the artificial parameter will be filled from the corresponding + master field.<br/> + If a string in this property denotes both a column name and a parameter name, it + is undefined which way it is interpreted, but implementations of the service are required + to either decide for the parameter or the column, and proceed as usual. + </p> + + <p>The columns specified herein typically represent a part of the primary key + fields or their aliases of the detail form.</p> + + <p>If the form is no sub form (e.g. its parent is not a form itself), this + property is not evaluated.</p> + */ + [property] sequence<string> DetailFields; + + /** returns the kind of tabulator controlling. + */ + [property] com::sun::star::form::TabulatorCycle Cycle; + + /** determines how a navigation bar for this form should act. + */ + [property] com::sun::star::form::NavigationBarMode NavigationBarMode; + + /** determines if insertions into the form's row set are allowed. + + <p>Note that this is a recommendation for user interface components displaying the + form. Form implementations may decide to allow for insertions done via the API, even + if the property is set to `FALSE`, but the user interface should respect the property + value.</p> + */ + [property] boolean AllowInserts; + + /** determines if modifications of the current record of the form are allowed. + + <p>Note that this is a recommendation for user interface components displaying the + form. Form implementations may decide to allow for updates done via the API, even + if the property is set to `FALSE`, but the user interface should respect the property + value.</p> + */ + [property] boolean AllowUpdates; + + /** determines if deletions of records of the form are allowed. + + <p>Note that this is a recommendation for user interface components displaying the + form. Form implementations may decide to allow for deletions done via the API, even + if the property is set to `FALSE`, but the user interface should respect the property + value.</p> + */ + [property] boolean AllowDeletes; +}; + + +}; }; }; }; }; + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |