Interface used to communicate with the action manager. More...

#include <IActionManager.h>

Inheritance diagram for Qtilities::CoreGui::Interfaces::IActionManager:

Signals
void	numberOfCommandsChanged ()
	Signal which is emitted when the number of actions in the action manager changes.

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

Detailed Description

Interface used to communicate with the action manager.

For more information see the Action Management article.

Member Function Documentation

virtual QWidget* Qtilities::CoreGui::Interfaces::IActionManager::commandEditor ( )

pure virtual

Creates the command editor/shortcut configuration page.

The command editor widget is returned by the function call.

See also:: Qtilities::CoreGui::CommandEditor

Implemented in Qtilities::CoreGui::ActionManager.

virtual ActionContainer* Qtilities::CoreGui::Interfaces::IActionManager::createMenu	(	const QString &	id,
		bool &	existed
	)

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

Implemented in Qtilities::CoreGui::ActionManager.

virtual ActionContainer* Qtilities::CoreGui::Interfaces::IActionManager::createMenuBar	(	const QString &	id,
		bool &	existed
	)

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

Implemented in Qtilities::CoreGui::ActionManager.

virtual ActionContainer* Qtilities::CoreGui::Interfaces::IActionManager::menu ( const QString & id )

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

Implemented in Qtilities::CoreGui::ActionManager.

virtual ActionContainer* Qtilities::CoreGui::Interfaces::IActionManager::menuBar ( const QString & id )

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

Implemented in Qtilities::CoreGui::ActionManager.

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

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

Implemented in Qtilities::CoreGui::ActionManager.

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

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

Implemented in Qtilities::CoreGui::ActionManager.

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

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

Implemented in Qtilities::CoreGui::ActionManager.

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

pure 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;

Implemented in Qtilities::CoreGui::ActionManager.

virtual void Qtilities::CoreGui::Interfaces::IActionManager::unregisterCommandsForContext ( int context )

pure virtual

Unregisters all commands for the specified context id.

Parameters:

context The applicable context.

This function was added in Qtilities v1.2.

Implemented in Qtilities::CoreGui::ActionManager.

Signals

Public Member Functions

Detailed Description

Member Function Documentation