Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
MCollectible, MControl, MGUIAttributeUser
Inherited By:
TEmbedderMenuItem
TBooleanMenuItem
TMomentaryMenuItem
Purpose:
MMenuItem derives from MControl and is an abstract base class that defines the protocol necessary to layout, draw, and interact with a menu item. Menu items can contain any number of subparts, which are automatically aligned by the menu. These parts can be graphical and/or textual in any combination. For example, a menu item can contain a check graphic, a text label, and a command key label. The layout of all the subparts is performed according to the layout orientation defined in MControl::SetControlLayout.
This class defines protocol for specifying one main label and an optional command key label. The command key is specified in terms of a virtual key code and a set of keyboard modifiers. The appropriate text label is calculated using the virtual keyboard mechanism and is presented in the item. Classes deriving from MMenuItem can add more subparts by adding to the result of GetNumberOfParts, and by overriding the other subpart layout functions. For example, the TBooleanMenuItem adds a checkmark.
Menu items can be visually separated from other items by separators before and/or after the item.
Instantiation:
Abstract base class; do not allocate.
Deriving Classes:
The User Interface Frameworks provide most of the derived classes you will need. Typically these derived classes hook up the menu item to some type of control state or allow the embedding of other controls inside a menu item. The different derived classes also tend to add different types of menu item parts.
Animate is a pure virtual function and must be overridden by derived classes. Derived classes can add new menu item parts, like checkmarks and submenu arrows by overriding GetNumberOfParts, GetLabelPartIndex, GetPreferredPartSize, SetPartBounds, and DrawParts.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- MMenuItem ()
- MMenuItem (TLabel * label)
- MMenuItem (const MMenuItem &)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a new menu item with the specified label.
- Copy constructor.
Calling Context:
MMenuItem is an abstract base class, so all these constructors are called during the construction of a derived class.
Parameters:
- Takes no parameters.
- TLabel * label -The label for the new menu item. The label is adopted by the new menu item.
- const MMenuItem & -The menu item to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
~ MMenuItem ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::operator=
MMenuItem & operator =(const MMenuItem &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
Return Value:
Returns a const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::operator>>=
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & -The stream the object streams itself out to.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::operator<<=
virtual TStream & operator <<= (TStream &)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & -The stream the object streams itself in from.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws TInvalidVersionError if the object has detected an unsupportable version during the stream-in process.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::AdoptLabel
virtual void AdoptLabel (TLabel * label)
Interface Category:
API.
Purpose:
Adopts the specified label as this menu item's main label. Typically, the main label indicates the action of the menu item and is presented in the menu. This function deletes any previously adopted label.
Calling Context:
Call this function directly.
Parameters:
- TLabel * label -The label to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::OrphanLabel
virtual TLabel * OrphanLabel ()
Interface Category:
API.
Purpose:
Orphans the main label from this menu item. The caller is responsible for destroying the orphaned label.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the orphaned label. This function returns NIL if this menu item has no main label.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetKeyboardEquivalent
virtual void SetKeyboardEquivalent (const TVirtualKeyCode :: EVirtualKey keycode, const TModifierKeys & modifiers)
Interface Category:
API.
Purpose:
Specifies a command key equivalent for this menu item. For example, the key equivalent might be kVirtualFunction1 with the ControlKeyDown modifier. This keyboard accelerator does not actually work until the menu item is adopted into a menu and the menu is activated. The client must ensure that the command keys are unique. If a duplicate exists, the one that belongs to the most-recently created menu will be the one that is selected.
Calling Context:
Call this function directly.
Parameters:
- const TVirtualKeyCode :: EVirtualKey keycode -The new key code for this menu item.
- const TModifierKeys & modifiers -The modifiers for the new key code.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::HasKeyboardEquivalent
virtual bool HasKeyboardEquivalent ()
Interface Category:
API.
Purpose:
Determines whether this menu item has a command key equivalent.
Calling Context:
Called when item is adopted into a menu or when menu is activated. You can also call this member function directly.
Parameters:
Return Value:
Returns true if this menu item has a command key equivalent; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetKeyboardEquivalent
virtual bool GetKeyboardEquivalent (TVirtualKeyCode :: EVirtualKey & keycode, TModifierKeys & modifiers) const
Interface Category:
API.
Purpose:
Returns the command key information for this menu item.
Calling Context:
Called when item is adopted into a menu or when menu is activated. You can also call this member function directly.
Parameters:
- TVirtualKeyCode :: EVirtualKey & keycode -The key code for this menu item as returned by this function.
- TModifierKeys & modifiers -The modifiers for the key code as returned by this function.
Return Value:
Returns true if this menu item has a command key equivalent; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::RemoveKeyboardEquivalent
virtual void RemoveKeyboardEquivalent ()
Interface Category:
API.
Purpose:
Removes the command key equivalent from this menu item.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetSeparator
virtual void SetSeparator (const ESeparatorType type)
Interface Category:
API.
Purpose:
Specifies the type of separator to draw around this menu item. This function requires an input parameter of type ESeparatorType as defined by this class. By default, menu items have no separators.
Calling Context:
Call this function directly.
Parameters:
- const ESeparatorType type -The new separator type for this menu item.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetSeparator
virtual ESeparatorType GetSeparator () const
Interface Category:
API.
Purpose:
Determines out what kind of separator the menu draws around the menu item. This function returns a value of type ESeparatorType, which is defined by this class.
Calling Context:
Called during drawing and menu layout. You can also call this function directly.
Parameters:
Return Value:
Returns the current separator type for this menu item.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetReverseLayout
virtual void SetReverseLayout (bool reversed)
Interface Category:
API.
Purpose:
This function controls how this menu item is positioned in its owning menu. Reversed layout menu items are laid out from the end of the menu back towards the beginning. This makes it possible to create a menu bar with some items on the left and some items on the right. Reverse layout is sensitive to the layout orientation of the menu itself. The default setting is false.
Calling Context:
Call this function directly.
Parameters:
- bool reversed -The flag indicating whether to reverse the layout of this menu item in its owning menu.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::IsReverseLayout
virtual bool IsReverseLayout () const
Interface Category:
API.
Purpose:
Determines whether this menu item is laid out in the reverse direction in its owning menu.
Calling Context:
Called during menu layout and interaction. You can also call this function directly.
Parameters:
Return Value:
Returns true if this menu item is laid out in reverse; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetPreferredSize
virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const
Interface Category:
API.
Purpose:
Returns the minimum size required for this menu item. This defaults to the sum of the preferred part sizes. The maximumMainDimension input parameter is ignored.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the number of parts.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetLabelPartIndex
virtual unsigned long GetLabelPartIndex () const
Interface Category:
API.
Purpose:
Returns the index of the main label for this menu item. The index indicates the position of the main label relative to the beginning edge of the menu item. Indexes begin at 0.
Each menu item must define a main subpart--known as the label part. The columns of the menu are aligned around this part. For example, when a menu contains two items; the first item contains a checkmark subpart and the second doesn't. The first item returns 1 from this function, and the second item returns 0. This tells the menu to align subpart 1 in the first item with subpart 0 in the second item. Hence, the label part in the second item is shifted over by the size of the checkmark part so that it is aligned with the label part of the first item.
Calling Context:
Called during menu layout. You can also call this function directly.
Parameters:
Return Value:
Returns the label part index.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetPreferredPartSize
virtual TGPoint GetPreferredPartSize (unsigned long part) const
Interface Category:
API.
Purpose:
Determines the preferred size of the specified subpart. The input parameter must be between zero and the result of GetNumberOfParts. The menu uses this information to align the subparts of each menu item.
Calling Context:
Called during menu layout. You can also call this function directly.
Parameters:
- unsigned long part -The index of the subpart for which to calculate the preferred size.
Return Value:
Returns the preferred size of the specified subpart. This function can return 0, 0 if the specified subpart is invalid.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetPartBounds
virtual void SetPartBounds (unsigned long part, TGRect & bounds)
Interface Category:
API.
Purpose:
Sets the bounds of the specified subpart. Once the owning menu has gone through each item calling GetNumberOfParts, GetLabelPartIndex, and GetPreferredPartSize, and the menu has determined the maximum size of each subpart, the menu calls this function to tell the menu item the final size of each subpart. The bounds given are relative to the overall bounds of the menu item (given in SetItemBounds). So do not count on the bounds being origin based. If the bounds are larger than required for the subpart, the menu item can then decide how to position the subpart within these bounds. For text labels, it is probably best to align the bottom of the label with the bottom of the given bounds. For graphic labels like checkmarks and arrows, it is probably better to center the graphic within the part bounds.
Calling Context:
Called during menu layout. Do not call this function directly unless it is from an override of this member function in a derived class.
Parameters:
- unsigned long part -The subpart index for which to set the bounds.
- TGRect & bounds -The new bounds for that subpart.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetItemBounds
virtual void SetItemBounds (TGRect & bounds)
Interface Category:
API.
Purpose:
Sets the overall bounds of this menu item. The owning menu calls this function to tell the menu item what its overall bounds are. This can be larger that the union of the subpart bounds. For example, if this menu item only contains one part, and if other menu items contain two or three sub parts, then the item bounds of this item is stretched out to include the space reserved for the subparts of the other items. This way, the menu item knows to draw a larger highlighted background, to be the same size as the other menu items. It also means that the menu item is a larger hit target.
Calling Context:
Called during menu layout. Do not call this function directly unless it is from an override of this member function in a derived class.
Parameters:
- TGRect & bounds -The new bounds for this menu item.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetItemBounds
virtual TGRect GetItemBounds () const
Interface Category:
API.
Purpose:
Returns the item bounds last specified in SetItemBounds. MMenuItem stores the item bounds specified by the menu and provides this function so that derived classes can find out what the bounds are. This function is also used by the menu during hit testing to see if the mouse is inside the menu item.
Calling Context:
Called during menu drawing and user interaction. You can also call this function directly.
Parameters:
Return Value:
Returns the item bounds last specified in SetItemBounds.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::DrawParts
virtual void DrawParts (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws this menu item's subparts to the specified port. MMenuItem maintains an item label and an optional command key label. This function draws these labels in the appropriate places.
Calling Context:
Called during a menu draw operation. You can also call this function directly.
Parameters:
- TGrafPort & port -The port into which to draw.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::DrawItemBackground
virtual void DrawItemBackground (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws the background of the menu item. MMenuItem draws a plain background using the fill paint defined in the owning menu's MGraphic TGrafBundle. It also draws a highlighted background when the menu item is pressed.
Calling Context:
Called during a menu draw operation. You can also call this function directly.
Parameters:
- TGrafPort & port -The port into which to draw.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetOwner
virtual void SetOwner (TMenu * menu)
Interface Category:
API.
Purpose:
Notifies this menu item that it has been added to a menu. Menu items require a pointer to the owning menu so that the item can call back to the menu when it needs to redraw itself. Menu items that are views can also adopt themselves into the view hierarchy at this time.
In addition to noting the owner for future reference, this function checks to see if the owning menu now needs to update its enabled state, and updates this object's enabled state.
Calling Context:
Called during initialization and destruction of a menu and sometimes during user interaction. You should not call this function directly.
Parameters:
- TMenu * menu -The menu that now owns this menu item.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetOwner
virtual TMenu * GetOwner () const
Interface Category:
API.
Purpose:
Returns a pointer to the owning menu. MMenuItem stores the pointer to the owning menu so that derived classes have access to that pointer.
Calling Context:
Called in many different contexts whenever the menu item needs to notify the owning menu that the layout needs updating and also called during user interaction. You can also call this function directly.
Parameters:
Return Value:
Returns a pointer to the owning menu, or NIL if the menu item has not yet been adopted into a menu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetEnabled
virtual void SetEnabled (bool enabled)
Interface Category:
API.
Purpose:
Enables or disables this menu item according to the specified flag. This function changes the appearance of the menu item labels, and causes the item to be redrawn (if autoredraw is true).
Calling Context:
Called when owning menu's enabled state is changed. You can also call this function directly.
Parameters:
- bool enabled -The flag indicating whether to enable or disable this menu item. Use true to enable the menu item.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function overrides MControl's function of the same name.
Member Function: MMenuItem::SetPressed
virtual void SetPressed (bool pressed)
Interface Category:
API.
Purpose:
Presses or unpresses this menu item according to the specified flag. This function changes the background of the menu item, and causes the item to be redrawn (if autoredraw is true).
Calling Context:
Called during user interaction on the menu and also when item is orphaned from a menu. You can also call this function directly, although Animate is probably more useful.
Parameters:
- bool pressed -The flag indicating whether to press or unpress the menu item. true implies the mouse button is down while the mouse is inside the item.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function overrides MControl's function of the same name.
Member Function: MMenuItem::SetAutoRedraw
virtual void SetAutoRedraw (bool redraw)
Interface Category:
API.
Purpose:
Sets whether the menu item automatically redraws itself. The menu item redraws itself automatically when some visible attribute (such as the label) changes. Redrawing frequently can become too expensive if you are making many changes to a lot of menu items. This function is provided so that you can temporarily turn off auto-redraw while making changes to the menu items.
Calling Context:
Called when owning menu's enabled state is changed. You can also call this function directly.
Parameters:
- bool redraw -The flag indicating whether this menu item should autoredraw. By default, menu items automatically redraw.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::DoAutoRedraw
virtual bool DoAutoRedraw () const
Interface Category:
API.
Purpose:
Determines whether this menu item is set to automatically redraw itself. By default, menu items are set to redraw automatically.
Calling Context:
Called by the menu item before it performs any autoredraw operation. You can also call this function directly.
Parameters:
Return Value:
Returns true if this menu item is set to autoredraw; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::RedrawItem
virtual void RedrawItem ()
Interface Category:
API.
Purpose:
Redraws this menu item if it is currently adopted by a menu. This function does nothing if autoredraw is turned off.
Calling Context:
Called by MMenuItem and by derived classes when the menu item needs to be redrawn synchronously.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetSubMenu
virtual TMenu * GetSubMenu () const
Interface Category:
API.
Purpose:
Returns this menu item's submenu, if any. Some menu items can contain a submenu. This function is defined in MMenuItem so that clients can walk the menu hierarchy.
Calling Context:
Called during menu initialization and user interaction. You can also call this function directly.
Parameters:
Return Value:
Returns this menu item's submenu. MMenuItem's implementation of this function always returns NIL because MMenuItem does not contain a submenu. Derived classes can return a real submenu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::AdoptKeyLabel
virtual void AdoptKeyLabel (TTextLabel * label)
Interface Category:
API.
Purpose:
Adopts the specified label as this menu item's key label. This function deletes the previously adopted key label. This function does not wire up any key for command key invocation of this menu item. So this is useful if you want to handle the command key yourself.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function will be obsoleted soon.
Member Function: MMenuItem::GetCachedEnabledState
virtual bool GetCachedEnabledState () const
Interface Category:
API.
Purpose:
Gets the cached enabled state. IsEnabled can be expensive for menu item derived classes. So, rather than lots of derived classes maintaining a separate cache of the enabled state -MMenuItem does it for them.
Calling Context:
Called during initialization, drawing and user interaction. You can also call this function from a derived class.
Parameters:
Return Value:
Returns true if this menu item is enabled, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: MMenuItem::HandleEnablingChanged
virtual void HandleEnablingChanged ()
Interface Category:
API.
Purpose:
Because MMenuItem maintains the cached enabling state, this member function can be used when the enabled state of the menu item might have been changed. This member function determines whether the menu item is still enabled by calling IsEnabled. If the enabled state has changed, this function redraws the menu item (if it is visible and autoredraw is true), and calls CheckOwnerEnabling to check whether the parent submenu item (if any) also needs to handle an enabling change and be redrawn.
Calling Context:
Called by the HandleStateChanged function of derived classes, and by other functions when the enabled state might have changed. Derived classes can also call this if new situations arise where you want the enabling to be reexamined.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::HandleActivationChanged
virtual void HandleActivationChanged (bool active)
Interface Category:
API.
Purpose:
Handles the situation where the activation state of this menu item has changed. The default behavior is to clear the cached enabling state because the enabling state of the menu item might change while the owning menu is inactive; derived classes can override, for example to establish or break notification connections with their owning menus.
Calling Context:
Called by the owning menu when the menu activation is changed or when the menu items are adopted or orphaned. Derived classes can also call this if new situations arise where you want the activation state to be reexamined.
Parameters:
- bool active -Set to true to activate, false to deactivate
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::HandleAttributesChanged
virtual void HandleAttributesChanged ()
Interface Category:
API.
Purpose:
Handles the situation where the menu item's GUI attributes have changed. The default behavior is to do nothing; derived classes can override.
Calling Context:
Called when attributes (such as colors) have changed. Derived classes can also call this if new situations arise where you want the attributes to be reexamined.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::EnableLabel
virtual void EnableLabel (TLabel * label, bool enabled)
Interface Category:
API.
Purpose:
Enables or disables the specified label, based on the value of the Boolean flag. Sets the paint of a disabled label to a light shadow color calculated from the fill paint defined in the owning menu's graf bundle.
Calling Context:
Called by MMenuItem and derived classes any time the enabled state of a label needs updating. You can also call this function directly.
Parameters:
- TLabel * label -The label to be enabled or disabled.
- bool enabled -Set to true to enable, false to disable.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::Animate
virtual void Animate ()
Interface Category:
API.
Purpose:
This pure virtual function selects the menu item programmatically, as if it was selected by a mouse, and then makes the appropriate control state changes (if there is a control state).
Calling Context:
Called during user interaction to invoke the action that the menu item represents. You can also call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a pure virtual function and needs to be overridden.
Member Function: MMenuItem::SetDomainID
virtual void SetDomainID (const TMenuDomainID & id)
Interface Category:
API.
Purpose:
Sets the domain ID of this menu item. The domain ID can be used to group a set of menu items into a specific domain.
Calling Context:
Called by a parent menu during AssignDomandID. You can also call this function directly.
Parameters:
- const TMenuDomainID & id -The domain ID.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetDomainID
virtual TMenuDomainID GetDomainID () const
Interface Category:
API.
Purpose:
Gets the domain ID of this menu item.
Calling Context:
Calling by a parent menu during FindItem and FindAllItems. You can also call this function directly.
Parameters:
Return Value:
The domain ID of this menu item.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::SetID
virtual void SetID (const TMenuItemID & id)
Interface Category:
API.
Purpose:
Sets the menu item to have the given client-specified ID, which can be used to find the item again at a later date.
Calling Context:
Call this function directly.
Parameters:
- const TMenuItemID & id -The client-specified ID.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetID
virtual TMenuItemID GetID () const
Interface Category:
API.
Purpose:
Gets the ID for this menu item which was specified in a call to SetID.
Calling Context:
Calling by a parent menu during FindItem. You can also call this function directly.
Parameters:
Return Value:
The ID for this menu item.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetKeyLabel
virtual const TTextLabel * GetKeyLabel () const
Interface Category:
API.
Purpose:
Converts this menu item's command key information into a new text label. The conversion is done via the virtual keyboard so that the label matches the keyboard configuration.
Calling Context:
Called during drawing, layout and user interaction. You can also call this function directly.
Parameters:
Return Value:
Returns a pointer to the text label. This label always belongs to the menu item. This function returns NIL if this menu item has no command key equivalent.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::GetLabel
virtual const TLabel * GetLabel () const
Interface Category:
API.
Purpose:
Returns a pointer to this menu item's main label.
Calling Context:
Called during drawing, layout and user interaction. You can also call this function directly.
Parameters:
Return Value:
Returns a pointer to the main label. This function returns NIL if this menu item has no main label.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: MMenuItem::CalculateOffset
virtual TGPoint CalculateOffset (const TGRect & labelBounds, const TGRect & boundingBox, const bool centered =false, const bool oppositeJustification =false) const
Interface Category:
API.
Purpose:
Calculates where the specified label bounds should be positioned within the given bounding box. The offset is adjusted according to the control layout. For example, if it is right to left, the offset is adjusted so that the label is drawn right-most within its bounding box.
Calling Context:
Called during layout. You can also call this function directly.
Parameters:
- const TGRect & labelBounds -The bounds of the label.
- const TGRect & boundingBox -The bounds of the subpart to which the label belongs.
- const bool centered =false -If set to true, causes the function to return the offset that centers the label bounds within the bounding box.
- const bool oppositeJustification =false -If set to true, causes the opposite layout of the label bounds in the bounding box. For example, if the item layout is kLeftToRight, it does kRightToLeft. This flag has no effect if centered =true.
Return Value:
The preferred offset.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This is a protected function.
Member Function: MMenuItem::GetNumberOfParts
virtual unsigned long GetNumberOfParts () const
Interface Category:
API.
Purpose:
Returns the number of parts in this menu item. Menu items can contain any num ber of parts, which are automatically aligned by the owning menu. The menu calls this function to determine how many parts a given menu item actually contains.
Calling Context:
Called by the owning menu during layout negotiations.
Parameters:
Return Value:
Returns the number of parts.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.