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