offapi/com/sun/star/ui/XAcceleratorConfiguration.idl

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