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