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