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