Class: TPopUpMenu

Declaration: PopUpMenus.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TView

Inherited By:

None.

Purpose:

Displays a mutually exclusive set of choices to the user in a pop-up menu format. TPopUpMenu is useful when you want to conserve screen real estate since unlike radio button groups, only the current selection is always visible. The rest of the choices only appear temporarily in a pop-up menu while the user holds the mouse button down on it. The user can drag to select a different item. The items that the user selects are TPopUpItems which are special TBooleanMenuItems. TPopUpMenu ensures that only one item is set to the kTrue state at any given time. When the submenu is popped open, the current selection is aligned with the submenu item in the pop-up menu. It is possible for the pop-up menu to have no current selection (which is the case at initialization or if the currently selected item is removed from the menu). It is important to understand that TPopUpMenu is really just a type safe wrapper on TMenu. This TMenu will always contain just one item which is a TPopUpSubMenuItem and the submenu contained in this item will only ever contain TPopUpItems. This guarantees a consistent look and feel for all popup menus.

Instantiation:

This class is usually allocated on the heap so that it can be adopted into a parent view.

Deriving Classes:

There are no derived classes of TPopUpMenu provided by CommonPoint and the need to derive should not be common. However, there is one protected function that allows a derived class to substantially change the behavior of this class: HandleCreatePopUpSubMenuItem.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPopUpMenu::TPopUpMenu

TPopUpMenu ()
TPopUpMenu (const TPopUpMenu &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TPopUpMenu & -The source to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.
Calls the assignment operator.

Member Function: TPopUpMenu::~TPopUpMenu

TPopUpMenu

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

TPopUpMenu & operator =(const TPopUpMenu &)

Interface Category:

API.

Purpose:

Assignment operator. This clones the entire pop-up submenu of the given TPopUpMenu.

Calling Context:

Called when an object is assigned to another compatible object. Called by the copy constructor.

Parameters:

const TPopUpMenu & -The object to be copied is to the right of the equals sign.

Return Value:

TPopUpMenu & -A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Called by the copy constructor.

Member Function: TPopUpMenu::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator. This flattens the entire pop-up submenu.

Calling Context:

Called to stream out data.

Parameters:

TStream & destination -The output stream into which the class writes itself.

Return Value:

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The input stream from which the class extracts the contents of its members.

Return Value:

TStream & -The stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if it encounters an object whose version number indicates it cannot be streamed in. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::AdoptLast

virtual void AdoptLast (TPopUpItem * item)

Interface Category:

API.

Purpose:

Adds a pop-up menu item at the end of the menu. If the item is already set to the MBooleanControlState::kTrue state then it will become the new selected item and any previously selected item will be switched off.

Calling Context:

You can call this function directly.

Parameters:

TPopUpItem * item -The menu item to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any item not added using this function or AdoptAfter or AdoptFirst will not participate in the management of the current selection. If the adopted item's boolean control state is on, it will become the selected item.

Member Function: TPopUpMenu::AdoptFirst

virtual void AdoptFirst (TPopUpItem * item)

Interface Category:

API.

Purpose:

Adds a pop-up menu item at the beginning of the menu. If the item is already set to the MBooleanControlState::kTrue state then it will become the new selected item and any previously selected item will be switched off.

Calling Context:

You can call this function directly.

Parameters:

TPopUpItem * item -The menu item to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any item not added using this function or AdoptAfter or AdoptLast will not participate in the management of the current selection. If the adopted item's boolean control state is on, it will become the selected item.

Member Function: TPopUpMenu::AdoptAfter

virtual void AdoptAfter (TPopUpItem & item1, TPopUpItem * item2)

Interface Category:

API.

Purpose:

Adds item2 as a menu item after item1. If the item is already set to the MBooleanControlState::kTrue state then it will become the new selected item and any previously selected item will be switched off.

Calling Context:

You can call this function directly.

Parameters:

TPopUpItem & item1 -The item after which the new item will be inserted.
TPopUpItem * item2 -The new menu item being adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any item not added using this function or AdoptLast or AdoptFirst will not participate in the management of the current selection. If the adopted item's boolean control state is on, it will become the selected item.

Member Function: TPopUpMenu::GetLast

virtual TPopUpItem * GetLast () const

Interface Category:

API.

Purpose:

Returns the last pop-up item in the menu.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPopUpItem * -The last item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function will return NIL if there are no menu items.

Member Function: TPopUpMenu::GetFirst

virtual TPopUpItem * GetFirst () const

Interface Category:

API.

Purpose:

Returns the first item in the menu.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPopUpItem * f- The first item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function will return NIL if there are no menu items.

Member Function: TPopUpMenu::GetAfter

virtual TPopUpItem * GetAfter (MMenuItem &) const

Interface Category:

API.

Purpose:

Returns the item in the menu after the item passed to this function.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPopUpItem * -The item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function will return NIL if there are no menu items.

Member Function: TPopUpMenu::Orphan

virtual TPopUpItem * Orphan (TPopUpItem & item)

Interface Category:

API.

Purpose:

Removes the pop-up item from the menu. If the item removed is the currently selected item the the popup menu will have no currently selected item, ie GetSelectedItem() will return NIL.

Calling Context:

You can call this function directly.

Parameters:

TPopUpItem & item -The menu item to be orphaned.

Return Value:

TPopUpItem * -The orphaned item which the caller now owns.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function does not delete the item it orphans.

Member Function: TPopUpMenu::DeleteAll

virtual void DeleteAll ()

Interface Category:

API.

Purpose:

Deletes all items in the menu.

Calling Context:

You can 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:

None.

Member Function: TPopUpMenu::GetCount

virtual unsigned long GetCount () const

Interface Category:

API.

Purpose:

Returns the number of pop-up menu items in the menu.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

unsigned long -The number of items in the menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::GetSelectedItem

virtual TPopUpItem * GetSelectedItem () const
virtual TPopUpItem * GetSelectedItem (unsigned long & index) const

Interface Category:

API.

Purpose:

Returns the currently selected item.
Returns the currently selected item, and reports the index of that item.

Calling Context:

You can call this function directly.
You can call this function directly.

Parameters:

Takes no parameters.
unsigned long & index -The function fills this parameter with the index number of the pop-up menu item.

Return Value:

TPopUpItem * -The selected item -which can be NIL if there is no current selection, i.e. there is no TPopUpItem with state MBooleanControlState::kTrue.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Will return NIL if there are no items.
The reported index will be -1 if there are no items. If the first item is selected, the index reported will be 0. If the second item is selected, the index reported will be 1, and so forth.

Member Function: TPopUpMenu::SetSelectedItem

virtual bool SetSelectedItem (TPopUpItem * itemToSelect)
virtual bool SetSelectedItem (unsigned long index)

Interface Category:

API.

Purpose:

Makes the specified item the selected item.

Specifies the item with a reference to it.
Specifies the item by its index. The index of the first item is 0, of the second item, 1, and so forth in the same order that the items were added to the menu, if AdoptLast was used to add them.

Calling Context:

You can call this function directly.
You can call this function directly.

Parameters:

TPopUpItem * itemToSelect
unsigned long index -The zero-based index of the item to select.

Return Value:

Returns true if successful.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

GetSelectedItem is the converse of SetSelectedItem.

Member Function: TPopUpMenu::SetControlLayout

virtual void SetControlLayout (MControl :: ELayout layout)

Interface Category:

API.

Purpose:

Assigns whether the pop-up menu in its small, un-popped-up condition is laid out right-to-left, left-to-right, top-to-bottom, or bottom-to-top. Typically it will be laid out left-to-right; that will place the arrow (pointing down) to the left of the label.

Calling Context:

You can call this function directly.

Parameters:

MControl :: ELayout layout -The value that sets the direction of layout.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::SetItemLayout

virtual void SetItemLayout (MControl :: ELayout layout)

Interface Category:

API.

Purpose:

Assigns whether the pop-up menu items are laid out right-to-left, left-to-right, top-to-bottom, or bottom-to-top.

Calling Context:

You can call this function directly.

Parameters:

MControl :: ELayout layout -The value that sets the direction of layout.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the minimum size required to present the menu in its small, un-popped-up condition.

Calling Context:

You can call this function directly.

Parameters:

GCoordinate maximumMainDimension =kInfinity -Any limitation that overrides the default value (kInfinity) may cause lines to be wrapped.

Return Value:

TGPoint -The size. The x-component indicates the width of the label, and the y-component indicates the height.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The value returned may change when the user selects a different pop-up item from the menu.

Member Function: TPopUpMenu::SetSize

virtual void SetSize (const TGPoint & size)

Interface Category:

API.

Purpose:

Adjusts the allocated area in the parent view to accommodate the menu in its small, un-popped-up condition.

Calling Context:

This member function is called automatically when items are added or removed from the popup menu. You can call this function directly, although your size may be reset the next time an item is added or removed.

Parameters:

const TGPoint & size -The size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::SetChildAllocatedArea

virtual void SetChildAllocatedArea (TView &, const TGArea &)

Interface Category:

API.

Purpose:

This is a special TView override that allows the pop-up menu allocated area to stay in sync with the child TMenu, since whenever the child TView changes its bounds, this function gets called.

Calling Context:

The framework calls this function; you do not call it.

Parameters:

TView &
const TGArea & -

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::SetChildAllocatedAreaAndLocation

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

Interface Category:

API.

Purpose:

This is a special TView override that allows the pop-up menu allocated area to stay in sync with the child TMenu, since whenever the child TView changes its bounds, this function gets called.

Calling Context:

The framework calls this function; you do not call it.

Parameters:

TView &
const TGArea & -
const TGPoint & -

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Reports the preferred bounds of the menu in its small, un-popped up state.

Calling Context:

You can call this function directly.

Parameters:

TGArea & area -Filled by the function with the preferred bounds of the menu.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the information provided by GetPreferredSize, but in the format of a TGArea which includes the location of the menu as well as its size. The preferred size may change if the user selects a new pop-up item from the menu.

Member Function: TPopUpMenu::AdoptMenuColor

virtual void AdoptMenuColor (TGrafBundle * bundle)

Interface Category:

API.

Purpose:

Assigns a color in which to display the menu.

Calling Context:

You can call this function directly.

Parameters:

TGrafBundle * bundle -Contains the color to be adopted. Currently, the entire bundle itself is not used, only the fill paint and only if this fill paint is a TColorPaint.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function deletes the TGrafBundle passed to it after copying the relevant information out of it.

Member Function: TPopUpMenu::GetPopUpSubMenuItem

virtual TPopUpSubMenuItem * GetPopUpSubMenuItem () const

Interface Category:

API.

Purpose:

Returns the TPopUpSubMenuItem which contains a TMenu which contains the pop-up items. (The TMenu inside the TPopUpSubMenuItem is a submenu because it is contained in a submenu item. Containing it in a submenu item was a convenient and efficient reuse of other framework classes, because submenus support pop-up behavior.) This documentation is provided for advanced developers who want to extend the capability of pop-up menus.

Calling Context:

You call this function directly from classes you derive from TPopUpMenu to extend its capability. Clients of the standard version of TPopUpMenu would not need to call this function. The only reason it's public is so that a UI Builder can use it.

Parameters:

Takes no parameters.

Return Value:

TPopUpSubMenuItem * -The pop-up menu.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPopUpMenu::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Called by the framework.

Calling Context:

You do not need to 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:

This function is protected.

Member Function: TPopUpMenu::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Called by the framework.

Calling Context:

You do not need to 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:

This function is protected.

Member Function: TPopUpMenu::HandleCreatePopUpSubMenuItem

virtual TPopUpSubMenuItem * HandleCreatePopUpSubMenuItem ()

Interface Category:

API.

Purpose:

Called by the framework. TPopUpMenu derived classes can override this function to return their own special derived class of TPopUpSubMenuItem and this way modify the look or behavior of this class.

Calling Context:

You do not need to call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPopUpSubMenuItem * newMenuItem -A newly created TPopUpSubMenuItem.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TPopUpMenu::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Respond to allocated area changes on the menu.

Calling Context:

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

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:

None.

Member Function: TPopUpMenu::DistributePositionalEvent

virtual bool DistributePositionalEvent (TEvent & theEvent, const TGPoint & local)

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.