View container class. More...

#include <ilviews/gadgets/gadcont.h>

Inheritance diagram for IlvGadgetContainer:

Public Member Functions
	IlvGadgetContainer (IlvDisplay display, const char name, const char *title, const IlvRect &rect, IlBoolean useacc=IlFalse, IlBoolean visible=IlTrue)
	Initializes a new instance of the `IlvGadgetContainer` class as a top view. More...

	IlvGadgetContainer (IlvDisplay display, const char name, const char *title, const IlvRect &rect, IlUInt properties, IlBoolean useacc=IlFalse, IlBoolean visible=IlTrue, IlvSystemView transientFor=0)
	Initializes a new instance of the `IlvGadgetContainer` class as a top view. More...

	IlvGadgetContainer (IlvAbstractView *parent, const IlvRect &rect, IlBoolean useacc=IlFalse, IlBoolean visible=IlTrue)
	Initializes a new instance of the `IlvGadgetContainer` class as a child view of another view. More...

	IlvGadgetContainer (IlvDisplay *display, IlvSystemView parent, const IlvRect &rect, IlBoolean useacc=IlFalse, IlBoolean visible=IlTrue)
	Initializes a new instance of the `IlvGadgetContainer` class as a child view of a system view. More...

	IlvGadgetContainer (IlvDisplay *display, IlvSystemView window, IlBoolean useacc=IlFalse)
	Initializes a new instance of the `IlvGadgetContainer` class using an existing system view. More...

virtual IlBoolean	allowFocus (IlBoolean value)
	Specifies whether the container manages the focus. More...

virtual void	applyResize (IlFloat sx, IlFloat sy, IlBoolean redraw=IlTrue)
	Is called to carry out the resize events applying to the gadget container. More...

IlBoolean	autoResize (IlBoolean a)
	Sets the auto resize mode of the gadget container. More...

IlvButton *	getDefaultButton () const
	Returns the default button of the gadget container. More...

virtual IlvGraphic *	getFirstFocusGraphic () const
	Returns the first object that receives the focus in this container. More...

virtual IlvGraphic *	getFocus () const
	Returns the object that has the keyboard focus in the gadget container. More...

virtual IlvGraphic *	getGrab () const
	Returns the object that is currently grabbing events in the container. More...

virtual IlvGraphic *	getLastFocusGraphic () const
	Returns the last object that receives the focus in this container. More...

IlvLookFeelHandler *	getLookFeelHandler () const
	Returns the look and feel handler associated with this container. More...

virtual IlvGraphic *	getNextFocusGraphic (IlvGraphic *object) const
	Returns the next object that will receive the focus after the specified object. More...

IlvGraphic *	getOverriddenFocus () const
	Returns the object that will receive the focus after calling `setFocus()`. More...

virtual IlvGraphic *	getPreviousFocusGraphic (IlvGraphic *object) const
	Returns the previous object that received the focus before the specified object. More...

IlBoolean	isAutoResizing () const
	Indicates whether the gadget container gets resized when loading a file. More...

virtual IlBoolean	isFocusAllowed () const
	Indicates whether the focus is allowed in the container. More...

virtual void	moveFocusAfter (IlBoolean redraw=IlTrue)
	Is called to find the next focusable object. More...

virtual void	moveFocusBefore (IlBoolean redraw=IlTrue)
	Is called to find the previous focusable object. More...

void	overrideFocus (IlvGraphic *obj)
	Sets the object that will receive the focus after calling `setFocus()`. More...

virtual void	removeGrab ()
	Cancels the grabbing settings defined with `setGrab()`. More...

void	setDefaultButton (IlvButton *button, IlBoolean redraw=IlTrue)
	Sets the default button of the gadget container. More...

virtual void	setFocus (IlvGraphic *graphic=0, IlBoolean redraw=IlTrue)
	Sets the focus to the specified object of the gadget container. More...

virtual void	setGrab (IlvGraphic *object)
	Sets the specified object as the grabbing object. More...

void	setLookFeelHandler (IlvLookFeelHandler *lfh)
	Sets the look and feel handler of this container. More...

Detailed Description

View container class.

Library: ilvgadgt
IlvGadgetContainer is a predefined subtype of the IlvContainer class used for storing, displaying, and manipulating gadgets. It has special member functions for handling:

keyboard focus.
grabbing objects (this is when an object interactor receives all input events)
attachments of objects to the container

The keyboard focus determines which gadget must receive keyboard events when the view gets the focus. The IlvGadgetContainer class features a keyboard navigation mechanism that lets the end user give the keyboard focus to any gadget by cycling through the list of objects using the Tab key (and sometimes the arrow keys). The IlvGadgetContainer class determines which gadget will be the next to get the keyboard 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 container to use a given order in keyboard navigation, that is, define its own focus chain.

Although the IlvContainer class allows you, if your display device has touch-screen capability, to use it to pan, zoom or rotate the view using regular multi-touch gestures, the IlvGadgetContainer does not: you usually do not want gadget containers to change their IlvTransformer.
If you do want this, you can set the environment variable ILVTOUCHSCREENNAVIGATION or the display resource touchScreenNavigation to true. This will force this behavior for every window of your application.
You can also set the display resource touchScreenNavigation specifically for your IlvGadgetContainer class or identifier.

See also: IlvGadget, IlvDialog.

Accessors

Accessors provide a scriptable and uniform way to inspect and modify an object by using its base class methods IlvValueInterface::queryValue(), IlvValueInterface::queryValues(), IlvValueInterface::changeValue(), IlvValueInterface::changeValues(). This class inherits the accessors of its superclass IlvContainer and adds the following ones:

Data accessors

Name	Type	Equivalent methods
`allowFocus`	Boolean	`isFocusAllowed()`, `allowFocus()`
`autoResize`	Boolean	`isAutoResizing()`, `autoResize()`

Method accessors

Name	Return type	Equivalent methods
`IlvGadgetContainer(String name, String title, IlvRect position, Boolean useacc = true, IlvAbstractView transientFor = 0)`	`IlvGadgetContainer`	See [Constructor note] below.
`getFocus()`	`IlvGraphic`	`getFocus()`
`setFocus(IlvGraphic object)`	Void	`setFocus(IlvGraphic* object, IlBoolean)`
`getGrab()`	`IlvGraphic`	`getGrab()`
`setGrab(IlvGraphic object)`	Void	`setGrab(IlvGraphic* object)`
`removeGrab()`	Void	`removeGrab()`

[Constructor note]: using this accessor allows to create an instance of IlvGadgetContainer from a script. For example:

mypanel = new IlvGadgetContainer("panel", "My panel",

new IlvRect(10, 10, 400, 300));

This is equivalent to the following C++ code :

new IlvGadgetContainer(display, // Deduced from the calling context
                       "panel",
                       "My panel",
                       IlvRect(10, 10, 400, 300)
                       0, // Window properties
                       IlTrue, // Use accelerators (default value)
                       IlTrue, // Visible
                       0); // Transient parent (default value)

Constructor & Destructor Documentation

§ IlvGadgetContainer() [1/5]

IlvGadgetContainer::IlvGadgetContainer	(	IlvDisplay *	display,
		const char *	name,
		const char *	title,
		const IlvRect &	rect,
		IlBoolean	useacc = `IlFalse`,
		IlBoolean	visible = `IlTrue`
	)

Initializes a new instance of the IlvGadgetContainer class as a top view.

Parameters

display	The connection to the display.
name	The name of the gadget container.
title	The title of the gadget container.
rect	The size and position of the gadget container.
useacc	Specifies whether the gadget container should install the default keyboard accelerators.
visible	Specifies whether the gadget container should be visible.

§ IlvGadgetContainer() [2/5]

IlvGadgetContainer::IlvGadgetContainer	(	IlvDisplay *	display,
		const char *	name,
		const char *	title,
		const IlvRect &	rect,
		IlUInt	properties,
		IlBoolean	useacc = `IlFalse`,
		IlBoolean	visible = `IlTrue`,
		IlvSystemView	transientFor = `0`
	)

Initializes a new instance of the IlvGadgetContainer class as a top view.

Parameters

display	The connection to the display.
name	The name of the gadget container.
title	The title of the gadget container.
rect	The size and position of the gadget container.
properties	The properties of the gadget container. For more details, see the `IlvView` constructors.
useacc	Specifies whether the gadget container should install the default keyboard accelerators.
visible	Specifies whether the gadget container should be visible.
transientFor	A system view for which the gadget container is transient. For more details, see the `IlvView` constructors.

§ IlvGadgetContainer() [3/5]

IlvGadgetContainer::IlvGadgetContainer	(	IlvAbstractView *	parent,
		const IlvRect &	rect,
		IlBoolean	useacc = `IlFalse`,
		IlBoolean	visible = `IlTrue`
	)

Initializes a new instance of the IlvGadgetContainer class as a child view of another view.

Parameters

parent	The parent view of the gadget container.
rect	The size and position of the gadget container.
useacc	Specifies whether the gadget container should install the default keyboard accelerators.
visible	Specifies whether the gadget container should be visible.

§ IlvGadgetContainer() [4/5]

IlvGadgetContainer::IlvGadgetContainer	(	IlvDisplay *	display,
		IlvSystemView	parent,
		const IlvRect &	rect,
		IlBoolean	useacc = `IlFalse`,
		IlBoolean	visible = `IlTrue`
	)

Initializes a new instance of the IlvGadgetContainer class as a child view of a system view.

Parameters

display	The connection to the display.
parent	The parent view of the gadget container.
rect	The size and position of the gadget container.
useacc	Specifies whether the gadget container should install the default keyboard accelerators.
visible	Specifies whether the gadget container should be visible.

§ IlvGadgetContainer() [5/5]

IlvGadgetContainer::IlvGadgetContainer	(	IlvDisplay *	display,
		IlvSystemView	window,
		IlBoolean	useacc = `IlFalse`
	)

Initializes a new instance of the IlvGadgetContainer class using an existing system view.

Parameters

display	The connection to the display.
window	The system view to which the gadget container will be mapped.
useacc	Specifies whether the gadget container should install the default keyboard accelerators.

Member Function Documentation

§ allowFocus()

virtual IlBoolean IlvGadgetContainer::allowFocus ( IlBoolean value )

virtual

Specifies whether the container manages the focus.

Parameters

value Specifies whether the container manages the focus (IlTrue).

See also: isFocusAllowed(), setFocus().

§ applyResize()

virtual void IlvGadgetContainer::applyResize	(	IlFloat	sx,
		IlFloat	sy,
		IlBoolean	redraw = `IlTrue`
	)

virtual

Is called to carry out the resize events applying to the gadget container.

This method is called internally to carry out any resize events applying to the view, and to manage the objects changes according to their attachments. It deals with the old Rogue Wave Views attachment model. If you want to use the new one, see the IlvGraphicHolder::attach() method.

Parameters

sx	The scale factor that applies to the container width.
sy	The scale factor that applies to the container height.
redraw	Specifies whether the container should be redrawn.

See also: IlvSetAttachment()

§ autoResize()

IlBoolean IlvGadgetContainer::autoResize ( IlBoolean a )

Sets the auto resize mode of the gadget container.

Parameters

a	Specifies whether the gadget container should be resized automatically when data containing size information is loaded.

Returns: IlTrue if the container should be resized automatically and IlFalse otherwise.

See also: isAutoResizing().

§ getDefaultButton()

IlvButton* IlvGadgetContainer::getDefaultButton ( ) const

Returns the default button of the gadget container.

Returns: A pointer to the default button of the gadget container, or 0 if this gadget container has no default button.

See also: IlvGadgetContainer::setDefaultButton().

§ getFirstFocusGraphic()

virtual IlvGraphic* IlvGadgetContainer::getFirstFocusGraphic ( ) const

virtual

Returns the first object that receives the focus in this container.

Note: This member function links the objects using their names. Redefining them would break this mechanism.

Returns: The first object that receives the focus in this container. The object must satisfy the conditions listed in the description of IlvGadgetContainer::getNextFocusGraphic().

See also: getPreviousFocusGraphic(), getLastFocusGraphic().

§ getFocus()

virtual IlvGraphic* IlvGadgetContainer::getFocus ( ) const

virtual

Returns the object that has the keyboard focus in the gadget container.

Returns: The object that has the keyboard focus in this gadget container or 0 if no object has the focus.

See also: setFocus(), allowFocus().

§ getGrab()

virtual IlvGraphic* IlvGadgetContainer::getGrab ( ) const

virtual

Returns the object that is currently grabbing events in the container.

Returns: The object that is currently grabbing events in this container, or 0 if there is no grabbing object in this container.

See also: setGrab(), removeGrab().

§ getLastFocusGraphic()

virtual IlvGraphic* IlvGadgetContainer::getLastFocusGraphic ( ) const

virtual

Returns the last object that receives the focus in this container.

Note: This member function links the objects using their names. Redefining them would break this mechanism.

Returns: The last object that receives the focus in this container. The object must satisfy the conditions listed in the description of IlvGadgetContainer::getNextFocusGraphic().

See also: getNextFocusGraphic(), getFirstFocusGraphic().

§ getLookFeelHandler()

IlvLookFeelHandler* IlvGadgetContainer::getLookFeelHandler ( ) const

Returns the look and feel handler associated with this container.

Returns: The look and feel handler associated with this container.

§ getNextFocusGraphic()

virtual IlvGraphic* IlvGadgetContainer::getNextFocusGraphic ( IlvGraphic * object ) const

virtual

Returns the next object that will receive the focus after the specified object.

By default, the focus chain goes from left to right and from top to bottom.

The method looks for an object that satisfies the following conditions:

Is visible (method IlvContainer::isVisible())
Is sensitive (method IlvGraphic::isSensitive())
Has an associated interactor (or is active and focusable if the object is a gadget)

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

Note: This member function links the objects using their names. Redefining them would break this mechanism.

Parameters

object The graphic object.

Returns: The object that will receive the focus after object. The method returns IlvGadgetContainer::getFirstFocusGraphic() when object is 0. If no valid object is found, the method returns 0.

See also: getPreviousFocusGraphic(), getFocus(), getLastFocusGraphic().

§ getOverriddenFocus()

IlvGraphic* IlvGadgetContainer::getOverriddenFocus ( ) const

Returns the object that will receive the focus after calling setFocus().

Returns: The object that will receive the focus after calling setFocus().

See also: overrideFocus(), setFocus().

§ getPreviousFocusGraphic()

virtual IlvGraphic* IlvGadgetContainer::getPreviousFocusGraphic ( IlvGraphic * object ) const

virtual

Returns the previous object that received the focus before the specified object.

By default, the focus chain goes from left to right and from top to bottom.

The method looks for an object that satisfies the following conditions:

Is visible (method IlvContainer::isVisible())
Is sensitive (method IlvGraphic::isSensitive())
Has an associated interactor (or is active and focusable if the object is a gadget)

The search is performed up the focus chain, starting before object.

Note: This member function links the objects using their names. Redefining them would break this mechanism.

Parameters

object The graphic object.

Returns: The object that had the focus before object. The method returns IlvGadgetContainer::getFirstFocusGraphic() when object is 0. If no valid object is found, the method returns 0.

See also: getNextFocusGraphic(), getFocus(), getFirstFocusGraphic().

§ isAutoResizing()

IlBoolean IlvGadgetContainer::isAutoResizing ( ) const

Indicates whether the gadget container gets resized when loading a file.

Returns: IlTrue if this gadget container gets resized automatically when data containing size information is loaded. Otherwise, the container keeps its original dimensions.

See also: autoResize().

§ isFocusAllowed()

virtual IlBoolean IlvGadgetContainer::isFocusAllowed ( ) const

virtual

Indicates whether the focus is allowed in the container.

Returns: IlTrue if this gadget container handles the focus for the objects it stores and IlFalse otherwise.

See also: setFocus(), allowFocus().

§ moveFocusAfter()

virtual void IlvGadgetContainer::moveFocusAfter ( IlBoolean redraw = IlTrue )

virtual

Is called to find the next focusable object.

Calls IlvGadgetContainer::getNextFocusGraphic() with the object currently having the focus to get the next valid object in the focus chain, then calls IlvGadgetContainer::setFocus() on it.

If getNextFocusGraphic() returns 0, the result of IlvGadgetContainer::getFirstFocusGraphic() is used instead.

Parameters

redraw Specifies whether the gadget container should be redrawn.

See also: moveFocusBefore(), getFirstFocusGraphic(), getFocus().

§ moveFocusBefore()

virtual void IlvGadgetContainer::moveFocusBefore ( IlBoolean redraw = IlTrue )

virtual

Is called to find the previous focusable object.

Calls IlvGadgetContainer::getPreviousFocusGraphic() with the object currently having the focus to get the previous valid object in the focus chain, then calls IlvGadgetContainer::setFocus() on it.

If getPreviousFocusGraphic() returns 0, the result of IlvGadgetContainer::getLastFocusGraphic() is used instead.

Parameters

redraw Specifies whether the gadget container should be redrawn.

See also: moveFocusAfter(), getLastFocusGraphic(), getFocus().

§ overrideFocus()

void IlvGadgetContainer::overrideFocus ( IlvGraphic * obj )

Sets the object that will receive the focus after calling setFocus().

Has no effect if it is not called from a Focus Out callback or from the IlvGadget::focusOut() member function.

See also: getOverriddenFocus(), setFocus().

§ removeGrab()

virtual void IlvGadgetContainer::removeGrab ( )

virtual

Cancels the grabbing settings defined with setGrab().

See also: getGrab(), setGrab().

§ setDefaultButton()

void IlvGadgetContainer::setDefaultButton	(	IlvButton *	button,
		IlBoolean	redraw = `IlTrue`
	)

Sets the default button of the gadget container.

The default button is triggered when the user presses the Return or Enter key in the dialog, even though it does not have the keyboard focus. Note that button doesn't need to be located in this gadget container.

Parameters

button	The new default button.
redraw	Specifies whether the dialog should be redrawn.

See also: IlvGadgetContainer::getDefaultButton(), IlvGadget::usesDefaultButtonKeys().

§ setFocus()

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

virtual

Sets the focus to the specified object of the gadget container.

Sends an IlvKeyboardFocusOut event to the previous focused object, and an IlvKeyboardFocusIn event to graphic. If you set a Focus Out callback (see IlvGadget::setFocusOutCallback()) on the previous focused object, it is possible inside this callback to force the gadget container not to give the focus to graphic, but to another object by using the method IlvGadgetContainer::overrideFocus(). This is useful if the Focus Out callback validates the previous focused object. In this case, if validation does not succeed, you may want to keep the focus on this object to give the user another try.

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

Parameters

graphic	The object that is given the keyboard focus.
redraw	Specifies whether the gadget container should be redrawn.

See also: getFocus(), isFocusAllowed(), IlvGadget::setFocusOutCallback(), overrideFocus().

§ setGrab()

virtual void IlvGadgetContainer::setGrab ( IlvGraphic * object )

virtual

Sets the specified object as the grabbing object.

Events will be sent to object. If this object has no associated interactor, the events will be lost.

Parameters

object The grabbing object.

See also: getGrab(), removeGrab().

§ setLookFeelHandler()

void IlvGadgetContainer::setLookFeelHandler ( IlvLookFeelHandler * lfh )

Sets the look and feel handler of this container.

Parameters

lfh	The new look and feel handler.

Public Member Functions

Detailed Description

Accessors

Data accessors

Method accessors

Constructor & Destructor Documentation

§ IlvGadgetContainer() [1/5]

§ IlvGadgetContainer() [2/5]

§ IlvGadgetContainer() [3/5]

§ IlvGadgetContainer() [4/5]

§ IlvGadgetContainer() [5/5]

Member Function Documentation

§ allowFocus()

§ applyResize()

§ autoResize()

§ getDefaultButton()

§ getFirstFocusGraphic()

§ getFocus()

§ getGrab()

§ getLastFocusGraphic()

§ getLookFeelHandler()

§ getNextFocusGraphic()

§ getOverriddenFocus()

§ getPreviousFocusGraphic()

§ isAutoResizing()

§ isFocusAllowed()

§ moveFocusAfter()

§ moveFocusBefore()

§ overrideFocus()

§ removeGrab()

§ setDefaultButton()

§ setFocus()

§ setGrab()

§ setLookFeelHandler()