Class: TBooleanMenuItem

Declaration: MenuControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MMenuItem, MDelegatingBooleanControl

Inherited By:

TPopUpItem

Purpose:

TBooleanMenuItem derives from MMenuItem and MDelegatingBooleanControl and implements a menu item that delegates to an adopted Boolean control state. This class adds a checkmark subpart to the subparts 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. One possibility is that you might want to add a new menu item subpart or rearrange the existing parts 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 MBooleanControlState.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations

The member functions GetBooleanGraphic and CreateBooleanGraphic are obsolete, and are no longer used by the framework.

Member Function: TBooleanMenuItem::TBooleanMenuItem

TBooleanMenuItem ()
TBooleanMenuItem (TLabel * label)
TBooleanMenuItem (MBooleanControlState * delegate, TLabel * label =NIL)
TBooleanMenuItem (const TBooleanMenuItem &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a menu item with the specified label.
Creates a menu item with the specified control state and label.
Copy constructor.

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 * label -The label for the menu item.
MBooleanControlState * delegate -The control state to which to delegate.
TLabel * label =NIL -The label for the menu item.
const TBooleanMenuItem & -The menu item to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanMenuItem::~TBooleanMenuItem

virtual ~ TBooleanMenuItem ()

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

TBooleanMenuItem & operator =(const TBooleanMenuItem &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TBooleanMenuItem & -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: TBooleanMenuItem::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: TBooleanMenuItem::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. Not multithread safe..

Other Considerations:

None.

Member Function: TBooleanMenuItem::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 for the Boolean checkmark graphic that is used to display the Boolean state.

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: TBooleanMenuItem::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 adds one to the label part index returned from MMenuItem. This causes the MMenuItem subparts to be pushed over by one subpart to allow room for the Boolean checkmark graphic.

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: TBooleanMenuItem::GetPreferredPartSize

virtual TGPoint GetPreferredPartSize (unsigned long part) const

Interface Category:

API.

Purpose:

Determines the preferred size of the specified subpart. If the part index is for the checkmark, this function returns the preferred size of the Boolean checkmark graphic. If the part index is not for the checkmark, then it returns the preferred size from MMenuItem (being careful to adjust the part number so that it matches what MMenuItem expects to get).

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: TBooleanMenuItem::SetPartBounds

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

Interface Category:

API.

Purpose:

Sets the bounds of the specified subpart. If the part index is for the checkmark, this function stores the new bounds for the checkmark. Otherwise, this function adjusts the part index and passes the bounds 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 the specified 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: TBooleanMenuItem::DrawParts

virtual void DrawParts (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this menu items subparts to the specified port. This function draws the checkmark (if the Boolean state is set), and then delegates to MMenuItem to draw the item label.

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: TBooleanMenuItem::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 TBooleanControlInteractor.

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: TBooleanMenuItem::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 MDelegatingBooleanControl functions.

Member Function: TBooleanMenuItem::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: TBooleanMenuItem::SetBooleanState

virtual void SetBooleanState (MBooleanControlState :: EBooleanState newState)

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 MDelegatingBooleanControl::SetBooleanState which in turn calls SetBooleanState 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:

MBooleanControlState :: EBooleanState newState -The new state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MDelegatingBooleanControl function.

Member Function: TBooleanMenuItem::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: TBooleanMenuItem::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Update the menu item according to the new results of IsEnabled, GetBooleanState 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: TBooleanMenuItem::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 Boolean 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: TBooleanMenuItem::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: TBooleanMenuItem::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, setting the Boolean state to true if it was false, and to false if it was true.

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: TBooleanMenuItem::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Sets this Boolean 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: TBooleanMenuItem::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: TBooleanMenuItem::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: TBooleanMenuItem::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. This function delegates to MMenuItem, then calls MMenuItem::EnableLabel on the graphic used to indicate the Boolean state, to enable or disable the graphic, based on the value returned by IsEnabled.

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: TBooleanMenuItem::GetGraphicBounds

virtual TGRect GetGraphicBounds () const

Interface Category:

API.

Purpose:

Returns the bounds of the check mark that is displayed when the state of the item is set to kTrue.

Calling Context:

Called during menu layout.

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.

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