offapi/com/sun/star/form/component/DatabaseListBox.idl

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