/**************************************************************
 * 
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 *************************************************************/


#ifndef __com_sun_star_ui_XAcceleratorConfiguration_idl__
#define __com_sun_star_ui_XAcceleratorConfiguration_idl__

#ifndef __com_sun_star_ui_XUIConfiguration_idl__
#include <com/sun/star/ui/XUIConfiguration.idl>
#endif

#ifndef __com_sun_star_ui_XUIConfigurationPersistence_idl__
#include <com/sun/star/ui/XUIConfigurationPersistence.idl>
#endif

#ifndef __com_sun_star_ui_XUIConfigurationStorage_idl__
#include <com/sun/star/ui/XUIConfigurationStorage.idl>
#endif

#ifndef __com_sun_star_awt_KeyEvent_idl__
#include <com/sun/star/awt/KeyEvent.idl>
#endif

#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
#include <com/sun/star/lang/IllegalArgumentException.idl>
#endif

#ifndef __com_sun_star_container_NoSuchElementException_idl__
#include <com/sun/star/container/NoSuchElementException.idl>
#endif

module com {  module sun {  module star {  module ui {

//-----------------------------------------------
/** provides read/write access to an accelerator configuration set.

    <p>
    Such configuration set base on:<br>
    <ul>
        <li>Key events structure</li>
        <li>and Commands, which are represented as URLs; describing
            a function, which and can be executed using the dispatch API.</li>
    </ul>
    </p>

	<p>
    Note further:<br>
    All changes you made on this configration access modify the
    the configuration set inside memory only. You have to use
    the <type scope="com::sun::star::util">XFlushable</type> interface
    (which must be available at the same implementation object too), to
    make it persistent.
    </p>
    
    @see    AcceleratorConfiguration
    @see    <type scope="dom::sun::star::util">XFlushable</type>

    @since OOo 2.0
*/
interface XAcceleratorConfiguration
{
    //-------------------------------------------
    /** return the list of all key events, which
        are available at this configration set.
        
        <p>
        The key events are the "primary keys" of this configuration sets.
        Means: Commands are registerd for key events.
        </p>
        
        <p>
        Such key event can be mapped to its bound command,
        using the method getCommandForKeyEvent(). 
        </p>
        
        @see        getCommandForKeyEvent().
        
        @return     A list of key events.
      */
    sequence< com::sun::star::awt::KeyEvent > getAllKeyEvents();
    
    //-------------------------------------------
    /** return the registered command for the specified key event.
    
        <p>
        This function can be used to:<br>
        <ul>
            <li>by a generic service, which can execute commands if a
                keyboard event occures.</li>
            <li>or to iterate over the whole container and change some
                accelerator bindings.</li>
        </ul>
        </p>
        
        @param  aKeyEvent
                the key event, where the registered command is searched for.
                
        @return The registered command for the specified key event.
                
        @throws ::com::sun::star::container::NoSuchElementException
                if the key event is an invalid one or does not exists
                inside this configuration set.
     */        
    string getCommandByKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
        raises(com::sun::star::container::NoSuchElementException);

    //-------------------------------------------
    /** modify or create a key - command - binding.
    
        <p>
        If the specified key event does not already exists inside this
        configuration access, it will be created and the command will be
        registered for it.
        </p>
        
        <p>
        If the specified key event already exists, its command will
        be overwritten with the new command. There is no warning nor any error
        about that! The outside code has to use the method getCommandForKeyEvent()
        to check for possible collisions.
        </p>
        
        <p>
        Note: This method cant be used to remove entities from the configuration set.
        Empty parameters will result into an exception!
        Use the method removeKeyEvent() instead.
        </p>
        
        @see    removeKeyEvent()
        
        @param  aKeyEvent
                specify the key event, which must be updated or new created.
                
        @param  sCommand
                the new command for the specified key event.

        @throws ::com::sun::star::lang::IllegalArgumentException
                if the key event isnt a valid one. Commands can be
                checked only, if they are empty. Because every URL schema can be used
                by commands in general, so its not possible to validate it.                
     */
    void setKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent,
                      [in] string                        sCommand )
        raises(com::sun::star::lang::IllegalArgumentException);

    //-------------------------------------------
    /** remove a key-command-binding from this configuration set.
    
        @param  aKeyEvent
                the key event, which should be removed.
                
        @throws ::com::sun::star::container::NoSuchElementException
                if the key event does not exists inside this configuration set.
     */
    void removeKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent )
        raises(com::sun::star::container::NoSuchElementException);
               
    //-------------------------------------------
    /** optimized access to the relation "command-key" instead
        of "key-command" which is provided normaly by this interface.
        
        <p>
        It can be used to implement collision handling, if more then one
        key event match to the same command. The returned list contains all
        possible key events - and the outside code can select an possible one.
        Of course - mostly this list will contain only one key event ...
        </p>
        
        @param  sCommand
                the command, where key bindings are searched for.
                
        @return A list of <type scope="com::sun::star::awt">KeyEvent</type> structures,
                where the pecified command is registered for.
                
        @throws ::com::sun::star::lang::IllegalArgumentException
                if the specified command is empty. It cant be checked, if a command
                is valid - because every URL schema can be used here.

        @throws ::com::sun::star::container::NoSuchElementException
                if the specified command isnt empty but does not
                occure inside this configuration set.
     */
    sequence< com::sun::star::awt::KeyEvent > getKeyEventsByCommand( [in] string sCommand )
        raises(com::sun::star::lang::IllegalArgumentException   ,
               com::sun::star::container::NoSuchElementException);
               
    //-------------------------------------------
    /** optimized function to map a list of commands to a corresponding
        list of key events.
        
        <p>
        It provides a fast mapping, which is e.g. needed by a menu or toolbar implementation.
        E.g. a sub menu is described by a list of commands - and the implementation of the menu
        must show the corresponding shortcuts. Iteration over all items of this configuration
        set can be very expensive.
        </p>
        
        <p>
        Instead to the method getKeyEventsForCommand() the returned list contains only
        one(!) key event bound to one(!) requested command. If more then one key event
        is bound to a command - a selection is done inside this method.
        This internal selection cant be influenced from outside.
        </p>
        
        @attention  Because its not defined, that any command (e.g. configured inside a menu)
                    must have an accelerator - we cant reject the call if at least one command
                    does not occure inside this configuration set ...
                    We handle it more gracefully - and return an empty item instead of throwing
                    and exception.
        
        @param  lCommandList
                a list of commands
                
        @return A (non packed!) list of key events, where every item match by index
                directly to a command of the specified <var>CommandList</var>.
                If a command does not exists inside this configuration set, the
                corresponding any value will be empty.

        @throws ::com::sun::star::lang::IllegalArgumentException
                if at least one of the specified commands is empty.
                It cant be checked, if a command is valid -
                because every URL schema can be used here.
     */
    sequence< any > getPreferredKeyEventsForCommandList( [in] sequence< string > lCommandList )
        raises(com::sun::star::lang::IllegalArgumentException);

    //-------------------------------------------
    /** search for an key-command-binding inside this configuration set,
        where the specified command is used.
        
        <p>
        If such binding could be located, the command will be removed
        from it. If as result of that the key binding will be empty,
        if will be removed too.
        </p>
        
        <p>
        This is an optimized method, which can perform removing of commands
        from this configuration set. Because normaly Commands are "foreign keys"
        and key identifier the "primary keys" - it needs some work to remove
        all commands outside this container ...
        </p>
        
        @param  sCommand
                the command, which should be removed from any key binding.
                
        @throws ::com::sun::star::lang::IllegalArgumentException
                if the specified command is empty.
                
        @throws ::com::sun::star::container::NoSuchElementException
                if the specified command isnt used inside this configuration set.
     */
    void removeCommandFromAllKeyEvents( [in] string sCommand )        
        raises(com::sun::star::lang::IllegalArgumentException   ,
               com::sun::star::container::NoSuchElementException);
               
    //-------------------------------------------
    /** specifies a persistence interface which supports to
        load/store accelerator configuration data to a storage
        and to retrieve information about the current state.
     */
    interface com::sun::star::ui::XUIConfigurationPersistence;
    
    //-------------------------------------------
    /** connects this configuration to a new storage
        which must be used further on subsequent calls of
        <type scope="com::sun::star::util::">XConfigurationPersistence.load()</type>
        and <type scope="com::sun::star::util::">XConfigurationPersistence.store()</type>.
     */
    interface com::sun::star::ui::XUIConfigurationStorage;
    
    //-------------------------------------------
    /** supports to notify other implementations about
        changes of this accelerator configuration.
     */
    interface com::sun::star::ui::XUIConfiguration;
    
}; // interface XAcceleratorConfiguration

}; }; }; }; // com.sun.star

#endif