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