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
|
/* -*- 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 .
*/
module com { module sun { module star { module form { module runtime {
interface XFeatureInvalidation;
/** encapsulates operations on a database form.
<p>This instance allows for operations on a user interface form, by saving its clients
from various tedious and error-prone operations.</p>
<p>As an example, imagine you have a database form, displayed in some user
interface, which you want to move to the next record.<br/>
It is as easy as calling com::sun::star::sdbc::XResultSet::next()
on this form, right? Wrong. First, you need to care for saving the current
record, so the user doesn't lose her input. So you need to call
com::sun::star::sdbc::XResultSetUpdate::updateRow() or
com::sun::star::sdbc::XResultSetUpdate::insertRow(), depending
on the form's com::sun::star::sdb::RowSet::IsNew property.<br/>
But then you're done, right? Wrong, again.<br/>
When the user just entered some data into one of the form fields, but did not yet
leave this field, then the data is not yet committed to the form, not to talk
about being committed to the underlying database. So, before everything else,
you would need to obtain the active control of the form, and commit it.<br/>
<em>Now</em> you're done ...</p>
<p>As another example, consider that you want to delete the current record from the
form. You have to take into account any com::sun::star::form::XConfirmDeleteListeners
registered at the com::sun::star::form::FormController or the
com::sun::star::form::component::DataForm.</p>
<p>If you agree that this is ugly to do and maintain, then <code>XFormOperations</code>
is for you. It provides an execute() method, which will do all of the above
for you; plus some similar convenient wrappers for similar functionality.</p>
@see FormFeature
@since OOo 2.2
*/
interface XFormOperations : ::com::sun::star::lang::XComponent
{
/** provides access to the cursor of the form the instance is operating on.
*/
[attribute, readonly] ::com::sun::star::sdbc::XRowSet Cursor;
/** provides access to the update cursor of the form the instance is operating on.
*/
[attribute, readonly] ::com::sun::star::sdbc::XResultSetUpdate UpdateCursor;
/** provides access to the form controller which the instance is operating on.
<p>Note that it is possible to operate on a user interface form without
actually having access to the form controller instance. However, in this
case some functionality will not be available. In particular, every feature
which relies on the active control of the controller might be of limited use.</p>
*/
[attribute, readonly] ::com::sun::star::form::runtime::XFormController Controller;
/** retrieves the current state of the given feature
<p>You would usually use this to update some user interface to reflect this state.
For instance, you could imagine a toolbar button which is associated with a given feature.
This button would be enabled if and only if the respective feature is currently
available, and be checked if and only if the feature state is a <code>boolean</code>
evaluating to `TRUE`.<p>
@param Feature
the feature whose state is to be determined. Must be one of the FormFeature
constants.<br/>
An invalid value here will be silently ignored, and simply return a FeatureState
indicating <em>disabled</em> with a `NULL` state.</p>
*/
FeatureState getState(
[in] short Feature
);
/** determines whether a feature is currently enabled.
<p>Calling this is equivalent to calling getState(), and evaluating the
FeatureState::Enabled member.</p>
@param Feature
the feature whose state is to be determined. Must be one of the FormFeature
constants.<br/>
An invalid value here will be silently ignored, and simply return `FALSE`.
*/
boolean isEnabled(
[in] short Feature
);
/** executes the operation associated with the given feature
@param Feature
the feature which is to be executed. Must be one of the FormFeature
constants.
@throws ::com::sun::star::lang::IllegalArgumentException
if the given Feature is unknown, not executable, or strictly requires arguments
to be executed.
@throws ::com::sun::star::sdbc::SQLException
if a database access error occurs
@throws ::com::sun::star::lang::WrappedTargetException
if an exception is caught which is no com::sun::star::uno::RuntimeException
and no com::sun::star::sdbc::SQLException.
@see executeWithArguments
*/
void execute(
[in] short Feature
)
raises ( ::com::sun::star::lang::IllegalArgumentException
, ::com::sun::star::sdbc::SQLException
, ::com::sun::star::lang::WrappedTargetException
);
/** executes the operation associated with the given feature, with passing arguments for execution
@param Feature
the feature which is to be executed. Must be one of the FormFeature
constants.
@param Arguments
the named arguments for the feature to execute. See the FormFeature list
for features which require arguments.
@throws ::com::sun::star::lang::IllegalArgumentException
if the given feature is unknown, or not executable
@throws ::com::sun::star::lang::IllegalArgumentException
if the given arguments are not sufficient to execute the feature
@throws ::com::sun::star::sdbc::SQLException
if a database access error occurs
@throws ::com::sun::star::lang::WrappedTargetException
if an exception is caught which is no com::sun::star::uno::RuntimeException
and no com::sun::star::sdbc::SQLException.
*/
void executeWithArguments(
[in] short Feature,
[in] sequence< ::com::sun::star::beans::NamedValue > Arguments
)
raises ( ::com::sun::star::lang::IllegalArgumentException
, ::com::sun::star::sdbc::SQLException
, ::com::sun::star::lang::WrappedTargetException
);
/** commits the current record of the form
@param RecordInserted
will be `TRUE` if a record has been inserted, i.e. the form was positioned
on the insertion row.
@return
`TRUE` if and only if the current record needed being committed. That's the
case if the record or the active control of the form were modified.
@throws ::com::sun::star::sdbc::SQLException
if a database access error occurs
*/
boolean commitCurrentRecord(
[out] boolean RecordInserted
)
raises ( ::com::sun::star::sdbc::SQLException );
/** commits the current control of our controller
@throws ::com::sun::star::sdbc::SQLException
if a database access error occurs
*/
boolean commitCurrentControl(
)
raises ( ::com::sun::star::sdbc::SQLException );
/** determines whether the form is currently positioned on the insertion row
<p>This is a convenience method only. Calling it is equivalent to examining the
com::sun::star::sdb::RowSet::IsNew property of the form.</p>
@throws ::com::sun::star::lang::WrappedTargetException
if an error occurs obtaining the form property
*/
boolean isInsertionRow(
)
raises ( ::com::sun::star::lang::WrappedTargetException );
/** determines whether the current row of the form is modified
<p>This is a convenience method only. Calling it is equivalent to examining the
com::sun::star::sdb::RowSet::IsModified property of the form.</p>
@throws ::com::sun::star::lang::WrappedTargetException
if an error occurs obtaining the form property
*/
boolean isModifiedRow(
)
raises ( ::com::sun::star::lang::WrappedTargetException );
/** denotes the instance which should be notified about features whose state might have changed.
<p>If this attribute is not `NULL`, the instance which it denotes will be notified
whenever the state of any supported feature might have changed.</p>
<p>For instance, imagine a form whose current row has just been moved to another
record, using the execute() method. This means that potentially, the state
of all movement-related features might have changed.</p>
<p>Note that the instance does not actually notify changes in the feature states, but only
<em>potential</em> changes: It's up to the callee to react on this appropriately. This is
since OpenOffice.org's application framework features own mechanisms to cache and invalidate
feature states, so we do not burden this implementation here with such mechanisms.</p>
@see FormFeature
*/
[attribute] XFeatureInvalidation FeatureInvalidation;
};
}; }; }; }; };
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
