Class: TEmbedderMenuItem

Declaration: MenuControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MMenuItem

Inherited By:

None.

Purpose:

TEmbedderMenuItem derives from MMenuItem and allows a menu to be added to another menu as a menu item. Normally, you'll use TSubMenuItem for attaching submenus to another menu. However, you'll use TEmbedderMenu for creating complex layouts of menu items. For example, you might define a TEmbeddableMenu for a 12-color palette with left-to-right layout and a maximum items constraint of 4. This produces a 4x3 grid of menu items. You can then add this into a normal top-to-bottom layout menu together with a normal momentary menu item that has the label "Other...". The embedded menu always contains a single subpart, which is the embedded menu itself. For this reason, TEmbeddableMenu overrides the MMenuItem layout and draw functions to disable the normal subparts provided by MMenuItem. The embedded menu is adopted as a View system child of the menu that owns this item.

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.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TEmbedderMenuItem::TEmbedderMenuItem

TEmbedderMenuItem ()
TEmbedderMenuItem (TMenu * menuToAdopt)
TEmbedderMenuItem (const TEmbedderMenuItem & copy)

Interface Category:

API.

Purpose:

Default constructor.
Constructs an embedder menu item that adopts the specified menu.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
TMenu * menuToAdopt -The menu to adopt.
const TEmbedderMenuItem & copy -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: TEmbedderMenuItem::~TEmbedderMenuItem

virtual ~ TEmbedderMenuItem ()

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

TEmbedderMenuItem & operator =(const TEmbedderMenuItem &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TEmbedderMenuItem & -The source object for the assignment.

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

virtual unsigned long GetNumberOfParts () const

Interface Category:

API.

Purpose:

Returns the number of parts in this menu item. TEmbedderMenuItem has a single part --the menu itself --and so this function always returns 1.

Calling Context:

Called by the owning menu during layout negotiations.

Parameters:

Takes no parameters.

Return Value:

Returns the number of parts. This function always returns 1.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TEmbedderMenuItem::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. The TEmbedderMenuItem itself is the first and only part in the menu; therefore, this function always returns 0.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns the label part index, which is always 0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TEmbedderMenuItem::GetPreferredPartSize

virtual TGPoint GetPreferredPartSize (unsigned long part) const

Interface Category:

API.

Purpose:

Determines the preferred size of the specified subpart. If the specified part is 0, this function returns the preferred size of the menu; otherwise, it returns TGPoint::kOrigin.

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

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

Interface Category:

API.

Purpose:

Sets the bounds of the embedded menu.

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. Any value other than 0 is ignored.
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: TEmbedderMenuItem::SetItemBounds

virtual void SetItemBounds (TGRect & bounds)

Interface Category:

API.

Purpose:

Sets the overall bounds of the embedded menu item. The embedded menu is translated so that it appears within these 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:

TGRect & bounds -The item bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TEmbedderMenuItem::DrawParts

virtual void DrawParts (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this menu item's subparts to the specified port. This function does nothing because the embedded menu is a view and is drawn by the View system.

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: TEmbedderMenuItem::DrawItemBackground

virtual void DrawItemBackground (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws this menu item's background to the specified port. This function does nothing, because the embedded menu is a view and is drawn by the View system.

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: TEmbedderMenuItem::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 the embedded menu's interactor. This way the user can interact on the menu items in the embedded menu, just like any other menu items in the owning menu.

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: TEmbedderMenuItem::SetOwner

virtual void SetOwner (TMenu * menu)

Interface Category:

API.

Purpose:

Establishes the owning menu for this menu item. This function is used to hook the embedded menu into a view hierarchy. This function delegates to MMenuItem, then orphans the embedded menu from its current parent (if any), and has the embedded menu adopted into the new parent view. It also calls SetVisibility(true) on the embedded menu.

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 new owner for the embedded menu.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEmbedderMenuItem::SetEnabled

virtual void SetEnabled (bool enabled)

Interface Category:

API.

Purpose:

Enables or disables this menu according to the specified flag by enabling or disabling all the menu items within this menu. Disabling always disables an item, but an item can only be enabled if the control state adopted into 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. 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: TEmbedderMenuItem::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Called by owning menu to determine if user interaction is allowed on the item. You can also call this function directly.

Calling Context:

Called to see if the user interaction is valid.

Parameters:

Takes no parameters.

Return Value:

Returns true if this embedded menu is enabled; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TEmbedderMenuItem::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Determines whether this control is visible.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is visible, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMenuItem function.

Member Function: TEmbedderMenuItem::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Sets this control to be visible or invisible. Invalidates the layout, so it is redrawn.

Calling Context:

Call this function directly.

Parameters:

bool visible -The flag indicating whether this control should become visible or invisible--true makes the control 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 MMenuItem function.

Member Function: TEmbedderMenuItem::SetControlLayout

virtual void SetControlLayout (ELayout layout)

Interface Category:

API.

Purpose:

Sets the layout of the menu item. Because there is only one subpart to an embedded menu, which is the embedded menu itself, this function has no effect.

Calling Context:

Called by the owning menu during a layout operation.

Parameters:

ELayout layout -The new control layout for this embedded menu.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TEmbedderMenuItem::GetControlLayout

virtual ELayout GetControlLayout () const

Interface Category:

API.

Purpose:

Returns the current control layout for this embedded menu. Because there is only one subpart to an embedded menu, which is the embedded menu itself, an embedded menu's control layout has no effect.

Calling Context:

Called by the owning menu during a layout operation.

Parameters:

Takes no parameters.

Return Value:

Returns the current control layout for this embedded menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TEmbedderMenuItem::AdoptEmbeddedMenu

virtual void AdoptEmbeddedMenu (TMenu * menuToAdopt)

Interface Category:

API.

Purpose:

Adopts the specified embedded menu. First orphans the previously adopted embedded menu from its parent.

Calling Context:

Call this function directly.

Parameters:

TMenu * menuToAdopt -The menu to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEmbedderMenuItem::GetSubMenu

virtual TMenu * GetSubMenu () const

Interface Category:

API.

Purpose:

Returns this menu item's submenu--itself. This function is provided so that a client can walk all menus in a given menu hierarchy. Because the TEmbeddableMenu is a menu, it returns a pointer to itself.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the embeddable menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEmbedderMenuItem::Animate

virtual void Animate ()

Interface Category:

API.

Purpose:

Does nothing; there is no special selection feedback for this type of menu item.

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: TEmbedderMenuItem::HandleAttributesChanged

virtual void HandleAttributesChanged ()

Interface Category:

API.

Purpose:

Handles the situation where the menu item's GUI attributes have changed. Calls HandleAttributesChanged on the embedded menu.

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: TEmbedderMenuItem::HandleActivationChanged

virtual void HandleActivationChanged (bool active)

Interface Category:

API.

Purpose:

Handles the situation where the activation state of this menu item has changed. Calls SetActive on the embedded menu.

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.

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