272 lines
11 KiB
Text
272 lines
11 KiB
Text
/* -*- 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
|
|
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
|
|
*/
|
|
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 its 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 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 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 its 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 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 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: */
|