Wraps around an Illustrator menu group. More...

#include <hdicoreMenuGroup.h>

Classes
struct	Child
	Menu groups can have both groups and items as children, so this acts as a simple wrapper to store one or the other. More...

Public Types
typedef std::vector< std::shared_ptr< Child > >	ChildVector

typedef std::unique_ptr< Child >	ChildUP

typedef std::shared_ptr< Child >	ChildSP

typedef std::weak_ptr< Child >	ChildWP

Public Member Functions
	MenuGroup ()
	Constructs an empty MenuGroup object.

	MenuGroup (const MenuGroup &m_)
	Constructs a new MenuGroup object from an existing MenuGroup object (copy constructor)

	MenuGroup (const BuiltinMenuGroup group_, const std::string &text_, const bool sort_=false, const bool mergeTop_=false, const bool divBelow_=false, const bool divAbove_=false)
	Constructs a new MenuGroup object.

	MenuGroup (const MenuGroup &group_, const std::string &text_, const bool sort_=false, const bool mergeTop_=false, const bool divBelow_=false, const bool divAbove_=false)
	Constructs a new MenuGroup object.

virtual	~MenuGroup ()
	Destructs a MenuGroup object.

virtual void	destroy ()
	Destroys the UI menu group, converting the target object to an empty MenuGroup object (see the default constructor for more info on empty MenuGroup objects)

virtual MenuGroup &	operator= (const MenuGroup &rhs_)
	Assigns one MenuGroup object to another.

virtual bool	operator== (const MenuGroup &rhs_) const
	Tests whether a given MenuGroup object is the same as another.

virtual bool	operator!= (const MenuGroup &rhs_) const
	Tests whether a given MenuGroup object is not the same as another.

virtual AIMenuGroup	aiMenuGroup () const
	Gets the menu group around which the target object is wrapped.

virtual AIMenuItemHandle	aiMenuItemHandle () const
	Gets the menu item handle around which the target object is wrapped.

virtual bool	isEmpty () const
	Gets whether the target MenuGroup object is empty (constructed with the default ctor)

virtual bool	isPartial () const
	Gets whether the menu group is a built-in Illustrator group.

virtual std::unique_ptr< MenuGroup >	parent () const
	Gets the parent of the target menu group.

virtual ChildVector	children () const
	Gets the children of the target menu group.

virtual bool	enabled () const
	Gets whether the menu group is enabled.

virtual void	setEnabled (const bool enabled_)
	Sets the menu group as enabled or disabled.

virtual std::string	text () const
	Gets the text of the menu group itself.

virtual void	setText (const std::string &text_)
	Sets the text of the menu group itself.

virtual bool	sorted () const
	Gets whether the children of the target menu group are sorted.

virtual void	setSorted (const bool sort_)
	Sets whether the children of the target menu group art sorted alphabetically or in order of creation.

Friends
MenuGroup	__accessCtor (AIMenuGroup, AIMenuItemHandle)

Detailed Description

Wraps around an Illustrator menu group.

Constructor & Destructor Documentation

◆ MenuGroup() [1/4]

hdi::core::MenuGroup::MenuGroup ( )

Constructs an empty MenuGroup object.

Author: GW

Date: 11/2013

Note: To test if a MenuGroup object is empty, call isEmpty() on it; Empty MenuGroup objects do not relate to any actual Illustrator menu group; they are designed to be "receivers" of some other MenuGroup object via the overloaded assignment operator. Empty MenuGroup objects are useless until such time (though it is safe to call any of their methods).

◆ MenuGroup() [2/4]

hdi::core::MenuGroup::MenuGroup ( const MenuGroup & m_ )

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

Author: GW

Date: 11/2013

Parameters

m_	Existing MenuGroup object

◆ MenuGroup() [3/4]

hdi::core::MenuGroup::MenuGroup	(	const BuiltinMenuGroup	group_,
		const std::string &	text_,
		const bool	sort_ = `false`,
		const bool	mergeTop_ = `false`,
		const bool	divBelow_ = `false`,
		const bool	divAbove_ = `false`
	)

Constructs a new MenuGroup object.

Author: GW

Date: 11/2013

Parameters

group_	Built-in Illustrator menu group to contain the new MenuGroup
text_	String that will show as the menu group title, as UTF-8
sort_	Whether to sort the children of the new group alphabetically, or in order of creation
mergeTop_	Whether to merge the new group with group_ and force any children of the new group to be at the top of the list
divBelow_	Whether to automatically place a separator item below the new group
divAbove_	Whether to automatically place a separator item above the new group

Note: divBelow_ and divAbove_ are only applicable if mergeTop_ is true.

◆ MenuGroup() [4/4]

hdi::core::MenuGroup::MenuGroup	(	const MenuGroup &	group_,
		const std::string &	text_,
		const bool	sort_ = `false`,
		const bool	mergeTop_ = `false`,
		const bool	divBelow_ = `false`,
		const bool	divAbove_ = `false`
	)

Constructs a new MenuGroup object.

Author: GW

Date: 11/2013

Parameters

group_	User-created menu group to contain the new MenuGroup
text_	String that will show as the menu group title, as UTF-8
sort_	Whether to sort the children of the new group alphabetically, or in order of creation
mergeTop_	Whether to merge the new group with group_ and force any children of the new group to be at the top of the list
divBelow_	Whether to automatically place a separator item below the new group
divAbove_	Whether to automatically place a separator item above the new group

Note: divBelow_ and divAbove_ are only applicable if mergeTop_ is true.

◆ ~MenuGroup()

virtual hdi::core::MenuGroup::~MenuGroup ( )

virtual

Destructs a MenuGroup object.

Author: GW

Date: 11/2013

Member Function Documentation

◆ aiMenuGroup()

virtual AIMenuGroup hdi::core::MenuGroup::aiMenuGroup ( ) const

virtual

Gets the menu group around which the target object is wrapped.

Author: GW

Date: 09/2014

Returns: AIMenuGroup 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.

◆ aiMenuItemHandle()

virtual AIMenuItemHandle hdi::core::MenuGroup::aiMenuItemHandle ( ) const

virtual

Gets the menu item handle around which the target object is wrapped.

Author: GW

Date: 11/2013

Returns: AIMenuItemHandle 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.

◆ children()

virtual ChildVector hdi::core::MenuGroup::children ( ) const

virtual

Gets the children of the target menu group.

Author: GW

Date: 09/2014

Returns: A vector of Child objects, with either the group or item members filled in each (never both)

Note: Illustrator offers no direct calls to obtain menu group children, so this method must iterate over all menu items in order to locate the children of the target group. As such, any e.g. recursive operations on a menu item hierarchy is inherently O(n^2).

◆ destroy()

virtual void hdi::core::MenuGroup::destroy ( )

virtual

Destroys the UI menu group, converting the target object to an empty MenuGroup object (see the default constructor for more info on empty MenuGroup objects)

Author: GW

Date: 11/2013

Note: This method must be called for any existing menu groups by the time the plugin is shutting down. If you no longer retain any of your own references to a menu group then the lib will call this method for you as it is shutting down.

◆ enabled()

virtual bool hdi::core::MenuGroup::enabled ( ) const

virtual

Gets whether the menu group is enabled.

Author: GW

Date: 11/2013

Returns: true if the group is enabled, false otherwise

Note: Ignore this method if isPartial() returns true.

◆ isEmpty()

virtual bool hdi::core::MenuGroup::isEmpty ( ) const

virtual

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

Author: GW

Date: 11/2013

Returns: true if the target MenuGroup object is empty, false otherwise

◆ isPartial()

virtual bool hdi::core::MenuGroup::isPartial ( ) const

virtual

Gets whether the menu group is a built-in Illustrator group.

Author: GW

Date: 09/2014

Returns: true if the target represents a built-in Illustrator menu group, false otherwise

Note: Most of Illustrator's menu groups are not actually groups at all, but rather a specific region of some top-level menu or other subgroup. This can be a bit confusing, as some "groups" do not actually behave like proper groups (e.g. their parent cannot be acquired, text value cannot be acquired, etc). If a specific method of this class is not behaving the way you expect, it would be wise to check this method as a hint. Methods that are affected by the return value of isPartial() are denoted in their documentation.

◆ operator!=()

virtual bool hdi::core::MenuGroup::operator!= ( const MenuGroup & rhs_ ) const

virtual

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

Author: GW

Date: 08/2013

Parameters

rhs_	MenuGroup to compare against (righthand side of inequality operator)

Returns: true for the target and rhs_ being different menu groups, false otherwise

◆ operator=()

virtual MenuGroup & hdi::core::MenuGroup::operator= ( const MenuGroup & rhs_ )

virtual

Assigns one MenuGroup object to another.

Author: GW

Date: 11/2013

Parameters

rhs_	Existing MenuGroup object to copy values from

Returns: The target MenuGroup object, but with its values updated to match that of the rhs_ argument

◆ operator==()

virtual bool hdi::core::MenuGroup::operator== ( const MenuGroup & rhs_ ) const

virtual

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

Author: GW

Date: 11/2013

Parameters

rhs_	MenuGroup to compare against (righthand side of equality operator)

Returns: true for the target and rhs_ being the same menu group, false otherwise

◆ parent()

virtual std::unique_ptr< MenuGroup > hdi::core::MenuGroup::parent ( ) const

virtual

Gets the parent of the target menu group.

Author: GW

Date: 09/2014

Returns: The parent menu group, or NULL for none/error

Note: Cannot be acquired if isPartial() returns true.

◆ setEnabled()

virtual void hdi::core::MenuGroup::setEnabled ( const bool enabled_ )

virtual

Sets the menu group as enabled or disabled.

Author: GW

Date: 11/2013

Parameters

enabled_ true to enable the group, false to disable

Note: Cannot be set if isPartial() returns true.

◆ setSorted()

virtual void hdi::core::MenuGroup::setSorted ( const bool sort_ )

virtual

Sets whether the children of the target menu group art sorted alphabetically or in order of creation.

Author: GW

Date: 09/2014

Parameters

sort_ true to sort alphabetically, false otherwise

◆ setText()

virtual void hdi::core::MenuGroup::setText ( const std::string & text_ )

virtual

Sets the text of the menu group itself.

Author: GW

Date: 11/2013

Parameters

text_ New text value for the menu group, as UTF-8

Note: Cannot be set if isPartial() returns true.

◆ sorted()

virtual bool hdi::core::MenuGroup::sorted ( ) const

virtual

Gets whether the children of the target menu group are sorted.

Author: GW

Date: 09/2014

Returns: true if sorted alphabetically, false otherwise

◆ text()

virtual std::string hdi::core::MenuGroup::text ( ) const

virtual

Gets the text of the menu group itself.

Author: GW

Date: 11/2013

Returns: Current text value of the menu group, as UTF-8

Note: Ignore this method if isPartial() returns true.

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ MenuGroup() [1/4]

◆ MenuGroup() [2/4]

◆ MenuGroup() [3/4]

◆ MenuGroup() [4/4]

◆ ~MenuGroup()

Member Function Documentation

◆ aiMenuGroup()

◆ aiMenuItemHandle()

◆ children()

◆ destroy()

◆ enabled()

◆ isEmpty()

◆ isPartial()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ parent()

◆ setEnabled()

◆ setSorted()

◆ setText()

◆ sorted()

◆ text()