IlvPopupMenu Class Reference

Gadget class. More...

#include <ilviews/gadgets/menu.h>

Inheritance diagram for IlvPopupMenu:

List of all members.

Public Member Functions
	IlvPopupMenu (IlvDisplay *display, IlUShort count, IlvMenuItem *items, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor.
	IlvPopupMenu (IlvDisplay *display, IlUShort count=0, const char *const *labels=0, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
	Constructor.
void	addOpenMenuCallback (IlSymbol *callbackName, IlAny arg)
	Adds a named Open Menu callback.
void	addOpenMenuCallback (IlvGraphicCallback callback, IlAny arg)
	Adds a Open Menu callback.
void	addOpenMenuCallback (IlSymbol *callbackName)
	Adds a named Open Menu callback.
void	addOpenMenuCallback (IlvGraphicCallback callback)
	Adds an Open Menu callback.
IlBoolean	autoLabelAlignment () const
	Indicates whether the automatic label alignment mode is on.
void	autoLabelAlignment (IlBoolean value, IlBoolean redraw=IlTrue)
	Specifies whether the automatic label alignment mode should be used.
virtual void	doIt ()
	Is called when the user selects an item from a standalone pop-up menu.
virtual void	drawGadgetItem (const IlvGadgetItem *, IlvPort *, const IlvRect &, const IlvTransformer *t=0, const IlvRegion *clip=0) const
	Draws a specific gadget item.
virtual void	empty ()
	Empties the list.
IlShort	get (const IlvPoint &point, IlvView *parent=0)
	Displays the menu at the specified location and waits until a selection is made.
virtual IlvPalette *	getHighlightTextPalette () const
	Returns the highlight palette used to draw the label of highlighted items.
virtual IlvDim	getLabelOffset () const
	Returns the offset applied to each item label.
IlvGraphicCallback	getOpenMenuCallback () const
	Returns a pointer to the first unnamed callback in the Open Menu callback list.
IlSymbol *	getOpenMenuCallbackName () const
	Returns the name of the first named callback in the Open Menu callback list.
IlvContainer *	getTopView () const
	Returns a pointer to the container associated with the pop-up menu.
IlBoolean	hasToolTips () const
	Indicates whether the pop-up menu displays tooltips.
virtual void	hide ()
	Hides the pop-up menu.
IlBoolean	isDoubleBuffering () const
	Tests the double buffering setting.
virtual IlBoolean	isGrabbed () const
	Returns IlTrue if the pop-up menu is visible and grabbed.
IlBoolean	isVisible () const
	Indicates whether the pop-up menu is visible.
virtual void	itemBBox (IlUShort item, IlvRect &rect, const IlvTransformer *t=0) const
	Returns the bounding box of a menu item in the menu.
virtual void	recomputeAllItems ()
	Recomputes the size of all the items managed by the holder.
virtual void	select (IlUShort pos)
	Is called when an item has been selected.
virtual void	setDoubleBuffering (IlBoolean value)
	Sets double buffering.
void	setLabelOffset (IlvDim offset, IlBoolean redraw=IlTrue)
	Sets the label offset of the pop-up menu.
void	setOpenMenuCallback (IlSymbol *callbackName, IlAny arg)
	Sets a named Open Menu callback.
void	setOpenMenuCallback (IlvGraphicCallback callback, IlAny arg)
	Sets an Open Menu callback.
void	setOpenMenuCallback (IlSymbol *callbackName)
	Sets a named Open Menu callback.
void	setOpenMenuCallback (IlvGraphicCallback callback)
	Sets an Open Menu callback.
virtual void	show (const IlvPoint &point, IlBoolean grab=IlTrue, IlvView *parent=0)
	Displays the menu at the specified location.
virtual void	unSelect (IlUShort pos)
	Is called when an item has been deselected.
void	useToolTips (IlBoolean value)
	Specifies whether the pop-up menu should display tooltips.
Static Public Member Functions
static IlBoolean	AreToolTipsEnabled ()
	Indicates whether pop-up menus should display tooltips.
static void	EnableToolTips (IlBoolean value=IlTrue)
	Specifies whether pop-up menus should display tooltips.
static IlSymbol *	OpenMenuCallbackSymbol ()
	Returns the symbol of the Open Menu callback list.
Friends
class	IlvDefaultPopupMenuLFHandler

---

Detailed Description

Gadget class.

Library: ilvgadgt

The IlvPopupMenu class handles a list of menu entries laid out vertically. These menu entries, called menu items, are instances of the IlvMenuItem class, which can store a label, a bitmap, or a graphic object of the class IlvGraphic. A pop-up menu can be used as a submenu or as a standalone menu by calling the member functions IlvPopupMenu::show or IlvPopupMenu::get.

- IlvPopupMenu -

A pop-up menu can be torn off and put into a floating window. A tear-off pop-up menu can be detached by selecting the dashed line appearing across its top border. The first item of a tear-off pop-up menu must be of the type IlvTearOffItem.

See also:

IlvAbstractBar, IlvMenuItem, IlvOptionMenu, IlvComboBox

---

Constructor & Destructor Documentation

IlvPopupMenu::IlvPopupMenu	(	IlvDisplay *	display,
		IlUShort	count = 0,
		const char *const *	labels = 0,
		IlUShort	thickness = IlvDefaultGadgetThickness,
		IlvPalette *	palette = 0
	)

Constructor.

Initializes a new instance of the IlvPopupMenu class.

Parameters:

	display	The connection to the display.
	count	The number of elements in the labels array.
	labels	An array of item labels.
	thickness	The thickness of the menu.
	palette	The palette used to draw the menu.

IlvPopupMenu::IlvPopupMenu	(	IlvDisplay *	display,
		IlUShort	count,
		IlvMenuItem *	items,
		IlUShort	thickness = IlvDefaultGadgetThickness,
		IlvPalette *	palette = 0
	)

Constructor.

Initializes a new instance of the IlvPopupMenu class. The items are copied by this constructor.

Parameters:

	display	The connection to the display.
	count	The number of elements in the items array.
	items	An array of menu items.
	thickness	The thickness of the menu.
	palette	The palette used to draw the menu.

---

Member Function Documentation

void IlvPopupMenu::addOpenMenuCallback	(	IlSymbol *	callbackName,
		IlAny	arg
	)

Adds a named Open Menu callback.

Adds callbackName to the Open Menu callback list. The callback function, when invoked, receives the user parameter arg. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

	callbackName	The name of the new callback.
	arg	The callback argument.

See also:

setOpenMenuCallback, getOpenMenuCallbackName

void IlvPopupMenu::addOpenMenuCallback	(	IlvGraphicCallback	callback,
		IlAny	arg
	)

Adds a Open Menu callback.

Adds callback to the Open Menu callback list. The callback function, when invoked, receives the user parameter arg. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

	callback	A pointer to the new callback.
	arg	The callback argument.

See also:

setOpenMenuCallback, getOpenMenuCallback

void IlvPopupMenu::addOpenMenuCallback

(

IlSymbol *

callbackName

)

Adds a named Open Menu callback.

Adds callbackName to the Open Menu callback list. gadget has the keyboard focus. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

callbackName

The name of the new callback.

See also:

setOpenMenuCallback, getOpenMenuCallbackName

void IlvPopupMenu::addOpenMenuCallback

(

IlvGraphicCallback

callback

)

Adds an Open Menu callback.

Adds callback to the Open Menu callback list. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

callback

A pointer to the new callback.

See also:

setOpenMenuCallback, getOpenMenuCallback

static IlBoolean IlvPopupMenu::AreToolTipsEnabled

(

)

[static]

Indicates whether pop-up menus should display tooltips.

Returns:

IlTrue if tooltips are allowed for pop-up menus, IlFalse otherwise.

See also:

hasToolTips, EnableToolTips

IlBoolean IlvPopupMenu::autoLabelAlignment

(

)

const

Indicates whether the automatic label alignment mode is on.

Returns:

IlTrue if the automatic label alignment mode is on and IlFalse otherwise.

See also:

autoLabelAlignment(IlBoolean, IlBoolean), setLabelOffset

void IlvPopupMenu::autoLabelAlignment	(	IlBoolean	value,
		IlBoolean	redraw = IlTrue
	)

Specifies whether the automatic label alignment mode should be used.

When the automatic label alignment mode is enabled (the default), a label offset is automatically computed to ensure that all the item pictures are visible and all the item labels are aligned.

Parameters:

	value	A Boolean value specifying whether the automatic alignment mode should be used.
	redraw	A Boolean value specifying whether the pop-up menu should be redrawn.

See also:

setLabelOffset, autoLabelAlignment()

virtual void IlvPopupMenu::doIt

(

)

[virtual]

Is called when the user selects an item from a standalone pop-up menu.

The default implementation calls the IlvGadgetItem::activate method of the selected menu item, which causes the item callback to be invoked. The method does nothing if no item is selected.

See also:

IlvAbstractMenu::whichSelected, IlvGadgetItem::activate

virtual void IlvPopupMenu::drawGadgetItem	(	const IlvGadgetItem *	item,
		IlvPort *	port,
		const IlvRect &	rect,
		const IlvTransformer *	t = 0,
		const IlvRegion *	clip = 0
	)			const [virtual]

Draws a specific gadget item.

Redraws item in port at the location specified by rect using the clipping area clip. This method simply calls IlvGadgetItem::draw using the item instance.

Parameters:

	item	The item to be redrawn.
	port	The destination drawing port.
	rect	The bounding box of the item.
	t	The transformer used to draw the item. Not used.
	clip	The clipping area.

See also:

IlvGadgetItem::draw.

Reimplemented from IlvGadgetItemHolder.

virtual void IlvPopupMenu::empty

(

)

[virtual]

Empties the list.

See also:

setItems, removeItem

Reimplemented from IlvAbstractMenu.

static void IlvPopupMenu::EnableToolTips

(

IlBoolean

value = IlTrue

)

[static]

Specifies whether pop-up menus should display tooltips.

Use this setting to enable or disable tooltips at the class level.

Parameters:

value

A Boolean value specifying whether pop-up menus of the application should display tooltips (IlTrue) or not (IlFalse). If value is IlTrue, then each instance of pop-up menu will choose whether to display tooltips or not by using the value set by IlvPopupMenu::useToolTips. If value is IlFalse, tooltips are disabled for all the pop-up menus of the application.

See also:

useToolTips, AreToolTipsEnabled

IlShort IlvPopupMenu::get	(	const IlvPoint &	point,
		IlvView *	parent = 0
	)

Displays the menu at the specified location and waits until a selection is made.

Calls IlvPopupMenu::show, enters a modal loop, and waits until the pop-up menu is hidden.

Parameters:

	point	The location where the menu is displayed.
	parent	The parent view for which the menu container is transient. For details on transient windows, see the IlvView constructors.

Returns:

The index of the selected item or -1 if there is no selected item.

See also:

show, hide

virtual IlvPalette* IlvPopupMenu::getHighlightTextPalette

(

)

const [virtual]

Returns the highlight palette used to draw the label of highlighted items.

Returns:

The palette used to draw the label of highlighted items.

Reimplemented from IlvGadgetItemHolder.

virtual IlvDim IlvPopupMenu::getLabelOffset

(

)

const [virtual]

Returns the offset applied to each item label.

Returns:

The offset applied to each item label or 0 if no offset has been defined.

See also:

setLabelOffset, autoLabelAlignment(IlBoolean, IlBoolean)

Reimplemented from IlvListGadgetItemHolder.

IlvGraphicCallback IlvPopupMenu::getOpenMenuCallback

(

)

const

Returns a pointer to the first unnamed callback in the Open Menu callback list.

Returns:

The function pointer to the first unnamed callback in the Open Menu callback list.

See also:

setOpenMenuCallback, addOpenMenuCallback

IlSymbol* IlvPopupMenu::getOpenMenuCallbackName

(

)

const

Returns the name of the first named callback in the Open Menu callback list.

Returns:

Returns a symbol representing the name of the first named callback in the Open Menu callback list.

See also:

setOpenMenuCallbackName, getOpenMenuCallback

IlvContainer* IlvPopupMenu::getTopView

(

)

const

Returns a pointer to the container associated with the pop-up menu.

When a pop-up menu is shown using IlvPopupMenu::show or IlvPopupMenu::get, an instance of the IlvContainer class is created to display the pop-up menu.

Returns:

A pointer to the container associated with the pop-up menu. If the menu has never been shown, the method returns 0 .

See also:

show, get, hide

IlBoolean IlvPopupMenu::hasToolTips

(

)

const [virtual]

Indicates whether the pop-up menu displays tooltips.

Returns:

IlTrue if the pop-up menu handles tooltips and IlFalse if it does not.

See also:

useToolTips, EnableToolTips

Reimplemented from IlvGadgetItemHolder.

virtual void IlvPopupMenu::hide

(

)

[virtual]

Hides the pop-up menu.

See also:

show, get

IlBoolean IlvPopupMenu::isDoubleBuffering

(

)

const

Tests the double buffering setting.

Returns:

A value that specifies whether (IlTrue) or not (IlFalse) the container associated with the pop-up menu is actually using double buffering.

virtual IlBoolean IlvPopupMenu::isGrabbed

(

)

const [virtual]

Returns IlTrue if the pop-up menu is visible and grabbed.

Returns:

IlTrue if the pop-up menu is visible and grabbed.

See also:

show, get

Implements IlvAbstractMenu.

IlBoolean IlvPopupMenu::isVisible

(

)

const

Indicates whether the pop-up menu is visible.

Returns:

IlTrue if the pop-up menu is visible and IlFalse otherwise.

See also:

show, hide

virtual void IlvPopupMenu::itemBBox	(	IlUShort	index,
		IlvRect &	bbox,
		const IlvTransformer *	t = 0
	)			const [virtual]

Returns the bounding box of a menu item in the menu.

Uses bbox to return the bounding box of the item specified by index when the object is displayed with the transformer t.

Parameters:

	index	The index of the item.
	bbox	The returned menu item's bounding box.
	t	The transformer used to compute the item's bounding box.

Implements IlvAbstractMenu.

static IlSymbol* IlvPopupMenu::OpenMenuCallbackSymbol

(

)

[static]

Returns the symbol of the Open Menu callback list.

Returns:

The symbol of the Open Menu callback list.

See also:

setOpenMenuCallback, IlvGraphic::setCallback

virtual void IlvPopupMenu::recomputeAllItems

(

)

[virtual]

Recomputes the size of all the items managed by the holder.

Calls the IlvGadgetItem::recomputeSize member function for all the items managed by this holder.

See also:

IlvGadgetItem::recomputeSize, applyToItems.

Reimplemented from IlvAbstractMenu.

virtual void IlvPopupMenu::select

(

IlUShort

pos

)

[virtual]

Is called when an item has been selected.

Parameters:

pos

The index of the selected item.

See also:

unSelect

Reimplemented from IlvAbstractMenu.

virtual void IlvPopupMenu::setDoubleBuffering

(

IlBoolean

value

)

[virtual]

Sets double buffering.

Use this member function to indicate whether or not the container associated with the pop-up menu should use double buffering.

Parameters:

value

A Boolean value indicating if the container associated with the pop-up menu should use double buffering (IlTrue) or not (IlFalse).

See also:

getTopView

void IlvPopupMenu::setLabelOffset	(	IlvDim	offset,
		IlBoolean	redraw = IlTrue
	)

Sets the label offset of the pop-up menu.

When a label offset is defined, all the item labels are aligned using this offset. Calling this method disables the automatic alignment mode.

Parameters:

	offset	The new label offset.
	redraw	A Boolean value specifying whether the pop-up menu should be redrawn.

See also:

getLabelOffset, autoLabelAlignment(IlBoolean, IlBoolean)

void IlvPopupMenu::setOpenMenuCallback	(	IlSymbol *	callbackName,
		IlAny	arg
	)

Sets a named Open Menu callback.

Removes all the existing Open Menu callbacks before adding callbackName to the Open Menu callback list. The callback function, when invoked, receives the user parameter arg. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

	callbackName	The name of the new callback.
	arg	The callback argument.

See also:

addOpenMenuCallback, getOpenMenuCallbackName

void IlvPopupMenu::setOpenMenuCallback	(	IlvGraphicCallback	callback,
		IlAny	arg
	)

Sets an Open Menu callback.

Removes all the existing Open Menu callbacks before adding callback to the Open Menu callback list. The callback function, when invoked, receives the user parameter arg. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

	callback	A pointer to the new callback.
	arg	The callback argument.

See also:

addOpenMenuCallback, getOpenMenuCallback

void IlvPopupMenu::setOpenMenuCallback

(

IlSymbol *

callbackName

)

Sets a named Open Menu callback.

Removes all the existing Open Menu callbacks before adding callbackName to the Open Menu callback list. An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

callbackName

The name of the new callback.

See also:

addOpenMenuCallback, getOpenMenuCallbackName

void IlvPopupMenu::setOpenMenuCallback

(

IlvGraphicCallback

callback

)

Sets an Open Menu callback.

Removes all the existing Open Menu callbacks before adding callback to the Open Menu callback list. A Open Menu callback is An Open Menu callback is invoked before the pop-up menu is displayed.

Parameters:

callback

A pointer to the new callback.

See also:

OpenMenu, addOpenMenuCallback, getOpenMenuCallback

virtual void IlvPopupMenu::show	(	const IlvPoint &	point,
		IlBoolean	grab = IlTrue,
		IlvView *	parent = 0
	)			[virtual]

Displays the menu at the specified location.

Creates and displays an IlvContainer object that contains the pop-up menu.

Parameters:

	point	The location where the menu is displayed.
	grab	A Boolean value specifying whether the events occurring to the menu container should be grabbed.
	parent	The parent view for which the menu container is transient. For details on transient windows, see the IlvView constructors.

See also:

get, IlvView, hide

virtual void IlvPopupMenu::unSelect

(

IlUShort

pos

)

[virtual]

Is called when an item has been deselected.

Parameters:

pos

The index of the unselected item.

See also:

select

Reimplemented from IlvAbstractMenu.

void IlvPopupMenu::useToolTips

(

IlBoolean

value

)

Specifies whether the pop-up menu should display tooltips.

The tooltips associated with menu items are displayed when the mouse remains over the items for a short period of time. For details on how to set tooltips to menu items, see IlvMenuItem::setToolTip.

Parameters:

value

A Boolean value specifying whether the pop-up menu should display tooltips (IlTrue) or not (IlFalse).

See also:

hasToolTips, IlvMenuItem::setToolTip