From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- .../com/sun/star/ui/XAcceleratorConfiguration.idl | 272 +++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 offapi/com/sun/star/ui/XAcceleratorConfiguration.idl (limited to 'offapi/com/sun/star/ui/XAcceleratorConfiguration.idl') 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 +#include +#include +#include +#include +#include + +module com { module sun { module star { module ui { + +/** provides read/write access to an accelerator configuration set. + +

+ Such configuration set base on:
+

    +
  • Key events structure
    • +
  • and Commands, which are represented as URLs; describing + a function, which and can be executed using the dispatch API.
    • +
+

+ +

+ Note further:
+ 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. +

+ + @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. + +

+ The key events are the "primary keys" of this configuration sets. + Means: Commands are registered for key events. +

+ +

+ Such key event can be mapped to its bound command, + using the method getCommandForKeyEvent(). +

+ + @see getCommandForKeyEvent(). + + @return A list of key events. + */ + sequence< com::sun::star::awt::KeyEvent > getAllKeyEvents(); + + /** return the registered command for the specified key event. + +

+ This function can be used to:
+

    +
  • by a generic service, which can execute commands if a + keyboard event occurs.
    • +
  • or to iterate over the whole container and change some + accelerator bindings.
    • +
+

+ + @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. + +

+ 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. +

+ +

+ 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. +

+ +

+ 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. +

+ + @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. + +

+ 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 ... +

+ + @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. + +

+ 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. +

+ +

+ 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. +

+ + @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 CommandList. + 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. + +

+ 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. +

+ +

+ 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 ... +

+ + @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: */ -- cgit v1.2.3