summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/ui/XAcceleratorConfiguration.idl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:06:44 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 09:06:44 +0000
commited5640d8b587fbcfed7dd7967f3de04b37a76f26 (patch)
tree7a5f7c6c9d02226d7471cb3cc8fbbf631b415303 /offapi/com/sun/star/ui/XAcceleratorConfiguration.idl
parentInitial commit. (diff)
downloadlibreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.tar.xz
libreoffice-ed5640d8b587fbcfed7dd7967f3de04b37a76f26.zip
Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'offapi/com/sun/star/ui/XAcceleratorConfiguration.idl')
-rw-r--r--offapi/com/sun/star/ui/XAcceleratorConfiguration.idl272
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: */