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