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
28#ifndef __com_sun_star_sdb_application_XDatabaseDocumentUI_idl__
29#define __com_sun_star_sdb_application_XDatabaseDocumentUI_idl__
30
31#include <com/sun/star/sdbc/XDataSource.idl>
32#include <com/sun/star/sdbc/SQLException.idl>
33#include <com/sun/star/sdbc/XConnection.idl>
34#include <com/sun/star/awt/XWindow.idl>
35#include <com/sun/star/lang/IllegalArgumentException.idl>
36#include <com/sun/star/container/NoSuchElementException.idl>
37#include <com/sun/star/lang/XComponent.idl>
38#include <com/sun/star/beans/PropertyValue.idl>
39#include <com/sun/star/beans/Pair.idl>
40
41//=============================================================================
42
43module com { module sun { module star { module sdb { module application {
44
45//=============================================================================
46
47/** provides access to the user interface of a database document
48
49    <p>This interface is available when a database document has been loaded into
50    a frame, at the controller of this frame.</p>
51
52    @see com::sun::star::frame::Controller
53    @see com::sun::star::sdb::DatabaseDocument
54
55    @since OOo 2.2
56 */
57published interface XDatabaseDocumentUI
58{
59    /** provides access to the data source belong to the database document
60    */
61    [attribute, readonly] com::sun::star::sdbc::XDataSource DataSource;
62
63    /** provides access to the applicatio's main window
64
65        <p>Note that reading this atttribute is equivalent to querying the component
66        for the <type scope="com::sun::star::frame">XController</type> interface,
67        asking the controller for its frame, and asking this frame for its
68        container window.</p>
69
70        @see ::com::sun::star::frame::XController
71        @see ::com::sun::star::frame::XFrame
72    */
73    [attribute, readonly] com::sun::star::awt::XWindow ApplicationMainWindow;
74
75    /** provides access to the current connection of the application
76
77        <p>Note that the connection returned here is really the working connection
78        of the application. Clients should not misuse it, in particular, closing
79        the connection can yield unexpected results and should definately be
80        avoided. If you need a separate connection to the data source, use
81        <member scope="com::sun::star::sdbc">XDataSource::getConnection</member>.</p>
82    */
83    [attribute, readonly] com::sun::star::sdbc::XConnection ActiveConnection;
84
85    /** determines whether the application is currently connected to the database
86    */
87    boolean isConnected();
88
89    /** lets the application connect to the database
90
91        <p>If the application is already connected, nothing happens. If it is not
92        connected, the application will try to establish a connection by using
93        <member scope="com::sun::star::sdbc">XDataSource::getConnection</member>
94        with the current settings, as specified in the
95        <member scope="com::sun::star::sdb">DataSource::Settings</member> member.</p>
96
97        <p>If the connection cannot be established, the respective error message is shown
98        in the application window.</p>
99
100        @throws ::com::sun::star::sdbc::SQLException
101            if the connection cannot be established
102    */
103    void    connect()
104        raises ( ::com::sun::star::sdbc::SQLException );
105
106    /** contains all sub components of the database document
107
108        <p>During working with the database, the user might open different sub components:
109        forms, reports, tables, queries. Those components are tracked by the application,
110        and provided in this attribute.</p>
111
112        <p>The components here might either be documents (<type scope="com::sun::star::frame">XModel</type>),
113        controllers (<type scope="com::sun::star::frame">XController</type>), or frames
114        (<type scope="com::sun::star::frame">XFrame</type>).
115
116        @since OOo 3.0
117    */
118    [attribute, readonly] sequence< ::com::sun::star::lang::XComponent >
119            SubComponents;
120
121    /** identifies the given sub component
122
123        @param SubComponent
124            the component to identify. Must be one of the components in <member>SubComponents</member>.
125
126        @return
127            a record describing the sub component. The first element of the returned pair is the type
128            of the component, denoted by one of the <type>DatabaseObject</type> constants. The second
129            element is the name of the component. For object types which support nested structures (forms
130            and reports, actually), this might be a hierachical name. If the sub component has been newly created,
131            and not yet saved, this name is empty.
132
133        @throws ::com::sun::star::lang::IllegalArgumentException
134            if the given component is not one of the controller's sub components
135    */
136    ::com::sun::star::beans::Pair< long, string >
137            identifySubComponent(
138                [in] ::com::sun::star::lang::XComponent SubComponent
139            )
140            raises (
141                ::com::sun::star::lang::IllegalArgumentException
142            );
143
144    /** closes all sub components of the database document.
145
146        <p>During working with the database, the user might open different sub components:
147        forms, reports, tables, queries. If you need to close all those documents, use
148        <code>closeSubComponents</code>, which will gracefully do this.</p>
149
150        <p>In a first step, the sub components will be suspended
151        (<member scope="com::sun::star::frame">XController::suspend</member>). There
152        are basically two reasons why suspending a single sub component can fail: The
153        user might veto it (she's asked if the document is currently modified), and
154        the component might be uncloseable currently, e.g. due to an open modal
155        dialog, or a long-lasting operation running currently (e.g. printing).</p>
156
157        <p>Once all sub components have been suspended, they will, in a second step,
158        be closed. Again, closing might be vetoed by other instances, e.g. by a close
159        listener registered at the component.</p>
160
161        @return
162            <TRUE/> if and only if both suspending and closing all sub components succeeds.
163
164        @since OOo 3.0
165    */
166    boolean closeSubComponents();
167
168    /** loads the given sub component of the database document
169
170        <p>This method allows programmatic access to the functionality which is present in the UI:
171        it allows opening a table, query, form, or report for either editing or viewing.</p>
172
173        <p>This method is a convenience wrapper for API which is also available otherwise. For instance,
174        for loading forms and reports, you could use the <type scope="com::sun::star::frame">XComponentLoader</type>
175        interface of the <type scope="::com::sun::star::sdb">Forms</type> resp. <type scope="::com::sun::star::sdb">Reports</type>
176        collections.</p>
177
178        <p>Note there must exist a connection to the database before you can call this method.</p>
179
180        <p>If an error occurs opening the given object, then this is reported to the user via an error dialog.</p>
181
182        @see isConnected
183        @see connect
184
185        @param ObjectType
186            specifies the type of the object, must be one of the <type>DatabaseObject</type>
187            constants.
188
189        @param ObjectName
190            specifies the name of the object. In case hierachical objects are supported
191            (as is the case form forms and reports), hierarchical names are supported here, too.
192
193        @param ForEditing
194            specifies whether the object should be opened for editing (<TRUE/>) or viewing (<FALSE/>).
195
196            <p>For the different object types, this means the following
197            <a name="component_types"></a>
198            <table style="width:100%;" border="1 solid black" cellpadding="2" cellspacing="2"><tbody>
199              <tr style="vertical-align: top;">
200                <td></td>
201                <td><code>ForEditing</code> = <TRUE/></td>
202                <td><code>ForEditing</code> = <FALSE/></td>
203              </tr>
204
205              <tr style="vertical-align: top;">
206                <td><em>Tables</em></td>
207                <td>A table designer is opened, and allows to edit the structure of the table.
208                    See also <type scope="::com::sun::star::sdb">TableDesign</type></td>
209                <td>A table data view is opened, and allows to view and edit the data contained in the table.
210                    See also <type scope="::com::sun::star::sdb">DataSourceBrowser</type></td>
211              </tr>
212
213              <tr style="vertical-align: top;">
214                <td><em>Queries</em></td>
215                <td>A query designer is opened, and allows to edit the statement constituting the query.
216                    See also <type scope="::com::sun::star::sdb">QueryDesign</type></td>
217                <td>A table data view is opened, and allows to view and edit the data contained in the query.
218                    See also <type scope="::com::sun::star::sdb">DataSourceBrowser</type></td>
219              </tr>
220
221              <tr style="vertical-align: top;">
222                <td><em>Forms</em></td>
223                <td>The form document is opened in design mode, that is, you can modify it.</td>
224                <td>The form document is opened in read-only mode, allowing you to view and enter the data
225                    which the form is based on, but not the form design.</td>
226              </tr>
227
228              <tr style="vertical-align: top;">
229                <td><em>Reports</em></td>
230                <td>The report document is opened in design mode, that is, you can modify it.</td>
231                <td>The report is executed, and the results will be displayed.</td>
232              </tr>
233
234            </tbody></table>
235            </p>
236
237        @return
238            the component which has been loaded. This is either an <type scope="com::sun::star::frame">XModel</type>,
239            or an <type scope="com::sun::star::frame">XController</type> if the component does is model-less.
240
241        @throws ::com::sun::star::lang::IllegalArgumentException
242            if <arg>ObjectType</arg> denotes an invalid object type
243
244        @throws ::com::sun::star::container::NoSuchElementException
245            if an object with the given name and of the given type does not exist
246
247        @throws ::com::sun::star::sdbc::SQLException
248            if there is no connection to the database at the time the method is called.
249    */
250    ::com::sun::star::lang::XComponent loadComponent(
251                    [in] long ObjectType,
252                    [in] string ObjectName,
253                    [in] boolean ForEditing )
254        raises ( ::com::sun::star::lang::IllegalArgumentException,
255                 ::com::sun::star::container::NoSuchElementException,
256                 ::com::sun::star::sdbc::SQLException );
257
258    /** loads the given sub component of the database document
259
260        <p>In opposite to <member>loadComponent</member>, this method allows you to specify
261        additional arguments which are passed to the to-be-loaded component.</p>
262
263        <p>The meaning of the the arguments is defined at the service which is effectively
264        created. See the <a href="#component_types">above table</a> for a list of those
265        services.</p>
266    */
267    ::com::sun::star::lang::XComponent loadComponentWithArguments(
268                    [in] long ObjectType,
269                    [in] string ObjectName,
270                    [in] boolean ForEditing,
271                    [in] sequence< ::com::sun::star::beans::PropertyValue > Arguments )
272        raises ( ::com::sun::star::lang::IllegalArgumentException,
273                 ::com::sun::star::container::NoSuchElementException,
274                 ::com::sun::star::sdbc::SQLException );
275
276    /** creates a new sub component of the given type
277
278        @param ObjectType
279            specifies the type of the object, must be one of the <type>DatabaseObject</type>
280            constants.
281
282        @param DocumentDefinition
283            Upon successful return, and if and only if <arg>ObjectType</arg> equals <member>DatabaseObject::FORM</member>
284            or <member>DatabaseObject::REPORT</member>, this will contain the <type scope="com::sun::star::sdb">DocumentDefinition</type>
285            object which controls the sub component.
286    */
287    ::com::sun::star::lang::XComponent createComponent(
288                    [in] long ObjectType,
289                    [out] ::com::sun::star::lang::XComponent DocumentDefinition )
290        raises ( ::com::sun::star::lang::IllegalArgumentException,
291                 ::com::sun::star::sdbc::SQLException );
292
293    /** creates a new sub component of the given type
294
295        <p>In opposite to <member>createComponent</member>, this method allows you to specify
296        additional arguments which are passed to the to-be-loaded component.</p>
297
298        <p>The meaning of the the arguments is defined at the service which is effectively
299        created. See the <a href="#component_types">above table</a> for a list of those
300        services.</p>
301
302        @param ObjectType
303            specifies the type of the object, must be one of the <type>DatabaseObject</type>
304            constants.
305
306        @param DocumentDefinition
307            Upon successful return, and if and only if <arg>ObjectType</arg> equals <member>DatabaseObject::FORM</member>
308            or <member>DatabaseObject::REPORT</member>, this will contain the <type scope="com::sun::star::sdb">DocumentDefinition</type>
309            object which controls the sub component.<br/>
310            You can use this object to control various aspects of the sub component. For instance, you could decide
311            to create the component hidden, by passing a <code>Hidden</code> flag (set to <TRUE/>) in <arg>Arguments</arg>,
312            manipulate the component, and then finally show it by invoking the <code>show</code> command at the
313            definition object.
314    */
315    ::com::sun::star::lang::XComponent createComponentWithArguments(
316                    [in] long ObjectType,
317                    [in] sequence< ::com::sun::star::beans::PropertyValue > Arguments,
318                    [out] ::com::sun::star::lang::XComponent DocumentDefinition )
319        raises ( ::com::sun::star::lang::IllegalArgumentException,
320                 ::com::sun::star::sdbc::SQLException );
321};
322
323//=============================================================================
324
325}; }; }; }; };
326
327//=============================================================================
328
329#endif
330
331