1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_ui_XAcceleratorConfiguration_idl__
24#define __com_sun_star_ui_XAcceleratorConfiguration_idl__
25
26#ifndef __com_sun_star_ui_XUIConfiguration_idl__
27#include <com/sun/star/ui/XUIConfiguration.idl>
28#endif
29
30#ifndef __com_sun_star_ui_XUIConfigurationPersistence_idl__
31#include <com/sun/star/ui/XUIConfigurationPersistence.idl>
32#endif
33
34#ifndef __com_sun_star_ui_XUIConfigurationStorage_idl__
35#include <com/sun/star/ui/XUIConfigurationStorage.idl>
36#endif
37
38#ifndef __com_sun_star_awt_KeyEvent_idl__
39#include <com/sun/star/awt/KeyEvent.idl>
40#endif
41
42#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
43#include <com/sun/star/lang/IllegalArgumentException.idl>
44#endif
45
46#ifndef __com_sun_star_container_NoSuchElementException_idl__
47#include <com/sun/star/container/NoSuchElementException.idl>
48#endif
49
50module com {  module sun {  module star {  module ui {
51
52//-----------------------------------------------
53/** provides read/write access to an accelerator configuration set.
54
55    <p>
56    Such configuration set base on:<br>
57    <ul>
58        <li>Key events structure</li>
59        <li>and Commands, which are represented as URLs; describing
60            a function, which and can be executed using the dispatch API.</li>
61    </ul>
62    </p>
63
64	<p>
65    Note further:<br>
66    All changes you made on this configration access modify the
67    the configuration set inside memory only. You have to use
68    the <type scope="com::sun::star::util">XFlushable</type> interface
69    (which must be available at the same implementation object too), to
70    make it persistent.
71    </p>
72
73    @see    AcceleratorConfiguration
74    @see    <type scope="dom::sun::star::util">XFlushable</type>
75
76    @since OpenOffice 2.0
77*/
78interface XAcceleratorConfiguration
79{
80    //-------------------------------------------
81    /** return the list of all key events, which
82        are available at this configration set.
83
84        <p>
85        The key events are the "primary keys" of this configuration sets.
86        Means: Commands are registerd for key events.
87        </p>
88
89        <p>
90        Such key event can be mapped to its bound command,
91        using the method getCommandForKeyEvent().
92        </p>
93
94        @see        getCommandForKeyEvent().
95
96        @return     A list of key events.
97      */
98    sequence< com::sun::star::awt::KeyEvent > getAllKeyEvents();
99
100    //-------------------------------------------
101    /** return the registered command for the specified key event.
102
103        <p>
104        This function can be used to:<br>
105        <ul>
106            <li>by a generic service, which can execute commands if a
107                keyboard event occures.</li>
108            <li>or to iterate over the whole container and change some
109                accelerator bindings.</li>
110        </ul>
111        </p>
112
113        @param  aKeyEvent
114                the key event, where the registered command is searched for.
115
116        @return The registered command for the specified key event.
117
118        @throws ::com::sun::star::container::NoSuchElementException
119                if the key event is an invalid one or does not exists
120                inside this configuration set.
121     */
122    string getCommandByKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
123        raises(com::sun::star::container::NoSuchElementException);
124
125    //-------------------------------------------
126    /** modify or create a key - command - binding.
127
128        <p>
129        If the specified key event does not already exists inside this
130        configuration access, it will be created and the command will be
131        registered for it.
132        </p>
133
134        <p>
135        If the specified key event already exists, its command will
136        be overwritten with the new command. There is no warning nor any error
137        about that! The outside code has to use the method getCommandForKeyEvent()
138        to check for possible collisions.
139        </p>
140
141        <p>
142        Note: This method can't be used to remove entities from the configuration set.
143        Empty parameters will result into an exception!
144        Use the method removeKeyEvent() instead.
145        </p>
146
147        @see    removeKeyEvent()
148
149        @param  aKeyEvent
150                specify the key event, which must be updated or new created.
151
152        @param  sCommand
153                the new command for the specified key event.
154
155        @throws ::com::sun::star::lang::IllegalArgumentException
156                if the key event isn't a valid one. Commands can be
157                checked only, if they are empty. Because every URL schema can be used
158                by commands in general, so its not possible to validate it.
159     */
160    void setKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent,
161                      [in] string                        sCommand )
162        raises(com::sun::star::lang::IllegalArgumentException);
163
164    //-------------------------------------------
165    /** remove a key-command-binding from this configuration set.
166
167        @param  aKeyEvent
168                the key event, which should be removed.
169
170        @throws ::com::sun::star::container::NoSuchElementException
171                if the key event does not exists inside this configuration set.
172     */
173    void removeKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
174        raises(com::sun::star::container::NoSuchElementException);
175
176    //-------------------------------------------
177    /** optimized access to the relation "command-key" instead
178        of "key-command" which is provided normally by this interface.
179
180        <p>
181        It can be used to implement collision handling, if more then one
182        key event match to the same command. The returned list contains all
183        possible key events - and the outside code can select an possible one.
184        Of course - mostly this list will contain only one key event ...
185        </p>
186
187        @param  sCommand
188                the command, where key bindings are searched for.
189
190        @return A list of <type scope="com::sun::star::awt">KeyEvent</type> structures,
191                where the pecified command is registered for.
192
193        @throws ::com::sun::star::lang::IllegalArgumentException
194                if the specified command is empty. It can't be checked, if a command
195                is valid - because every URL schema can be used here.
196
197        @throws ::com::sun::star::container::NoSuchElementException
198                if the specified command isn't empty but does not
199                occur inside this configuration set.
200     */
201    sequence< com::sun::star::awt::KeyEvent > getKeyEventsByCommand( [in] string sCommand )
202        raises(com::sun::star::lang::IllegalArgumentException   ,
203               com::sun::star::container::NoSuchElementException);
204
205    //-------------------------------------------
206    /** optimized function to map a list of commands to a corresponding
207        list of key events.
208
209        <p>
210        It provides a fast mapping, which is e.g. needed by a menu or toolbar implementation.
211        E.g. a sub menu is described by a list of commands - and the implementation of the menu
212        must show the corresponding shortcuts. Iteration over all items of this configuration
213        set can be very expensive.
214        </p>
215
216        <p>
217        Instead to the method getKeyEventsForCommand() the returned list contains only
218        one(!) key event bound to one(!) requested command. If more then one key event
219        is bound to a command - a selection is done inside this method.
220        This internal selection can't be influenced from outside.
221        </p>
222
223        @attention  Because its not defined, that any command (e.g. configured inside a menu)
224                    must have an accelerator - we can't reject the call if at least one command
225                    does not occur inside this configuration set ...
226                    We handle it more gracefully - and return an empty item instead of throwing
227                    and exception.
228
229        @param  lCommandList
230                a list of commands
231
232        @return A (non packed!) list of key events, where every item match by index
233                directly to a command of the specified <var>CommandList</var>.
234                If a command does not exists inside this configuration set, the
235                corresponding any value will be empty.
236
237        @throws ::com::sun::star::lang::IllegalArgumentException
238                if at least one of the specified commands is empty.
239                It can't be checked, if a command is valid -
240                because every URL schema can be used here.
241     */
242    sequence< any > getPreferredKeyEventsForCommandList( [in] sequence< string > lCommandList )
243        raises(com::sun::star::lang::IllegalArgumentException);
244
245    //-------------------------------------------
246    /** search for an key-command-binding inside this configuration set,
247        where the specified command is used.
248
249        <p>
250        If such binding could be located, the command will be removed
251        from it. If as result of that the key binding will be empty,
252        if will be removed too.
253        </p>
254
255        <p>
256        This is an optimized method, which can perform removing of commands
257        from this configuration set. Because normally Commands are "foreign keys"
258        and key identifier the "primary keys" - it needs some work to remove
259        all commands outside this container ...
260        </p>
261
262        @param  sCommand
263                the command, which should be removed from any key binding.
264
265        @throws ::com::sun::star::lang::IllegalArgumentException
266                if the specified command is empty.
267
268        @throws ::com::sun::star::container::NoSuchElementException
269                if the specified command isn't used inside this configuration set.
270     */
271    void removeCommandFromAllKeyEvents( [in] string sCommand )
272        raises(com::sun::star::lang::IllegalArgumentException   ,
273               com::sun::star::container::NoSuchElementException);
274
275    //-------------------------------------------
276    /** specifies a persistence interface which supports to
277        load/store accelerator configuration data to a storage
278        and to retrieve information about the current state.
279     */
280    interface com::sun::star::ui::XUIConfigurationPersistence;
281
282    //-------------------------------------------
283    /** connects this configuration to a new storage
284        which must be used further on subsequent calls of
285        <type scope="com::sun::star::util::">XConfigurationPersistence.load()</type>
286        and <type scope="com::sun::star::util::">XConfigurationPersistence.store()</type>.
287     */
288    interface com::sun::star::ui::XUIConfigurationStorage;
289
290    //-------------------------------------------
291    /** supports to notify other implementations about
292        changes of this accelerator configuration.
293     */
294    interface com::sun::star::ui::XUIConfiguration;
295
296}; // interface XAcceleratorConfiguration
297
298}; }; }; }; // com.sun.star
299
300#endif
301