Class: TPopUpItem

Declaration: PopUpMenus.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TBooleanMenuItem

Inherited By:

None.

Purpose:

TPopUpItem is a special TBooleanMenuItem that draws a down pointing arrow instead of a check mark. It also has special knowledge of the fact that it is contained in a TPopUpMenu so that it can help participate in ensuring that only one TPopUpItem is set to the kTrue state at any given time. Note that a TPopUpMenu is a view that contains one TMenu and this TMenu contains a TPopUpSubMenuItem. This is what is normally visible. When the user clicks on this TPopUpSubMenuItem a submenu containing all TPopUpItems is displayed. The when the submenu is popped up it is aligned so that the currently selected TPopUpItem sits directly on top of the TPopUpSubMenuItem. Therefore we want the TPopUpItem to look identical to the TPopUpSubMenuItem to give the user the illusion that the menu sprouted up and down around the TPopUpSubMenuItem and this is why the TPopUpItem draws a down pointing arrow instead of a tick mark. Clients of a TPopUpMenu should not need to call the member functions of TPopUpItem. The TPopUpMenu API should be sufficient for most needs. This documentation is provided for developers who need to derive classes from TPopUpItem.

Instantiation:

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

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPopUpItem::TPopUpItem

TPopUpItem ()
TPopUpItem (TLabel * adoptedLabel)
TPopUpItem (MBooleanControlState * adoptedState, TLabel * adoptedLabel =NIL)
TPopUpItem (const TPopUpItem &)

Interface Category:

API.

Purpose:

Default constructor.
Constructor with the label for the item.
Constructor with the label for the item and a control state for it.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
TLabel * adoptedLabel -The label for the item.
MBooleanControlState * adoptedState -The control state for the item.
TLabel * adoptedLabel =NIL -The label for the item.
const TPopUpItem & -The source object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::~TPopUpItem

virtual ~ TPopUpItem ()

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: TPopUpItem::operator=

TPopUpItem & operator =(const TPopUpItem &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPopUpItem & sourceItem -The object to be copied.

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: TPopUpItem::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 streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::SetPressed

virtual void SetPressed (bool pressed)

Interface Category:

API.

Purpose:

Presses or unpresses this menu item according to the specified flag, thereby providing feedback to the user as an item is selected.

Calling Context:

The framework calls this function during user interaction on the menu; You don't have to call it yourself.

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:

None.

Member Function: TPopUpItem::SetBooleanState

virtual void SetBooleanState (MBooleanControlState :: EBooleanState newState)

Interface Category:

API.

Purpose:

Sets the Boolean state for this menu item indicating that the item is selected by user. This function maintains the current selection.

Calling Context:

The framework calls this function during user interaction on the menu; You don't have to call it yourself.

Parameters:

MBooleanControlState :: EBooleanState newState -The new state for this menu item.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::SetPartBounds

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

Interface Category:

API.

Purpose:

Sets the bounds of the specified subpart.

Calling Context:

Called by the framework during menu layout; you do not need to call this function directly yourself.

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: TPopUpItem::DrawParts

virtual void DrawParts (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this menu item's subparts to the specified port. This function draws the arrow head graphic in the correct orientation, and then delegates to MMenuItem to draw the item label.

Calling Context:

Called by the framework or by a derived class during a draw operation; you do not need to call this function directly yourself.

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: TPopUpItem::CreateInteractor

virtual TInteractor * CreateInteractor (const TGPoint & pt)

Interface Category:

API.

Purpose:

Creates an interactor used to interpret user gestures on this menu item. This is an MControl override that is used by the menu owning this menu item to interact with the menu item. The interactor returned from this function must know how to translate user input, in the context of menu interaction, into state changes on the menu item. This function returns a special interactor, similar to the one returned by radio buttons in a radio button group, so that the user can not turn off the current selection by merely choosing it again.

Calling Context:

Called by the framework during user interaction. You should not need to call this function unless you are creating a compound interaction involving a popup item.

Parameters:

const TGPoint & pt -The mouse location of the event that started the user interaction.

Return Value:

Returns the newly created interactor, or NIL if no interactor is appropriate. If no interactor is returned, the owning menu simply calls SetPressed(true) when the mouse is inside the item and SetPressed(false) when the mouse moves outside the item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::SetPopUpSubMenuItem

virtual void SetPopUpSubMenuItem (TPopUpSubMenuItem * submenuitem)

Interface Category:

API.

Purpose:

Stores a pointer to the submenu item which contains a submenu which will contain this pop-up menu item. The TPopUpItem and the TPopUpSubMenuItem work together to maintain the current selection.

Calling Context:

The framework calls this function during initialization and when the item is adopted into a pop-up menu; you should not call it yourself.

Parameters:

TPopUpSubMenuItem * submenuitem -The pop-up menu item.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::Animate

virtual void Animate ()

Interface Category:

API.

Purpose:

This function allows programmatic selection of the item -as if the user clicked on the item with a pointing device.

Calling Context:

The framework calls this function during command key invocation of the menu item; You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::HandleAttributesChanged

virtual void HandleAttributesChanged ()

Interface Category:

API.

Purpose:

Adjusts the item in response to a change in look-attributes.

Calling Context:

The framework calls this function after a look-attribute is changed; You do not need to call it directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default behavior supplied by TPopUpItem is to do nothing. You would override this function if you wanted a class derived from TPopUpItem to exhibit some particular response to a change in look-attribute.

Member Function: TPopUpItem::GetGraphicBounds

virtual TGRect GetGraphicBounds () const

Interface Category:

API.

Purpose:

This is an override of the TBooleanMenuItem function that returns the bounds of the arrow that is displayed in the currently selected TPopUpItem.

Calling Context:

This function is called by the framework when laying out the items.

Parameters:

Takes no parameters.

Return Value:

The bounds of the graphic displayed in the item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpItem::AdoptLabel

virtual void AdoptLabel (TLabel * label)

Interface Category:

API.

Purpose:

Replace the current label with the new label passed as an argument.

Calling Context:

Call this function directly.

Parameters:

TLabel * label -The new label to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any previously adopted label will be deleted.

Click the icon to mail questions or corrections about this material to Taligent personnel.