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