One of these objects holds a list of all the commands your app can perform, and despatches these commands when needed. More...

#include <juce_ApplicationCommandManager.h>

Inheritance diagram for ApplicationCommandManager:

[legend]

Collaboration diagram for ApplicationCommandManager:

[legend]

Public Member Functions
	ApplicationCommandManager ()
	Creates an ApplicationCommandManager. More...

virtual	~ApplicationCommandManager ()
	Destructor. More...

void	addListener (ApplicationCommandManagerListener *listener)
	Registers a listener that will be called when various events occur. More...

void	clearCommands ()
	Clears the current list of all commands. More...

void	commandStatusChanged ()
	This should be called to tell the manager that one of its registered commands may have changed its active status. More...

StringArray	getCommandCategories () const
	Returns the list of categories. More...

const ApplicationCommandInfo *	getCommandForID (CommandID commandID) const noexcept
	Returns the details about a given command ID. More...

const ApplicationCommandInfo *	getCommandForIndex (int index) const noexcept
	Returns the details about one of the registered commands. More...

Array< CommandID >	getCommandsInCategory (const String &categoryName) const
	Returns a list of all the command UIDs in a particular category. More...

String	getDescriptionOfCommand (CommandID commandID) const noexcept
	Returns the description field for a command. More...

virtual ApplicationCommandTarget *	getFirstCommandTarget (CommandID commandID)
	Chooses the ApplicationCommandTarget to which a command should be sent. More...

KeyPressMappingSet *	getKeyMappings () const noexcept
	Returns the manager's internal set of key mappings. More...

String	getNameOfCommand (CommandID commandID) const noexcept
	Returns the name field for a command. More...

int	getNumCommands () const noexcept
	Returns the number of commands that have been registered. More...

ApplicationCommandTarget *	getTargetForCommand (CommandID commandID, ApplicationCommandInfo &upToDateInfo)
	Tries to find the best target to use to perform a given command. More...

bool	invoke (const ApplicationCommandTarget::InvocationInfo &invocationInfo, bool asynchronously)
	Sends a command to the default target. More...

bool	invokeDirectly (CommandID commandID, bool asynchronously)
	Invokes the given command directly, sending it to the default target. More...

void	registerAllCommandsForTarget (ApplicationCommandTarget *target)
	Adds all the commands that this target publishes to the manager's list. More...

void	registerCommand (const ApplicationCommandInfo &newCommand)
	Adds a command to the list of registered commands. More...

void	removeCommand (CommandID commandID)
	Removes the command with a specified ID. More...

void	removeListener (ApplicationCommandManagerListener *listener)
	Deregisters a previously-added listener. More...

void	setFirstCommandTarget (ApplicationCommandTarget *newTarget) noexcept
	Sets a target to be returned by getFirstCommandTarget(). More...

Static Public Member Functions
static ApplicationCommandTarget *	findDefaultComponentTarget ()
	Looks for a suitable command target based on which Components have the keyboard focus. More...

static ApplicationCommandTarget *	findTargetForComponent (Component *)
	Examines this component and all its parents in turn, looking for the first one which is an ApplicationCommandTarget. More...

Private Member Functions
void	cancelPendingUpdate () noexcept
	This will stop any pending updates from happening. More...

ApplicationCommandInfo *	getMutableCommandForID (CommandID) const noexcept

void	globalFocusChanged (Component *) override
	Callback to indicate that the currently focused component has changed. More...

void	handleAsyncUpdate () override
	Called back to do whatever your class needs to do. More...

void	handleUpdateNowIfNeeded ()
	If an update has been triggered and is pending, this will invoke it synchronously. More...

bool	isUpdatePending () const noexcept
	Returns true if there's an update callback in the pipeline. More...

void	sendListenerInvokeCallback (const ApplicationCommandTarget::InvocationInfo &)

void	triggerAsyncUpdate ()
	Causes the callback to be triggered at a later time. More...

Private Attributes
OwnedArray< ApplicationCommandInfo >	commands

ApplicationCommandTarget *	firstTarget

ScopedPointer< KeyPressMappingSet >	keyMappings

ListenerList< ApplicationCommandManagerListener >	listeners

Detailed Description

One of these objects holds a list of all the commands your app can perform, and despatches these commands when needed.

Application commands are a good way to trigger actions in your app, e.g. "Quit", "Copy", "Paste", etc. Menus, buttons and keypresses can all be given commands to invoke automatically, which means you don't have to handle the result of a menu or button click manually. Commands are despatched to ApplicationCommandTarget objects which can choose which events they want to handle.

This architecture also allows for nested ApplicationCommandTargets, so that for example you could have two different objects, one inside the other, both of which can respond to a "delete" command. Depending on which one has focus, the command will be sent to the appropriate place, regardless of whether it was triggered by a menu, keypress or some other method.

To set up your app to use commands, you'll need to do the following:

Create a global ApplicationCommandManager to hold the list of all possible commands. (This will also manage a set of key-mappings for them).
Make some of your UI components (or other objects) inherit from ApplicationCommandTarget. This allows the object to provide a list of commands that it can perform, and to handle them.
Register each type of command using ApplicationCommandManager::registerAllCommandsForTarget(), or ApplicationCommandManager::registerCommand().
If you want key-presses to trigger your commands, use the ApplicationCommandManager::getKeyMappings() method to access the key-mapper object, which you will need to register as a key-listener in whatever top-level component you're using. See the KeyPressMappingSet class for more help about setting this up.
Use methods such as PopupMenu::addCommandItem() or Button::setCommandToTrigger() to cause these commands to be invoked automatically.
Commands can be invoked directly by your code using ApplicationCommandManager::invokeDirectly().

When a command is invoked, the ApplicationCommandManager will try to choose the best ApplicationCommandTarget to receive the specified command. To do this it will use the current keyboard focus to see which component might be interested, and will search the component hierarchy for those that also implement the ApplicationCommandTarget interface. If an ApplicationCommandTarget isn't interested in the command that is being invoked, then the next one in line will be tried (see the ApplicationCommandTarget::getNextCommandTarget() method), and so on until ApplicationCommandTarget::getNextCommandTarget() returns nullptr. At this point if the command still hasn't been performed, it will be passed to the current JUCEApplication object (which is itself an ApplicationCommandTarget).

To exert some custom control over which ApplicationCommandTarget is chosen to invoke a command, you can override the ApplicationCommandManager::getFirstCommandTarget() method and choose the object yourself.

See also: ApplicationCommandTarget, ApplicationCommandInfo

Constructor & Destructor Documentation

◆ ApplicationCommandManager()

ApplicationCommandManager::ApplicationCommandManager ( )

Creates an ApplicationCommandManager.

Once created, you'll need to register all your app's commands with it, using ApplicationCommandManager::registerAllCommandsForTarget() or ApplicationCommandManager::registerCommand().

◆ ~ApplicationCommandManager()

virtual ApplicationCommandManager::~ApplicationCommandManager ( )

virtual

Destructor.

Make sure that you don't delete this if pointers to it are still being used by objects such as PopupMenus or Buttons.

Member Function Documentation

◆ addListener()

void ApplicationCommandManager::addListener ( ApplicationCommandManagerListener * listener )

Registers a listener that will be called when various events occur.

◆ cancelPendingUpdate()

void AsyncUpdater::cancelPendingUpdate ( )

noexceptinherited

This will stop any pending updates from happening.

If called after triggerAsyncUpdate() and before the handleAsyncUpdate() callback happens, this will cancel the handleAsyncUpdate() callback.

Note that this method simply cancels the next callback - if a callback is already in progress on a different thread, this won't block until the callback finishes, so there's no guarantee that the callback isn't still running when the method returns.

◆ clearCommands()

void ApplicationCommandManager::clearCommands ( )

Clears the current list of all commands.

Note that this will also clear the contents of the KeyPressMappingSet.

◆ commandStatusChanged()

void ApplicationCommandManager::commandStatusChanged ( )

This should be called to tell the manager that one of its registered commands may have changed its active status.

Because the command manager only finds out whether a command is active or inactive by querying the current ApplicationCommandTarget, this is used to tell it that things may have changed. It allows things like buttons to update their enablement, etc.

This method will cause an asynchronous call to ApplicationCommandManagerListener::applicationCommandListChanged() for any registered listeners.

◆ findDefaultComponentTarget()

static ApplicationCommandTarget* ApplicationCommandManager::findDefaultComponentTarget ( )

static

Looks for a suitable command target based on which Components have the keyboard focus.

This is used by the default implementation of ApplicationCommandTarget::getFirstCommandTarget(), but is exposed here in case it's useful.

It tries to pick the best ApplicationCommandTarget by looking at focused components, top level windows, etc., and using the findTargetForComponent() method.

◆ findTargetForComponent()

static ApplicationCommandTarget* ApplicationCommandManager::findTargetForComponent ( Component * )

static

Examines this component and all its parents in turn, looking for the first one which is an ApplicationCommandTarget.

Returns the first ApplicationCommandTarget that it finds, or nullptr if none of them implement that class.

◆ getCommandCategories()

StringArray ApplicationCommandManager::getCommandCategories ( ) const

Returns the list of categories.

This will go through all registered commands, and return a list of all the distinct categoryName values from their ApplicationCommandInfo structure.

See also: getCommandsInCategory()

◆ getCommandForID()

const ApplicationCommandInfo* ApplicationCommandManager::getCommandForID ( CommandID commandID ) const

noexcept

Returns the details about a given command ID.

This will search the list of registered commands for one with the given command ID number, and return its associated info. If no matching command is found, this will return nullptr.

◆ getCommandForIndex()

const ApplicationCommandInfo* ApplicationCommandManager::getCommandForIndex ( int index ) const

inlinenoexcept

Returns the details about one of the registered commands.

The index is between 0 and (getNumCommands() - 1).

◆ getCommandsInCategory()

Array<CommandID> ApplicationCommandManager::getCommandsInCategory ( const String & categoryName ) const

Returns a list of all the command UIDs in a particular category.

See also: getCommandCategories()

◆ getDescriptionOfCommand()

String ApplicationCommandManager::getDescriptionOfCommand ( CommandID commandID ) const

noexcept

Returns the description field for a command.

An empty string is returned if no command with this ID has been registered. If the command has no description, this will return its short name field instead.

See also: getNameOfCommand

◆ getFirstCommandTarget()

virtual ApplicationCommandTarget* ApplicationCommandManager::getFirstCommandTarget ( CommandID commandID )

virtual

Chooses the ApplicationCommandTarget to which a command should be sent.

Whenever the manager needs to know which target a command should be sent to, it calls this method to determine the first one to try.

By default, this method will return the target that was set by calling setFirstCommandTarget(). If no target is set, it will return the result of findDefaultComponentTarget().

If you need to make sure all commands go via your own custom target, then you can either use setFirstCommandTarget() to specify a single target, or override this method if you need more complex logic to choose one.

It may return nullptr if no targets are available.

See also: getTargetForCommand, invoke, invokeDirectly

◆ getKeyMappings()

KeyPressMappingSet* ApplicationCommandManager::getKeyMappings ( ) const

inlinenoexcept

Returns the manager's internal set of key mappings.

This object can be used to edit the keypresses. To actually link this object up to invoke commands when a key is pressed, see the comments for the KeyPressMappingSet class.

See also: KeyPressMappingSet

◆ getMutableCommandForID()

ApplicationCommandInfo* ApplicationCommandManager::getMutableCommandForID ( CommandID ) const

privatenoexcept

◆ getNameOfCommand()

String ApplicationCommandManager::getNameOfCommand ( CommandID commandID ) const

noexcept

Returns the name field for a command.

An empty string is returned if no command with this ID has been registered.

See also: getDescriptionOfCommand

◆ getNumCommands()

int ApplicationCommandManager::getNumCommands ( ) const

inlinenoexcept

Returns the number of commands that have been registered.

See also: registerCommand

◆ getTargetForCommand()

ApplicationCommandTarget* ApplicationCommandManager::getTargetForCommand	(	CommandID	commandID,
		ApplicationCommandInfo &	upToDateInfo
	)

Tries to find the best target to use to perform a given command.

This will call getFirstCommandTarget() to find the preferred target, and will check whether that target can handle the given command. If it can't, then it'll use ApplicationCommandTarget::getNextCommandTarget() to find the next one to try, and so on until no more are available.

If no targets are found that can perform the command, this method will return nullptr.

If a target is found, then it will get the target to fill-in the upToDateInfo structure with the latest info about that command, so that the caller can see whether the command is disabled, ticked, etc.

◆ globalFocusChanged()

void ApplicationCommandManager::globalFocusChanged ( Component * focusedComponent )

overrideprivatevirtual

Callback to indicate that the currently focused component has changed.

Implements FocusChangeListener.

◆ handleAsyncUpdate()

void ApplicationCommandManager::handleAsyncUpdate ( )

overrideprivatevirtual

Called back to do whatever your class needs to do.

This method is called by the message thread at the next convenient time after the triggerAsyncUpdate() method has been called.

Implements AsyncUpdater.

◆ handleUpdateNowIfNeeded()

void AsyncUpdater::handleUpdateNowIfNeeded ( )

inherited

If an update has been triggered and is pending, this will invoke it synchronously.

Use this as a kind of "flush" operation - if an update is pending, the handleAsyncUpdate() method will be called immediately; if no update is pending, then nothing will be done.

Because this may invoke the callback, this method must only be called on the main event thread.

◆ invoke()

bool ApplicationCommandManager::invoke	(	const ApplicationCommandTarget::InvocationInfo &	invocationInfo,
		bool	asynchronously
	)

Sends a command to the default target.

This will choose a target using getFirstCommandTarget(), and send the specified command to it using the ApplicationCommandTarget::invoke() method. This means that if the first target can't handle the command, it will be passed on to targets further down the chain (see ApplicationCommandTarget::invoke() for more info).

Parameters

invocationInfo	this must be correctly filled-in, describing the context for the invocation.
asynchronously	if false, the command will be performed before this method returns. If true, a message will be posted so that the command will be performed later on the message thread, and this method will return immediately.

See also: ApplicationCommandTarget::invoke

◆ invokeDirectly()

bool ApplicationCommandManager::invokeDirectly	(	CommandID	commandID,
		bool	asynchronously
	)

Invokes the given command directly, sending it to the default target.

This is just an easy way to call invoke() without having to fill out the InvocationInfo structure.

◆ isUpdatePending()

bool AsyncUpdater::isUpdatePending ( ) const

noexceptinherited

Returns true if there's an update callback in the pipeline.

◆ registerAllCommandsForTarget()

void ApplicationCommandManager::registerAllCommandsForTarget ( ApplicationCommandTarget * target )

Adds all the commands that this target publishes to the manager's list.

This will use ApplicationCommandTarget::getAllCommands() and ApplicationCommandTarget::getCommandInfo() to get details about all the commands that this target can do, and will call registerCommand() to add each one to the manger's list.

See also: registerCommand

◆ registerCommand()

void ApplicationCommandManager::registerCommand ( const ApplicationCommandInfo & newCommand )

Adds a command to the list of registered commands.

See also: registerAllCommandsForTarget

◆ removeCommand()

void ApplicationCommandManager::removeCommand ( CommandID commandID )

Removes the command with a specified ID.

Note that this will also remove any key mappings that are mapped to the command.

◆ removeListener()

void ApplicationCommandManager::removeListener ( ApplicationCommandManagerListener * listener )

Deregisters a previously-added listener.

◆ sendListenerInvokeCallback()

void ApplicationCommandManager::sendListenerInvokeCallback ( const ApplicationCommandTarget::InvocationInfo & )

private

◆ setFirstCommandTarget()

void ApplicationCommandManager::setFirstCommandTarget ( ApplicationCommandTarget * newTarget )

noexcept

Sets a target to be returned by getFirstCommandTarget().

If this is set to nullptr, then getFirstCommandTarget() will by default return the result of findDefaultComponentTarget().

If you use this to set a target, make sure you call setFirstCommandTarget(nullptr) before deleting the target object.

◆ triggerAsyncUpdate()

void AsyncUpdater::triggerAsyncUpdate ( )

inherited

Causes the callback to be triggered at a later time.

This method returns immediately, having made sure that a callback to the handleAsyncUpdate() method will occur as soon as possible.

If an update callback is already pending but hasn't happened yet, calls to this method will be ignored.

It's thread-safe to call this method from any number of threads without needing to worry about locking.

Member Data Documentation

◆ commands

OwnedArray<ApplicationCommandInfo> ApplicationCommandManager::commands

private

◆ firstTarget

ApplicationCommandTarget* ApplicationCommandManager::firstTarget

private

◆ keyMappings

ScopedPointer<KeyPressMappingSet> ApplicationCommandManager::keyMappings

private

◆ listeners

ListenerList<ApplicationCommandManagerListener> ApplicationCommandManager::listeners

private

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

juce_ApplicationCommandManager.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ApplicationCommandManager()

◆ ~ApplicationCommandManager()

Member Function Documentation

◆ addListener()

◆ cancelPendingUpdate()

◆ clearCommands()

◆ commandStatusChanged()

◆ findDefaultComponentTarget()

◆ findTargetForComponent()

◆ getCommandCategories()

◆ getCommandForID()

◆ getCommandForIndex()

◆ getCommandsInCategory()

◆ getDescriptionOfCommand()

◆ getFirstCommandTarget()

◆ getKeyMappings()

◆ getMutableCommandForID()

◆ getNameOfCommand()

◆ getNumCommands()

◆ getTargetForCommand()

◆ globalFocusChanged()

◆ handleAsyncUpdate()

◆ handleUpdateNowIfNeeded()

◆ invoke()

◆ invokeDirectly()

◆ isUpdatePending()

◆ registerAllCommandsForTarget()

◆ registerCommand()

◆ removeCommand()

◆ removeListener()

◆ sendListenerInvokeCallback()

◆ setFirstCommandTarget()

◆ triggerAsyncUpdate()

Member Data Documentation

◆ commands

◆ firstTarget

◆ keyMappings

◆ listeners