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 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
  43 module 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.0
  56  */
  57 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