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_DatabaseListBox_idl__ 24#define __com_sun_star_form_component_DatabaseListBox_idl__ 25 26#ifndef __com_sun_star_form_component_ListBox_idl__ 27#include <com/sun/star/form/component/ListBox.idl> 28#endif 29 30#ifndef __com_sun_star_form_DataAwareControlModel_idl__ 31#include <com/sun/star/form/DataAwareControlModel.idl> 32#endif 33 34#ifndef __com_sun_star_form_ListSourceType_idl__ 35#include <com/sun/star/form/ListSourceType.idl> 36#endif 37 38 39//============================================================================= 40 41 module com { module sun { module star { module form { module component { 42 43//============================================================================= 44 45/** This service specifies a data-aware list box control model. 46 47 <p>The base service for list boxes (<type>ListBox</type>) offers only 48 one possibility to specify the list entries: the <member>ListBox::ListSource</member> 49 property, which contains all the strings to be displayed.</p> 50 51 <p>This service here extends this mimic. It allows to fill the list from a data source. 52 This means that a second result set is opened, which works on the same connection as the 53 form which the list box belongs to, but can be based on an arbitrary table or SQL statement.</p> 54 55 <p>For instance, you may have a form which is bound to a table <em>invoice</em>, and you use it 56 to enter invoices for your customers. Probably, you will have a second table (say <em>customer</em>), 57 which (amonst other data) contains a unique key for identifying customers. In your invoice table, you will 58 have a foreign key referring to these customers.<br/> 59 Now, besides the result set the form is based on (all your invoices), the list box can be caused 60 to open a second result set, this time for the <em>customer</em> table, and fill it's list with entries 61 from this result set.<br/> 62 Additionally, it allows to model the relation between the two tables: When the user selects a customer from 63 the list, this customer has the unique id we just talked about (which is not necessarily visible to the 64 user in any way). The list box then automatically transfers this id into the foreign key column of 65 <em>invoice</em>, thus allowing the user to transparently work with human-readable strings instead of 66 pure numbers.<br/> 67 Let's call this result set the list is filled from the <em>list result set</em> here ...</p> 68 69 */ 70published service DatabaseListBox 71{ 72 service com::sun::star::form::component::ListBox; 73 74 service com::sun::star::form::DataAwareControlModel; 75 76 //------------------------------------------------------------------------- 77 78 /** specifies which column of the list result set should be used for data exchange. 79 80 <p>When you make a selection from a list box, the "BoundColumn" 81 property reflects which column value of a result set should 82 be used as the value of the component. If the control is bound 83 to a database field, the column value is stored in the 84 database field identified by the property 85 <member scope="com::sun::star::form">DataAwareControlModel::DataField</member>. 86 87 <dl> 88 <dt>0</dt> 89 <dd>The selected (displayed) list box string is stored in 90 the current database field.</dd> 91 92 <dt>1 or greater</dt> 93 <dd>The column value of the result set at the position is 94 stored in the current database field.</dd> 95 </dl></p> 96 97 <p>The bound column property is only used if a list source is defined 98 and the list source matches with the types 99 <member scope="com::sun::star::form">ListSourceType::TABLE</member>, 100 <member scope="com::sun::star::form">ListSourceType::QUERY</member>, 101 <member scope="com::sun::star::form">ListSourceType::SQL</member> or 102 <member scope="com::sun::star::form">ListSourceType::SQLPASSTHROUGH</member>. 103 Otherwise the property is ignored, as there is no result set from which to 104 get the column values.</p> 105 */ 106 [property] short BoundColumn; 107 108 //------------------------------------------------------------------------- 109 110 /** describes the kind of list source used. 111 112 <p>Depending on the value of this property, the way the value of <member>ListBox::ListSource</member> 113 is evaluated varies. 114 <dl> 115 <dt><member scope="com::sun::star::form">ListSourceType::VALUELIST</member></dt> 116 <dd>The elements in the string sequence in <member>ListBox::ListSource</member> 117 build up the entry list.</dd> 118 119 <dt><member scope="com::sun::star::form">ListSourceType::TABLE</member></dt> 120 <dd>The first element of the string sequence in <member>ListBox::ListSource</member> 121 determines the table which the list result set should be based on.</dd> 122 123 <dt><member scope="com::sun::star::form">ListSourceType::QUERY</member></dt> 124 <dd>The first element of the string sequence in <member>ListBox::ListSource</member> 125 determines the query which the list result set should be based on.<br/> 126 For retrieving the query, the connection which the data form is working with 127 (<member scope="com::sun::star::sdb">RowSet::ActiveConnection</member>) is queried for 128 the <type scope="com::sun::star::sdb">XQueriesSupplier</type> interface.</dd> 129 130 <dt><member scope="com::sun::star::form">ListSourceType::SQL</member></dt> 131 <dd>The first element of the string sequence in <member>ListBox::ListSource</member> 132 contains the SQL statement which the list result set should be based on.</p> 133 134 <dt><member scope="com::sun::star::form">ListSourceType::SQLPASSTHROUGH</member></dt> 135 <dd>The first element of the string sequence in <member>ListBox::ListSource</member> 136 contains the SQL statement which the list result set should be based on.<br/> 137 The statement is not analyzed by the parser. This means that you can use database specific 138 SQL features here, but, on the other hand, loose features like parameter value substitution.</dd> 139 140 <dt><member scope="com::sun::star::form">ListSourceType::TABLEFIELDS</member></dt> 141 <dd>The first element of the string sequence in <member>ListBox::ListSource</member> 142 determines the table which's column names should fill the list.</dd> 143 </dl> 144 </p> 145 146 */ 147 [property] com::sun::star::form::ListSourceType ListSourceType; 148 149}; 150 151//============================================================================= 152 153}; }; }; }; }; 154 155#endif 156