| /************************************************************** | |
| * | |
| * Licensed to the Apache Software Foundation (ASF) under one | |
| * or more contributor license agreements. See the NOTICE file | |
| * distributed with this work for additional information | |
| * regarding copyright ownership. The ASF licenses this file | |
| * to you under the Apache License, Version 2.0 (the | |
| * "License"); you may not use this file except in compliance | |
| * with the License. You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, | |
| * software distributed under the License is distributed on an | |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| * KIND, either express or implied. See the License for the | |
| * specific language governing permissions and limitations | |
| * under the 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 OpenOffice 3.0 | |
| */ | |
| [optional] interface ::com::sun::star::ui::XContextMenuInterception; | |
| }; | |
| //============================================================================= | |
| }; }; }; }; | |
| #endif |