| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_form_component_DatabaseListBox_idl__ |
| #define __com_sun_star_form_component_DatabaseListBox_idl__ |
| |
| #ifndef __com_sun_star_form_component_ListBox_idl__ |
| #include <com/sun/star/form/component/ListBox.idl> |
| #endif |
| |
| #ifndef __com_sun_star_form_DataAwareControlModel_idl__ |
| #include <com/sun/star/form/DataAwareControlModel.idl> |
| #endif |
| |
| #ifndef __com_sun_star_form_ListSourceType_idl__ |
| #include <com/sun/star/form/ListSourceType.idl> |
| #endif |
| |
| |
| //============================================================================= |
| |
| 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 (<type>ListBox</type>) offers only |
| one possibility to specify the list entries: the <member>ListBox::ListSource</member> |
| property, which contains all the strings to be displayed.</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 (amonst 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 caused |
| to open a second result set, this time for the <em>customer</em> table, and fill it's 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> |
| |
| */ |
| 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 |
| <member scope="com::sun::star::form">DataAwareControlModel::DataField</member>. |
| |
| <dl> |
| <dt>0</dt> |
| <dd>The selected (displayed) list box string is stored in |
| the current database field.</dd> |
| |
| <dt>1 or greater</dt> |
| <dd>The column value of the result set at the position is |
| stored in the current database field.</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 |
| <member scope="com::sun::star::form">ListSourceType::TABLE</member>, |
| <member scope="com::sun::star::form">ListSourceType::QUERY</member>, |
| <member scope="com::sun::star::form">ListSourceType::SQL</member> or |
| <member scope="com::sun::star::form">ListSourceType::SQLPASSTHROUGH</member>. |
| 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 <member>ListBox::ListSource</member> |
| is evaluated varies. |
| <dl> |
| <dt><member scope="com::sun::star::form">ListSourceType::VALUELIST</member></dt> |
| <dd>The elements in the string sequence in <member>ListBox::ListSource</member> |
| build up the entry list.</dd> |
| |
| <dt><member scope="com::sun::star::form">ListSourceType::TABLE</member></dt> |
| <dd>The first element of the string sequence in <member>ListBox::ListSource</member> |
| determines the table which the list result set should be based on.</dd> |
| |
| <dt><member scope="com::sun::star::form">ListSourceType::QUERY</member></dt> |
| <dd>The first element of the string sequence in <member>ListBox::ListSource</member> |
| 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 |
| (<member scope="com::sun::star::sdb">RowSet::ActiveConnection</member>) is queried for |
| the <type scope="com::sun::star::sdb">XQueriesSupplier</type> interface.</dd> |
| |
| <dt><member scope="com::sun::star::form">ListSourceType::SQL</member></dt> |
| <dd>The first element of the string sequence in <member>ListBox::ListSource</member> |
| contains the SQL statement which the list result set should be based on.</p> |
| |
| <dt><member scope="com::sun::star::form">ListSourceType::SQLPASSTHROUGH</member></dt> |
| <dd>The first element of the string sequence in <member>ListBox::ListSource</member> |
| 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, loose features like parameter value substitution.</dd> |
| |
| <dt><member scope="com::sun::star::form">ListSourceType::TABLEFIELDS</member></dt> |
| <dd>The first element of the string sequence in <member>ListBox::ListSource</member> |
| determines the table which's column names should fill the list.</dd> |
| </dl> |
| </p> |
| |
| */ |
| [property] com::sun::star::form::ListSourceType ListSourceType; |
| |
| }; |
| |
| //============================================================================= |
| |
| }; }; }; }; }; |
| |
| #endif |