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
|
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* This file incorporates work covered by the following license notice:
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed
* with this work for additional information regarding copyright
* ownership. The ASF licenses this file to you under the Apache
* License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.apache.org/licenses/LICENSE-2.0 .
*/
#ifndef __com_sun_star_sdb_DataSourceBrowser_idl__
#define __com_sun_star_sdb_DataSourceBrowser_idl__
#include <com/sun/star/frame/XController.idl>
#include <com/sun/star/lang/XInitialization.idl>
#include <com/sun/star/frame/XDispatchProvider.idl>
#include <com/sun/star/form/FormController.idl>
#include <com/sun/star/ui/XContextMenuInterception.idl>
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
com::sun::star::sdb::DatabaseContext
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
com::sun::star::sdb::ContentLoader
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
com::sun::star::frame::XDispatchProvider
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
com::sun::star::frame::XDispatchProviderInterceptor
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
com::sun::star::frame::XDispatch::dispatch() 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 (
com::sun::star::frame::XDispatch)
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(
com::sun::star::frame::XDispatch
) 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 (
com::sun::star::frame::XDispatch) 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 DataAccessDescriptor,
where the following properties are present:
<ul>
<li>DataAccessDescriptor::DataSourceName</li>
<li>DataAccessDescriptor::Command</li>
<li>DataAccessDescriptor::CommandType</li>
<li><em>optional</em> DataAccessDescriptor::Selection</li>
<li><em>optional</em> DataAccessDescriptor::BookmarkSelection</li>
<li><em>optional</em> DataAccessDescriptor::ResultSet</li>
</ul>
</p>
<p>The default for DataAccessDescriptor::Selection is to contain bookmarks, if not specified
otherwise by DataAccessDescriptor::BookmarkSelection.
</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 com::sun::star::awt::XTabController::getControls())
</li>
<li>the data form used for displaying objects. As always for components implementing this service,
the object returned by
com::sun::star::awt::XTabController::getModel() 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 com::sun::star::lang::XInitialization::initialize())
have to be instances of com::sun::star::beans::PropertyValue, or
instances of com::sun::star::beans::NamedValue, 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 com::sun::star::frame::XFrame interface specifying the frame to
plug the browser component into.</li>
<li><b>DataSourceName</b><br/>
The name of the globally registered DataSource 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 CommandType 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
com::sun::star::frame::XDispatchProvider::queryDispatch()
method
to query for objects which implement the
com::sun::star::frame::XDispatch
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 com::sun::star::ui::ContextMenuExecuteEvent::Selection,
in the event structure passed to the context menu interceptors, actually is a value from the
com::sun::star::sdb::application::NamedDatabaseObject group.</p>
@since OOo 3.0
*/
[optional] interface ::com::sun::star::ui::XContextMenuInterception;
};
}; }; }; };
#endif
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
