A class which represents an action manager. More...

#include <ActionManager.h>

Inheritance diagram for Qtilities::CoreGui::ActionManager:

Public Slots
void	unregisterCommandsForContext (int context)
	Unregisters all commands for the specified context id.

Public Member Functions
ActionContainer *	actionContainer (const QString &id) const
	Access function for menus and menu bars.
Core::Observer *	actionContainerObserver ()
	Returns the observer managing action containers.
Command *	command (const QString &id) const
	Access function for actions and shortcuts.
QWidget *	commandEditor ()
	Creates the command editor/shortcut configuration page.
Core::Observer *	commandObserver ()
	Returns the observer managing commands.
QList< Command * >	commandsWithKeySequence (QKeySequence shortcut)
	Returns commands that uses a specific shortcut mapping.
ActionContainer *	createMenu (const QString &id, bool &existed)
	Creates a menu with the given string ID.
ActionContainer *	createMenuBar (const QString &id, bool &existed)
	Creates a menu bar with the given string ID.
bool	loadShortcutMapping (const QString &file_name)
	Imports a previously exported shortcut configuration.
ActionContainer *	menu (const QString &id)
	Function to access a menu.
ActionContainer *	menuBar (const QString &id)
	Function to access a menu bar.
Command *	registerAction (const QString &id, QAction *action, const QList< int > &context=QList< int >())
	Registers an action with the action manager.
Command *	registerActionPlaceHolder (const QString &id, const QString &user_text, const QKeySequence &shortcut=QKeySequence(), const QList< int > &context=QList< int >(), const QIcon &icon=QIcon())
	Registers an action placeholder with the action manager.
Command *	registerShortcut (const QString &id, const QString &user_text, QShortcut *shortcut, const QList< int > &active_contexts=QList< int >())
	Function to register a shortcut in the action manager.
void	restoreDefaultShortcuts ()
	Restores the default shortcut configuration.
bool	saveShortcutMapping (const QString &file_name, Qtilities::ExportVersion version=Qtilities::Qtilities_Latest)
	Exports the current shortcut configuraiton.

Additional Inherited Members
Signals inherited from Qtilities::CoreGui::Interfaces::IActionManager
void	numberOfCommandsChanged ()
	Signal which is emitted when the number of actions in the action manager changes.

Detailed Description

A class which represents an action manager.

For more information see the Action Management article.

Member Function Documentation

QWidget * Qtilities::CoreGui::ActionManager::commandEditor ( )

virtual

Creates the command editor/shortcut configuration page.

The command editor widget is returned by the function call.

See also:: Qtilities::CoreGui::CommandEditor

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::ActionContainer * Qtilities::CoreGui::ActionManager::createMenu	(	const QString &	id,
		bool &	existed
	)

virtual

Creates a menu with the given string ID.

Parameters:

id	The string id which should be used to identify the menu.
existed	If a menu with the same name already existed this parameter will be set to true, false otherwise.

Returns:: The menu (newly created or old) which is represented by the string id.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::ActionContainer * Qtilities::CoreGui::ActionManager::createMenuBar	(	const QString &	id,
		bool &	existed
	)

virtual

Creates a menu bar with the given string ID.

Parameters:

id	The string id which should be used to identify the menu bar.
existed	If a menu bar with the same name already existed this parameter will be set to true, false otherwise.

Returns:: The menu bar (newly created or old) which is represented by the string id.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::ActionContainer * Qtilities::CoreGui::ActionManager::menu ( const QString & id )

virtual

Function to access a menu.

Parameters:

id	The string id of the menu requested.

Returns:: The menu which is represented by the string id. Null if no menu with the given id exists.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::ActionContainer * Qtilities::CoreGui::ActionManager::menuBar ( const QString & id )

virtual

Function to access a menu bar.

Parameters:

id	The string id of the menu bar requested.

Returns:: The menu bar which is represented by the string id. Null if no menu bar with the given id exists.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::Command * Qtilities::CoreGui::ActionManager::registerAction	(	const QString &	id,
		QAction *	action,
		const QList< int > &	context = `QList< int >()`
	)

virtual

Registers an action with the action manager.

This function can be used to register an action with the action manager. If an action placeholder already exists with the given id, this action will be added as a backend for the current proxy action under the given contexts.

Parameters:

id	The internal id used to represent the action. This is the name used to display the action in the action manager.
action	The backend action associated with the id & context pairing.
context	The context for which this action should be registered. The action manager is linked with the context manager and when the context changes, all the actions will be updated for the new context. When an action does not have a backend action specified for a given context, it will be disabled. Leaving the context the default QList<int>() will register it in the standard application context (always active).

Returns:: The command created for the given id. If a command with the given id already exists, the existing command is returned.

Note:: This function will set the shortcut of the backend action to QKeySequence() to avoid ambigious action triggers when the frontend action and the backend action are both active. If the frontend action does not have an shortcut associated with it yet, it will inherit the shortcut of action. If the frontend already contains an action which is different than the shortcut provided by action, an error message will be printed and the original shortcut will be used.; The user_text of the command will be taken from the action's text() function.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::Command * Qtilities::CoreGui::ActionManager::registerActionPlaceHolder	(	const QString &	id,
		const QString &	user_text,
		const QKeySequence &	key_sequence = `QKeySequence()`,
		const QList< int > &	context = `QList< int >()`,
		const QIcon &	icon = `QIcon()`
	)

virtual

Registers an action placeholder with the action manager.

This function is used to create a placeholder for future action types in the system. This is usefull in cases where the actual backend action is not registered at application startup. An example of this would be actions contained in an object produced by a factory. For these scenarios you must register an place holder for the action at startup (to allow the action to be visible in the command editor, and to allow the action to be set according to a previous shortcut mapping scheme at application startup). If you want to use the registerActionPlaceHolder function in this way, leave the context as default. This will create the action place holder and you can register backend actions at a later time using the registerAction() call.

You can also use this function if you want to create a command which is not a multi-backed proxy action. In that case you connect directly to the command->action() triggered() signal to access the action. If you want to use the registerActionPlaceHolder() function in this way you must provide an context for the action to force the function to create a default backend action for you for the specified context.

Parameters:

id	The internal id used to represent the action. This is the name used to display the action in the command editor.
user_text	The user visible text that will be used for this command.
shortcut	A shortcut to be associated with the command.
context	Pass an empty QList<int>() if you do want to use the action as an mutli backed action, pass the needed context otherwise.
icon	An icon to use in this placeholder.

Returns:: The command created for the given id. If a command with the given id already exists, the existing command is returned.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Qtilities::CoreGui::Command * Qtilities::CoreGui::ActionManager::registerShortcut	(	const QString &	id,
		const QString &	user_text,
		QShortcut *	shortcut,
		const QList< int > &	active_contexts = `QList< int >()`
	)

virtual

Function to register a shortcut in the action manager.

Parameters:

id	The internal id used to represent the shortcut. This is the name used to display the shortcut in the command editor.
user_text	The user visible text that will be used for this command.
shortcut	A reference to the shortcut to be registered. If this reference is invalid, this function does nothing.
active_contexts	Pass an empty QList<int>() if you do want to use the shortcut to be always active.

Returns:: The command created for the given id. If a command with the given id already exists, the existing command is returned.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

bool Qtilities::CoreGui::ActionManager::saveShortcutMapping	(	const QString &	file_name,
		Qtilities::ExportVersion	version = `Qtilities::Qtilities_Latest`
	)

virtual

Exports the current shortcut configuraiton.

Shorcut mappings are saved automatically when the user clicks apply on Qtilities::CoreGui::CommandEditor. Apart from that you need to save and load your settings manually as shown below:

// Load the previous session's keyboard mapping file.
QString shortcut_mapping_file = QString("%1/%2").arg(QtilitiesApplication::applicationSessionPath()).arg(qti_def_PATH_SHORTCUTS_FILE);
ACTION_MANAGER->loadShortcutMapping(shortcut_mapping_file);
int result = application.exec();
// Save the current keyboard mapping for the next session.
ACTION_MANAGER->saveShortcutMapping(shortcut_mapping_file);
return result;

Implements Qtilities::CoreGui::Interfaces::IActionManager.

void ActionManager::unregisterCommandsForContext ( int context )

virtualslot

Unregisters all commands for the specified context id.

Parameters:

context The applicable context.

This function was added in Qtilities v1.2.

Implements Qtilities::CoreGui::Interfaces::IActionManager.

Public Slots

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation