Class: TMomentaryMenuItem

Declaration: MenuControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MMenuItem, MDelegatingMomentaryControl

Inherited By:

TSliderMenuItem TSubMenuItem

Purpose:

TMomentaryMenuItem derives from MMenuItem and MDelegatingMomentaryControl and is a menu item that delegates to an adopted momentary control state. This class does not add any more subparts to the ones already provided by MMenuItem.

Instantiation:

Usually allocated on the heap so that it can be adopted into a menu.

Deriving Classes:

It is unlikely that you will need to derive from this class. One possibility is that you might want to add a new menu item subpart like a submenu arrow, by overriding GetNumberOfParts, GetLabelPartIndex, GetPreferredPartSize, SetPartBounds, and DrawParts or you might want to change the behavior of the interactor by overriding CreateInteractor to return your own interactor. Derived classes should not attempt to change or add to the type of control state that is adopted by this class, namely MMomentaryControlState.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TMomentaryMenuItem::~TMomentaryMenuItem

virtual ~ TMomentaryMenuItem ()

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

TMomentaryMenuItem & operator =(const TMomentaryMenuItem &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TMomentaryMenuItem & -The object to be copied.

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: TMomentaryMenuItem::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: TMomentaryMenuItem::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: TMomentaryMenuItem::GetNumberOfParts

virtual unsigned long GetNumberOfParts () const

Interface Category:

API.

Purpose:

Returns the number of parts in this menu item. This function simply calls MMenuItem::GetNumberOfParts.

Calling Context:

Called by the owning menu during layout negotiations.

Parameters:

Takes no parameters.

Return Value:

Returns the number of parts.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::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 function simply delegates to MMenuItem.

Calling Context:

Called during menu layout. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the label part index.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::GetPreferredPartSize

virtual TGPoint GetPreferredPartSize (unsigned long part) const

Interface Category:

API.

Purpose:

Determines the preferred size of the specified subpart. This function simply delegates to MMenuItem.

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.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::SetPartBounds

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

Interface Category:

API.

Purpose:

Sets the bounds of the specified subpart. This function simply delegates to MMenuItem.

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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::DrawParts

virtual void DrawParts (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this menu items subparts to the specified port. This function simply delegates to MMenuItem.

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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::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 creates a TMomentaryControlInteractor.

Calling Context:

Called during user interaction. You can also call this function directly.

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:

Overrides the inherited MControl function.

Member Function: TMomentaryMenuItem::SetPressed

virtual void SetPressed (bool pressed)

Interface Category:

API.

Purpose:

Presses or unpresses this menu item according to the specified flag. This function simply delegates to MMenuItem.

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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines whether this menu item is enabled.

Calling Context:

Called by owning menu to determine if user interaction is allowed on the item. Also queried again when the item receives a change notification from the state. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the logical AND of the inherited MControl::IsEnabled and the MDelegatingMomentaryControl::IsEnabled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl and MDelegatingMomentaryControl functions.

Member Function: TMomentaryMenuItem::SetEnabled

virtual void SetEnabled (bool enabled)

Interface Category:

API.

Purpose:

Enables or disables this menu item according to the specified flag. The menu item cannot be enabled if MDelegatingMomentaryControl returns false from IsEnabled. So, clients should call IsEnabled after calling this function to determine if the item is enabled.

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 the menu item. true enables the menu item.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Update the menu item according to the new results of IsEnabled and GetLabel from the adopted control state.

Calling Context:

Called by a notification from the state class. You can also call this function directly if you want the state of the menu item to be re-examined.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TMomentaryMenuItem::HandleActivationChanged

virtual void HandleActivationChanged (bool active)

Interface Category:

API.

Purpose:

Handles the situation where the activation state of this menu item has changed. If the menu item is to be activated, this function establishes a notification connection using the interests returned from the adopted momentary control state. Similarly, the notification connection is broken if the menu item is deactivated.

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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::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:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Sets this momentary menu item to be visible or invisible. Invalidates the layout of the menu that owns this menu item, so that it is redrawn.

Calling Context:

Call this function directly.

Parameters:

bool visible -The flag indicating whether this menu item should become visible or invisible--true makes it visible; false makes it invisible.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryMenuItem::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Determines whether this menu item is visible.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this menu item is visible, false if it's not.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryMenuItem::GetLabel

virtual const TLabel * GetLabel () const

Interface Category:

API.

Purpose:

Resolve the ambiguity between MMenuItem::GetLabel and MDelegatingMomentaryControl::GetLabel. It returns MMenuItem::GetLabel if the result is not NIL, otherwise it returns MDelegatingMomentaryControl::GetLabel.

Calling Context:

Called during menu drawing, layout and user interaction. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::SetOwner

virtual void SetOwner (TMenu * owner)

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. This function delegates to MMenuItem.

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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::Animate

virtual void Animate ()

Interface Category:

API.

Purpose:

Selects the menu item programmatically, as if it was selected by a mouse, and then makes the appropriate control state changes.

Calling Context:

Called during user interaction to invoke the action that the menu item represents. You can also 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:

Overrides the inherited MMenuItem function.

Member Function: TMomentaryMenuItem::TMomentaryMenuItem

TMomentaryMenuItem ()
TMomentaryMenuItem (TLabel * adoptedLabel)
TMomentaryMenuItem (MMomentaryControlState * adoptedDelegate, TLabel * adoptedLabel =NIL)
TMomentaryMenuItem (const TMomentaryMenuItem &)

Interface Category:

API.

Purpose:

Default constructor.
Constructs a momentary menu item that adopts the specified label.
Constructs a momentary menu item that adopts the specified control state and label.
Copy constructor. If the control being copied had adopted its state object, then the state object is cloned; otherwise, a pointer to the state object is copied and marked as not adopted. Non-adopted state objects are not flattened and resurrected.

Calling Context:

Called by the stream-in operators and derived classes.
Call this function directly.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
TLabel * adoptedLabel -The label to be adopted for the new menu item.
MMomentaryControlState * adoptedDelegate -The control state to which to delegate. This is adopted.
TLabel * adoptedLabel =NIL -The label to be adopted for the new menu item.
const TMomentaryMenuItem & -The menu item to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMomentaryMenuItem::Select

virtual void Select ()

Interface Category:

API.

Purpose:

This is the member function that is called to invoke the action that is represented by the menu item. It calls MDelegatingMomentaryControl::Select which in turn calls Select on the adopted control state.

Calling Context:

Called during mouse up over the menu item or during key down of the item's keyboard equivalent.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

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