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