Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 272 insertions, 0 deletions

diff --git a/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl b/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl
new file mode 100644
index 000000000..39d02b28d
--- /dev/null
+++ b/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl
@@ -0,0 +1,272 @@
+/* -*- 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: */