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< ArtboardPoint >	ArtboardPointVector

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 Tool &	operator= (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< HitData >	mouseDownHitData (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< HitData >	mouseUpHitData (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< HitData >	cursorHitData (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.

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation