Class: TPopUpSubMenuItem

Declaration: PopUpMenus.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSubMenuItem

Inherited By:

None.

Purpose:

TPopUpSubMenuItem is provided for advanced use only. It derives from TSubMenuItem and is used internally by TPopUpMenu. TPopUpMenuItem keeps track of the last item that was selected from its submenu, and copies the label from this item. For this to work correctly, the submenu adopted into this item should contain TPopUpItems only. These TPopUpItems tell the TPopUpSubMenuItem when they have been selected. TPopUpSubMenuItem also changes the pop-up behavior of TSubMenuItem by overriding the GetPopUpBounds function to return a different bounds. TPopUpSubMenuItem aligns the submenu so that the currently selected TPopUpItem in the submenu sits directly on top of the TPopUpSubMenuItem. Clients of a TPopUpMenu would not need to call the member functions of TPopUpSubMenuItem directly. This documentation is provided for developers who want to derive classes from TPopUpMenu. See the description of the TPopUpItem class for additional relevant information.

Instantiation:

This class is usually allocated on the heap so that it can be adopted into a menu.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPopUpSubMenuItem::TPopUpSubMenuItem

TPopUpSubMenuItem ()
TPopUpSubMenuItem (TMenu * submenu)
TPopUpSubMenuItem (const TPopUpSubMenuItem &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TPopUpSubMenuItem and initializes its submenu to the one specified.
Copy constructor.

Calling Context:

Called by the stream-in operators.
You can call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
TMenu * submenu -The initial submenu for the new item.
const TPopUpSubMenuItem & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::~TPopUpSubMenuItem

virtual ~ TPopUpSubMenuItem ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::operator=

TPopUpSubMenuItem & operator =(const TPopUpSubMenuItem &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPopUpSubMenuItem & -The object to be copied, appearing to the right of the equals sign.

Return Value:

A non-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: TPopUpSubMenuItem::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & destination -The output stream into which the class writes itself.

Return Value:

TStream & -The stream the object writes itself to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The input stream from which the class extracts the contents of its members.

Return Value:

TStream & -The stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if it encounters an object whose version number indicates it cannot be streamed in. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::SetSelectedItem

virtual void SetSelectedItem (TPopUpItem * item)

Interface Category:

API.

Purpose:

Selects the specified pop-up item and updates the submenu item's label.

Calling Context:

The framework calls this function during mouse interaction on this item. You do not need call this function directly; for programmatic selection of an item use TPopUpMenu::SetSelectedItem.

Parameters:

TPopUpItem * item -The pop-up item to select.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The converse of this function is GetSelectedItem.

Member Function: TPopUpSubMenuItem::GetSelectedItem

virtual TPopUpItem * GetSelectedItem () const

Interface Category:

API.

Purpose:

Reports which item is currently selected.

Calling Context:

You do not need call this function directly; to programmatically discover which item is selected, use TPopUpMenu::GetSelectedItem.

Parameters:

Takes no parameters.

Return Value:

TPopUpItem * -The currently selected pop-up item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is the converse of SetSelectedItem.

Member Function: TPopUpSubMenuItem::GetNumberOfParts

virtual unsigned long GetNumberOfParts () const

Interface Category:

API.

Purpose:

Returns the number of parts in this menu item. This function adds one to the number of subparts returned from MMenuItem. The additional part is the submenu arrow.

Calling Context:

Called during menu layout. You do not need to call this function directly yourself; the framework calls it for you.

Parameters:

Takes no parameters.

Return Value:

unsigned long -The number of parts.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::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. This class reverses the label part and the submenu arrow.

Calling Context:

Called during menu layout. You do not need to call this function directly yourself; the framework calls it for you.

Parameters:

Takes no parameters.

Return Value:

unsigned long -The label part index number.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::GetPreferredPartSize

virtual TGPoint GetPreferredPartSize (unsigned long part) const

Interface Category:

API.

Purpose:

Determines the preferred size of the specified subpart.

Calling Context:

Called during menu layout. You do not need to call this function directly yourself; the framework calls it for you.

Parameters:

unsigned long part -The index of the subpart for which to calculate the preferred size.

Return Value:

TGPoint -The preferred size of the specified subpart.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::SetPartBounds

virtual void SetPartBounds (unsigned long part, TGRect & bounds)

Interface Category:

API.

Purpose:

Sets the bounds of the specified subpart.

Calling Context:

Called during menu layout. You do not need to call this function directly yourself; the framework calls it for you.

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: TPopUpSubMenuItem::GetPopUpBounds

virtual TGRect GetPopUpBounds () const

Interface Category:

API.

Purpose:

Reports where the submenu should be popped open. The location of the pop-up menu depends on the layout of the menu that owns this item, the bounds of the screen, the preferred size of the submenu and whether or not the pop-up is reversed. This function may also decide to reverse the pop-up direction if it fits better on the other side of the item. The pop-up bounds are returned in global coordinates. The default behavior supplied by TPopUpSubMenuItem aligns the popped-up menu so that the current selection appears directly on top of this TPopUpSubMenuItem.

Calling Context:

Called when the user selects this submenu item. You do not need to call this function directly yourself; the framework calls it for you.

Parameters:

Takes no parameters.

Return Value:

TGRect -The bounds indicating where the submenu should be popped up.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpSubMenuItem::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Find out whether or not the submenu item is enabled.

Calling Context:

This member function is called during user interaction and drawing. You can also call this member function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if there is at least one enabled item in the submenu or the submenu is empty.

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.