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

Base class for all tools; stores hit data, cursor loc, dialogs, etc.; receives tool-related messages. More...

#include <hdicoreTool.h>

Public Types

enum  Options {
  NoOptions = 0, TracksCursorOption = 1 << 0, DoesntAutoScrollOption = 1 << 1, BufferedDraggingOption = 1 << 2,
  MaintainsEditContextOption = 1 << 3, WantsToEditTextOption = 1 << 4, WantsToChangeDiameterOption = 1 << 5, WantsAlternateSelectionOption = 1 << 6,
  HiddenOption = 1 << 7, DoesntAllowSoftSelectionOption = 1 << 8, DefaultOptions = (TracksCursorOption | WantsToChangeDiameterOption)
}
 Controls various options for a tool.
 
typedef std::vector< ArtboardPointArtboardPointVector
 

Public Member Functions

 Tool ()
 Constructs an empty Tool object. More...
 
 Tool (const Tool &tool_)
 Constructs a new Tool object from an existing Tool object (copy constructor) More...
 
 Tool (const Tool &sameGroupAs_, const Tool *const sameSetAs_, const std::string &title_, const std::string &tip_, const int16_t lightIconID_, const int16_t darkIconID_, const Options options_=DefaultOptions)
 Constructs a new Tool object, optionally in the same set/group as one of your own tools. More...
 
 Tool (const BuiltinTool &sameGroupAs_, const BuiltinTool *const sameSetAs_, const std::string &title_, const std::string &tip_, const int16_t lightIconID_, const int16_t darkIconID_, const Options options_=DefaultOptions)
 Constructs a new Tool object in the same set/group as a built-in Illustrator tool. More...
 
 Tool (const int16_t sameGroupAs_, const int16_t sameSetAs_, const std::string &title_, const std::string &tip_, const int16_t lightIconID_, const int16_t darkIconID_, const Options options_=DefaultOptions)
 Constructs a new Tool object in the same set/group as some third-party tool (via handles) More...
 
virtual ~Tool ()
 Destructs a Tool object. More...
 
virtual void destroy ()
 Destroys the tool, converting the target object to an empty Tool object (see the default constructor for more info on empty Tool objects) More...
 
virtual Tooloperator= (const Tool &rhs_)
 Assigns one Tool object to another. More...
 
virtual bool operator== (const Tool &rhs_) const
 Tests whether a given Tool object is the same as another. More...
 
virtual bool operator!= (const Tool &rhs_) const
 Tests whether a given Tool object is not the same as another. More...
 
virtual AIToolHandle aiToolHandle () const
 Gets the tool handle around which the target object is wrapped. More...
 
virtual int16_t number () const
 Gets the tool's number. More...
 
virtual bool isEmpty () const
 Gets whether the target Tool object is empty (constructed with the default ctor) More...
 
virtual bool selected () const
 Gets whether the target Tool object is the currently selected tool. More...
 
virtual void setSelected ()
 Sets the target Tool object as the currently selected tool. More...
 
virtual Options options () const
 Gets the options set for the tool. More...
 
virtual void setOptions (const Options options_)
 Sets the options for the tool. More...
 
virtual std::string title () const
 Gets the tool's title. More...
 
virtual void setTitle (const std::string &title_)
 Sets the tool's title. More...
 
virtual std::string tip () const
 Gets the tool's tip string. More...
 
virtual void setTip (const std::string &tip_)
 Sets the tool's tip string. More...
 
virtual int16_t lightIconID () const
 Gets the light UI icon ID as set when the tool was created. More...
 
virtual void setLightIconID (const int16_t imgID_)
 Sets the light UI icon ID. More...
 
virtual int16_t darkIconID () const
 Gets the dark UI icon ID as set when the tool was created. More...
 
virtual void setDarkIconID (const int16_t imgID_)
 Sets the dark UI icon ID. More...
 
virtual ArtboardPoint cursorLoc () const
 Gets the current location of the cursor. More...
 
virtual void setCursorLoc (const ArtboardPoint &loc_)
 Stores the current location of the cursor. More...
 
virtual ArtboardPointVector mouseDownLocs () const
 Gets the mouse down points for the target tool. More...
 
virtual ArtboardPointVector mouseUpLocs () const
 Gets the mouse up points for the target tool. More...
 
virtual std::auto_ptr< HitDatamouseDownHitData (const uint32_t index_, const HitRequest request_, const double tolerance_=2.0) const
 Gets hit data for a given point in the mouse down location vector. More...
 
virtual std::auto_ptr< HitDatamouseUpHitData (const uint32_t index_, const HitRequest request_, const double tolerance_=2.0) const
 Gets hit data for a given point in the mouse up location vector. More...
 
virtual std::auto_ptr< HitDatacursorHitData (const HitRequest request_, const double tolerance_=2.0) const
 Gets hit data for the current cursor location. More...
 
virtual Callback *const selectionCallback () const
 Gets the registered callback for the tool selection event. More...
 
virtual void setSelectionCallback (const Callback &cb_)
 Sets the callback for the tool selection event. More...
 
virtual Callback *const reselectionCallback () const
 Gets the registered callback for the tool reselection event. More...
 
virtual void setReselectionCallback (const Callback &cb_)
 Sets the callback for the tool reselection event. More...
 
virtual Callback *const deselectionCallback () const
 Gets the registered callback for the tool deselection event. More...
 
virtual void setDeselectionCallback (const Callback &cb_)
 Sets the callback for the tool deselection event. More...
 
virtual Callback *const trackCallback () const
 Gets the registered callback for the tool tracking event (mouse move) More...
 
virtual void setTrackCallback (const Callback &cb_)
 Sets the callback for the tool tracking event (mouse move) More...
 
virtual Callback *const mouseDownCallback () const
 Gets the registered callback for the mouse down event. More...
 
virtual void setMouseDownCallback (const Callback &cb_)
 Sets the callback for the mouse down event. More...
 
virtual Callback *const dragCallback () const
 Gets the registered callback for the drag event. More...
 
virtual void setDragCallback (const Callback &cb_)
 Sets the callback for the drag event. More...
 
virtual Callback *const mouseUpCallback () const
 Gets the registered callback for the mouse up event. More...
 
virtual void setMouseUpCallback (const Callback &cb_)
 Sets the callback for the mouse up event. More...
 
virtual Callback *const decreaseDiameterCallback () const
 Gets the registered callback for the decrease diameter event ('[' key) More...
 
virtual void setDecreaseDiameterCallback (const Callback &cb_)
 Sets the callback for the decrease diameter event. More...
 
virtual Callback *const increaseDiameterCallback () const
 Gets the registered callback for the increase diameter event (']' key) More...
 
virtual void setIncreaseDiameterCallback (const Callback &cb_)
 Sets the callback for the increase diameter event. More...
 
virtual Callback *const editCallback () const
 Gets the registered callback for the tool edit event (when its icon is double-clicked) More...
 
virtual void setEditCallback (const Callback &cb_)
 Sets the callback for the tool edit event. More...
 
virtual void resetCursorLocs ()
 Clears the mouse down and mouse up location containers. More...
 
virtual bool wasDragged () const
 Gets whether the tool has been dragged. More...
 
virtual bool shiftKeyDown () const
 Determines whether the shift key is down. More...
 
virtual bool commandKeyDown () const
 Determines whether the command key is down. More...
 
virtual bool optionKeyDown () const
 Determines whether the option key is down. More...
 
virtual bool controlKeyDown () const
 Determines whether the control key is down. More...
 
virtual ModalDialog *const inputDialog () const
 Gets the modal input dialog for the target tool. More...
 
virtual void setInputDialog (const ModalDialog &dialog_)
 Sets the modal input dialog for the target tool. More...
 
virtual ModalDialog *const prefsDialog () const
 Gets the modal prefs dialog for the target tool. More...
 
virtual void setPrefsDialog (const ModalDialog &dialog_)
 Sets the modal prefs dialog for the target tool. More...
 
virtual bool autoShowPrefsDialog () const
 Gets whether the tool prefs dialog should automatically be shown when the tool is double-clicked in the Illustrator toolbox. More...
 
virtual void setAutoShowPrefsDialog (const bool show_)
 Sets whether the tool prefs dialog should automatically be shown when the tool is double- clicked in the Illustrator toolbox. More...
 

Friends

plugin::BaseTool * __accessImpl (const Tool &)
 
Tool __accessCtorTool (const void *)
 

Detailed Description

Base class for all tools; stores hit data, cursor loc, dialogs, etc.; receives tool-related messages.

Constructor & Destructor Documentation

hdi::core::Tool::Tool ( )

Constructs an empty Tool object.

Author
GW
Date
09/2013
Note
To test if a Tool object is empty, call isEmpty() on it
Empty Tool objects do not relate to any actual Illustrator tool; they are designed to be "receivers" of some other Tool object via the overloaded assignment operator. Empty Tool objects are useless until such time (though it is safe to call any of their methods)
hdi::core::Tool::Tool ( const Tool tool_)

Constructs a new Tool object from an existing Tool object (copy constructor)

Author
GW
Date
09/2013
Parameters
tool_Existing Tool object
hdi::core::Tool::Tool ( const Tool sameGroupAs_,
const Tool *const  sameSetAs_,
const std::string &  title_,
const std::string &  tip_,
const int16_t  lightIconID_,
const int16_t  darkIconID_,
const Options  options_ = DefaultOptions 
)

Constructs a new Tool object, optionally in the same set/group as one of your own tools.

Author
GW
Date
09/2013
Parameters
sameGroupAs_Existing reference Tool object for the group the new Tool object belongs in; pass an empty Tool object to force a new group
sameSetAs_Existing reference Tool object for the set the new Tool object belongs in (sets are inside groups); pass NULL for a new set
title_Tool title (must be unique), as UTF-8
tip_Tool tip (shown when the tool is rolled over in the toolbar), as UTF-8
lightIconID_PNGI resource ID for the light interface icon
darkIconID_PNGI resource ID for the dark interface icon
options_Bitwise OR of Options enum values, controlling behavior of the tool
Note
If the sameGroupAs_ argument is empty, then sameSetAs_ will be ignored.
As of Illustrator 21, Adobe has still not updated tools to truly accept Unicode titles and tips. This method takes UTF-8 strings as arguments but converts them internally to platform-encoding, so be sure to use platform encoding-compatible values for your strings! It would also be wise to detect the locale of Illustrator at startup and use the appropriate value for your localized strings, if any.
Illustrator 17 and above requires lightIconID_ and darkIconID_ to have a "sibling" resource that is lightIconID_+1 and darkIconID_+1 in value (respectively). Additionally, the name of the PNGI resource for lightIconID_+1 and darkIconID_+1 must be same name as lightIconID_ and darkIconID_ but suffixed with "@2x". The reason is that Illustrator 17+ supports HiDPI displays, and this is their solution for supporting higher resolution images. If you do not follow this advice, you will receive a mysterious 'CANT' error from Illustrator in a modal dialog at startup and your tool(s) will not be loaded.
hdi::core::Tool::Tool ( const BuiltinTool sameGroupAs_,
const BuiltinTool *const  sameSetAs_,
const std::string &  title_,
const std::string &  tip_,
const int16_t  lightIconID_,
const int16_t  darkIconID_,
const Options  options_ = DefaultOptions 
)

Constructs a new Tool object in the same set/group as a built-in Illustrator tool.

Author
GW
Date
09/2013
Parameters
sameGroupAs_Existing reference BuiltinTool object for the group the new Tool object belongs in; pass an empty BuiltinTool object to force a new group
sameSetAs_Existing reference BuiltinTool object for the set the new Tool object belongs in (sets are inside groups); pass NULL for a new set
title_Tool title (must be unique), as UTF-8
tip_Tool tip (shown when the tool is rolled over in the toolbar), as UTF-8
lightIconID_PNGI resource ID for the light interface icon
darkIconID_PNGI resource ID for the dark interface icon
options_Bitwise OR of Options enum values, controlling behavior of the tool
Note
If the sameGroupAs_ argument is empty, then sameSetAs_ will be ignored.
As of Illustrator 21, Adobe has still not updated tools to truly accept Unicode titles and tips. This method takes UTF-8 strings as arguments but converts them internally to platform-encoding, so be sure to use platform encoding-compatible values for your strings! It would also be wise to detect the locale of Illustrator at startup and use the appropriate value for your localized strings, if any.
Illustrator 17 and above requires lightIconID_ and darkIconID_ to have a "sibling" resource that is lightIconID_+1 and darkIconID_+1 in value (respectively). Additionally, the name of the PNGI resource for lightIconID_+1 and darkIconID_+1 must be same name as lightIconID_ and darkIconID_ but suffixed with "@2x". The reason is that Illustrator 17+ supports HiDPI displays, and this is their solution for supporting higher resolution images. If you do not follow this advice, you will receive a mysterious 'CANT' error from Illustrator in a modal dialog at startup and your tool(s) will not be loaded.
hdi::core::Tool::Tool ( const int16_t  sameGroupAs_,
const int16_t  sameSetAs_,
const std::string &  title_,
const std::string &  tip_,
const int16_t  lightIconID_,
const int16_t  darkIconID_,
const Options  options_ = DefaultOptions 
)
explicit

Constructs a new Tool object in the same set/group as some third-party tool (via handles)

Author
GW
Date
02/2016
Parameters
sameGroupAs_Tool number for the existing group the new Tool object belongs in; pass -2 for a new group
sameSetAs_Tool number for the existing set the new Tool object belongs in (sets are inside groups); pass -2 for a new set
title_Tool title (must be unique), as UTF-8
tip_Tool tip (shown when the tool is rolled over in the toolbar), as UTF-8
lightIconID_PNGI resource ID for the light interface icon
darkIconID_PNGI resource ID for the dark interface icon
options_Bitwise OR of Options enum values, controlling behavior of the tool
Note
Illustrator itself uses a value of -2 to mean "no tool".
If the sameGroupAs_ argument is -2, then sameSetAs_ will be ignored.
As of Illustrator 21, Adobe has still not updated tools to truly accept Unicode titles and tips. This method takes UTF-8 strings as arguments but converts them internally to platform-encoding, so be sure to use platform encoding-compatible values for your strings! It would also be wise to detect the locale of Illustrator at startup and use the appropriate value for your localized strings, if any.
Illustrator 17 and above requires lightIconID_ and darkIconID_ to have a "sibling" resource that is lightIconID_+1 and darkIconID_+1 in value (respectively). Additionally, the name of the PNGI resource for lightIconID_+1 and darkIconID_+1 must be same name as lightIconID_ and darkIconID_ but suffixed with "@2x". The reason is that Illustrator 17+ supports HiDPI displays, and this is their solution for supporting higher resolution images. If you do not follow this advice, you will receive a mysterious 'CANT' error from Illustrator in a modal dialog at startup and your tool(s) will not be loaded.
virtual hdi::core::Tool::~Tool ( )
virtual

Destructs a Tool object.

Author
GW
Date
09/2013

Member Function Documentation

virtual AIToolHandle hdi::core::Tool::aiToolHandle ( ) const
virtual

Gets the tool handle around which the target object is wrapped.

Author
GW
Date
11/2013
Returns
AIToolHandle for this object
Note
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 hdi_core library.
virtual bool hdi::core::Tool::autoShowPrefsDialog ( ) const
virtual

Gets whether the tool prefs dialog should automatically be shown when the tool is double-clicked in the Illustrator toolbox.

Author
GW
Date
10/2013
Returns
true if the dialog will automatically be shown, false otherwise
virtual bool hdi::core::Tool::commandKeyDown ( ) const
virtual

Determines whether the command key is down.

Author
GW
Date
09/2013
Returns
true if the command key was down in the last tool event
Note
Windows machines do not have a command key. If this method is called on a Windows machine, it will return the same value as the controlKeyDown() method (because the control key is the closest command key analog on Windows).
The return value is only valid if the last message the plugin received was a tool-related event, and only if the event relates to the target Tool.
virtual bool hdi::core::Tool::controlKeyDown ( ) const
virtual

Determines whether the control key is down.

Author
GW
Date
09/2013
Returns
true if the control key was down in the last tool event
Note
The return value is only valid if the last message the plugin received was a tool-related event, and only if the event relates to the target Tool.
virtual std::auto_ptr<HitData> hdi::core::Tool::cursorHitData ( const HitRequest  request_,
const double  tolerance_ = 2.0 
) const
virtual

Gets hit data for the current cursor location.

Author
GW
Date
09/2013
Parameters
request_Type of hit request to perform
tolerance_Point radius around cursor location in which a hit is valid
Returns
The HitData object for the cursor location
virtual ArtboardPoint hdi::core::Tool::cursorLoc ( ) const
virtual

Gets the current location of the cursor.

Author
GW
Date
09/2013
Returns
The last known cursor location for the tool
Note
The cursor location is automatically set when a mouse event occurs
virtual int16_t hdi::core::Tool::darkIconID ( ) const
virtual

Gets the dark UI icon ID as set when the tool was created.

Author
GW
Date
02/2014
Returns
The PNGI resource ID for the dark interface icon for the target tool
virtual Callback* const hdi::core::Tool::decreaseDiameterCallback ( ) const
virtual

Gets the registered callback for the decrease diameter event ('[' key)

Author
GW
Date
09/2013
Returns
Callback for decreasing diameter, or NULL if none
virtual Callback* const hdi::core::Tool::deselectionCallback ( ) const
virtual

Gets the registered callback for the tool deselection event.

Author
GW
Date
09/2013
Returns
Callback for deselection, or NULL if none
virtual void hdi::core::Tool::destroy ( )
virtual

Destroys the tool, converting the target object to an empty Tool object (see the default constructor for more info on empty Tool objects)

Author
GW
Date
12/2013
Note
This method must be called for any existing tools by the time the plugin is shutting down. If you no longer retain any of your own references to a tool then the lib will call this method for you as it is shutting down.
virtual Callback* const hdi::core::Tool::dragCallback ( ) const
virtual

Gets the registered callback for the drag event.

Author
GW
Date
09/2013
Returns
Callback for dragging, or NULL if none
virtual Callback* const hdi::core::Tool::editCallback ( ) const
virtual

Gets the registered callback for the tool edit event (when its icon is double-clicked)

Author
GW
Date
09/2013
Returns
Callback for tool edit, or NULL if none
virtual Callback* const hdi::core::Tool::increaseDiameterCallback ( ) const
virtual

Gets the registered callback for the increase diameter event (']' key)

Author
GW
Date
09/2013
Returns
Callback for increasing diameter, or NULL if none
virtual ModalDialog* const hdi::core::Tool::inputDialog ( ) const
virtual

Gets the modal input dialog for the target tool.

Author
GW
Date
10/2013
Returns
A pointer to the modal input dialog for the tool, or NULL if none/error
Note
It is common for tools to have modal input dialogs that are shown when the mouse button comes up; however, this process is not automated for the creator of the tool as not all tools show an input dialog at the same point in the mouse event timeline. The Tool class merely offers a convenient place to store said dialog object.
virtual bool hdi::core::Tool::isEmpty ( ) const
virtual

Gets whether the target Tool object is empty (constructed with the default ctor)

Author
GW
Date
09/2013
Returns
true if the target Tool object is empty, false otherwise
virtual int16_t hdi::core::Tool::lightIconID ( ) const
virtual

Gets the light UI icon ID as set when the tool was created.

Author
GW
Date
02/2014
Returns
The PNGI resource ID for the light interface icon for the target tool
virtual Callback* const hdi::core::Tool::mouseDownCallback ( ) const
virtual

Gets the registered callback for the mouse down event.

Author
GW
Date
09/2013
Returns
Callback for mouse down, or NULL if none
virtual std::auto_ptr<HitData> hdi::core::Tool::mouseDownHitData ( const uint32_t  index_,
const HitRequest  request_,
const double  tolerance_ = 2.0 
) const
virtual

Gets hit data for a given point in the mouse down location vector.

Author
GW
Date
09/2013
Parameters
index_Index of the point in the mouse down vector
request_Type of hit request to perform
tolerance_Point radius around mouse down location in which a hit is valid
Returns
The HitData object for the specified mouse down location
virtual ArtboardPointVector hdi::core::Tool::mouseDownLocs ( ) const
virtual

Gets the mouse down points for the target tool.

Author
GW
Date
09/2013
Returns
A vector of points where the user performed a mouse down
virtual Callback* const hdi::core::Tool::mouseUpCallback ( ) const
virtual

Gets the registered callback for the mouse up event.

Author
GW
Date
09/2013
Returns
Callback for mouse up, or NULL if none
virtual std::auto_ptr<HitData> hdi::core::Tool::mouseUpHitData ( const uint32_t  index_,
const HitRequest  request_,
const double  tolerance_ = 2.0 
) const
virtual

Gets hit data for a given point in the mouse up location vector.

Author
GW
Date
09/2013
Parameters
index_Index of the point in the mouse up vector
request_Type of hit request to perform
tolerance_Point radius around mouse up location in which a hit is valid
Returns
The HitData object for the specified mouse up location
virtual ArtboardPointVector hdi::core::Tool::mouseUpLocs ( ) const
virtual

Gets the mouse up points for the target tool.

Author
GW
Date
09/2013
Returns
A vector of points where the user performed a mouse up
virtual int16_t hdi::core::Tool::number ( ) const
virtual

Gets the tool's number.

Author
GW
Date
08/2015
Returns
The unique number for the tool, assigned by Illustrator
Note
Illustrator uses a value of -2 for "no tool", so this is used to indicate an error or empty Tool object (hence no underlying number)
virtual bool hdi::core::Tool::operator!= ( const Tool rhs_) const
virtual

Tests whether a given Tool object is not the same as another.

Author
GW
Date
08/2013
Parameters
rhs_Tool to compare against (righthand side of inequality operator)
Returns
true for the target and rhs_ being different tools, false otherwise
virtual Tool& hdi::core::Tool::operator= ( const Tool rhs_)
virtual

Assigns one Tool object to another.

Author
GW
Date
09/2013
Parameters
rhs_Existing Tool object to copy values from
Returns
The target Tool object, but with its values updated to match that of the rhs_ argument
virtual bool hdi::core::Tool::operator== ( const Tool rhs_) const
virtual

Tests whether a given Tool object is the same as another.

Author
GW
Date
08/2013
Parameters
rhs_Tool to compare against (righthand side of equality operator)
Returns
true for the target and rhs_ being the same tool, false otherwise
virtual bool hdi::core::Tool::optionKeyDown ( ) const
virtual

Determines whether the option key is down.

Author
GW
Date
09/2013
Returns
true if the option key was down in the last tool event
Note
The option key on Mac is akin to the alt key on Windows.
The return value is only valid if the last message the plugin received was a tool-related event, and only if the event relates to the target Tool.
virtual Options hdi::core::Tool::options ( ) const
virtual

Gets the options set for the tool.

Author
GW
Date
09/2013
Returns
A bitwise OR of Options enum values
virtual ModalDialog* const hdi::core::Tool::prefsDialog ( ) const
virtual

Gets the modal prefs dialog for the target tool.

Author
GW
Date
10/2013
Returns
A pointer to the modal prefs dialog for the tool, or NULL if none/error
Note
It is common for tools to have modal prefs dialogs that are shown when the tool is double-clicked in the Illustrator toolbox; this process is automated for the creator of the tool unless setAutoShowPrefsDialog(false) is called.
virtual Callback* const hdi::core::Tool::reselectionCallback ( ) const
virtual

Gets the registered callback for the tool reselection event.

Author
GW
Date
09/2013
Returns
Callback for reselection, or NULL if none
virtual void hdi::core::Tool::resetCursorLocs ( )
virtual

Clears the mouse down and mouse up location containers.

Author
GW
Date
09/2013
Note
Since tool implementations often vary (e.g. a tool might require exactly two clicks instead of just one click), it is up to the tool creator to call this method when appropriate.
virtual bool hdi::core::Tool::selected ( ) const
virtual

Gets whether the target Tool object is the currently selected tool.

Author
GW
Date
07/2014
Returns
true if the tool is selected, false otherwise
virtual Callback* const hdi::core::Tool::selectionCallback ( ) const
virtual

Gets the registered callback for the tool selection event.

Author
GW
Date
09/2013
Returns
Callback for selection, or NULL if none
virtual void hdi::core::Tool::setAutoShowPrefsDialog ( const bool  show_)
virtual

Sets whether the tool prefs dialog should automatically be shown when the tool is double- clicked in the Illustrator toolbox.

Author
GW
Date
10/2013
Parameters
show_true to show the prefs dialog automatically
virtual void hdi::core::Tool::setCursorLoc ( const ArtboardPoint loc_)
virtual

Stores the current location of the cursor.

Author
GW
Date
09/2013
Parameters
loc_Current cursor location
Note
Typically, this method shouldn't need to be called. The cursor loc for the current (active) tool is automatically set when a mouse event occurs.
virtual void hdi::core::Tool::setDarkIconID ( const int16_t  imgID_)
virtual

Sets the dark UI icon ID.

Author
GW
Date
04/2015
Parameters
imgID_New PNGI resource ID for the dark interface icon for the target tool
Note
This method is only meaningful in Illustrator 19 and above (setting the dark tool icon after creation is not supported in Illustrator 16 through 18).
virtual void hdi::core::Tool::setDecreaseDiameterCallback ( const Callback cb_)
virtual

Sets the callback for the decrease diameter event.

Author
GW
Date
09/2013
Parameters
cb_The new decrease diameter callback
virtual void hdi::core::Tool::setDeselectionCallback ( const Callback cb_)
virtual

Sets the callback for the tool deselection event.

Author
GW
Date
09/2013
Parameters
cb_The new deselection callback
virtual void hdi::core::Tool::setDragCallback ( const Callback cb_)
virtual

Sets the callback for the drag event.

Author
GW
Date
09/2013
Parameters
cb_The new dragging callback
virtual void hdi::core::Tool::setEditCallback ( const Callback cb_)
virtual

Sets the callback for the tool edit event.

Author
GW
Date
09/2013
Parameters
cb_The new edit callback
virtual void hdi::core::Tool::setIncreaseDiameterCallback ( const Callback cb_)
virtual

Sets the callback for the increase diameter event.

Author
GW
Date
09/2013
Parameters
cb_The new increase diameter callback
virtual void hdi::core::Tool::setInputDialog ( const ModalDialog dialog_)
virtual

Sets the modal input dialog for the target tool.

Author
GW
Date
10/2013
Parameters
dialog_New modal input dialog for the tool
Note
It is common for tools to have modal input dialogs that are shown when the mouse button comes up; however, this process is not automated for the creator of the tool as not all tools show an input dialog at the same point in the mouse event timeline. The Tool class merely offers a convenient place to store said dialog object.
virtual void hdi::core::Tool::setLightIconID ( const int16_t  imgID_)
virtual

Sets the light UI icon ID.

Author
GW
Date
04/2015
Parameters
imgID_New PNGI resource ID for the light interface icon for the target tool
Note
This method performs no action in Illustrator 16 through 18 (setting the light tool icon after tool creation in these versions is unsupported).
virtual void hdi::core::Tool::setMouseDownCallback ( const Callback cb_)
virtual

Sets the callback for the mouse down event.

Author
GW
Date
09/2013
Parameters
cb_The new mouse down callback
virtual void hdi::core::Tool::setMouseUpCallback ( const Callback cb_)
virtual

Sets the callback for the mouse up event.

Author
GW
Date
09/2013
Parameters
cb_The new mouse up callback
virtual void hdi::core::Tool::setOptions ( const Options  options_)
virtual

Sets the options for the tool.

Author
GW
Date
09/2013
Parameters
options_A bitwise OR of new Options enum values
virtual void hdi::core::Tool::setPrefsDialog ( const ModalDialog dialog_)
virtual

Sets the modal prefs dialog for the target tool.

Author
GW
Date
10/2013
Parameters
dialog_New modal prefs dialog for the tool
Note
It is common for tools to have modal prefs dialogs that are shown when the tool is double- clicked in the Illustrator toolbox; this process is automated for the creator of the tool unless setAutoShowPrefsDialog(false) is called.
virtual void hdi::core::Tool::setReselectionCallback ( const Callback cb_)
virtual

Sets the callback for the tool reselection event.

Author
GW
Date
09/2013
Parameters
cb_The new reselection callback
virtual void hdi::core::Tool::setSelected ( )
virtual

Sets the target Tool object as the currently selected tool.

Author
GW
Date
09/2014
virtual void hdi::core::Tool::setSelectionCallback ( const Callback cb_)
virtual

Sets the callback for the tool selection event.

Author
GW
Date
09/2013
Parameters
cb_The new selection callback
virtual void hdi::core::Tool::setTip ( const std::string &  tip_)
virtual

Sets the tool's tip string.

Author
GW
Date
09/2013
Parameters
tip_New rollover tip for the tool, as UTF-8
Note
As of Illustrator 21, Adobe has still not updated tools to truly accept Unicode titles and tips. This method takes UTF-8 strings as arguments but converts them internally to platform-encoding, so be sure to use platform encoding-compatible values for your strings! It would also be wise to detect the locale of Illustrator at startup and use the appropriate value for your localized strings, if any.
virtual void hdi::core::Tool::setTitle ( const std::string &  title_)
virtual

Sets the tool's title.

Author
GW
Date
09/2013
Parameters
title_New title for the tool, as UTF-8
Note
As of Illustrator 21, Adobe has still not updated tools to truly accept Unicode titles and tips. This method takes UTF-8 strings as arguments but converts them internally to platform-encoding, so be sure to use platform encoding-compatible values for your strings! It would also be wise to detect the locale of Illustrator at startup and use the appropriate value for your localized strings, if any.
virtual void hdi::core::Tool::setTrackCallback ( const Callback cb_)
virtual

Sets the callback for the tool tracking event (mouse move)

Author
GW
Date
09/2013
Parameters
cb_The new tracking callback
virtual bool hdi::core::Tool::shiftKeyDown ( ) const
virtual

Determines whether the shift key is down.

Author
GW
Date
09/2013
Returns
true if the shift key was down in the last tool event
Note
The return value is only valid if the last message the plugin received was a tool-related event, and only if the event relates to the target Tool.
virtual std::string hdi::core::Tool::tip ( ) const
virtual

Gets the tool's tip string.

Author
GW
Date
09/2013
Returns
The rollover tip for the tool, as UTF-8
virtual std::string hdi::core::Tool::title ( ) const
virtual

Gets the tool's title.

Author
GW
Date
09/2013
Returns
The title for the tool, as UTF-8
virtual Callback* const hdi::core::Tool::trackCallback ( ) const
virtual

Gets the registered callback for the tool tracking event (mouse move)

Author
GW
Date
09/2013
Returns
Callback for tracking, or NULL if none
virtual bool hdi::core::Tool::wasDragged ( ) const
virtual

Gets whether the tool has been dragged.

Author
GW
Date
09/2013
Returns
true if a mouse drag event was received between mouse down and mouse up events
Note
The state of the dragged bit is reset with each mouse down event.