Hot Door CORE  0.7.0
Adobe® Illustrator® Plug-in Library
Public Types | Public Member Functions | Friends | List of all members
hdi::core::Dispatcher Class Reference

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< Notifier * > NotifierVector
 

Public Member Functions

bool registerMessageCallback (const MessageType type_, const Callback &callback_)
 Registers a new callback for a given message type. More...
 
bool registerMessageCallback (const std::string &caller_, const std::string &selector_, const Callback &callback_)
 Registers a new callback for a given caller/selector pair. More...
 
void unregisterMessageCallback (const MessageType type_)
 Unregisters a callback for a given message type. More...
 
void unregisterMessageCallback (const std::string &caller_, const std::string &selector_)
 Unregisters a callback for a given caller/selector pair. More...
 
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. More...
 
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. More...
 
Message *const lastMessage ()
 Gets a Message object that wraps around the last message data received. More...
 
ToolMessage *const lastToolMessage ()
 Gets the last tool message received, regardless of whether subsequent non-tool messages have been received. More...
 
void registerNotifier (const Notifier &notifier_)
 Registers a Notifier object for a given Illustrator notifier subscription. More...
 
NotifierVector registeredNotifiersOfType (const NotifierType type_)
 Gets registered notifiers by their type. More...
 
bool unregisterNotifier (const Notifier &notifier_)
 Unregisters a given notifier. More...
 
void registerTimer (const Timer &timer_)
 Registers a Timer object. More...
 
bool unregisterTimer (const Timer &timer_)
 Unregisters a given timer. More...
 
void scheduleCallback (const Callback &callback_, const double delay_=0.0)
 Executes a given callback after a delay. More...
 
void registerAnnotator (const Annotator &annotator_)
 Registers an Annotator object. More...
 
bool unregisterAnnotator (const Annotator &annotator_)
 Unregisters a given annotator. More...
 
uint32_t addKeypressMonitor (const VirtualKey key_, const Callback &cb_)
 Creates an Illustrator-wide keypress monitor that calls a callback when a specific key down event has been received. More...
 
bool getKeypressMonitor (const VirtualKey key_, uint32_t &id__, std::auto_ptr< Callback > &cb__) const
 Gets an existing keypress monitor, if any. More...
 
void removeKeypressMonitor (const uint32_t id_)
 Removes a keypress monitor previously created with addKeypressMonitor() More...
 

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

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

Creates an Illustrator-wide keypress monitor that calls a callback when a specific key down event has been received.

Author
GW
Date
03/2014
Parameters
key_Key that should be monitored
cb_Callback to execute when key_ has been pressed
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 Illustrator. 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 :(
bool hdi::core::Dispatcher::getKeypressMonitor ( const VirtualKey  key_,
uint32_t &  id__,
std::auto_ptr< Callback > &  cb__ 
) const

Gets an existing keypress 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
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 Illustrator (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 Illustrator 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 tools/panels/etc. Be careful!
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 Illustrator is not handled by this class (or related classes), then it should probably be added to the library.
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.
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 Illustrator), such that a developer can receive custom messages.
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
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
Warning
The caller assumes responsibility for the memory of the contained Notifier objects.
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.
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 Illustrator (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.
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.
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
void hdi::core::Dispatcher::removeKeypressMonitor ( const uint32_t  id_)

Removes a keypress monitor previously created with addKeypressMonitor()

Author
GW
Date
03/2014
Parameters
id_ID for the keypress monitor (returned by earlier call to addKeypressMonitor() method)
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)
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
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
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.
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
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