| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the 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 OpenOffice 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 |
