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