IlvGadgetManager Class Reference

Gadget class. More...

#include <ilviews/gadmgr/gadmgr.h>

Inheritance diagram for IlvGadgetManager:

Public Member Functions
	IlvGadgetManager (IlvDisplay *display, int layers=2, IlBoolean useacc=IlTrue, IlUShort maxInList=IlvMaxObjectsInList, IlUShort maxInNode=IlvMaxObjectsInList)
	Constructor.
virtual void	addObject (const char objectName, IlvGraphic obj, IlBoolean redraw=IlTrue, int layer=-1)
	Adds a graphic object to a manager, and then names the object.
virtual void	addObject (IlvGraphic *obj, IlBoolean redraw=IlTrue, int layer=-1)
	Adds an object to the manager.
virtual void	addView (IlvView *view)
	Adds a view to the manager.
virtual IlBoolean	allowFocus (IlBoolean flag)
	Enable or disables keyboard focus handling.
void	applyResize (IlvView view, IlvGraphic g, IlBoolean redraw=IlTrue)
	Resolves attachment constraints for an object when the view is resized.
virtual void	applyResize (IlvView view, IlvGraphic g, IlFloat sx, IlFloat sy, IlBoolean redraw=IlTrue)
	Resolves attachment constraints for an object when the view is resized.
void	applyResize (IlvView *view, IlBoolean redraw=IlTrue)
	Resolves attachment constraints when the view is resized.
virtual void	applyResize (IlvView *view, IlFloat sx, IlFloat sy, IlBoolean redraw=IlTrue)
	Resolves attachment constraints when the view is resized.
IlBoolean	autoResize (IlBoolean a)
	Sets the auto resizing mechanism.
virtual IlBoolean	dispatchToObjects (IlvEvent &event, IlvView *view)
	Dispatches an event to the appropriate graphic objects.
virtual void	drawFocus (IlvPort dst, const IlvTransformer t=0, const IlvRegion *clip=0) const
	Draws the representation of the keyboard focus.
virtual IlBoolean	gadgetShortCut (IlvEvent &)
	Dispatches an event to the appropriate graphic objects.
virtual IlvGraphic *	getFirstFocusGraphic () const
	Returns the first graphic object in the focus chain.
virtual IlvGraphic *	getFocus () const
	Returns the graphic object with the keyboard focus.
virtual IlvGraphic *	getGrab () const
	Returns the grabbing graphic object.
virtual IlvGraphic *	getLastFocusGraphic () const
	Returns the last graphic object in the focus chain.
IlvLookFeelHandler *	getLookFeelHandler () const
	Returns the look and feel handler associated with this gadget manager.
virtual IlvGraphic *	getNextFocusGraphic (IlvGraphic *object) const
	Returns the next graphic object in the focus chain.
virtual IlvGraphic *	getPreviousFocusGraphic (IlvGraphic *object) const
	Returns the previous graphic object in the focus chain.
virtual void	handleInput (IlvEvent &event, IlvView *view)
	Adds an accelerator to the manager.
IlBoolean	isAutoResizing () const
	Indicates whether the auto resizing mechanism is enabled.
virtual IlBoolean	isFocusAllowed () const
	Indicates if keyboard focus handling is enabled.
virtual void	moveFocusAfter (IlBoolean redraw=IlTrue)
	Moves the keyboard focus to the next graphic object in the focus chain.
virtual void	moveFocusBefore (IlBoolean redraw=IlTrue)
	Moves the keyboard focus to the previous graphic object in the focus chain.
virtual void	removeGrab ()
virtual IlBoolean	removeView (IlvView *view)
	Removes a view from the manager view list.
virtual void	setBackground (IlvView view, IlvColor color, IlvBitmap *bitmap=0)
	Sets the background of a manager view.
virtual void	setFocus (IlvGraphic *graphic=0, IlBoolean redraw=IlTrue)
	Sets the keyboard focus on a graphic object.
virtual void	setGrab (IlvGraphic *object)
	Sets a graphic object to grab events.
void	setLookFeelHandler (IlvLookFeelHandler *lfh)
	Sets the look and feel handler of this gadget manager.
virtual void	setSelected (IlvGraphic *, IlBoolean selected=IlTrue, IlBoolean erase=IlTrue)
	Selects or deselects a graphic object.
virtual void	viewResized (const IlvView *, IlvRect &)
	Draws a graphic object in a manager view by means of a temporary pixmap.

Detailed Description

Gadget class.

Library: ilvgadmgr

The IlvGadgetManager class creates a manager that is specifically designed to handle gadgets. It has special member functions handling the input focus and the grabbing of an object (so that the object interactor attached to the grabbing object receives every event). This class also manages the attachments of objects to the view in which they are located. The input focus determines which gadget must receive keyboard events when a view gets the focus. The IlvGadgetManager has a keyboard navigation mechanism allowing the end user to give the input focus to any gadget by cycling through the list of objects using the Tab key (and sometimes the arrow keys). The IlvGadgetManager must decide which gadget will be the next to get the input focus at each step of keyboard navigation; the default algorithm is based on the geometry of the gadgets (from left to right and from top to bottom). The programmer can force the use of a given order in keyboard navigation, that is, define its own focus chain.

See also:: IlvGraphic ("Gadget Properties" and "Focus Chain Management" member functions).

Constructor & Destructor Documentation

IlvGadgetManager::IlvGadgetManager	(	IlvDisplay *	display,
		int	layers = `2`,
		IlBoolean	useacc = `IlTrue`,
		IlUShort	maxInList = `IlvMaxObjectsInList`,
		IlUShort	maxInNode = `IlvMaxObjectsInList`
	)

Constructor.

Initializes a new instance of the IlvGadgetManager class, with the same initialization parameters as those described for the IlvManager class.

Member Function Documentation

virtual void IlvGadgetManager::addObject	(	const char *	name,
		IlvGraphic *	object,
		IlBoolean	redraw = `IlTrue`,
		int	layer = `-1`
	)			`[virtual]`

Adds a graphic object to a manager, and then names the object.

This function is equivalent to

 addObject(object, redraw, layer);
 setObjectName(object, name);

If the object has a name that is already in use in the manager, the name is removed from the object. For more information, see the description of the IlvManager::addObject member function.

Parameters:

	name	Specifies the name to set on the object.
	object	The graphic object.
	redraw	Indicates whether the manager must immediately display the object.
	layer	Specifies the layer index where the object must be inserted. The default value `-1` indicates that the object is stored in the last (topmost) layer.

Warning:: [note] See "Note" under the first IlvManager::addObject member function.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::addObject	(	IlvGraphic *	object,
		IlBoolean	redraw = `IlTrue`,
		int	layer = `-1`
	)			`[virtual]`

Adds an object to the manager.

If an object is inserted in a non-existent layer, the layer, as well as any intermediate ones, are automatically created. For example, by default, a manager is created with three layers (0, 1 and 2); the code

 addObject(obj, IlTrue, 5);

creates layers 3, 4, and 5. An object cannot be added to a manager more than once.

Parameters:

	object	The graphic object.
	redraw	Indicates whether the manager must immediately display the object.
	layer	Specifies the layer index where the object must be inserted. The default value `-1` indicates that the object is stored in the last (topmost) layer.

Warning:: [note] You can accelerate the process of storing and removing objects to and from the manager. When you call IlvManager::addObject or IlvManager::removeObject, tests ensure that the data structure remains consistent. These tests ensure that an object is not stored twice, or remove an object that is not stored in this manager. You can bypass these tests and accelerate the process of storing and removing objects in a manager. See the global functions IlvGetOptimizeMode and IlvSetOptimizeMode.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::addView ( IlvView * view ) [virtual]

Adds a view to the manager.

Attaches a new view to the manager. All events are then handled by the hierarchy of interactors located in the manager.

Parameters:

view

The view.

Reimplemented from IlvManager.

virtual IlBoolean IlvGadgetManager::allowFocus ( IlBoolean flag ) [virtual]

Enable or disables keyboard focus handling.

Parameters:

flag IlTrue to enable keyboard focus handling and IlFalse to disable it.

Reimplemented from IlvManager.

void IlvGadgetManager::applyResize	(	IlvView *	view,
		IlvGraphic *	g,
		IlBoolean	redraw = `IlTrue`
	)

Resolves attachment constraints for an object when the view is resized.

Recomputes the position of a graphic object depending on its attachments settings. It corresponds to a call to the second member function applyResize, where the scaling factors are set.

Parameters:

	view	The manager view.
	g	The graphic object.
	redraw	Specifies whether to redraw the view contents.

virtual void IlvGadgetManager::applyResize	(	IlvView *	view,
		IlvGraphic *	g,
		IlFloat	sx,
		IlFloat	sy,
		IlBoolean	redraw = `IlTrue`
	)			`[virtual]`

Resolves attachment constraints for an object when the view is resized.

Does the same as the first applyResize member function for the particular graphic object.

Parameters:

	view	The manager view.
	g	The graphic object.
	sx	Horizontal scaling factor.
	sy	Vertical scaling factor.
	redraw	Specifies whether to redraw the view contents.

void IlvGadgetManager::applyResize	(	IlvView *	view,
		IlBoolean	redraw = `IlTrue`
	)

Resolves attachment constraints when the view is resized.

Recomputes the positions of all objects depending on their relative attachments. It corresponds to a call to the first member function applyResize, where the scaling factors are set.

Parameters:

	view	The manager view.
	redraw	Specifies whether to redraw the view contents.

virtual void IlvGadgetManager::applyResize	(	IlvView *	view,
		IlFloat	sx,
		IlFloat	sy,
		IlBoolean	redraw = `IlTrue`
	)			`[virtual]`

Resolves attachment constraints when the view is resized.

Applies geometric rules to satisfy all constraint attachments when the specified view is scaled by the specified factors. If this manager is not in autoResize mode, this member function does nothing (see the member function autoResize).

Parameters:

	view	The manager view.
	sx	Horizontal scaling factor.
	sy	Vertical scaling factor.
	redraw	Specifies whether to redraw the view contents.

IlBoolean IlvGadgetManager::autoResize ( IlBoolean a )

Sets the auto resizing mechanism.

Sets or unsets the mechanism for managing attachments.

Parameters:

a IlTrue to enable auto resizing and IlFalse to disable it.

virtual IlBoolean IlvGadgetManager::dispatchToObjects	(	IlvEvent &	,
		IlvView *
	)			`[virtual]`

Dispatches an event to the appropriate graphic objects.

Called by the manager event handler for every incoming user event when no view interactor was set in the view where the event occurred. It checks whether there is an object under the cursor. If there is one and if it is associated with an interactor, the event handler propagates the event to the interactor.

Returns:: IlTrue if the object interactor handled the event. If there is no object under the pointer or if its object interactor cannot handle the event, the returned value is IlFalse.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::drawFocus	(	IlvPort *	dst,
		const IlvTransformer *	t = `0`,
		const IlvRegion *	clip = `0`
	)			const `[virtual]`

Draws the representation of the keyboard focus.

Draws the graphic representation of the keyboard focus on the focus object.

Parameters:

	dst	The destination port.
	t	The transformer to apply.
	clip	The clipping region.

Reimplemented from IlvManager.

virtual IlBoolean IlvGadgetManager::gadgetShortCut ( IlvEvent & ) [virtual]

Dispatches an event to the appropriate graphic objects.

Called by the manager event handler for every incoming user event when no view interactor was set in the view where the event occurred. It checks whether there is an object under the cursor. If there is one and if it is associated with an interactor, the event handler propagates the event to the interactor.

Returns:: IlTrue if the object interactor handled the event. If there is no object under the pointer or if its object interactor cannot handle the event, the returned value is IlFalse.

Reimplemented from IlvManager.

virtual IlvGraphic* IlvGadgetManager::getFirstFocusGraphic ( ) const [virtual]

Returns the first graphic object in the focus chain.

Returns:: The first object that receives the keyboard focus.

virtual IlvGraphic* IlvGadgetManager::getFocus ( ) const [virtual]

Returns the graphic object with the keyboard focus.

Returns:: The current object that has the keyboard focus in this manager, or 0 if there is none.

Reimplemented from IlvManager.

virtual IlvGraphic* IlvGadgetManager::getGrab ( ) const [virtual]

Returns the grabbing graphic object.

Returns:: The current object that is currently grabbing in this manager. It returns 0 if there is no grabbing object in this manager.

Reimplemented from IlvManager.

virtual IlvGraphic* IlvGadgetManager::getLastFocusGraphic ( ) const [virtual]

Returns the last graphic object in the focus chain.

Returns:: The last object that receives the keyboard focus.

Warning:: [note]getFirstFocusGraphic and getLastFocusGraphic are only used by getNextFocusGraphic and getPreviousFocusGraphic to make the focus chain circular. These four member functions implement the linking of objects using their names. Redefining them would break this mechanism.

IlvLookFeelHandler* IlvGadgetManager::getLookFeelHandler ( ) const

Returns the look and feel handler associated with this gadget manager.

Returns:: The look and feel handler associated with this gadget manager.

virtual IlvGraphic* IlvGadgetManager::getNextFocusGraphic ( IlvGraphic * object ) const [virtual]

Returns the next graphic object in the focus chain.

The default focus chain orders the objects according to their position, from left to right and from top to bottom. The method looks for an object that would fulfill the following conditions:

must be visible (method IlvManager::isVisible)
must be sensitive (method IlvGraphic::isSensitive)
must have an interactor (or be active and focusable in case of a gadget)

The search is performed down the focus chain, starting after object.

Returns:: The next graphic object that must receive the keyboard focus after object. It returns getFirstFocusGraphic when object is 0. If no valid object is found, the method returns 0.

Parameters:

object

The graphic object.

virtual IlvGraphic* IlvGadgetManager::getPreviousFocusGraphic ( IlvGraphic * object ) const [virtual]

Returns the previous graphic object in the focus chain.

Returns:: The previous object that must receive the focus before object. It returns getLastFocusGraphic when object is 0. The method is similar to getNextFocusGraphic, except that the search is performed up the focus chain, starting before object.

Parameters:

object

The graphic object.

virtual void IlvGadgetManager::handleInput	(	IlvEvent &	event,
		IlvView *	view
	)			`[virtual]`

Adds an accelerator to the manager.

Creates an IlvManagerAccelerator using the same arguments and adds it to the manager. If the accelerator already matches an action in the manager accelerator watch list (see IlvAccelerator::match), the action in the list is replaced by the action described in the function parameters. Accelerator actions are called by the IlvManager::shortCut method, which uses IlvAccelerator::trigger to check whether an accelerator must be activated.

Parameters:

	f	The user function used as accelerator action.
	type	The accelerator event type.
	buttonOrKey	The accelerator event data.
	modifiers	The accelerator mandatory event modifiers.
	userArg	The accelerator action user argument.
	optModifiers	The accelerator optional event modifiers.

Reimplemented from IlvManager.

IlBoolean IlvGadgetManager::isAutoResizing ( ) const

Indicates whether the auto resizing mechanism is enabled.

Returns:: IlTrue if this gadget manager allows the automatic resizing of the objects it stores, depending on their relative graphic attachments. It returns IlFalse if this manager does not handle the attachments.

virtual IlBoolean IlvGadgetManager::isFocusAllowed ( ) const [virtual]

Indicates if keyboard focus handling is enabled.

Returns:: IlTrue if this gadget manager allows the manipulation of the keyboard focus on the objects it stores. Otherwise it returns IlFalse.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::moveFocusAfter ( IlBoolean redraw = IlTrue ) [virtual]

Moves the keyboard focus to the next graphic object in the focus chain.

Calls getNextFocusGraphic with the object that currently has the focus to get the next valid object in the focus chain, and then calls setFocus on it. If getNextFocusGraphic returns 0, the result of getFirstFocusGraphic is used instead.

Parameters:

redraw

Specifies whether to redraw the graphic objects.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::moveFocusBefore ( IlBoolean redraw = IlTrue ) [virtual]

Moves the keyboard focus to the previous graphic object in the focus chain.

Calls getPreviousFocusGraphic with the object that currently has the focus to get the previous valid object in the focus chain, and then calls setFocus on it. If getPreviousFocusGraphic returns 0, the result of getLastFocusGraphic is used instead.

Parameters:

redraw

Specifies whether to redraw the graphic objects.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::removeGrab ( ) [virtual]

Removes any grab that has been set in this manager.

Reimplemented from IlvManager.

virtual IlBoolean IlvGadgetManager::removeView ( IlvView * view ) [virtual]

Removes a view from the manager view list.

The view is no longer handled by the manager.

Parameters:

view

The manager view.

Returns:: IlTrue on success, and IlFalse on error (the view could not be detached).

Reimplemented from IlvManager.

virtual void IlvGadgetManager::setBackground	(	IlvView *	view,
		IlvColor *	color,
		IlvBitmap *	bitmap = `0`
	)			`[virtual]`

Sets the background of a manager view.

Sets the color used to erase the double buffering bitmap for the view. When the view is set to double buffering mode, the color is initially updated to the background color of the view. If you change the view background color and want to set the double buffering color accordingly, call this member function with this color. If a bitmap is specified, it will be used as the background for the view; this means that it will not remain as a single image but will be tiled to the size of the manager view. To remove properly a background bitmap that was previously set, you must do the following:

 view->setBackgroundBitmap(0); // Remove the background bitmap
 manager->setBackground(view, view->getBackground()); // Update the manager
 manager->draw(view, IlTrue); // Redraw the view

Parameters:

	view	The manager view.
	color	The background color.
	bitmap	The background bitmap.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::setFocus	(	IlvGraphic *	graphic = `0`,
		IlBoolean	redraw = `IlTrue`
	)			`[virtual]`

Sets the keyboard focus on a graphic object.

If the manager has disallowed the keyboard focus mechanism, this method has no effect.

Parameters:

	graphic	The graphic object.
	redraw	Specifies whether to redraw the graphic object.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::setGrab ( IlvGraphic * object ) [virtual]

Sets a graphic object to grab events.

Sets the grab on the specified graphic object; every event is sent to this object. If this object has no object interactor, the events are lost.

Parameters:

object

The graphic object.

Reimplemented from IlvManager.

void IlvGadgetManager::setLookFeelHandler ( IlvLookFeelHandler * lfh )

Sets the look and feel handler of this gadget manager.

Parameters:

lfh

The new look and feel handler.

virtual void IlvGadgetManager::setSelected	(	IlvGraphic *	object,
		IlBoolean	selected = `IlTrue`,
		IlBoolean	redraw = `IlTrue`
	)			`[virtual]`

Selects or deselects a graphic object.

Selects or deselects an object in the manager.

Parameters:

	object	The graphic object.
	selected	`IlTrue` if the graphic object must be selected, `IlFalse` otherwise.
	redraw	Specifies whether the manager must redraw the invalidate region occupied by the selection object.

Reimplemented from IlvManager.

virtual void IlvGadgetManager::viewResized	(	const IlvView *	,
		IlvRect &
	)			`[virtual]`

Draws a graphic object in a manager view by means of a temporary pixmap.

Draws a graphic object in a manager view using a technique similar to double-buffering: the drawings are done in a hidden pixmap, then the pixmap is displayed in the manager view at once. Unlike with true double-buffering, the pixmap is temporary and has the size of the object bounding box, not the whole view.

Parameters:

	view	The manager view.
	object	The graphic object.

Reimplemented from IlvManager.

Rogue Wave ViewsManager Package API Reference Guide

IlvGadgetManager Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Rogue Wave Views
Manager Package API Reference Guide