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.
- 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.
virtual ~ TPopUpMenu ()
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: 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:
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:
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:
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:
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:
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:
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:
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:
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.
GetSelectedItem is the converse of SetSelectedItem.
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:
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:
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:
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:
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:
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:
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:
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.
Copyright©1995 Taligent,Inc. All rights reserved.