JUCE  v5.1.1-3-g1a0b28c73
JUCE API
ApplicationCommandTarget Class Referenceabstract

A command target publishes a list of command IDs that it can perform. More...

#include <juce_ApplicationCommandTarget.h>

Inheritance diagram for ApplicationCommandTarget:
Collaboration diagram for ApplicationCommandTarget:

Classes

struct  InvocationInfo
 Contains contextual details about the invocation of a command. More...
 

Public Member Functions

 ApplicationCommandTarget ()
 Creates a command target. More...
 
virtual ~ApplicationCommandTarget ()
 Destructor. More...
 
ApplicationCommandTargetfindFirstTargetParentComponent ()
 If this object is a Component, this method will search upwards in its current UI hierarchy for the next parent component that implements the ApplicationCommandTarget class. More...
 
virtual void getAllCommands (Array< CommandID > &commands)=0
 This must return a complete list of commands that this target can handle. More...
 
virtual void getCommandInfo (CommandID commandID, ApplicationCommandInfo &result)=0
 This must provide details about one of the commands that this target can perform. More...
 
virtual ApplicationCommandTargetgetNextCommandTarget ()=0
 This must return the next target to try after this one. More...
 
ApplicationCommandTargetgetTargetForCommand (const CommandID commandID)
 Searches this target and all subsequent ones for the first one that can handle the specified command. More...
 
bool invoke (const InvocationInfo &invocationInfo, const bool asynchronously)
 Makes this target invoke a command. More...
 
bool invokeDirectly (const CommandID commandID, const bool asynchronously)
 Invokes a given command directly on this target. More...
 
bool isCommandActive (const CommandID commandID)
 Checks whether this command can currently be performed by this target. More...
 
virtual bool perform (const InvocationInfo &info)=0
 This must actually perform the specified command. More...
 

Private Member Functions

bool tryToInvoke (const InvocationInfo &, bool async)
 

Private Attributes

WeakReference< ApplicationCommandTarget >::Master masterReference
 

Friends

class CommandMessage
 
class WeakReference< ApplicationCommandTarget >
 

Detailed Description

A command target publishes a list of command IDs that it can perform.

An ApplicationCommandManager despatches commands to targets, which must be able to provide information about what commands they can handle.

To create a target, you'll need to inherit from this class, implementing all of its pure virtual methods.

For info about how a target is chosen to receive a command, see ApplicationCommandManager::getFirstCommandTarget().

See also
ApplicationCommandManager, ApplicationCommandInfo

Constructor & Destructor Documentation

◆ ApplicationCommandTarget()

ApplicationCommandTarget::ApplicationCommandTarget ( )

Creates a command target.

◆ ~ApplicationCommandTarget()

virtual ApplicationCommandTarget::~ApplicationCommandTarget ( )
virtual

Destructor.

Member Function Documentation

◆ findFirstTargetParentComponent()

ApplicationCommandTarget* ApplicationCommandTarget::findFirstTargetParentComponent ( )

If this object is a Component, this method will search upwards in its current UI hierarchy for the next parent component that implements the ApplicationCommandTarget class.

If your target is a Component, this is a very handy method to use in your getNextCommandTarget() implementation.

◆ getAllCommands()

virtual void ApplicationCommandTarget::getAllCommands ( Array< CommandID > &  commands)
pure virtual

This must return a complete list of commands that this target can handle.

Your target should add all the command IDs that it handles to the array that is passed-in.

Implemented in CodeEditorComponent, and JUCEApplication.

◆ getCommandInfo()

virtual void ApplicationCommandTarget::getCommandInfo ( CommandID  commandID,
ApplicationCommandInfo result 
)
pure virtual

This must provide details about one of the commands that this target can perform.

This will be called with one of the command IDs that the target provided in its getAllCommands() methods.

It should fill-in all appropriate fields of the ApplicationCommandInfo structure with suitable information about the command. (The commandID field will already have been filled-in by the caller).

The easiest way to set the info is using the ApplicationCommandInfo::setInfo() method to set all the fields at once.

If the command is currently inactive for some reason, this method must use ApplicationCommandInfo::setActive() to make that clear, (or it should set the isDisabled bit of the ApplicationCommandInfo::flags field).

Any default key-presses for the command should be appended to the ApplicationCommandInfo::defaultKeypresses field.

Note that if you change something that affects the status of the commands that would be returned by this method (e.g. something that makes some commands active or inactive), you should call ApplicationCommandManager::commandStatusChanged() to cause the manager to refresh its status.

Implemented in CodeEditorComponent, and JUCEApplication.

◆ getNextCommandTarget()

virtual ApplicationCommandTarget* ApplicationCommandTarget::getNextCommandTarget ( )
pure virtual

This must return the next target to try after this one.

When a command is being sent, and the first target can't handle that command, this method is used to determine the next target that should be tried.

It may return nullptr if it doesn't know of another target.

If your target is a Component, you would usually use the findFirstTargetParentComponent() method to return a parent component that might want to handle it.

See also
invoke

Implemented in CodeEditorComponent, and JUCEApplication.

◆ getTargetForCommand()

ApplicationCommandTarget* ApplicationCommandTarget::getTargetForCommand ( const CommandID  commandID)

Searches this target and all subsequent ones for the first one that can handle the specified command.

This will use getNextCommandTarget() to determine the chain of targets to try after this one.

◆ invoke()

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

Makes this target invoke a command.

Your code can call this method to invoke a command on this target, but normally you'd call it indirectly via ApplicationCommandManager::invoke() or ApplicationCommandManager::invokeDirectly().

If this target can perform the given command, it will call its perform() method to do so. If not, then getNextCommandTarget() will be used to determine the next target to try, and the command will be passed along to it.

Parameters
invocationInfothis must be correctly filled-in, describing the context for the invocation.
asynchronouslyif 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
perform, ApplicationCommandManager::invoke

◆ invokeDirectly()

bool ApplicationCommandTarget::invokeDirectly ( const CommandID  commandID,
const bool  asynchronously 
)

Invokes a given command directly on this target.

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

◆ isCommandActive()

bool ApplicationCommandTarget::isCommandActive ( const CommandID  commandID)

Checks whether this command can currently be performed by this target.

This will return true only if a call to getCommandInfo() doesn't set the isDisabled flag to indicate that the command is inactive.

◆ perform()

virtual bool ApplicationCommandTarget::perform ( const InvocationInfo info)
pure virtual

This must actually perform the specified command.

If this target is able to perform the command specified by the commandID field of the InvocationInfo structure, then it should do so, and must return true.

If it can't handle this command, it should return false, which tells the caller to pass the command on to the next target in line.

See also
invoke, ApplicationCommandManager::invoke

Implemented in CodeEditorComponent, and JUCEApplication.

◆ tryToInvoke()

bool ApplicationCommandTarget::tryToInvoke ( const InvocationInfo ,
bool  async 
)
private

Friends And Related Function Documentation

◆ CommandMessage

friend class CommandMessage
friend

◆ WeakReference< ApplicationCommandTarget >

friend class WeakReference< ApplicationCommandTarget >
friend

Member Data Documentation

◆ masterReference

WeakReference<ApplicationCommandTarget>::Master ApplicationCommandTarget::masterReference
private

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