diff options
Diffstat (limited to 'offapi/com/sun/star/ui/XAcceleratorConfiguration.idl')
| -rw-r--r-- | offapi/com/sun/star/ui/XAcceleratorConfiguration.idl | 272 |
1 files changed, 272 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 000000000..39d02b28d --- /dev/null +++ b/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl @@ -0,0 +1,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: */ |