1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
/*************************************************************************
*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* Copyright 2000, 2010 Oracle and/or its affiliates.
*
* OpenOffice.org - a multi-platform office productivity suite
*
* This file is part of OpenOffice.org.
*
* OpenOffice.org is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License version 3
* only, as published by the Free Software Foundation.
*
* OpenOffice.org is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License version 3 for more details
* (a copy is included in the LICENSE file that accompanied this code).
*
* You should have received a copy of the GNU Lesser General Public License
* version 3 along with OpenOffice.org. If not, see
* <http://www.openoffice.org/license.html>
* for a copy of the LGPLv3 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, e.g.,
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 URLs 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> method of the object
provided by the external instance.
</p>
<p>
In particular, the supported URLs 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>) for this URL.
<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 URLs, 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 browser 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 OOo 3.0
*/
[optional] interface ::com::sun::star::ui::XContextMenuInterception;
};
//=============================================================================
}; }; }; };
#endif
|