offapi/com/sun/star/sdb/QueryDesign.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: QueryDesign.idl,v $
  10  * $Revision: 1.9 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_sdb_QueryDesign_idl__
  31 #define __com_sun_star_sdb_QueryDesign_idl__
  32
  33 #ifndef __com_sun_star_frame_XController_idl__
  34 #include <com/sun/star/frame/XController.idl>
  35 #endif
  36 #ifndef __com_sun_star_lang_XInitialization_idl__
  37 #include <com/sun/star/lang/XInitialization.idl>
  38 #endif
  39 #ifndef __com_sun_star_frame_XDispatchProvider_idl__
  40 #include <com/sun/star/frame/XDispatchProvider.idl>
  41 #endif
  42 #ifndef __com_sun_star_form_FormController_idl__
  43 #include <com/sun/star/form/FormController.idl>
  44 #endif
  45
  46 module com {  module sun {  module star {  module sdb {
  47
  48 //=============================================================================
  49 /** implements a component which allows the creation of SQL statements.
  50
  51     <p>This service implements a user interface for creating SQL statements either through a graphical design
  52     interface or simply to enter the SQL statement directly.</p>
  53
  54     <p>The design view of the QueryDesign is divided into two parts. The first part contains the table windows
  55     where columns can be selected for the SQL statement. The second part contains the columns which should appear
  56     in the selection of the SQL statement or criterias which narrow the query.</p>
  57
  58     <h3>Operation Modes</h3>
  59
  60     <p>A <code>QueryDesign</code> component has 3 operation modes, which control what kind of object is edited:
  61     <ul><li><a name="query_mode"></a><b>Query Mode</b>
  62         <p>In <code>Query Mode</code>, the designer is used to modify an existing or create a new client-side
  63         query.</p></li>
  64
  65         <li><a name="view_mode"</a><b>View Mode</b>
  66         <p>In <code>View Mode</code>, the designer is used to modify an existing or create a new server-side
  67         view.</p>
  68         <p>The view which is being designed must support the <type scope="com::sun::star::sdbcx">XAlterView</type>
  69         interface, except when a new view is being designed. In the latter case, the designer closes itself
  70         automatically when <code>XAlterView</code> is not supported, and the view has been saved.</p></li>
  71
  72         <li><a name="command_mode"</a><b>Command Mode</b>
  73         <p>In <code>Command Mode</code>, the designer is used to design an standalone SQL command.</p>
  74         <p>The client of the designer is then responsible to listen at changes in the
  75         <member>ActiveCommand</member> and <member>EscapeProcessing</member> members, which are updated
  76         every time the user saves the command.</p></li>
  77     </ul></p>
  78
  79     <h3><a name="initialization"></a>Initialization</h3>
  80
  81     <p>Initialization is done using the <type scope="com::sun::star::lang">XInitialization</type> interface,
  82     which expects a sequence of objects being either <type scope="com::sun::star::beans">NamedValue</type>s or
  83     <type scope="com::sun::star::beans">PropertyValue</type>s. The following parameters are supported at
  84     initialization time:
  85     <ul>
  86         <li><b>Frame</b><br/>
  87         has to be an <type scope="com::sun::star::frame">XFrame</type> interface specifying the frame to plug the
  88         QueryDesign component into.<br/>
  89         This parameter is mandatory.
  90         </li>
  91
  92         <li><a name="data_source"></a><b>DataSourceName</b><br/>
  93         specifies the name of the globally registered <type>DataSource</type> for which a query, view, or SQL
  94         command is to be designed.<br/>
  95         The DataSourceName may be omitted if and only if a valid <a href="#active_connection">ActiveConnection</a>
  96         parameter is present.<br/>
  97         If both <code>DataSourceName</code> and <code>ActiveConnection</code> are present, the former
  98         is ignored.
  99         </li>
 100
 101         <li><a name="active_connection"></a><b>ActiveConnection</b><br/>
 102         specifies the connection to work with.<br/>
 103         May be ommitted if and only if a valid <a href="#data_source">DataSourceName</a> parameter is supplied.
 104         </li>
 105
 106         <li><a name="command"></a><b>Command</b><br/>
 107         specifies the name of the query or view to design, or, in case of the <a href="#command_type">CommandType</a>
 108         being <member>CommandType::COMMAND</member>, the initial SQL command.<br/>
 109         If this parameter is not present, a new query/view will be designed, respectively the initial
 110         command will be empty.
 111         </li>
 112
 113         <li><a name="command_type"></a><b>CommandType</b><br/>
 114         specifies the type of object which should be designed. The following options are
 115         supported:
 116         <ul><li><member>CommandType::QUERY</member> specifies the designer should operate in
 117             <a href="#query_mode">query mode</a>, that is, an existing client-side query should be
 118             designed, or a new query should be created, depending on the presence of the
 119             <a href="#command">Command</a> parameter.<br/>
 120             If the <a href="#data_source">DataSourceName</a> parameter is present, the query is
 121             looked up in the specified data source. Otherwise, the designer tries to determine
 122             the data source which the <a href="#active_connection">ActiveConnection</a> belongs
 123             to, and looks up the query there.</li>
 124
 125             <li><member>CommandType::COMMAND</member> specifies the designer should operate in
 126             <a href="#command_mode">command mode</a>, that is, a standalone SQL command
 127             should be designed. When the user attempts to save the designed SQL statement,
 128             the <member>ActiveCommand</member> and <member>EscapeProcessing</member> properties
 129             of the designer are updated.</li>
 130
 131             <li><member>CommandType::TABLE</member> specifies the designer should operate in
 132             <a href="#view_mode">view mode</a>, that is, an existing or a new
 133             server-side view should be designed, depending on the presence of the
 134             <a href="#command">Command</a> parameter.<br/>
 135             If the <a href="#data_source">DataSourceName</a> parameter is present, the view is
 136             looked up in a newly created connection for the specified data source. Otherwise,
 137             it is looked up in the connection given as <a href="#active_connection">ActiveConnection</a>.</li>
 138         </ul>
 139         If not present, this parameter defaults to <member>CommandType::QUERY</member>.
 140         </li>
 141
 142         <li><b>EscapeProcessing</b><br/>
 143         Specifies whether or not escape processing should be initially enabled in the query designer. If set
 144         to <FALSE/>, then the designer can operate in text view only (as opposed to the graphical view). The
 145         <a href="#graphical_design">GraphicalDesign</a> parameter will be ignored then, and assumed to be <FALSE/>.<br/>
 146         If not present, <TRUE/> is assumed for this parameter.</li>
 147
 148         <li><a name="graphical_design"></a><b>GraphicalDesign</b><br/>
 149         This value indicates whether the designer should be opened in the graphical design view
 150         (<TRUE/>) or in the text view (<FALSE/>).<br/>
 151         If not present, <FALSE/> is assumed for this parameter.
 152         </li>
 153     </ul>
 154     </p>
 155
 156     <p>There's a number of legacy settings which are recognized for compatibility reasons, though
 157     you're discouraged from using them:
 158     <ul>
 159         <li><b>CurrentQuery</b><br/>
 160         is the same as Command, and implies a <a href="#command_type">CommandType</a> of
 161         <member>CommandType::QUERY</member></li>
 162
 163         <li><b>QueryDesignView</b><br/>
 164         is the same as <a href="#graphical_design">GraphicalDesign</a>.</li>
 165
 166         <li><b>IndependentSQLCommand</b><br/>
 167         is the same as Command, and implies a <a href="#command_type">CommandType</a> of
 168         <member>CommandType::COMMAND</member></li>
 169
 170         <li><b>CreateView</b><br/>
 171         implies a <a href="#command_type">CommandType</a> of <member>CommandType::TABLE</member></li>
 172     </ul>
 173
 174     @see com::sun::star::sdb::ContentLoader
 175 */
 176
 177 published service QueryDesign
 178 {
 179     /** allows the component to be plugged into frames.
 180     */
 181     interface com::sun::star::frame::XController;
 182
 183     /** is used to initialize the QueryDesign.
 184
 185         <p>See chapter <a href="#initialization">Initialization</a> for details.</p>
 186     */
 187     interface com::sun::star::lang::XInitialization;
 188
 189     /** reflects the designed SQL command at the moment it was last saved by the user.
 190     */
 191     [readonly, property] string ActiveCommand;
 192
 193     /** specifies whether the user enabled escape processing for the statement being designed.
 194
 195         @see DataAccessDescriptor::EscapeProcessing
 196         @since OOo 2.4
 197     */
 198     [readonly, property, optional] boolean EscapeProcessing;
 199 };
 200
 201 //=============================================================================
 202 }; }; }; };
 203
 204 #endif