/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   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 .
 */
#ifndef __com_sun_star_ui_XAcceleratorConfiguration_idl__
#define __com_sun_star_ui_XAcceleratorConfiguration_idl__

#include <com/sun/star/ui/XUIConfiguration.idl>
#include <com/sun/star/ui/XUIConfigurationPersistence.idl>
#include <com/sun/star/ui/XUIConfigurationStorage.idl>
#include <com/sun/star/awt/KeyEvent.idl>
#include <com/sun/star/lang/IllegalArgumentException.idl>
#include <com/sun/star/container/NoSuchElementException.idl>

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 configuration access modify the
    configuration set inside memory only. You have to use
    the com::sun::star::util::XFlushable interface
    (which must be available at the same implementation object too), to
    make it persistent.
    </p>

    @see    AcceleratorConfiguration
    @see    dom::sun::star::util::XFlushable

    @since OOo 2.0
*/
published interface XAcceleratorConfiguration
{
    /** return the list of all key events, which
        are available at this configuration set.

        <p>
        The key events are the "primary keys" of this configuration sets.
        Means: Commands are registered 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 occurs.</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 can't 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 isn't a valid one. Commands can be
                checked only, if they are empty. Because every URL schema can be used
                by commands in general, so it's not possible to validate it.
     */
    void setKeyEvent( [in] com::sun::star::awt::KeyEvent aKeyEvent,
                      [in] string                        sCommand )
        raises(com::sun::star::lang::IllegalArgumentException,
               com::sun::star::container::NoSuchElementException);

    /** 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 normally by this interface.

        <p>
        It can be used to implement collision handling, if more than one
        key event match to the same command. The returned list contains all
        possible key events - and the outside code can select a 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 com::sun::star::awt::KeyEvent structures,
                where the specified command is registered for.

        @throws ::com::sun::star::lang::IllegalArgumentException
                if the specified command is empty. It can't 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 isn't empty but does not
                occur 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 than one key event
        is bound to a command - a selection is done inside this method.
        This internal selection can't be influenced from outside.
        </p>

        @attention  Because it's not defined, that any command (e.g. configured inside a menu)
                    must have an accelerator - we can't reject the call if at least one command
                    does not occur 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 can't 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,
               com::sun::star::container::NoSuchElementException);

    /** search for a 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 normally 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 isn't 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
        com::sun::star::util::XConfigurationPersistence.load()
        and com::sun::star::util::XConfigurationPersistence.store().
     */
    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

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */