diff options
Diffstat (limited to 'offapi/com/sun/star/ui/XAcceleratorConfiguration.idl')
| -rw-r--r-- | offapi/com/sun/star/ui/XAcceleratorConfiguration.idl | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl b/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl new file mode 100644 index 000000000000..46f04e31064f --- /dev/null +++ b/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl @@ -0,0 +1,304 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_ui_XAcceleratorConfiguration_idl__ +#define __com_sun_star_ui_XAcceleratorConfiguration_idl__ + +#ifndef __com_sun_star_ui_XUIConfiguration_idl__ +#include <com/sun/star/ui/XUIConfiguration.idl> +#endif + +#ifndef __com_sun_star_ui_XUIConfigurationPersistence_idl__ +#include <com/sun/star/ui/XUIConfigurationPersistence.idl> +#endif + +#ifndef __com_sun_star_ui_XUIConfigurationStorage_idl__ +#include <com/sun/star/ui/XUIConfigurationStorage.idl> +#endif + +#ifndef __com_sun_star_awt_KeyEvent_idl__ +#include <com/sun/star/awt/KeyEvent.idl> +#endif + +#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ +#include <com/sun/star/lang/IllegalArgumentException.idl> +#endif + +#ifndef __com_sun_star_container_NoSuchElementException_idl__ +#include <com/sun/star/container/NoSuchElementException.idl> +#endif + +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 configration access modify the + the configuration set inside memory only. You have to use + the <type scope="com::sun::star::util">XFlushable</type> interface + (which must be available at the same implementation object too), to + make it persistent. + </p> + + @see AcceleratorConfiguration + @see <type scope="dom::sun::star::util">XFlushable</type> + + @since OOo 2.0 +*/ +interface XAcceleratorConfiguration +{ + //------------------------------------------- + /** return the list of all key events, which + are available at this configration set. + + <p> + The key events are the "primary keys" of this configuration sets. + Means: Commands are registerd 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 occures.</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 cant 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 isnt a valid one. Commands can be + checked only, if they are empty. Because every URL schema can be used + by commands in general, so its not possible to validate it. + */ + void setKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent, + [in] string sCommand ) + raises(com::sun::star::lang::IllegalArgumentException); + + //------------------------------------------- + /** 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 normaly by this interface. + + <p> + It can be used to implement collision handling, if more then one + key event match to the same command. The returned list contains all + possible key events - and the outside code can select an 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 <type scope="com::sun::star::awt">KeyEvent</type> structures, + where the pecified command is registered for. + + @throws ::com::sun::star::lang::IllegalArgumentException + if the specified command is empty. It cant 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 isnt empty but does not + occure 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 then one key event + is bound to a command - a selection is done inside this method. + This internal selection cant be influenced from outside. + </p> + + @attention Because its not defined, that any command (e.g. configured inside a menu) + must have an accelerator - we cant reject the call if at least one command + does not occure 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 cant 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); + + //------------------------------------------- + /** search for an 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 normaly 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 isnt 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 + <type scope="com::sun::star::util::">XConfigurationPersistence.load()</type> + and <type scope="com::sun::star::util::">XConfigurationPersistence.store()</type>. + */ + 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 |