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