Class: TMenuWindow

Declaration: MenuWindow.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TWindow

Inherited By:

None.

Purpose:

TMenuWindow is the window that is used to present a desktop menu. It provides special functions for hiding all torn off submenus and for disabling the command keys for all the submenus when the window is disabled or hidden, and for re-showing the torn off menus and re-enabling the command keys when the window is shown and enabled.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive classes from TMenuWindow if you want to add functionality. For example, the provided derived class TActionMenuWindow adds the MActionTarget mixin so that it can redirect actions that have moved up the menu hierarchy to some other target.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TMenuWindow::TMenuWindow

TMenuWindow ()
TMenuWindow (TMenu * adoptedMenu, const TText & title, bool hasCloseBox =false)
TMenuWindow (TMenu * adoptedMenu, TLabel * adoptedTitle, bool hasCloseBox =false)
TMenuWindow (const TMenuWindow &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a menu window that adopts the specified menu and has the specified title.
Creates a menu window that adopts the specified menu and label.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to create a menu window that adopts the specified menu and has the specified title.
Called to create a menu window that adopts the specified menu and label.
Called to copy an object.

Parameters:

Takes no parameters.
TMenu * adoptedMenu -The menu to adopt.
const TText & title -The title to put in the menu title bar.
bool hasCloseBox =false -Specifies whether or not the menu has a close box.
TMenu * adoptedMenu -The menu to adopt.
TLabel * adoptedTitle -The label to adopt.
bool hasCloseBox =false -Specifies whether or not the menu has a close box.
const TMenuWindow & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::~TMenuWindow

virtual ~ TMenuWindow ()

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

TMenuWindow & operator =(const TMenuWindow &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TMenuWindow & -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: TMenuWindow::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -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: TMenuWindow::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -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: TMenuWindow::AdoptMenu

virtual TMenu * AdoptMenu (TMenu * menu, const TText & title)
virtual TMenu * AdoptMenu (TMenu * menu, TLabel * title)
virtual TMenu * AdoptMenu (TMenu * menu)

Interface Category:

API.

Purpose:

Installs the specified menu into the window, and returns the old menu, if any. Gives the menu the specified title. If the given menu already contains a title bar, the title bar label will be replaced with one containing the given text.
Installs the specified menu into the window, and returns the old menu, if any. Gives the menu the specified label. If the given menu already contains a title bar, the title bar label will be replaced with the specified label.
Installs the specified menu into the window, and returns the old menu, if any.

Calling Context:

Called to install the specified menu and give it the specified title.
Called to install the specified menu and give it the specified label.
Called to install the specified menu. It you want to create your own title item, or re-adopt a previously orphaned menu, use this function.

Parameters:

TMenu * menu -The menu to adopt and install.
const TText & title -The title to give to the menu.
TMenu * menu -The menu to adopt and install.
TLabel * title -The label to give to the menu.
TMenu * menu -The menu to adopt and install.

Return Value:

A pointer to the old menu, if any.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::GetMenu

virtual TMenu * GetMenu () const

Interface Category:

API.

Purpose:

Returns a pointer to the menu installed in this window. This menu is basically the same as the menu passed in to be adopted in either the constructor, or a call to AdoptMenu, except that those functions modify the menu to contain a new item at the beginning: a menu title bar. If you make changes to the menu returned from GetMenu, be sure to call SetWindowSize with the menu's new preferred size.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the menu installed in this window.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::OrphanMenu

virtual TMenu * OrphanMenu ()

Interface Category:

API.

Purpose:

Orphans and returns a pointer to the menu installed in this window. This menu is basically the same as the menu passed in to be adopted in either the constructor, or a call to AdoptMenu, except that those functions modify the menu to contain a new item at the beginning: a menu title bar.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the orphaned menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::SetColor

virtual void SetColor (const TColor & color)

Interface Category:

API.

Purpose:

Assigns the specified color to the menu bar.

Calling Context:

Call this function directly.

Parameters:

const TColor & color -The color to assign to the menu bar.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::GetColor

void GetColor (TColor & color) const

Interface Category:

API.

Purpose:

Returns the current menu bar color.

Calling Context:

Call this function directly.

Parameters:

TColor & color -Receives the current menu bar color.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::SetTitle

virtual void SetTitle (TText & title)

Interface Category:

API.

Purpose:

Gives the menu the specified title. Replaces the previous title, if any.

Calling Context:

Call this function directly.

Parameters:

TText & title -The title to give to the menu.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::AdoptTitle

virtual void AdoptTitle (TLabel * title)

Interface Category:

API.

Purpose:

Adopts the specified title label, installing it in the menu bar. Replaces the old label, if any.

Calling Context:

Call this function directly.

Parameters:

TLabel * title -The title label to install in the menu title bar.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::CopyTitle

virtual TLabel * CopyTitle () const

Interface Category:

API.

Purpose:

Returns a copy of the menu title label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to a copy of the menu title label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::SetWindowSize

virtual void SetWindowSize (const TGPoint &)

Interface Category:

API.

Purpose:

Sets the size of the window, and of the menu installed in it.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The new width and height for the window's bounding box. The x-coordinate of the point is the width, and the y-coordinate of the point is the height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TWindow function.

Member Function: TMenuWindow::SetHasCloseBox

virtual void SetHasCloseBox (bool hasCloseBox)

Interface Category:

API.

Purpose:

Specifies whether or not the menu window has a close box, according to the specified input parameter.

Calling Context:

Clients can call to modify the indication as to whether or not the menu window has a close box, after the window has already been constructed.

Parameters:

bool -If true, the window has a close box. If false, it does not.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::HasCloseBox

virtual bool HasCloseBox () const

Interface Category:

API.

Purpose:

Determines if the window has a close box or not.

Calling Context:

Derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the window has a close box, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMenuWindow::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Tells whether or not the menu window needs to be clipped when drawing this view.

Calling Context:

Called by the View system to determine whether or not to clip when drawing this view.

Parameters:

Takes no parameters.

Return Value:

Returns true if the menu window needs to be clipped, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited TView function.

Member Function: TMenuWindow::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws a background fill for the menu.

Calling Context:

Called by the View system to draw the contents of this view.

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:

This protected function overrides the inherited TView function.

Member Function: TMenuWindow::HandleShow

virtual void HandleShow ()

Interface Category:

API.

Purpose:

Makes the menu window visible, and activates the menu.

Calling Context:

Called by TWindow::Show.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::HandleHide

virtual void HandleHide ()

Interface Category:

API.

Purpose:

Makes the menu window invisible and deactivates the menu.

Calling Context:

Called by the TWindow Hide function.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::HandleEnable

virtual void HandleEnable ()

Interface Category:

API.

Purpose:

Enables the menu window.

Calling Context:

Called by TWindow::Enable.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::HandleDisable

virtual void HandleDisable ()

Interface Category:

API.

Purpose:

Disables the menu window.

Calling Context:

Called by TWindow::Disable.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Handles a change to the allocated area for the menu, keeping the window bounds in sync with the menu bounds.

Calling Context:

Called when there is a change to the allocated area of the menu.

Parameters:

const TGArea & newArea -A reference to the new TGArea object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TView function.

Member Function: TMenuWindow::SetChildAllocatedArea

virtual void SetChildAllocatedArea (TView &, const TGArea &)

Interface Category:

API.

Purpose:

Sets the area that's allocated to the child menu to the specified area, to keep the menu bounds in sync with the window bounds. The area is in menu-relative coordinates.

Calling Context:

Called by the View system.

Parameters:

TView & -The view.
const TGArea & -The area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::SetChildAllocatedAreaAndLocation

virtual void SetChildAllocatedAreaAndLocation (TView &, const TGArea &, const TGPoint &)

Interface Category:

API.

Purpose:

Sets the area that's allocated to the child menu to the specified area, to keep the menu bounds in sync with the window bounds. The area is in the menu's parent's (the window's) coordinate system. Also sets the menu's location.

Calling Context:

Called to keep the menu bounds in sync with the window bounds.

Parameters:

TView & -The view.
const TGArea & -The new area.
const TGPoint & -Specifies the top left corner of the child's allocated area in the parent (the menu window), specified in the parent's coordinate system.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TWindow function.

Member Function: TMenuWindow::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

TView override that does nothing, as it doesn't make sense to transform a menu window.

Calling Context:

Called from MGraphic internally.

Parameters:

const TGrafMatrix & -The matrix by which to transform this view.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TView function.

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