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

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< Child * > ChildVector
 
typedef std::auto_ptr< ChildChildAP
 

Public Member Functions

 MenuGroup ()
 Constructs an empty MenuGroup object. More...
 
 MenuGroup (const MenuGroup &m_)
 Constructs a new MenuGroup object from an existing MenuGroup object (copy constructor) More...
 
 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. More...
 
 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. More...
 
virtual ~MenuGroup ()
 Destructs a MenuGroup object. More...
 
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) More...
 
virtual MenuGroupoperator= (const MenuGroup &rhs_)
 Assigns one MenuGroup object to another. More...
 
virtual bool operator== (const MenuGroup &rhs_) const
 Tests whether a given MenuGroup object is the same as another. More...
 
virtual bool operator!= (const MenuGroup &rhs_) const
 Tests whether a given MenuGroup object is not the same as another. More...
 
virtual AIMenuGroup aiMenuGroup () const
 Gets the menu group around which the target object is wrapped. More...
 
virtual AIMenuItemHandle aiMenuItemHandle () const
 Gets the menu item handle around which the target object is wrapped. More...
 
virtual bool isEmpty () const
 Gets whether the target MenuGroup object is empty (constructed with the default ctor) More...
 
virtual bool isPartial () const
 Gets whether the menu group is a built-in Illustrator group. More...
 
virtual std::auto_ptr< MenuGroupparent () const
 Gets the parent of the target menu group. More...
 
virtual ChildVector children () const
 Gets the children of the target menu group. More...
 
virtual bool enabled () const
 Gets whether the menu group is enabled. More...
 
virtual void setEnabled (const bool enabled_)
 Sets the menu group as enabled or disabled. More...
 
virtual std::string text () const
 Gets the text of the menu group itself. More...
 
virtual void setText (const std::string &text_)
 Sets the text of the menu group itself. More...
 
virtual bool sorted () const
 Gets whether the children of the target menu group are sorted. More...
 
virtual void setSorted (const bool sort_)
 Sets whether the children of the target menu group art sorted alphabetically or in order of creation. More...
 

Friends

MenuGroup __accessCtor (AIMenuGroup, AIMenuItemHandle)
 

Detailed Description

Wraps around an Illustrator menu group.

Constructor & Destructor Documentation

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).
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
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.
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.
virtual hdi::core::MenuGroup::~MenuGroup ( )
virtual

Destructs a MenuGroup object.

Author
GW
Date
11/2013

Member Function Documentation

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.
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.
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).
Warning
The caller assumes responsibility of the memory for the contained Child objects.
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.
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.
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
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.
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
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
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
virtual std::auto_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.
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.
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
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.
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
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.