offapi/com/sun/star/sdb/DataSourceBrowser.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
  29 #ifndef __com_sun_star_sdb_DataSourceBrowser_idl__
  30 #define __com_sun_star_sdb_DataSourceBrowser_idl__
  31
  32 #ifndef __com_sun_star_frame_XController_idl__
  33 #include <com/sun/star/frame/XController.idl>
  34 #endif
  35 #ifndef __com_sun_star_lang_XInitialization_idl__
  36 #include <com/sun/star/lang/XInitialization.idl>
  37 #endif
  38 #ifndef __com_sun_star_frame_XDispatchProvider_idl__
  39 #include <com/sun/star/frame/XDispatchProvider.idl>
  40 #endif
  41 #ifndef __com_sun_star_form_FormController_idl__
  42 #include <com/sun/star/form/FormController.idl>
  43 #endif
  44 #ifndef __com_sun_star_ui_XContextMenuInterception_idl__
  45 #include <com/sun/star/ui/XContextMenuInterception.idl>
  46 #endif
  47
  48 module com {  module sun {  module star {  module sdb {
  49
  50 //=============================================================================
  51 /** implements a component which allows browsing the data sources registered on the system.
  52
  53     <p>
  54     This service implements a user interface for browsing data sources registered on the
  55     <type scope="com::sun::star::sdb">
  56     DatabaseContext
  57     </type>
  58     instance of the system.
  59     </p>
  60
  61     <p>
  62     It is possible to navigate through all the data sources, it's queries and it's tables.
  63     The queries/tables can be displayed in a grid-like view, where functionality for searching,
  64     sorting, filtering, and such is provided.
  65     </p>
  66
  67     <p>
  68     Usually, you won't instantiate this service directly, instead you use the dispatch mechanisms
  69     of the application framework to load the URL <b>.component:DB/DataSourceBrowser</b> into an arbitrary
  70     frame. This should involve a
  71     <type scope="com::sun::star::sdb">
  72     ContentLoader
  73     </type>
  74     service, which creates and initializes
  75     the browser.
  76     </p>
  77
  78     <p>
  79     Some aspects of the browser can be controlled from outside, eg.,
  80     it is possible to dispatch a sort or filter
  81     request, if a table or query is being displayed.
  82     </p>
  83
  84     <p
  85     >The communication between the browser and external instances works in two ways.
  86     <br/>
  87     The way <em>in</em> is provided by the
  88     <type scope="com::sun::star::frame">XDispatchProvider</type>
  89     interface the service exports (Please see below for more details on this).
  90     <br/>
  91     The way <em>out</em> works in another way. There are several URL's which an external
  92     instance can provide dispatches for (usually by implementing a
  93     <type scope="com::sun::star::frame">XDispatchProviderInterceptor</type>
  94     for the parent frame of the browser), thus indicating that the browser should provide special functionality.
  95     <br/>
  96     In this case, the browser displays and maintains some additional slots (to be more concrete: toolbox items), which,
  97     upon triggering, call the
  98     <member scope="com::sun::star::frame">XDispatch::dispatch()</member>methodoftheobject
  99     provided by the external instance.
 100     </p>
 101
 102     <p>
 103         In particular, the supported URL's for communicating to an external instance are:
 104         <ul>
 105             <li><b>.uno:DataSourceBrowser/InsertColumns</b>
 106             <br/>
 107             Available whenever an external instance provides a dispatcher (
 108             <type scope="com::sun::star::frame">XDispatch</type>)
 109             for this URL.
 110             <br/>
 111             Enabled, if at least one row in the grid view of a table or query is selected.
 112             <br/>
 113             It is the task of the external instance to provide functionality for this URL, but usually it is used
 114             to implement some kind of "Data To Text" functionality.
 115             <br/>
 116             </li>
 117             <li><b>.uno:DataSourceBrowser/InsertContent</b>
 118             <br/>
 119             Available whenever an external instance provides a dispatcher(
 120             <type scope="com::sun::star::frame">XDispatch</type>
 121             ) for this URL.
 122             <br/>
 123             Enabled, if at least one row in the grid view of a table or query is selected.
 124             <br/>
 125             It is the task of the external instance to provide functionality for this URL, but usually it is used
 126             to implement some kind of "Data To Fields" functionality.
 127             <br/>
 128             </li>
 129             <li><b>.uno:DataSourceBrowser/FormLetter</b>
 130             <br/>
 131             Available whenever an external instance provides a dispatcher (
 132             <type scope="com::sun::star::frame">XDispatch</type>)forthisURL.
 133             <br/>
 134             It is the task of the external instance to provide functionality for this URL, but usually it is used
 135             to implement some kind of "Form Letter" functionality.
 136             <br/>
 137             </li>
 138         </ul>
 139     </p>
 140     <p>For all kinds of URL's, the parameters supplied during dispatching build up a <type>DataAccessDescriptor</type>,
 141     where the following properties are present:
 142     <ul>
 143         <li><member>DataAccessDescriptor::DataSourceName</member></li>
 144         <li><member>DataAccessDescriptor::Command</member></li>
 145         <li><member>DataAccessDescriptor::CommandType</member></li>
 146         <li><em>optional</em> <member>DataAccessDescriptor::Selection</member></li>
 147         <li><em>optional</em> <member>DataAccessDescriptor::BookmarkSelection</member></li>
 148         <li><em>optional</em> <member>DataAccessDescriptor::ResultSet</member></li>
 149     </ul>
 150     </p>
 151     <p>The default for <member>DataAccessDescriptor::Selection</member> is to contain bookmarks, if not specified
 152     otherwise by <member>DataAccessDescriptor::BookmarkSelection</member>.</pr>
 153     </p>
 154
 155     @see com::sun::star::sdb::ContentLoader
 156     @see com::sun::star::sdb::DatabaseContext
 157     @see com::sun::star::sdb::DataSource
 158     @see com::sun::star::frame::XDispatch
 159     @see com::sun::star::frame::XDispatchProvider
 160     @see com::sun::star::frame::XDispatchProviderInterceptor
 161 */
 162 published service DataSourceBrowser
 163 {
 164     /** implements basic form controller functionality.
 165         <p>
 166         With a data source browser implementing this interface, external components have access to
 167         <ul><li>the grid control which is used to display the currently selected table/query
 168             (see <method scope="com::sun::star::awt">XTabController::getControls</method>)
 169             </li>
 170             <li>the data form used for displaying objects. As always for components implementing this service,
 171             the object returned by
 172             <method scope="com::sun::star::awt">XTabController::getModel</method>is a dataform.
 173             </li>
 174         </ul>
 175         </p>
 176     */
 177     [optional] service com::sun::star::form::FormController;
 178
 179     /** allows the component to be plugged into frames.
 180     */
 181     interface com::sun::star::frame::XController;
 182
 183     /** is used to initialize the browser.
 184
 185         <p>
 186         Parameters (passed to the method <member scope="com::sun::star::lang">XInitialization::initialize()</member>)
 187         have to be instances of <type scope="com::sun::star::beans">PropertyValue</type>, or
 188         instances of <type scope="com::sun::star::beans">NamedValue</type>, where the <code>Name</code> member
 189         specifies what the parameter controls, with the <code>Value</code> member containing the value to be used.
 190         <br/>
 191         Recognized parameters are:
 192         <ul>
 193             <li><b>Frame</b><br/>
 194             has to be an  <type scope="com::sun::star::frame">XFrame</type> interface specifying the frame to
 195             plug the browser component into.</li>
 196
 197             <li><b>DataSourceName</b><br/>
 198             The name of the globally registered <type>DataSource</type> to be used for initial display. It is only
 199             meaningful together with the other parameters specifying the object to display.</li>
 200
 201             <li><b>CommandType</b><br/>
 202             This has to be a <type>CommandType</type> value, specifying the type of the object to display initially.
 203             It is only meaningful together with the <em>DataSourceName</em> and the <em>Command</em> parameters.</li>
 204
 205             <li><b>Command</b><br/>
 206             This is a string giving the name of the object to display initially. Whether it is table name, a query
 207             name or a SQL string is controller by the <em>CommandType</em> parameter.</li>
 208
 209             <li><b>EnableBrowser</b><br/>
 210             is a boolean value (defaulting to <TRUE/>), which specifies whether to enable the data source browser
 211             control. This is a tree control on the left hand side of the view, which allows to browse all registered
 212             data sources, including their tables and queries.</li>
 213
 214             <li><b>ShowBrowser</b><br/>
 215             is a boolean value (defaulting to <TRUE/>), which specifies whether to initially show the data source
 216             browser control. If <code>EnableBrowser</code> is <FALSE/>, then this parameter is ignored. If
 217             <code>EnableBrowser</code> is <TRUE/>, and <code>ShowBrowser</code> is <FALSE/>, then the control
 218             is initially hidden, but can be toggled by a toolbar button.</p>
 219
 220             <li><b>ShowMenu</b><br/>
 221             is a boolean value (defaulting to <TRUE/>), specifying whether or not to show a menu in the frame
 222             where the component is plugged.</li>
 223         </ul>
 224         </p>
 225     */
 226     interface com::sun::star::lang::XInitialization;
 227
 228     /** is used to control the browser from outside.
 229
 230     <p>
 231     You may use the
 232     <member scope="com::sun::star::frame">XDispatchProvider::queryDispatch</member>
 233     method
 234     to query for objects which implement the
 235     <type scope="com::sun::star::frame">XDispatch</type>
 236     interface,
 237     and which allow you to be notified on status changes and to dispatch special requests.
 238     </p>
 239     <p>
 240     The recognized URLs are:
 241         <ul>
 242             <li><b>.uno:Copy</b>
 243             <br/>
 244             implements the usual <em>Copy</em> command. Enabled if the grid view has the focus and text in any cell
 245             is selected.
 246             </li>
 247             <li><b>.uno:Cut</b>
 248             <br/>
 249             implements the usual <em>Cut</em> command. Enabled if the grid view has the focus and text in any cell
 250             is selected.
 251             </li>
 252             <li><b>.uno:Paste</b>
 253             <br/>
 254             implements the usual <em>Paste</em> command. Enabled if the grid view has the focus and a cell which
 255             allows text input is being edited.
 256             </li>
 257             <li><b>.uno:EditDoc</b>
 258             <br/>
 259             allows switching the edit mode of the grid view. Enabled if editing the data is allowed in general.
 260             </li>
 261             <li><b>.uno:Undo</b>
 262             <br/>
 263             revokes any changes done in the current row.
 264             </li>
 265             <li><b>.uno:Save</b><br/>
 266             saves the changes done in the current row.
 267             </li>
 268         </ul>
 269     </p>
 270     */
 271     interface com::sun::star::frame::XDispatchProvider;
 272
 273     /** allows to intercept user-triggered context menus in the data source browser
 274
 275         <p>Context menu interception is currently supported only for the brower control where the registered
 276         data sources and all their tables and queries are displayed in a tree view.</p>
 277
 278         <p>The selection supplied by <member scope="com::sun::star::ui">ContextMenuExecuteEvent::Selection</member>,
 279         in the event structure passed to the context menu interceptors, actually is a value from the
 280         <type scope="com::sun::star::sdb::application">NamedDatabaseObject</type> group.</p>
 281
 282         @since OOo 3.0
 283     */
 284     [optional] interface ::com::sun::star::ui::XContextMenuInterception;
 285 };
 286
 287 //=============================================================================
 288 }; }; }; };
 289
 290 #endif