Class through which all messages ultimately pass; holds registered callbacks for messages, notifiers, timers, etc. and calls them at the proper time. More...

#include <hdicoreDispatcher.h>

Public Types
enum	Error { NoDispatchError = 0 , UnhandledMessageError = 10 , UnknownMessageTypeError = 20 , RedundantMessageReceivedError = 30 }
	Describes a variety of dispatch-related errors.

enum	VirtualKey { CommandKey = 10 , OptionKey = 20 , AltKey = OptionKey , ControlKey = 30 , ShiftKey = 40 , CapsLockKey = 50 , SpaceKey = 110 , TabKey = 100 , ReturnKey = 120 , EscapeKey = 200 , ClearKey = 210 , DeleteKey = 220 , ForwardDeleteKey = 230 , UpArrowKey = 300 , DownArrowKey = 310 , LeftArrowKey = 320 , RightArrowKey = 330 , HomeKey = 400 , EndKey = 410 , PageUpKey = 420 , PageDownKey = 430 , HelpKey = 440 , F1Key = 500 , F2Key = 510 , F3Key = 520 , F4Key = 530 , F5Key = 540 , F6Key = 550 , F7Key = 560 , F8Key = 570 , F9Key = 580 , F10Key = 590 , F11Key = 600 , F12Key = 610 , F13Key = 620 , F14Key = 630 , F15Key = 640 , F16Key = 650 , F17Key = 660 , F18Key = 670 , F19Key = 680 , F20Key = 690 , NumPad0Key = 800 , NumPad1Key = 810 , NumPad2Key = 820 , NumPad3Key = 830 , NumPad4Key = 840 , NumPad5Key = 850 , NumPad6Key = 860 , NumPad7Key = 870 , NumPad8Key = 880 , NumPad9Key = 890 , NumPadDecimalKey = 1000 , NumPadPlusKey = 1010 , NumPadMinusKey = 1020 , NumPadMultiplyKey = 1030 , NumPadDivideKey = 1040 , LD_0Key = 2010 , LD_1Key = 2020 , LD_2Key = 2030 , LD_3Key = 2040 , LD_4Key = 2050 , LD_5Key = 2060 , LD_6Key = 2070 , LD_7Key = 2080 , LD_8Key = 2090 , LD_9Key = 2100 , LD_AKey = 2110 , LD_BKey = 2120 , LD_CKey = 2130 , LD_DKey = 2140 , LD_EKey = 2150 , LD_FKey = 2160 , LD_GKey = 2170 , LD_HKey = 2180 , LD_IKey = 2190 , LD_JKey = 2200 , LD_KKey = 2210 , LD_LKey = 2220 , LD_MKey = 2230 , LD_NKey = 2240 , LD_OKey = 2250 , LD_PKey = 2260 , LD_QKey = 2270 , LD_RKey = 2280 , LD_SKey = 2290 , LD_TKey = 2300 , LD_UKey = 2310 , LD_VKey = 2320 , LD_WKey = 2330 , LD_XKey = 2340 , LD_YKey = 2350 , LD_ZKey = 2360 , LD_SlashKey = 2370 , LD_BackslashKey = 2380 , LD_CommaKey = 2390 , LD_PeriodKey = 2400 , LD_SemicolonKey = 2410 , LD_MinusKey = 2420 , LD_EqualKey = 2430 , LD_LeftBracketKey = 2440 , LD_RightBracketKey = 2450 , LD_GraveKey = 2460 , LD_QuoteKey = 2470 }
	Describes which keys can be monitored for presses at anytime.

typedef std::vector< std::shared_ptr< Notifier > >	NotifierVector

Public Member Functions
bool	registerMessageCallback (const MessageType type_, const Callback &callback_)
	Registers a new callback for a given message type.

void	unregisterMessageCallback (const MessageType type_)
	Unregisters a callback for a given message type.

bool	registerMessageCallback (const std::string &caller_, const std::string &selector_, const Callback &callback_)
	Registers a new callback for a given caller/selector pair.

void	unregisterMessageCallback (const std::string &caller_, const std::string &selector_)
	Unregisters a callback for a given caller/selector pair.

Error	message (const MessageType type_, void *const msg_)
	Notifies the dispatcher of an incoming message, causing it to call the appropriate callback or return UnhandledMessageError in the case no callback is registered.

Error	message (const std::string &caller_, const std::string &selector_, void *const msg_)
	Notifies the dispatcher of an incoming (custom) message, causing it to call the appropriate callback or return UnhandledMessageError in the case no callback is registered.

Message *const	lastMessage ()
	Gets a Message object that wraps around the last message data received.

void	scheduleCallback (const Callback &callback_, const double delay_=0.0)
	Executes a given callback after a delay.

void	registerTimer (const Timer &timer_)
	Registers a Timer object.

bool	unregisterTimer (const Timer &timer_)
	Unregisters a given timer.

ToolMessage *const	lastToolMessage ()
	Gets the last tool message received, regardless of whether subsequent non-tool messages have been received.

void	registerNotifier (const Notifier &notifier_)
	Registers a Notifier object for a given Illustrator notifier subscription.

NotifierVector	registeredNotifiersOfType (const NotifierType type_)
	Gets registered notifiers by their type.

bool	unregisterNotifier (const Notifier &notifier_)
	Unregisters a given notifier.

void	registerAnnotator (const Annotator &annotator_)
	Registers an Annotator object.

bool	unregisterAnnotator (const Annotator &annotator_)
	Unregisters a given annotator.

uint32_t	addKeyDownMonitor (const VirtualKey key_, const Callback &cb_)
	Creates an app-wide key-down monitor that executes a callback when a specific key has been pressed.

uint32_t	addKeyUpMonitor (const VirtualKey key_, const Callback &cb_)
	Creates an app-wide key-up monitor that executes a callback when a specific key has been released.

bool	getKeyDownMonitor (const VirtualKey key_, uint32_t &id__, std::unique_ptr< Callback > &cb__) const
	Gets an existing key-down monitor, if any.

bool	getKeyUpMonitor (const VirtualKey key_, uint32_t &id__, std::unique_ptr< Callback > &cb__) const
	Gets an existing key-up monitor, if any.

void	removeKeyDownMonitor (const uint32_t id_)
	Removes a key-down monitor previously created with addKeyDownMonitor()

void	removeKeyUpMonitor (const uint32_t id_)
	Removes a key-up monitor previously created with addKeyUpMonitor()

bool	isKeyDown (const VirtualKey key_, bool &down__)
	Gets whether the given key is down.

Friends
class	Plugin

Detailed Description

Class through which all messages ultimately pass; holds registered callbacks for messages, notifiers, timers, etc. and calls them at the proper time.

Member Function Documentation

◆ addKeyDownMonitor()

uint32_t hdi::core::Dispatcher::addKeyDownMonitor	(	const VirtualKey	key_,
		const Callback &	cb_
	)

Creates an app-wide key-down monitor that executes a callback when a specific key has been pressed.

Author: GW

Date: 03/2014

Parameters

key_	Key that should be monitored for pressing
cb_	Callback to execute when key_ has been pressed (may be called repeatedly if the user holds down the key)

Returns: A unique ID for the monitor that was created, or 0 for error

Note: This method is not required to check for modifier keys during tool use. See the hdi::core::Tool::shiftKeyDown(), controlKeyDown(), optionKeyDown(), and commandKeyDown() methods for more information.; Response time from the key being pressed and the callback being executed varies between each platform and version of the app. This is handled by the OS itself, so there's not much to be done if you find the response time to be too slow :(

◆ addKeyUpMonitor()

uint32_t hdi::core::Dispatcher::addKeyUpMonitor	(	const VirtualKey	key_,
		const Callback &	cb_
	)

Creates an app-wide key-up monitor that executes a callback when a specific key has been released.

Author: GW

Date: 10/2022

Parameters

key_	Key that should be monitored for release
cb_	Callback to execute when key_ has been release

Returns: A unique ID for the monitor that was created, or 0 for error

Note: Response time from the key being released and the callback being executed varies between each platform and version of the app. This is handled by the OS itself, so there's not much to be done if you find the response time to be too slow :(

◆ getKeyDownMonitor()

bool hdi::core::Dispatcher::getKeyDownMonitor	(	const VirtualKey	key_,
		uint32_t &	id__,
		std::unique_ptr< Callback > &	cb__
	)		const

Gets an existing key-down monitor, if any.

Author: GW

Date: 03/2014

Parameters

key_	Virtual key in question
id__	Return-by-reference for the monitor's ID number
cb__	Return-by-reference for the monitor's callback

Returns: true if the monitor exists, false otherwise

◆ getKeyUpMonitor()

bool hdi::core::Dispatcher::getKeyUpMonitor	(	const VirtualKey	key_,
		uint32_t &	id__,
		std::unique_ptr< Callback > &	cb__
	)		const

Gets an existing key-up monitor, if any.

Author: GW

Date: 10/2022

Parameters

key_	Virtual key in question
id__	Return-by-reference for the monitor's ID number
cb__	Return-by-reference for the monitor's callback

Returns: true if the monitor exists, false otherwise

◆ isKeyDown()

bool hdi::core::Dispatcher::isKeyDown	(	const VirtualKey	key_,
		bool &	down__
	)

Gets whether the given key is down.

Author: GW

Date: 10/2022

Parameters

key_	The key in question
down__	Return-by-reference for whether the key is down; true means down, false means up

Returns: true if the key down state could be acquired, false otherwise

Note: This method is not suitable to check for modifier keys during tool use. See the hdi::core::Tool::shiftKeyDown(), controlKeyDown(), optionKeyDown(), and commandKeyDown() methods for more information.; This method can only perform its job if a key monitor has been registered (either up or down) for the given key, and if the user has actually pressed the key since such time. If not, then it will return false.

◆ lastMessage()

Message *const hdi::core::Dispatcher::lastMessage ( )

Gets a Message object that wraps around the last message data received.

Author: GW

Date: 09/2013

Returns: A Message object describing the last message sent by the app (or the current message if you are calling this from inside a callback that was executed by the dispatcher itself)

Note: If you are calling this from inside a message callback, then it will be the current message relating to the aforementioned callback (e.g. the returned Message object can be safely modified in the case of app messages that have data output fields). Once your message callback has finished, however, not all data in a Message subclass will be available (which subclasses and which data varies greatly between each message type, so do as much processing as possible inside your message callback)!; The return value is a pointer to the internal Message object; it will be modified if you assign anything in it, which may affect subsequent messages. Be careful!

◆ lastToolMessage()

ToolMessage *const hdi::core::Dispatcher::lastToolMessage ( )

Gets the last tool message received, regardless of whether subsequent non-tool messages have been received.

Author: GW

Date: 09/2013

Returns: The last tool-related message received by the dispatcher

Note: The return value is a pointer to the internal ToolMessage object; it will be modified if you assign anything in it, which may affect subsequent tools/panels/etc. Be careful!; Generally, you shouldn't need to call this method. Only use it if you know what you're doing. If a specific piece of functionality provided by the app is not handled by this class (or related classes), then it should probably be added to the library.

◆ message() [1/2]

Error hdi::core::Dispatcher::message	(	const MessageType	type_,
		void *const	msg_
	)

Notifies the dispatcher of an incoming message, causing it to call the appropriate callback or return UnhandledMessageError in the case no callback is registered.

Author: GW

Date: 09/2013

Parameters

type_	Type of message that is being received
msg_	Message data sent along with the message; this will automatically be processed by the dispatcher and made available by the lastMessage() method

Returns: Error that occurred during event dispatching (essentially unused at this point)

Note: You can acquire the most recent message by calling lastMessage(); It would be an extreme rarity for this method to be called directly.; For Photoshop this also handles known action plugin messages.

◆ message() [2/2]

Error hdi::core::Dispatcher::message	(	const std::string &	caller_,
		const std::string &	selector_,
		void *const	msg_
	)

Notifies the dispatcher of an incoming (custom) message, causing it to call the appropriate callback or return UnhandledMessageError in the case no callback is registered.

Author: GW

Date: 04/2014

Parameters

caller_	Caller ID string
selector_	Selector ID string for caller_
msg_	Message data sent along with the message; this will automatically be processed by the dispatcher and made available by the lastMessage() method

Returns: Error that occurred during event dispatching (essentially unused at this point)

Note: You can acquire the most recent message by calling lastMessage(); It would be an extreme rarity for this method to be called directly.; Essentially any caller/selector pair that is not known to the internal PluginMain() function is forwarded to this method (i.e. any caller/selector pair that is not built into the app), such that a developer can receive custom messages.; For Photoshop this also handles custom action plugin messages.

◆ registerAnnotator()

void hdi::core::Dispatcher::registerAnnotator ( const Annotator & annotator_ )

Registers an Annotator object.

Author: GW

Date: 09/2013

Parameters

annotator_ New annotator, whose callback will be called when the proper notification is received by the dispatcher

◆ registeredNotifiersOfType()

NotifierVector hdi::core::Dispatcher::registeredNotifiersOfType ( const NotifierType type_ )

Gets registered notifiers by their type.

Author: GW

Date: 09/2013

Parameters

type_ Type of the notifiers to find

Returns: notifier__ All notifiers whose type matches the type_ argument

◆ registerMessageCallback() [1/2]

bool hdi::core::Dispatcher::registerMessageCallback	(	const MessageType	type_,
		const Callback &	callback_
	)

Registers a new callback for a given message type.

Author: GW

Date: 09/2013

Parameters

type_	Type of message to which callback_ will be associated (only one callback per message is allowed)
callback_	Callback to perform when the caller/selector pair associated with type_ is received in a message

Returns: true if the callback was registered successfully

Note: Many of the available message types are already automatically handled by the hdi::core lib. See the MessageType enum docs for more information.

◆ registerMessageCallback() [2/2]

bool hdi::core::Dispatcher::registerMessageCallback	(	const std::string &	caller_,
		const std::string &	selector_,
		const Callback &	callback_
	)

Registers a new callback for a given caller/selector pair.

Author: GW

Date: 04/2014

Parameters

caller_	Caller ID string
selector_	Selector ID string for caller_
callback_	Callback to perform when the caller/selector pair is received in a message

Returns: true if the caller was registered successfully

Note: Only one callback per caller/selector pair is allowed.; If the caller/selector pair is already known by the hdi::core lib, then this function will bail. Always try to use the version of this method that takes a MessageType argument instead; if the message you're interested in is not built into the app (or you know a special third-party plugin will send the message to you) then utilize this method.; Any message associated with the caller/selector pair will always be processed as a CustomMessage object, so be aware when calling the lastMessage() method from within your callback.

◆ registerNotifier()

void hdi::core::Dispatcher::registerNotifier ( const Notifier & notifier_ )

Registers a Notifier object for a given Illustrator notifier subscription.

Author: GW

Date: 09/2013

Parameters

notifier_ New notifier, whose callback will be called when the proper notification is received by the dispatcher

Note: If multiple notifiers are registered for the same type of notification, their callbacks will be executed in the order of registration.

◆ registerTimer()

void hdi::core::Dispatcher::registerTimer ( const Timer & timer_ )

Registers a Timer object.

Author: GW

Date: 09/2013

Parameters

timer_ New timer, whose callback will be called when the proper notification is received by the dispatcher

◆ removeKeyDownMonitor()

void hdi::core::Dispatcher::removeKeyDownMonitor ( const uint32_t id_ )

Removes a key-down monitor previously created with addKeyDownMonitor()

Author: GW

Date: 03/2014

Parameters

id_	ID for the keypress monitor (returned by earlier call to addKeyDownMonitor() method)

◆ removeKeyUpMonitor()

void hdi::core::Dispatcher::removeKeyUpMonitor ( const uint32_t id_ )

Removes a key-up monitor previously created with addKeyUpMonitor()

Author: GW

Date: 10/2022

Parameters

id_	ID for the keypress monitor (returned by earlier call to addKeyUpMonitor() method)

◆ scheduleCallback()

void hdi::core::Dispatcher::scheduleCallback	(	const Callback &	callback_,
		const double	delay_ = `0.0`
	)

Executes a given callback after a delay.

Author: GW

Date: 08/2013

Parameters

callback_	Callback object to execute on delay
delay_	Number of seconds to wait before executing (approximately - the OS may wait longer)

◆ unregisterAnnotator()

bool hdi::core::Dispatcher::unregisterAnnotator ( const Annotator & annotator_ )

Unregisters a given annotator.

Author: GW

Date: 09/2013

Parameters

annotator_ Annotator to be unregistered

Returns: true if the annotator was removed, false otherwise

◆ unregisterMessageCallback() [1/2]

void hdi::core::Dispatcher::unregisterMessageCallback ( const MessageType type_ )

Unregisters a callback for a given message type.

Author: GW

Date: 09/2013

Parameters

type_ Type of message from which the caller is unsubscribing

◆ unregisterMessageCallback() [2/2]

void hdi::core::Dispatcher::unregisterMessageCallback	(	const std::string &	caller_,
		const std::string &	selector_
	)

Unregisters a callback for a given caller/selector pair.

Author: GW

Date: 04/2014

Parameters

caller_	Caller ID string from which the caller is unsubscribing
selector_	Selector ID string for caller_

Note: Only use this method if you originally registered the message callback with the registerMessageCallback() method variant that takes a caller/selector pair.

◆ unregisterNotifier()

bool hdi::core::Dispatcher::unregisterNotifier ( const Notifier & notifier_ )

Unregisters a given notifier.

Author: GW

Date: 09/2013

Parameters

notifier_ Notifier to be unregistered

Returns: true if the notifier was removed, false otherwise

◆ unregisterTimer()

bool hdi::core::Dispatcher::unregisterTimer ( const Timer & timer_ )

Unregisters a given timer.

Author: GW

Date: 09/2013

Parameters

timer_ Timer to be unregistered

Returns: true if the timer was removed, false otherwise

Public Types

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ addKeyDownMonitor()

◆ addKeyUpMonitor()

◆ getKeyDownMonitor()

◆ getKeyUpMonitor()

◆ isKeyDown()

◆ lastMessage()

◆ lastToolMessage()

◆ message() [1/2]

◆ message() [2/2]

◆ registerAnnotator()

◆ registeredNotifiersOfType()

◆ registerMessageCallback() [1/2]

◆ registerMessageCallback() [2/2]

◆ registerNotifier()

◆ registerTimer()

◆ removeKeyDownMonitor()

◆ removeKeyUpMonitor()

◆ scheduleCallback()

◆ unregisterAnnotator()

◆ unregisterMessageCallback() [1/2]

◆ unregisterMessageCallback() [2/2]

◆ unregisterNotifier()

◆ unregisterTimer()