KCommandManager Class Reference

The KCommandManager class emulates the way MFC command handling. More...

#include <kcommandmanager.h>

Inheritance diagram for KCommandManager:

Collaboration diagram for KCommandManager:

Signals
void	commandUpdated ()
	Emitted when commands have been updated.

Public Member Functions
void	addMenu (QMenu *menu)
	Adds an existing menu, to manage the update of the menu items.
void	addToolBar (int id, QToolBar *toolBar, QWidget *context=nullptr)
	Adds an existing toolbar, to manage the update of the toolbar items.
void	clearAllCommands ()
	Removes all commands.
QAction *	command (int id)
	Returns the command with the given id, or nullptr if it doesn't exist.
template<typename T >
void	connectCommand (int id, T *object, void(T::*method)())
	Connects a command handler to the command with the given id.
template<typename T >
void	connectCommand (int id, T *object, void(T::*method)(unsigned int))
	Connects a command handler to the command with the given id.
template<typename T >
void	connectCommand (int id, T method)
	Connects a command handler to the command with the given id.
template<typename T >
void	connectCommandRange (int first, int last, T *object, void(T::*method)(unsigned int))
	Connects a command handler to a range of commands.
template<typename T >
void	connectCommandRangeUpdater (int first, int last, T *object, void(T::*method)(QAction *))
	Connects an update handler to a range of commands.
template<typename T >
void	connectCommandUpdater (int id, T *object, void(T::*method)(QAction *))
	Connects an update handler to the command with the given id.
template<typename T >
void	connectCommandUpdater (int id, T method)
	Connects an update handler to the command with the given id.
QAction *	createCommand (int id, const QString &title=QString(), QWidget *context=nullptr)
	Create a command object.
QMenu *	createMenu (const QString &title, QWidget *parent=nullptr)
	Creates a menu with the given title.
QMenu *	createMenu (QWidget *parent=nullptr)
	Creates a menu with the given title.
QToolBar *	createToolBar (int id, const QString &title, QWidget *context=nullptr)
	Creates a toolbar with the given title.
QWidgetAction *	createWidgetCommand (int id, QWidget *defaultWidget, QWidget *context=nullptr)
	Create a Widget command object.
QAction *	findOrCreateCommand (int id, const QString &title=QString(), QWidget *context=nullptr)
	Find or create a command object.
bool	hasCommand (int id) const
	Returns true if a command with the given id exists.
	KCommandManager (QObject *parent=nullptr)
void	removeCommand (int id)
	Returns the command with the given id.
void	setCommandChecked (int id, bool checked)
	Checks or unchecks the command with the given id.
void	setCommandEnabled (int id, bool enabled)
	Enables or disables the command with the given id.
void	startUpdateTimer ()
	Starts the update timer.
void	stopUpdateTimer ()
	Stops the update timer.
QToolBar *	toolBar (int id) const
	Returns the toolbar with the given id.
void	triggerCommand (int id) const
	Triggers the command with the given id.
void	triggerCommandAsync (int id) const
	Triggers the command with the given id asynchronously.
void	updateAllToolBars ()
	Updates the state of the commands on all toolbars.
template<typename Func >
void	visitCommands (Func fn)
	Visits each command in the command manager and applies the given function.
	~KCommandManager ()

Detailed Description

The KCommandManager class emulates the way MFC command handling.

The way Qt handles command messages from objects such as menu items or toolbar buttons is different from MFC. In MFC, commands are identified by command IDs, and a command target receives a WM_COMMAND message when an object is activated. In Qt, these actions are represented by QAction objects which emit the triggered() signal when activated.

To facilitate porting from MFC to Qt code with minimal changes, this class provides a mapping from MFC command IDs to QActions. QActions representing a command ID should be created via this class, and command target handlers should be registered with this class. When QActions are triggered, the registered handler will be called.

In MFC it's also possible to register update handlers for the commands to update their state in menus and toolbars (e.g. via the ON_UPDATE_COMMAND_UI macro). To emulate this, QToolBars can be created via this class, and their update handlers can be registered with this class.

In MFC updates for commands are done automatically on idle time, but in Qt, this is done via a timer. All commands on visible toolbars will be periodically updated.

See also

https://learn.microsoft.com/en-us/cpp/mfc/reference/message-map-macros-mfc#on_command

https://learn.microsoft.com/en-us/cpp/mfc/reference/message-map-macros-mfc#on_update_command_ui

Constructor & Destructor Documentation

KCommandManager()

KCommandManager::KCommandManager ( QObject * parent = nullptr )

explicit

~KCommandManager()

KCommandManager::~KCommandManager

(

)

Member Function Documentation

addMenu()

void KCommandManager::addMenu

(

QMenu *

menu

)

Adds an existing menu, to manage the update of the menu items.

addToolBar()

void KCommandManager::addToolBar	(	int	id,
		QToolBar *	toolBar,
		QWidget *	context = nullptr )

Adds an existing toolbar, to manage the update of the toolbar items.

clearAllCommands()

void KCommandManager::clearAllCommands

(

)

Removes all commands.

command()

QAction * KCommandManager::command

(

int

id

)

Returns the command with the given id, or nullptr if it doesn't exist.

commandUpdated

void KCommandManager::commandUpdated ( )

signal

Emitted when commands have been updated.

connectCommand() [1/3]

template<typename T >

void KCommandManager::connectCommand	(	int	id,
		T *	object,
		void(T::*	method )() )

Connects a command handler to the command with the given id.

connectCommand() [2/3]

template<typename T >

void KCommandManager::connectCommand	(	int	id,
		T *	object,
		void(T::*	method )(unsigned int) )

Connects a command handler to the command with the given id.

connectCommand() [3/3]

template<typename T >

void KCommandManager::connectCommand	(	int	id,
		T	method )

Connects a command handler to the command with the given id.

connectCommandRange()

template<typename T >

void KCommandManager::connectCommandRange	(	int	first,
		int	last,
		T *	object,
		void(T::*	method )(unsigned int) )

Connects a command handler to a range of commands.

connectCommandRangeUpdater()

template<typename T >

void KCommandManager::connectCommandRangeUpdater	(	int	first,
		int	last,
		T *	object,
		void(T::*	method )(QAction *) )

Connects an update handler to a range of commands.

connectCommandUpdater() [1/2]

template<typename T >

void KCommandManager::connectCommandUpdater	(	int	id,
		T *	object,
		void(T::*	method )(QAction *) )

Connects an update handler to the command with the given id.

connectCommandUpdater() [2/2]

template<typename T >

void KCommandManager::connectCommandUpdater	(	int	id,
		T	method )

Connects an update handler to the command with the given id.

createCommand()

QAction * KCommandManager::createCommand	(	int	id,
		const QString &	title = QString(),
		QWidget *	context = nullptr )

Create a command object.

Parameters

id	ID of the command, should be the same as the MFC command ID
title	Title of the command
context	Context used for the command, the command will be added to the widget's action list

Returns

QAction* Return the created command

createMenu() [1/2]

QMenu * KCommandManager::createMenu	(	const QString &	title,
		QWidget *	parent = nullptr )

Creates a menu with the given title.

The menu will be added to the menu bar if the parent is a QMenuBar, or to the parent menu if the parent is a QMenu. Just before showing the menu, all update handlers will be called to update the state of the menu items.

createMenu() [2/2]

QMenu * KCommandManager::createMenu

(

QWidget *

parent = nullptr

)

Creates a menu with the given title.

Just before showing the menu, all update handlers will be called to update the state of the menu items.

createToolBar()

QToolBar * KCommandManager::createToolBar	(	int	id,
		const QString &	title,
		QWidget *	context = nullptr )

Creates a toolbar with the given title.

createWidgetCommand()

QWidgetAction * KCommandManager::createWidgetCommand	(	int	id,
		QWidget *	defaultWidget,
		QWidget *	context = nullptr )

Create a Widget command object.

This is used to create a command that is represented by a widget.

See also

createCommand

findOrCreateCommand()

QAction * KCommandManager::findOrCreateCommand	(	int	id,
		const QString &	title = QString(),
		QWidget *	context = nullptr )

Find or create a command object.

The command will be created if it doesn't exist, otherwise it will be returned. Note that the title or context is note changed if the command already exists.

See also

createCommand

hasCommand()

bool KCommandManager::hasCommand

(

int

id

)

const

Returns true if a command with the given id exists.

removeCommand()

void KCommandManager::removeCommand

(

int

id

)

Returns the command with the given id.

setCommandChecked()

void KCommandManager::setCommandChecked	(	int	id,
		bool	checked )

Checks or unchecks the command with the given id.

setCommandEnabled()

void KCommandManager::setCommandEnabled	(	int	id,
		bool	enabled )

Enables or disables the command with the given id.

startUpdateTimer()

void KCommandManager::startUpdateTimer

(

)

Starts the update timer.

stopUpdateTimer()

void KCommandManager::stopUpdateTimer

(

)

Stops the update timer.

toolBar()

QToolBar * KCommandManager::toolBar

(

int

id

)

const

Returns the toolbar with the given id.

triggerCommand()

void KCommandManager::triggerCommand

(

int

id

)

const

Triggers the command with the given id.

triggerCommandAsync()

void KCommandManager::triggerCommandAsync

(

int

id

)

const

Triggers the command with the given id asynchronously.

updateAllToolBars()

void KCommandManager::updateAllToolBars

(

)

Updates the state of the commands on all toolbars.

This is called automatically when the update timer times out. You should not need to call this method yourself.

visitCommands()

template<typename Func >

void KCommandManager::visitCommands

(

Func

fn

)

Visits each command in the command manager and applies the given function.

---

The documentation for this class was generated from the following file:

• kdwinutils/widgets/kcommandmanager.h