Rogue Wave Views
Gadgets Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions
IlvGadgetContainer Class Reference

View container class. More...

#include <ilviews/gadgets/gadcont.h>

Inheritance diagram for IlvGadgetContainer:
IlvContainer IlvStylist IlvDrawingView IlvView IlvAbstractView IlvSystemPort IlvStylable IlvPort IlvValueInterface IlvDialog IlvPanedContainer IlvScrolledView IlvViewFrame IlvColorSelector IlvFileChooser IlvFontSelector IlvGradientSelector IlvIFileSelector IlvIMessageDialog IlvIPromptString IlvPageMarginDialog IlvPostScriptPrinterDialog IlvPrinterPreviewDialog IlvDockableContainer

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...
 
IlvButtongetDefaultButton () const
 Returns the default button of the gadget container. More...
 
virtual IlvGraphicgetFirstFocusGraphic () const
 Returns the first object that receives the focus in this container. More...
 
virtual IlvGraphicgetFocus () const
 Returns the object that has the keyboard focus in the gadget container. More...
 
virtual IlvGraphicgetGrab () const
 Returns the object that is currently grabbing events in the container. More...
 
virtual IlvGraphicgetLastFocusGraphic () const
 Returns the last object that receives the focus in this container. More...
 
IlvLookFeelHandlergetLookFeelHandler () const
 Returns the look and feel handler associated with this container. More...
 
virtual IlvGraphicgetNextFocusGraphic (IlvGraphic *object) const
 Returns the next object that will receive the focus after the specified object. More...
 
IlvGraphicgetOverriddenFocus () const
 Returns the object that will receive the focus after calling setFocus(). More...
 
virtual IlvGraphicgetPreviousFocusGraphic (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:

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
displayThe connection to the display.
nameThe name of the gadget container.
titleThe title of the gadget container.
rectThe size and position of the gadget container.
useaccSpecifies whether the gadget container should install the default keyboard accelerators.
visibleSpecifies 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
displayThe connection to the display.
nameThe name of the gadget container.
titleThe title of the gadget container.
rectThe size and position of the gadget container.
propertiesThe properties of the gadget container. For more details, see the IlvView constructors.
useaccSpecifies whether the gadget container should install the default keyboard accelerators.
visibleSpecifies whether the gadget container should be visible.
transientForA 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
parentThe parent view of the gadget container.
rectThe size and position of the gadget container.
useaccSpecifies whether the gadget container should install the default keyboard accelerators.
visibleSpecifies 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
displayThe connection to the display.
parentThe parent view of the gadget container.
rectThe size and position of the gadget container.
useaccSpecifies whether the gadget container should install the default keyboard accelerators.
visibleSpecifies 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
displayThe connection to the display.
windowThe system view to which the gadget container will be mapped.
useaccSpecifies 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
valueSpecifies 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
sxThe scale factor that applies to the container width.
syThe scale factor that applies to the container height.
redrawSpecifies 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
aSpecifies 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:

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
objectThe 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:

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
objectThe 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
redrawSpecifies 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
redrawSpecifies 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
buttonThe new default button.
redrawSpecifies 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
graphicThe object that is given the keyboard focus.
redrawSpecifies 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
objectThe grabbing object.
See also
getGrab(), removeGrab().

§ setLookFeelHandler()

void IlvGadgetContainer::setLookFeelHandler ( IlvLookFeelHandler lfh)

Sets the look and feel handler of this container.

Parameters
lfhThe new look and feel handler.

© Copyright 2018, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.