diff options
Diffstat (limited to 'offapi/com/sun/star/sdb/DataSourceBrowser.idl')
| -rw-r--r-- | offapi/com/sun/star/sdb/DataSourceBrowser.idl | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/offapi/com/sun/star/sdb/DataSourceBrowser.idl b/offapi/com/sun/star/sdb/DataSourceBrowser.idl new file mode 100644 index 000000000000..feaf0262e26d --- /dev/null +++ b/offapi/com/sun/star/sdb/DataSourceBrowser.idl @@ -0,0 +1,290 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + + +#ifndef __com_sun_star_sdb_DataSourceBrowser_idl__ +#define __com_sun_star_sdb_DataSourceBrowser_idl__ + +#ifndef __com_sun_star_frame_XController_idl__ +#include <com/sun/star/frame/XController.idl> +#endif +#ifndef __com_sun_star_lang_XInitialization_idl__ +#include <com/sun/star/lang/XInitialization.idl> +#endif +#ifndef __com_sun_star_frame_XDispatchProvider_idl__ +#include <com/sun/star/frame/XDispatchProvider.idl> +#endif +#ifndef __com_sun_star_form_FormController_idl__ +#include <com/sun/star/form/FormController.idl> +#endif +#ifndef __com_sun_star_ui_XContextMenuInterception_idl__ +#include <com/sun/star/ui/XContextMenuInterception.idl> +#endif + +module com { module sun { module star { module sdb { + +//============================================================================= +/** implements a component which allows browsing the data sources registered on the system. + + <p> + This service implements a user interface for browsing data sources registered on the + <type scope="com::sun::star::sdb"> + DatabaseContext + </type> + instance of the system. + </p> + + <p> + It is possible to navigate through all the data sources, it's queries and it's tables. + The queries/tables can be displayed in a grid-like view, where functionality for searching, + sorting, filtering, and such is provided. + </p> + + <p> + Usually, you won't instantiate this service directly, instead you use the dispatch mechanisms + of the application framework to load the URL <b>.component:DB/DataSourceBrowser</b> into an arbitrary + frame. This should involve a + <type scope="com::sun::star::sdb"> + ContentLoader + </type> + service, which creates and initializes + the browser. + </p> + + <p> + Some aspects of the browser can be controlled from outside, eg., + it is possible to dispatch a sort or filter + request, if a table or query is being displayed. + </p> + + <p + >The communication between the browser and external instances works in two ways. + <br/> + The way <em>in</em> is provided by the + <type scope="com::sun::star::frame">XDispatchProvider</type> + interface the service exports (Please see below for more details on this). + <br/> + The way <em>out</em> works in another way. There are several URL's which an external + instance can provide dispatches for (usually by implementing a + <type scope="com::sun::star::frame">XDispatchProviderInterceptor</type> + for the parent frame of the browser), thus indicating that the browser should provide special functionality. + <br/> + In this case, the browser displays and maintains some additional slots (to be more concrete: toolbox items), which, + upon triggering, call the + <member scope="com::sun::star::frame">XDispatch::dispatch()</member>methodoftheobject + provided by the external instance. + </p> + + <p> + In particular, the supported URL's for communicating to an external instance are: + <ul> + <li><b>.uno:DataSourceBrowser/InsertColumns</b> + <br/> + Available whenever an external instance provides a dispatcher ( + <type scope="com::sun::star::frame">XDispatch</type>) + for this URL. + <br/> + Enabled, if at least one row in the grid view of a table or query is selected. + <br/> + It is the task of the external instance to provide functionality for this URL, but usually it is used + to implement some kind of "Data To Text" functionality. + <br/> + </li> + <li><b>.uno:DataSourceBrowser/InsertContent</b> + <br/> + Available whenever an external instance provides a dispatcher( + <type scope="com::sun::star::frame">XDispatch</type> + ) for this URL. + <br/> + Enabled, if at least one row in the grid view of a table or query is selected. + <br/> + It is the task of the external instance to provide functionality for this URL, but usually it is used + to implement some kind of "Data To Fields" functionality. + <br/> + </li> + <li><b>.uno:DataSourceBrowser/FormLetter</b> + <br/> + Available whenever an external instance provides a dispatcher ( + <type scope="com::sun::star::frame">XDispatch</type>)forthisURL. + <br/> + It is the task of the external instance to provide functionality for this URL, but usually it is used + to implement some kind of "Form Letter" functionality. + <br/> + </li> + </ul> + </p> + <p>For all kinds of URL's, the parameters supplied during dispatching build up a <type>DataAccessDescriptor</type>, + where the following properties are present: + <ul> + <li><member>DataAccessDescriptor::DataSourceName</member></li> + <li><member>DataAccessDescriptor::Command</member></li> + <li><member>DataAccessDescriptor::CommandType</member></li> + <li><em>optional</em> <member>DataAccessDescriptor::Selection</member></li> + <li><em>optional</em> <member>DataAccessDescriptor::BookmarkSelection</member></li> + <li><em>optional</em> <member>DataAccessDescriptor::ResultSet</member></li> + </ul> + </p> + <p>The default for <member>DataAccessDescriptor::Selection</member> is to contain bookmarks, if not specified + otherwise by <member>DataAccessDescriptor::BookmarkSelection</member>.</pr> + </p> + + @see com::sun::star::sdb::ContentLoader + @see com::sun::star::sdb::DatabaseContext + @see com::sun::star::sdb::DataSource + @see com::sun::star::frame::XDispatch + @see com::sun::star::frame::XDispatchProvider + @see com::sun::star::frame::XDispatchProviderInterceptor +*/ +published service DataSourceBrowser +{ + /** implements basic form controller functionality. + <p> + With a data source browser implementing this interface, external components have access to + <ul><li>the grid control which is used to display the currently selected table/query + (see <method scope="com::sun::star::awt">XTabController::getControls</method>) + </li> + <li>the data form used for displaying objects. As always for components implementing this service, + the object returned by + <method scope="com::sun::star::awt">XTabController::getModel</method>is a dataform. + </li> + </ul> + </p> + */ + [optional] service com::sun::star::form::FormController; + + /** allows the component to be plugged into frames. + */ + interface com::sun::star::frame::XController; + + /** is used to initialize the browser. + + <p> + Parameters (passed to the method <member scope="com::sun::star::lang">XInitialization::initialize()</member>) + have to be instances of <type scope="com::sun::star::beans">PropertyValue</type>, or + instances of <type scope="com::sun::star::beans">NamedValue</type>, where the <code>Name</code> member + specifies what the parameter controls, with the <code>Value</code> member containing the value to be used. + <br/> + Recognized parameters are: + <ul> + <li><b>Frame</b><br/> + has to be an <type scope="com::sun::star::frame">XFrame</type> interface specifying the frame to + plug the browser component into.</li> + + <li><b>DataSourceName</b><br/> + The name of the globally registered <type>DataSource</type> to be used for initial display. It is only + meaningful together with the other parameters specifying the object to display.</li> + + <li><b>CommandType</b><br/> + This has to be a <type>CommandType</type> value, specifying the type of the object to display initially. + It is only meaningful together with the <em>DataSourceName</em> and the <em>Command</em> parameters.</li> + + <li><b>Command</b><br/> + This is a string giving the name of the object to display initially. Whether it is table name, a query + name or a SQL string is controller by the <em>CommandType</em> parameter.</li> + + <li><b>EnableBrowser</b><br/> + is a boolean value (defaulting to <TRUE/>), which specifies whether to enable the data source browser + control. This is a tree control on the left hand side of the view, which allows to browse all registered + data sources, including their tables and queries.</li> + + <li><b>ShowBrowser</b><br/> + is a boolean value (defaulting to <TRUE/>), which specifies whether to initially show the data source + browser control. If <code>EnableBrowser</code> is <FALSE/>, then this parameter is ignored. If + <code>EnableBrowser</code> is <TRUE/>, and <code>ShowBrowser</code> is <FALSE/>, then the control + is initially hidden, but can be toggled by a toolbar button.</p> + + <li><b>ShowMenu</b><br/> + is a boolean value (defaulting to <TRUE/>), specifying whether or not to show a menu in the frame + where the component is plugged.</li> + </ul> + </p> + */ + interface com::sun::star::lang::XInitialization; + + /** is used to control the browser from outside. + + <p> + You may use the + <member scope="com::sun::star::frame">XDispatchProvider::queryDispatch</member> + method + to query for objects which implement the + <type scope="com::sun::star::frame">XDispatch</type> + interface, + and which allow you to be notified on status changes and to dispatch special requests. + </p> + <p> + The recognized URLs are: + <ul> + <li><b>.uno:Copy</b> + <br/> + implements the usual <em>Copy</em> command. Enabled if the grid view has the focus and text in any cell + is selected. + </li> + <li><b>.uno:Cut</b> + <br/> + implements the usual <em>Cut</em> command. Enabled if the grid view has the focus and text in any cell + is selected. + </li> + <li><b>.uno:Paste</b> + <br/> + implements the usual <em>Paste</em> command. Enabled if the grid view has the focus and a cell which + allows text input is being edited. + </li> + <li><b>.uno:EditDoc</b> + <br/> + allows switching the edit mode of the grid view. Enabled if editing the data is allowed in general. + </li> + <li><b>.uno:Undo</b> + <br/> + revokes any changes done in the current row. + </li> + <li><b>.uno:Save</b><br/> + saves the changes done in the current row. + </li> + </ul> + </p> + */ + interface com::sun::star::frame::XDispatchProvider; + + /** allows to intercept user-triggered context menus in the data source browser + + <p>Context menu interception is currently supported only for the brower control where the registered + data sources and all their tables and queries are displayed in a tree view.</p> + + <p>The selection supplied by <member scope="com::sun::star::ui">ContextMenuExecuteEvent::Selection</member>, + in the event structure passed to the context menu interceptors, actually is a value from the + <type scope="com::sun::star::sdb::application">NamedDatabaseObject</type> group.</p> + + @since OOo 3.0 + */ + [optional] interface ::com::sun::star::ui::XContextMenuInterception; +}; + +//============================================================================= +}; }; }; }; + +#endif |