diff options
Diffstat (limited to 'offapi/com/sun/star/form/component/DatabaseListBox.idl')
| -rw-r--r-- | offapi/com/sun/star/form/component/DatabaseListBox.idl | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/offapi/com/sun/star/form/component/DatabaseListBox.idl b/offapi/com/sun/star/form/component/DatabaseListBox.idl new file mode 100644 index 000000000..0b8f95210 --- /dev/null +++ b/offapi/com/sun/star/form/component/DatabaseListBox.idl @@ -0,0 +1,157 @@ +/* -*- 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 . + */ +#ifndef __com_sun_star_form_component_DatabaseListBox_idl__ +#define __com_sun_star_form_component_DatabaseListBox_idl__ + +#include <com/sun/star/form/component/ListBox.idl> + +#include <com/sun/star/form/DataAwareControlModel.idl> + +#include <com/sun/star/form/ListSourceType.idl> + + + + module com { module sun { module star { module form { module component { + + +/** This service specifies a data-aware list box control model. + + <p>The base service for list boxes (ListBox) offers only + one possibility to specify the list entries: + The display strings in the + com::sun::star::awt::UnoControlListBoxModel::StringItemList + property and the corresponding values in the ListBox::ListSource + property.</p> + + <p>This service here extends this mimic. It allows to fill the list from a data source. + This means that a second result set is opened, which works on the same connection as the + form which the list box belongs to, but can be based on an arbitrary table or SQL statement.</p> + + <p>For instance, you may have a form which is bound to a table <em>invoice</em>, and you use it + to enter invoices for your customers. Probably, you will have a second table (say <em>customer</em>), + which (among other data) contains a unique key for identifying customers. In your invoice table, you will + have a foreign key referring to these customers.<br/> + Now, besides the result set the form is based on (all your invoices), the list box can be instructed + to open a second result set, this time for the <em>customer</em> table, and fill its list with entries + from this result set.<br/> + Additionally, it allows to model the relation between the two tables: When the user selects a customer from + the list, this customer has the unique id we just talked about (which is not necessarily visible to the + user in any way). The list box then automatically transfers this id into the foreign key column of + <em>invoice</em>, thus allowing the user to transparently work with human-readable strings instead of + pure numbers.<br/> + Let's call this result set the list is filled from the <em>list result set</em> here ...</p> + + <p>The display strings are always taken from the first column of that result set, + and the corresponding value as per the BoundColumn property.</p> + */ +published service DatabaseListBox +{ + service com::sun::star::form::component::ListBox; + + service com::sun::star::form::DataAwareControlModel; + + + /** specifies which column of the list result set should be used for data exchange. + + <p>When you make a selection from a list box, the "BoundColumn" + property reflects which column value of a result set should + be used as the value of the component. If the control is bound + to a database field, the column value is stored in the + database field identified by the property + com::sun::star::form::DataAwareControlModel::DataField. + + <dl> + <dt>-1</dt> + <dd>The index (starting at 0) of the selected list box entry + is stored in the current database field.</dd> + + <dt>0 or greater</dt> + <dd>The column value of the result set at the position + (0-indexed) is stored in the current database field. + In particular, for value 0, the selected (displayed) + list box string is stored.</dd> + </dl></p> + + <p>The bound column property is only used if a list source is defined + and the list source matches with the types + com::sun::star::form::ListSourceType::TABLE, + com::sun::star::form::ListSourceType::QUERY, + com::sun::star::form::ListSourceType::SQL or + com::sun::star::form::ListSourceType::SQLPASSTHROUGH. + Otherwise the property is ignored, as there is no result set from which to + get the column values.</p> + */ + [property] short BoundColumn; + + + /** describes the kind of list source used. + + <p>Depending on the value of this property, the way the value of ListBox::ListSource + is evaluated varies. + <dl> + <dt>com::sun::star::form::ListSourceType::VALUELIST</dt> + <dd>The elements in the string sequence in ListBox::ListSource + build up the entry list.</dd> + + <dt>com::sun::star::form::ListSourceType::TABLE</dt> + <dd>The first element of the string sequence in ListBox::ListSource + determines the table which the list result set should be based on.</dd> + + <dt>com::sun::star::form::ListSourceType::QUERY</dt> + <dd>The first element of the string sequence in ListBox::ListSource + determines the query which the list result set should be based on.<br/> + For retrieving the query, the connection which the data form is working with + (com::sun::star::sdb::RowSet::ActiveConnection) is queried for + the com::sun::star::sdb::XQueriesSupplier interface.</dd> + + <dt>com::sun::star::form::ListSourceType::SQL</dt> + <dd>The first element of the string sequence in ListBox::ListSource + contains the SQL statement which the list result set should be based on.</p> + + <dt>com::sun::star::form::ListSourceType::SQLPASSTHROUGH</dt> + <dd>The first element of the string sequence in ListBox::ListSource + contains the SQL statement which the list result set should be based on.<br/> + The statement is not analyzed by the parser. This means that you can use database specific + SQL features here, but, on the other hand, lose features like parameter value substitution.</dd> + + <dt>com::sun::star::form::ListSourceType::TABLEFIELDS</dt> + <dd>The first element of the string sequence in ListBox::ListSource + determines the table whose column names should fill the list.</dd> + </dl> + </p> + + */ + [property] com::sun::star::form::ListSourceType ListSourceType; + + /** The selected values. + */ + [property, transient, optional] sequence< any > SelectedValues; + + /** The selected value, if there is at most one. + */ + [property, transient, optional] any SelectedValue; + +}; + + +}; }; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |