offapi/com/sun/star/sdb/QueryDesign.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
  20 module com {  module sun {  module star {  module sdb {
  21
  22 /** implements a component which allows the creation of SQL statements.
  23
  24     <p>This service implements a user interface for creating SQL statements either through a graphical design
  25     interface or simply to enter the SQL statement directly.</p>
  26
  27     <p>The design view of the QueryDesign is divided into two parts. The first part contains the table windows
  28     where columns can be selected for the SQL statement. The second part contains the columns which should appear
  29     in the selection of the SQL statement or criteria which narrow the query.</p>
  30
  31     <h3>Operation Modes</h3>
  32
  33     <p>A <code>QueryDesign</code> component has 3 operation modes, which control what kind of object is edited:
  34     <ul><li><a name="query_mode"></a><b>Query Mode</b>
  35         <p>In <code>Query Mode</code>, the designer is used to modify an existing or create a new client-side
  36         query.</p></li>
  37
  38         <li><a name="view_mode"</a><b>View Mode</b>
  39         <p>In <code>View Mode</code>, the designer is used to modify an existing or create a new server-side
  40         view.</p>
  41         <p>The view which is being designed must support the com::sun::star::sdbcx::XAlterView
  42         interface, except when a new view is being designed. In the latter case, the designer closes itself
  43         automatically when <code>XAlterView</code> is not supported, and the view has been saved.</p></li>
  44
  45         <li><a name="command_mode"</a><b>Command Mode</b>
  46         <p>In <code>Command Mode</code>, the designer is used to design an standalone SQL command.</p>
  47         <p>The client of the designer is then responsible to listen at changes in the
  48         #ActiveCommand and #EscapeProcessing members, which are updated
  49         every time the user saves the command.</p></li>
  50     </ul></p>
  51
  52     <h3><a name="initialization"></a>Initialization</h3>
  53
  54     <p>Initialization is done using the com::sun::star::lang::XInitialization interface,
  55     which expects a sequence of objects being either com::sun::star::beans::NamedValues or
  56     com::sun::star::beans::PropertyValues. The following parameters are supported at
  57     initialization time:
  58     <ul>
  59         <li><b>Frame</b><br/>
  60         has to be a com::sun::star::frame::XFrame interface specifying the frame to plug the
  61         QueryDesign component into.<br/>
  62         This parameter is mandatory.
  63         </li>
  64
  65         <li><a name="data_source"></a><b>DataSourceName</b><br/>
  66         specifies the name of the globally registered DataSource for which a query, view, or SQL
  67         command is to be designed.<br/>
  68         The DataSourceName may be omitted if and only if a valid <a href="#active_connection">ActiveConnection</a>
  69         parameter is present.<br/>
  70         If both <code>DataSourceName</code> and <code>ActiveConnection</code> are present, the former
  71         is ignored.
  72         </li>
  73
  74         <li><a name="active_connection"></a><b>ActiveConnection</b><br/>
  75         specifies the connection to work with.<br/>
  76         May be omitted if and only if a valid <a href="#data_source">DataSourceName</a> parameter is supplied.
  77         </li>
  78
  79         <li><a name="command"></a><b>Command</b><br/>
  80         specifies the name of the query or view to design, or, in case of the <a href="#command_type">CommandType</a>
  81         being CommandType::COMMAND, the initial SQL command.<br/>
  82         If this parameter is not present, a new query/view will be designed, respectively the initial
  83         command will be empty.
  84         </li>
  85
  86         <li><a name="command_type"></a><b>CommandType</b><br/>
  87         specifies the type of object which should be designed. The following options are
  88         supported:
  89         <ul><li>CommandType::QUERY specifies the designer should operate in
  90             <a href="#query_mode">query mode</a>, that is, an existing client-side query should be
  91             designed, or a new query should be created, depending on the presence of the
  92             <a href="#command">Command</a> parameter.<br/>
  93             If the <a href="#data_source">DataSourceName</a> parameter is present, the query is
  94             looked up in the specified data source. Otherwise, the designer tries to determine
  95             the data source which the <a href="#active_connection">ActiveConnection</a> belongs
  96             to, and looks up the query there.</li>
  97
  98             <li>CommandType::COMMAND specifies the designer should operate in
  99             <a href="#command_mode">command mode</a>, that is, a standalone SQL command
 100             should be designed. When the user attempts to save the designed SQL statement,
 101             the #ActiveCommand and #EscapeProcessing properties
 102             of the designer are updated.</li>
 103
 104             <li>CommandType::TABLE specifies the designer should operate in
 105             <a href="#view_mode">view mode</a>, that is, an existing or a new
 106             server-side view should be designed, depending on the presence of the
 107             <a href="#command">Command</a> parameter.<br/>
 108             If the <a href="#data_source">DataSourceName</a> parameter is present, the view is
 109             looked up in a newly created connection for the specified data source. Otherwise,
 110             it is looked up in the connection given as <a href="#active_connection">ActiveConnection</a>.</li>
 111         </ul>
 112         If not present, this parameter defaults to CommandType::QUERY.
 113         </li>
 114
 115         <li><b>EscapeProcessing</b><br/>
 116         Specifies whether or not escape processing should be initially enabled in the query designer. If set
 117         to `FALSE`, then the designer can operate in text view only (as opposed to the graphical view). The
 118         <a href="#graphical_design">GraphicalDesign</a> parameter will be ignored then, and assumed to be `FALSE`.<br/>
 119         If not present, `TRUE` is assumed for this parameter.</li>
 120
 121         <li><a name="graphical_design"></a><b>GraphicalDesign</b><br/>
 122         This value indicates whether the designer should be opened in the graphical design view
 123         (`TRUE`) or in the text view (`FALSE`).<br/>
 124         If not present, `FALSE` is assumed for this parameter.
 125         </li>
 126     </ul>
 127     </p>
 128
 129     <p>There's a number of legacy settings which are recognized for compatibility reasons, though
 130     you're discouraged from using them:
 131     <ul>
 132         <li><b>CurrentQuery</b><br/>
 133         is the same as Command, and implies a <a href="#command_type">CommandType</a> of
 134         CommandType::QUERY</li>
 135
 136         <li><b>QueryDesignView</b><br/>
 137         is the same as <a href="#graphical_design">GraphicalDesign</a>.</li>
 138
 139         <li><b>IndependentSQLCommand</b><br/>
 140         is the same as Command, and implies a <a href="#command_type">CommandType</a> of
 141         CommandType::COMMAND</li>
 142
 143         <li><b>CreateView</b><br/>
 144         implies a <a href="#command_type">CommandType</a> of CommandType::TABLE</li>
 145     </ul>
 146
 147     @see com::sun::star::sdb::ContentLoader
 148 */
 149
 150 published service QueryDesign
 151 {
 152     /** allows the component to be plugged into frames.
 153     */
 154     interface com::sun::star::frame::XController;
 155
 156     /** is used to initialize the QueryDesign.
 157
 158         <p>See chapter <a href="#initialization">Initialization</a> for details.</p>
 159     */
 160     interface com::sun::star::lang::XInitialization;
 161
 162     /** reflects the designed SQL command at the moment it was last saved by the user.
 163     */
 164     [readonly, property] string ActiveCommand;
 165
 166     /** specifies whether the user enabled escape processing for the statement being designed.
 167
 168         @see DataAccessDescriptor::EscapeProcessing
 169         @since OOo 2.4
 170     */
 171     [readonly, property, optional] boolean EscapeProcessing;
 172 };
 173
 174 }; }; }; };
 175
 176 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */