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