Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TSimpleView, MMouseEventHandler, MControl, MKeyEventHandler, MGUIAttributeUser
Inherited By:
None.
Purpose:
TMenu derives from TSimpleView, MMouseEventHandler, MControl, and MKeyEventHandler and implements a one-dimensional list of MMenuItems. The menu items can be aligned back to back like in a menu bar, which occurs when the MControl::ELayout for the menu is kLeftToRight and the MControl::ELayout for the menu items is also kLeftToRight. The menu items can also be laid out perpendicular to one another like in a pop-up menu, which occurs when the menu layout is kTopToBottom and the item layout is kLeftToRight.
The menu view can be placed within a view hierarchy. If it is not placed in a hierarchy, it creates its own new view hierarchy in a new system window layer when PopUpLayer is called (usually by a submenu item).
Instantiation:
Usually allocated on the heap so that it can be adopted into a view or window.
Deriving Classes:
It is unlikely that you will need to derive from this. One possibility is that you might want to change the behavior of the interactor by overriding CreateInteractor or change the appearance by overriding DrawContents.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
- TMenu ()
- TMenu (const TMenu & copy)
Interface Category:
API.
Purpose:
- Default constructor.
- Copy constructor. Copies the entire menu hierarchy in the specified menu.
Calling Context:
- Called by the stream-in operators and derived classes.
- Called to copy an object.
Parameters:
- Takes no parameters.
- const TMenu & copy -The menu hierarchy to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TMenu ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::operator=
TMenu & operator =(const TMenu &)
Interface Category:
API.
Purpose:
Assignment operator. This member function copies the entire menu hierarchy.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
- const TMenu & -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: TMenu::operator>>=
virtual TStream & operator >>=(TStream &) const
Interface Category:
API.
Purpose:
Stream-out operator. This member function streams out the entire menu hierarchy.
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: TMenu::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: TMenu::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 the items, but an item can only be enabled if the control state adopted into the item is also enabled. This member function enables or disables all the items in the entire menu hierarchy starting at this menu.
Calling Context:
Called by SetEnabled in a parent item. 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 MControl function.
Member Function: TMenu::IsEnabled
virtual bool IsEnabled () const
Interface Category:
API.
Purpose:
Determines whether this menu is enabled. This function returns true if at least one menu item contained in this menu is enabled or if the menu is empty.
Calling Context:
Called by IsEnabled from a parent item. You can also call this function directly.
Parameters:
Return Value:
Returns true if at least one menu item contained in this 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: TMenu::AdoptLast
virtual void AdoptLast (MMenuItem *)
Interface Category:
API.
Purpose:
Adds a new menu item to the end of the list of items in this menu. The position of a menu item in storage is different than the position where the menu item is displayed. The position where the menu item is displayed within the menu is determined by the menu layout and by the reverse layout setting on the menu item itself. This function relays out the menu and redraws it if the menu is currently visible.
Notice that the menu only knows that the menu item is an MMenuItem. This means that developers can put TMomentaryMenuItems, TBooleanMenuItems, TEmbedderMenuItems, and TSubMenuItems into a menu, as well as their own special MMenuItem derived classes.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::AdoptFirst
virtual void AdoptFirst (MMenuItem *)
Interface Category:
API.
Purpose:
Adds a new menu item to the beginning of the list of menu items. The position of a menu item in storage is different than the position where the menu item is displayed. The position where the menu item is displayed within the menu is determined by the menu layout and by the reverse layout setting on the menu item itself. This function relays out the menu and redraws it if the menu is currently visible.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::AdoptAfter
virtual void AdoptAfter (MMenuItem &, MMenuItem *)
Interface Category:
API.
Purpose:
Adds a new menu item after the specified menu item in the current list of menu items. The position of a menu item in storage is different than the position where the menu item is displayed. The position where the menu item is displayed within the menu is determined by the menu layout and by the reverse layout setting on the menu item itself. This function relays out the menu and redraws it if the menu is currently visible. If the specified item was not found in the current list, the new item is adopted at the beginning of the list.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
- MMenuItem & -The item after which to place the adopted item.
- MMenuItem * -The item to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetLast
virtual MMenuItem * GetLast () const
Interface Category:
API.
Purpose:
Returns a pointer to the last item in the list of items in the menu.
Calling Context:
Call this function directly
Parameters:
Return Value:
Returns the pointer to the item, or NIL if there are no items.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetFirst
virtual MMenuItem * GetFirst () const
Interface Category:
API.
Purpose:
Returns a pointer to the first item in the list of items in the menu.
Calling Context:
Call this function directly
Parameters:
Return Value:
Returns the pointer to the item, or NIL if there are no items.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetAfter
virtual MMenuItem * GetAfter (MMenuItem &) const
Interface Category:
API.
Purpose:
Returns a pointer to the item that is stored after the specified item in the menu.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The pointer to the item; or NIL if there are no items, or if the specified item was not found in the menu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::NextSeparatedItemAfter
virtual MMenuItem * NextSeparatedItemAfter (MMenuItem *)
Interface Category:
API.
Purpose:
Locates the next item that has a separator, after the specified item in the list of items in the menu. If you want to locate the first item that has a separator, pass in NIL for the parameter.
Calling Context:
Call this function directly.
Parameters:
- MMenuItem * -The item from where to start the search or NIL if you want to start from the beginning of the menu.
Return Value:
Returns the item that contains the next separator. This function returns NIL if the specified item is not found in the menu, or if there are no more items in the menu that have separators.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::Orphan
virtual MMenuItem * Orphan (MMenuItem &)
Interface Category:
API.
Purpose:
Orphans the specified item from the menu. The caller is responsible for deleting the orphaned item.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the orphaned item.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::DeleteAll
virtual void DeleteAll ()
Interface Category:
API.
Purpose:
Deletes all the items in the menu -including submenu items.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetCount
virtual unsigned long GetCount () const
Interface Category:
API.
Purpose:
Determines how many menu items are in the menu -not including the title bar item.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the number of items in the menu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetItemLayout
virtual void SetItemLayout (MControl :: ELayout layout)
Interface Category:
API.
Purpose:
Sets the layout for all the items in the menu. Even though MMenuItem inherits MControl::SetControlLayout, the items in a given menu are all given the same control layout according to the layout parameter provided in this function. The subparts of each menu item are arranged according to this layout. Consider, for example, a Boolean menu item. If the item layout is kLeftToRight, the menu positions the checkmark on the left of the label. If the item layout is kRightToLeft, the menu puts the checkmark on the right of the label.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
- MControl :: ELayout layout -The new layout parameter.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetDesktop
virtual void SetDesktop (bool desktop)
Interface Category:
API.
Purpose:
Sets whether this menu appears permanently on the desktop. By default, a menu does not appear unless it is adopted into a view hierarchy, or unless PopUpLayer is called by a submenu item. This function can be called to tell the menu to create a system window, adopt itself into the window, and make itself permanently visible. This is useful for global menu bars, menu palettes, and torn off menus. Developers are encouraged to use TMenuWindow instead of calling this member function.
Calling Context:
Called when a submenu is opened or torn off. You can also call this function directly.
Parameters:
- bool desktop -The flag indicating whether this menu should appear permanently visible on the desktop. Use true to make this menu permanently visible on the desktop.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::IsDesktop
virtual bool IsDesktop () const
Interface Category:
API.
Purpose:
Determines whether this menu appears permanently on the desktop.
Calling Context:
Called by the menu during certain interactions. You can also call this function directly.
Parameters:
Return Value:
Returns true if this menu is a desktop menu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetCompressed
virtual void SetCompressed (bool compressed)
Interface Category:
API.
Purpose:
Sets whether the menu compresses the layout of the menu items. The subparts of the items are automatically aligned in columns. The width of these columns can either be the maximum width of the subparts in that column or a more compressed width to conserve screen real estate, similar to the insetting of the command key labels in Macintosh menus. The default is to have compression on.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
- bool compressed -The flag indicating whether to compress the layout of the menu items.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::IsCompressed
virtual bool IsCompressed () const
Interface Category:
API.
Purpose:
Determines whether the layout of the menu items is compressed.
Calling Context:
Called during layout of the menu.
Parameters:
Return Value:
Returns true if this menu's layout is compressed; false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetPreferredSize
virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const >Interface Category:
API.
Purpose:
Calculates and returns the preferred size of this menu. The preferred size of the menu is determined by the preferred sizes of the items in the menu. If a maximumMainDimension is specified, the menu can wrap the items around on multiple lines. (This only happens if the item layout is parallel to the menu layout, as in a menu bar.)
A menu always re-sets itself to this preferred size whenever the layout is invalidated. For example, if you adopt a new item the menu will set itself to the new referred size.
Calling Context:
Called during autoresize of the menu. You can also call this function directly.
Parameters:
- GCoordinate maximumMainDimension =kInfinity -The size constraint for laying out this menu.
Return Value:
Returns the preferred size of this menu.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetSize
virtual void SetSize (const TGPoint & size)
Interface Category:
API.
Purpose:
Sets the size of the menu.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Called during autoresize of the menu. You can also call this function directly if you want to manually size the menu.
Parameters:
- const TGPoint & size -The new size for this menu.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetMaxItemConstraint
virtual unsigned long GetMaxItemConstraint () const
Interface Category:
API.
Purpose:
Returns the maximum number of menu items that can be arranged per line in this menu.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the max item constraint which defaults to MAXLONG.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::Layout
virtual void Layout (const TGRect & bounds)
Interface Category:
API.
Purpose:
Lays out the menu items within the specified bounds.
Calling Context:
Usually called automatically during layout of the menu. You should not call this function directly, but instead call SetSize or SetAllocatedArea.
Parameters:
- const TGRect & bounds -The bounds within which to layout the menu items.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::AdoptBackground
virtual void AdoptBackground (TBorder * back, const TGRect & margin)
Interface Category:
API.
Purpose:
Specifies a background and a margin for this menu. The default background is a TRaisedBackground. The background can be any TBorder derived class. This function deletes the previously adopted background object.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Called by TEmbeddableMenu to change the background to a plain TBackground for the embedded menu. You can also call this function directly.
Parameters:
- TBorder * back -The background object to be adopted.
- const TGRect & margin -The new margin.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetBackground
virtual TBorder * GetBackground () const
Interface Category:
API.
Purpose:
Returns a pointer to the current background object. This function never returns NIL.
Calling Context:
Called during drawing of the menu. You can also call this function directly.
Parameters:
Return Value:
Returns the background object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetBackgroundMargin
virtual TGRect GetBackgroundMargin () const
Interface Category:
API.
Purpose:
Returns the margin around the menu items in this menu.
Calling Context:
Called during layout of the menu items. You can also call this function directly.
Parameters:
Return Value:
Returns the current margin.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::OrphanBackground
virtual TBorder * OrphanBackground ()
Interface Category:
API.
Purpose:
Orphans the adopted background object. The caller is responsible for deleting the orphaned background object. This function effectively resets the background style to the default provided by TMenu, which is a TRaisedBackground.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns the orphaned background.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::AdoptMenuColor
virtual void AdoptMenuColor (TGrafBundle * bundle)
Interface Category:
API.
Purpose:
Sets the color of the menu (and all its submenus). The color is specified in the fill paint in the specified bundle. The color is stored in a TTaligentGUIPaints attribute that is adopted as a view attribute.
Calling Context:
Call this function directly.
Parameters:
- TGrafBundle * bundle -The bundle containing the new color for this menu.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetItemAt
virtual MMenuItem * GetItemAt (TGPoint & pt) const
Interface Category:
API.
Purpose:
Returns the menu item at the specified point within the menu.
Calling Context:
Called during user interaction on the menu. You can also call this function directly.
Parameters:
- TGPoint & pt -The point of interest specified in the menu's coordinate system.
Return Value:
Returns the item at the specified point, or NIL if there is no item at the point.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::CreateInteractor
virtual TInteractor * CreateInteractor (const TGPoint & pt)
Interface Category:
API.
Purpose:
Creates an interactor used to interpret user gestures on this 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.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited MControl function.
Member Function: TMenu::RedrawItem
virtual void RedrawItem (MMenuItem & item, TGRect updateArea =TGRect :: kInfiniteRect) const
Category:
API.
Purpose:
Redraws the specified menu item.
Calling Context:
Called during user interaction on the menu, or if a menu item receives notification of a state change. The default, kInfiniteRect, results in the whole item being redrawn.
Parameters:
- MMenuItem & item -The item to redraw.
- TGRect updateArea =TGRect :: kInfiniteRect -The area of the item to redraw.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetPopUpReversed
virtual void SetPopUpReversed (bool reversed)
Interface Category:
API.
Purpose:
Sets whether to reverse the pop-up direction in all contained submenus.
Calling Context:
Called during user interaction on the menu.
Parameters:
- bool reversed -The flag indicating whether to reverse the pop-up direction in this menu. true reverses the layout.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::PopUpLayer
virtual void PopUpLayer (TGRect & popUpBounds)
Interface Category:
API.
Purpose:
Pops up the menu in a new front-most system window layer. If the given bounds is not large enough to display the entire menu, autoscrolling is enabled.
Calling Context:
Called by an owning submenu item when the item is selected. You should not call this member function directly. Instead, call SetPressed(true) on the parent submenu item, or call SetDesktop(false) if there is no parent item.
Parameters:
- TGRect & popUpBounds -The location to pop up the menu specified, in global coordinates.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::HideLayer
virtual void HideLayer ()
Interface Category:
API.
Purpose:
Hides the system window layer that contains this pop-up menu. You should not call this member function directly. Instead call SetPressed(false) on the parent submenu item, or call SetDesktop(true) if there is no parent item.
Calling Context:
Called by an owning submenu item after the interaction on the item is ended.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetLayer
virtual TView * GetLayer () const
Interface Category:
API.
Purpose:
Returns this menu or the scrolling view that contains this menu.
Calling Context:
Called during user interaction on the menu.
Parameters:
Return Value:
Returns the topmost view in this menu's view hierarchy.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetLayoutInvalid
void SetLayoutInvalid ()
Interface Category:
API.
Purpose:
Invalidates the layout of the menu, indicating that the menu should be laid out again.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Called by the menu itself.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::MouseDown
virtual bool MouseDown (TMouseDownEvent & mouseEvent)
Interface Category:
API.
Purpose:
Receives the mouse-down events that occur inside the menu and starts an interactor on the menu.
Calling Context:
Called by the Input System framework.
Parameters:
- TMouseDownEvent & mouseEvent -The event that caused this function to be called.
Return Value:
Returns true if this menu handled the mouse-down event, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited MMouseEventHandler function.
Member Function: TMenu::DrawContents
virtual void DrawContents (TGrafPort & port) const
Interface Category:
API.
Purpose:
Draws this menu and each of its menu items.
Calling Context:
Called by the View system when all or part of the menu needs redrawing.
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 function is protected.
Member Function: TMenu::DrawBackground
virtual void DrawBackground (TGrafPort & port, const TGArea & visibleArea) const >Interface Category:
API.
Purpose:
Draws the background of the menu.
Calling Context:
Called by DrawContents.
Parameters:
- TGrafPort & port -The port into which to draw.
- const TGArea & visibleArea -The area that is being drawn.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::IsItemRedraw
virtual bool IsItemRedraw () const
Interface Category:
API.
Purpose:
Determines whether the menu is drawing because one of the menu items contained in this menu called RedrawItem. This member function is obsolete because item redrawing is now done directly.
Calling Context:
Called internally. This function is not intended to be used by clients.
Parameters:
Return Value:
Returns true if this menu is drawing because of a call to RedrawItem.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::AddScroller
virtual void AddScroller (TGRect & bounds)
Interface Category:
API.
Purpose:
Adopts this menu into an autoscrolling view. The autoscrolling view draws arrows on the top and bottom and/or left and right to indicate which direction the menu will scroll. As the mouse moves into the arrow area, the menu will scroll.
Calling Context:
Called from PopUpLayer if this menu is told to pop up in a rectangle that is not large enough to contain the entire menu.
Parameters:
- TGRect & bounds -The bounds of the popup.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::RemoveLayer
virtual void RemoveLayer ()
Interface Category:
API.
Purpose:
Removes this menu from the system window.
Calling Context:
Called during cleanup of the menus, or if SetDesktop(false) is called.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::KeyDown
virtual bool KeyDown (TKeyDownEvent & event)
Interface Category:
API.
Purpose:
Handles a command key press. This function determines if a menu item has the key event defined as a keyboard equivalent. If so, KeyDown invokes the menu item and returns true. This function only gets called if the key-down event modifiers match the modifiers specified in the items in this menu.
Calling Context:
Called by the keyboard input architecture when a command key is received by the menu command key filter.
Parameters:
Return Value:
Returns true if the event was handled, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This protected function overrides inherited MKeyEventHandler function.
Member Function: TMenu::PrintLayoutDebugInfo
virtual void PrintLayoutDebugInfo (bool printIt =true)
Interface Category:
API.
Purpose:
Used for debugging purposes. This function prints information about the menu layout by delegating to this menu's menu layout object.
Calling Context:
Call this function directly.
Parameters:
- bool printIt =true -The flag indicating whether to print the debugging information. This flag is passed directly to the menu layout's PrintLayoutDebugInfo member function.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::HandleAllocatedAreaChanged
virtual void HandleAllocatedAreaChanged (const TGArea & newArea)
Interface Category:
API.
Purpose:
Handles the situation where the menu's allocated area has changed.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
This function is called by the framework when the menu's allocated area is changed.
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: TMenu::FoldUpMenus
virtual void FoldUpMenus ()
Interface Category:
API.
Purpose:
Folds up all the submenus from this menu up to the desktop menu.
Calling Context:
Called to close a number of submenus in a chain at once. You should not call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::HandleBeforeDisconnectionFromViewRoot
virtual void HandleBeforeDisconnectionFromViewRoot ()
Interface Category:
API.
Purpose:
Performs actions required before disconnecting from the view root. Delegates to TSimpleView, and hides any torn off submenus.
Calling Context:
Called before disconnecting from the view root.
Parameters:
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: TMenu::HandleAfterConnectionToViewRoot
virtual void HandleAfterConnectionToViewRoot ()
Interface Category:
API.
Purpose:
Performs setup actions required after connection to the view root. Delegates to TSimpleView, and shows any torn off submenus.
Calling Context:
Called by the View system after the view is connected (directly or indirectly) to the view root.
Parameters:
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: TMenu::DrawItemSeparator
virtual void DrawItemSeparator (TGrafPort & port, const TGRect & itemBounds, MMenuItem :: ESeparatorType type, const TAttributeState & shadowBundle, const TAttributeState & highlightBundle) const
Interface Category:
API.
Purpose:
Draws an item separator according to the specified parameters.
Calling Context:
Called by DrawContents.
Parameters:
- TGrafPort & port -The port into which to draw.
- const TGRect & itemBounds -The bounds of the item for which the separator is being drawn.
- MMenuItem :: ESeparatorType type -The type of separator the item requested.
- const TAttributeState & shadowBundle -The bundle to use for the shadow line.
- const TAttributeState & highlightBundle -The bundle to use for the highlight line.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
This function is protected.
Member Function: TMenu::NeedsClipping
virtual bool NeedsClipping ()
Interface Category:
API.
Purpose:
Tells whether this menu needs to be clipped to fit within its bounds.
Calling Context:
This function is called by the framework during a View system refresh.
Parameters:
Return Value:
Returns true if it needs clipping, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited TView function.
Member Function: TMenu::HasTitleBar
virtual bool HasTitleBar () const
Interface Category:
API.
Purpose:
Determines whether the menu has a title bar.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the menu has a title bar, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetHasTitleBar
virtual void SetHasTitleBar (bool titleBar =true)
Interface Category:
API.
Purpose:
Specifies whether the menu has a title bar. By default, a menu is given a title bar for moving and tearing off the menu, unless the menu is adopted into a parent view, or if the menu is kTopToBottom and is a submenu of a kLeftToRight menu bar. This function allows you to turn the title bar on and off for other reasons as well (but it still won't let child view menus have a title bar because this doesn't make sense).
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
- bool titleBar =true -Set to true if the menu has a title bar, false if it doesn't.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetRequestProcessor
virtual TRequestProcessor * GetRequestProcessor () const
Interface Category:
API.
Purpose:
Delegates to TView to return the request processor that's used for this menu view. If TView returns NIL, and there is a parent submenu item, then this function calls GetRequestProcessor on its owner. This allows submenus to get access to the request processor even before they are adopted into a TViewRoot.
Calling Context:
Called by TView derived classes to get the request queue for this view.
Parameters:
Return Value:
The request queue for the view, and the view's hierarchy. Returns NIL if the menu isn't part of a rooted view hierarchy, or if the view root doesn't have a request processor of its own.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited TView function.
Member Function: TMenu::HandleAttributesChanged
virtual void HandleAttributesChanged ()
Interface Category:
API.
Purpose:
Handles the situation where the menu's GUI attributes have changed. Marks the menu as invalid so it is redrawn. Calls HandleAttributesChanged on each of the child menu items.
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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::IsActive
virtual bool IsActive () const
Interface Category:
API.
Purpose:
Determines whether the menu is active.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the menu is active, false if it's not.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetActive
virtual void SetActive (bool active =true)
Interface Category:
API.
Purpose:
Activates or deactivates the menu, based on the value of the Boolean flag. When the menu is activated, it is set up to accept command keys, and the menu items are activated and set up for notification of state changes.
Calling Context:
Call this function directly.
Parameters:
- bool active =true -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.
Member Function: TMenu::SetVisibility
virtual void SetVisibility (bool visible)
Interface Category:
API.
Purpose:
Sets this menu to be visible or invisible. Delegates to the inherited TView and MControl SetVisibility functions.
Calling Context:
Call this function directly.
Parameters:
- bool visible -The flag indicating whether this menu 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 and TView functions.
Member Function: TMenu::GetVisibility
virtual bool GetVisibility () const
Interface Category:
API.
Purpose:
Delegates to TView to determine whether this menu item is visible.
Calling Context:
Call this function directly.
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 and TView functions.
Member Function: TMenu::SetControlLayout
virtual void SetControlLayout (MControl :: ELayout layout)
Interface Category:
API.
Purpose:
Sets the layout orientation of this menu. This determines how the items are arranged within the menu. For example, a menu palette might have a layout of MControl::kTopToBottom, whereas a menu bar might have MControl::kLeftToRight.
The menu is automatically updated if IsAutoUpdate returns true. Calling SetAutoUpdate(false) is a good performance improvement if you are going to make more than one change that affects the layout of the menu, but remember to set the auto-update flag back to its original setting.
Calling Context:
Call this function directly.
Parameters:
- ELayout layout -The orientation to set.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited MControl function.
Member Function: TMenu::IsAutoUpdate
virtual bool IsAutoUpdate () const
Interface Category:
API.
Purpose:
Determines whether the menu is automatically resized and its layout is redone every time the state of the menu changes--when an item is added or removed, or when a change is made to the layout, the background, compression, or the constraints.
Calling Context:
Call this function directly.
Parameters:
Return Value:
Returns true if the menu is automatically updated, false if it's not.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetAutoUpdate
virtual void SetAutoUpdate (bool flag)
Interface Category:
API.
Purpose:
Specifies whether the menu should be automatically resized and its layout redone every time the state of the menu changes--when an item is added or removed, or when a change is made to the layout, the background, compression, or the constraints. The default is true. A more efficient batch change mechanism can occur when autoupdate is set to false during a group of changes. Setting autoupdate to true does an update if necessary.
Clients are encouraged not to explicitly call SetAutoUpdate(true) because it might not be the right time for autoupdate to be set to true. If you want to set auto update to false, first call IsAutoUpdate to record the current setting, then set it to false, and when you're done set it back to what it was.
Calling Context:
Call this function directly.
Parameters:
- bool flag -Set to true to automatically update the menu every time changes are made, false to not automatically do the updates.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetPressed
virtual void SetPressed (bool pressed)
Interface Category:
API.
Purpose:
Delegates to MControl to set this menu as either pressed or unpressed according to the specified Boolean flag. This member function has no meaning for menus.
Calling Context:
Called during user interaction.
Parameters:
- bool -The flag indicating whether this menu should become pressed or unpressed--true presses the menu; false unpresses it.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited MControl function.
Member Function: TMenu::CreateItemIterator
TDequeOfIterator < MMenuItem > * CreateItemIterator (TMemoryHeap * whichHeap =NIL)
Interface Category:
API.
Purpose:
Creates an iterator for iterating over the array of menu items.
Calling Context:
Called whenever the system needs to iterate over the items in a menu. You can also call this function directly.
Parameters:
- TMemoryHeap * whichHeap =NIL -The heap from which to allocate the iterator.
Return Value:
The newly created menu item iterator. The caller is responsible for deleting this iterator when it is no longer needed.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::CreateLayer
virtual TViewRoot * CreateLayer (TRequestProcessor * proc, TMemoryHeap * whichHeap =NIL)
Interface Category:
API.
Purpose:
Creates the system window for the menu in the menu layer as defined by the window group that contains the top most menu in the menuhierarchy.
Calling Context:
Called when the system window for a pop-up menu is created for the first time, which is usually during user interaction on the menu.
Parameters:
- TRequestProcessor * proc -The request processor for the new root view.
- TMemoryHeap * whichHeap =NIL -The heap from which to allocate the system window.
Return Value:
Returns the new root view.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::SetMaxItemConstraint
virtual void SetMaxItemConstraint (unsigned long maxItems =kMaxConstraint)
Interface Category:
API.
Purpose:
Establishes a limit to the number of items that can be arranged per line in this menu. This function is ignored if the menu layout orientation is perpendicular to the menu item layout orientation. This is ideal if you know that each item is the same size and you want a 2-D grid layout. For example, setting the constraint to 3 in a kLeftToRight menu that contains 9 kLeftToRight items, where each item displays a color choice, produces a color palette containing a 3x3 grid of menu items.
Calling Context:
Call this function directly.
Parameters:
- unsigned long maxItems =kMaxConstraint -The maximum number of items that can be arranged per line in this menu.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::GetBounds
virtual void GetBounds (TGArea & area) const
Interface Category:
API.
Purpose:
Returns an area of the preferred size for the menu.
Calling Context:
Called externally and internally by the View system. You can also call this function directly.
Parameters:
- TGArea & area -Receives the area of the preferred size.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
Overrides the inherited TView function.
Member Function: TMenu::GetItemLayout
virtual MControl :: ELayout GetItemLayout () const
Interface Category:
API.
Purpose:
Returns the current layout for the menu items.
Calling Context:
Call this function directly.
Parameters:
Return Value:
The current layout for the menu items.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::AssignDomainID
virtual void AssignDomainID (const TMenuDomainID & id)
Interface Category:
API.
Purpose:
Assigns a given domain ID to each menu item in the menu and its submenus. This way, you can then merge these menu items in with another menu hierarchy and later be able to find your items again (via FindAllItems). This provides a name space mechanism so that your menu item IDs don't clash with other menu item IDs assigned by other developers.
Calling Context:
Call this function directly.
Parameters:
- const TMenuDomainID & id -The domain ID.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::FindAllItems
virtual void FindAllItems (const TMenuDomainID & id, TCollectionOf < MMenuItem > & result) const
Interface Category:
API.
Purpose:
Finds all menu items that have the specified domain ID.
Calling Context:
Call this function directly.
Parameters:
- const TMenuDomainID & id -The domain ID.
- TCollectionOf < MMenuItem > & result -All the menu items that have the specified domain ID. When you are finished with the collection do not call DeleteAll -because the collection does not own the menu items.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::FindItem
virtual MMenuItem * FindItem (const TMenuDomainID & domain, const TMenuItemID & id) const >Interface Category:
API.
Purpose:
Find a menu item with the specified domain ID and item ID. The order of the search is to first search all the items in this menu from first to last, and then search each submenu from the first submenu to the last in a depth-first manner.
Calling Context:
Call this function directly.
Parameters:
- const TMenuDomainID & domain -The domain ID.
- const TMenuItemID & id -The ID of the menu item found.
Return Value:
The menu item found.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TMenu::DistributePositionalEvent
virtual bool DistributePositionalEvent (TEvent & theEvent, const TGPoint & where)
Interface Category:
API.
Purpose:
Same as the TView member function.
Calling Context:
Called by the View system to direct positional events to the correct view.
Parameters:
- TEvent & theEvent -The event that's being distributed.
- const TGPoint & where -The position of the positional event, in coordinates relative to this view.
Return Value:
Returns true if the event was handled by this view or one of its children.
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.
Copyright©1995 Taligent,Inc. All rights reserved.