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

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