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

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