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