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
|
/* -*- 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_ui_XAcceleratorConfiguration_idl__
#define __com_sun_star_ui_XAcceleratorConfiguration_idl__
#include <com/sun/star/ui/XUIConfiguration.idl>
#include <com/sun/star/ui/XUIConfigurationPersistence.idl>
#include <com/sun/star/ui/XUIConfigurationStorage.idl>
#include <com/sun/star/awt/KeyEvent.idl>
#include <com/sun/star/lang/IllegalArgumentException.idl>
#include <com/sun/star/container/NoSuchElementException.idl>
module com { module sun { module star { module ui {
/** provides read/write access to an accelerator configuration set.
<p>
Such configuration set base on:<br>
<ul>
<li>Key events structure</li>
<li>and Commands, which are represented as URLs; describing
a function, which and can be executed using the dispatch API.</li>
</ul>
</p>
<p>
Note further:<br>
All changes you made on this configuration access modify the
configuration set inside memory only. You have to use
the com::sun::star::util::XFlushable interface
(which must be available at the same implementation object too), to
make it persistent.
</p>
@see AcceleratorConfiguration
@see dom::sun::star::util::XFlushable
@since OOo 2.0
*/
published interface XAcceleratorConfiguration
{
/** return the list of all key events, which
are available at this configuration set.
<p>
The key events are the "primary keys" of this configuration sets.
Means: Commands are registered for key events.
</p>
<p>
Such key event can be mapped to its bound command,
using the method getCommandForKeyEvent().
</p>
@see getCommandForKeyEvent().
@return A list of key events.
*/
sequence< com::sun::star::awt::KeyEvent > getAllKeyEvents();
/** return the registered command for the specified key event.
<p>
This function can be used to:<br>
<ul>
<li>by a generic service, which can execute commands if a
keyboard event occurs.</li>
<li>or to iterate over the whole container and change some
accelerator bindings.</li>
</ul>
</p>
@param aKeyEvent
the key event, where the registered command is searched for.
@return The registered command for the specified key event.
@throws ::com::sun::star::container::NoSuchElementException
if the key event is an invalid one or does not exists
inside this configuration set.
*/
string getCommandByKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
raises(com::sun::star::container::NoSuchElementException);
/** modify or create a key - command - binding.
<p>
If the specified key event does not already exists inside this
configuration access, it will be created and the command will be
registered for it.
</p>
<p>
If the specified key event already exists, its command will
be overwritten with the new command. There is no warning nor any error
about that! The outside code has to use the method getCommandForKeyEvent()
to check for possible collisions.
</p>
<p>
Note: This method can't be used to remove entities from the configuration set.
Empty parameters will result into an exception!
Use the method removeKeyEvent() instead.
</p>
@see removeKeyEvent()
@param aKeyEvent
specify the key event, which must be updated or new created.
@param sCommand
the new command for the specified key event.
@throws ::com::sun::star::lang::IllegalArgumentException
if the key event isn't a valid one. Commands can be
checked only, if they are empty. Because every URL schema can be used
by commands in general, so it's not possible to validate it.
*/
void setKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent,
[in] string sCommand )
raises(com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::NoSuchElementException);
/** remove a key-command-binding from this configuration set.
@param aKeyEvent
the key event, which should be removed.
@throws ::com::sun::star::container::NoSuchElementException
if the key event does not exists inside this configuration set.
*/
void removeKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
raises(com::sun::star::container::NoSuchElementException);
/** optimized access to the relation "command-key" instead
of "key-command" which is provided normally by this interface.
<p>
It can be used to implement collision handling, if more than one
key event match to the same command. The returned list contains all
possible key events - and the outside code can select a possible one.
Of course - mostly this list will contain only one key event ...
</p>
@param sCommand
the command, where key bindings are searched for.
@return A list of com::sun::star::awt::KeyEvent structures,
where the specified command is registered for.
@throws ::com::sun::star::lang::IllegalArgumentException
if the specified command is empty. It can't be checked, if a command
is valid - because every URL schema can be used here.
@throws ::com::sun::star::container::NoSuchElementException
if the specified command isn't empty but does not
occur inside this configuration set.
*/
sequence< com::sun::star::awt::KeyEvent > getKeyEventsByCommand( [in] string sCommand )
raises(com::sun::star::lang::IllegalArgumentException ,
com::sun::star::container::NoSuchElementException);
/** optimized function to map a list of commands to a corresponding
list of key events.
<p>
It provides a fast mapping, which is e.g. needed by a menu or toolbar implementation.
E.g. a sub menu is described by a list of commands - and the implementation of the menu
must show the corresponding shortcuts. Iteration over all items of this configuration
set can be very expensive.
</p>
<p>
Instead to the method getKeyEventsForCommand() the returned list contains only
one(!) key event bound to one(!) requested command. If more than one key event
is bound to a command - a selection is done inside this method.
This internal selection can't be influenced from outside.
</p>
@attention Because it's not defined, that any command (e.g. configured inside a menu)
must have an accelerator - we can't reject the call if at least one command
does not occur inside this configuration set ...
We handle it more gracefully - and return an empty item instead of throwing
and exception.
@param lCommandList
a list of commands
@return A (non packed!) list of key events, where every item match by index
directly to a command of the specified <var>CommandList</var>.
If a command does not exists inside this configuration set, the
corresponding any value will be empty.
@throws ::com::sun::star::lang::IllegalArgumentException
if at least one of the specified commands is empty.
It can't be checked, if a command is valid -
because every URL schema can be used here.
*/
sequence< any > getPreferredKeyEventsForCommandList( [in] sequence< string > lCommandList )
raises(com::sun::star::lang::IllegalArgumentException,
com::sun::star::container::NoSuchElementException);
/** search for a key-command-binding inside this configuration set,
where the specified command is used.
<p>
If such binding could be located, the command will be removed
from it. If as result of that the key binding will be empty,
if will be removed too.
</p>
<p>
This is an optimized method, which can perform removing of commands
from this configuration set. Because normally Commands are "foreign keys"
and key identifier the "primary keys" - it needs some work to remove
all commands outside this container ...
</p>
@param sCommand
the command, which should be removed from any key binding.
@throws ::com::sun::star::lang::IllegalArgumentException
if the specified command is empty.
@throws ::com::sun::star::container::NoSuchElementException
if the specified command isn't used inside this configuration set.
*/
void removeCommandFromAllKeyEvents( [in] string sCommand )
raises(com::sun::star::lang::IllegalArgumentException ,
com::sun::star::container::NoSuchElementException);
/** specifies a persistence interface which supports to
load/store accelerator configuration data to a storage
and to retrieve information about the current state.
*/
interface com::sun::star::ui::XUIConfigurationPersistence;
/** connects this configuration to a new storage
which must be used further on subsequent calls of
com::sun::star::util::XConfigurationPersistence.load()
and com::sun::star::util::XConfigurationPersistence.store().
*/
interface com::sun::star::ui::XUIConfigurationStorage;
/** supports to notify other implementations about
changes of this accelerator configuration.
*/
interface com::sun::star::ui::XUIConfiguration;
}; // interface XAcceleratorConfiguration
}; }; }; }; // com.sun.star
#endif
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
