Reference Page for vwWidget

vwWidget is the abstract class from which all other widgets in this library are publicly inherit. Since vwWidget is publicly derived from vwSubject, all subsequent derivations of vwWidget inherit the ability to attach() vwObservers to themselves, and inherit the notify() method which generates an update() in all vwObservers attached to a notifying widget. This message passing follows an observer pattern with a mediator pattern. The abstract mediator class is vwMediator. The abstract vwWidget class contains many of the method which widgets of any kind share in common (e.g., setColor(), getOver(), etc.)

METHOD DESCRIPTIONS

vwWidget() [Protected]

vwWidget (

vwMediator *concreteMediator, pfNode *node);

Construct a widget

*concreteMediator specifies a pointer to the concrete mediator of the interface being created.

*node specifies a pointer to a Performer pfDCS or pfSCS containing the widget geometry.

~vwWidget()

virtual ~vwWidget (

void);

Destruct an instance. pfDelete color LUT memory and pfDelete the widget's group; either pfDCS or pfSCS.

setActive()

virtual void setActive (

int activeState);

Set the widget's Active State. The widget will be ignored if its Active State is set to False (0) and will not generate any events. With one or two exceptions, widgets are created with a default Active State of True.

activeState specifies a value of False (0) or True. Default value is True.

setOver()

virtual void setOver (

int overState);

Set the widget's Over State. Setting the Over State is often a pre-cursor to an event (e.g., drag, press). A widget's Over State (getOver()) should be True while the Wand vector is intersecting the geometry contained in the widget's pfGeode. The static handleWidgets() method ensures that the widget's Over State is updated correctly.

overState specifies a value of False (0) or True. Default value is True.

setVisible()

virtual void setVisible (

int visibilityState);

Set the Visibility State of a widget. Not completely implemented. Should either temporarily remove the widget from the traversed scenegraph or make the widget's geometry transparent.

visibilityState specifies a value of False (0) or True. Default value is True.

getActive()

inline int getActive (

void);

Get the widget's Active State. Returns 0 (False) if inactive, 1 (True) if active.

getOver()

inline int getOver (

void);

Get the widget's Over State. Returns 1 (True) if pointer is over widget, else 0 (False).

getPressed()

inline int getPressed (

void);

Get the widget's Pressed State. Returns 1 (True) if widget is in a Pressed State, else 0 (False).

getVisible()

inline int getVisible (

void);

Get the widget's Visibility State. Returns 1 (True) if widget is visible, else 0 (False).

getDragged()

inline int getDragged (

void);

Get the widget's Dragged State. Returns 1 (True) if widget is being dragged, else 0 (False).

getIdent()

virtual int getIdent (

void);

Get the widget's specific identification. Returns -1. To be overridden for application specific widget identification. This would also coencide with an application specific declaration and definition of setIdent(). A straighforward approach is to create a subclass of, say, vwRadioButton and define setIdent() to take an enum argument of a type that is known to most classes in the application (i.e., myEnums.h). Then override vwWidget::getIdent() to return the value of your application-specific, enum-type variable. Unfortunately, there is no way for vwWidget to know about these enums, so getIdent() will return an int which must be cast to the expected enum type. But in almost all cases this is a safe and effective way to determine the specific identity of the widget.

getInterface()

virtual int getInterface (

void);

Get the widget's group or interface identification. Or, narrow down the widget's identity to that of one belonging to a specific interface. Returns -1. To be overridden for applciation specific group identification. This would also coencide with an application specific declaration and definition of setInterface(). A straighforward approach is to create a subclass of, say, vwRadioButton and define setInterface() to take an enum argument of a type that is known to most classes in the application (i.e., myEnums.h). Then override vwWidget::getInterface() to return the vaule of your application-specific, enum-type variable. Unfortunately, there is no way for vwWidget to know about these enums, so getInterface() will return an int which must be cast to the expected enum type. But in almost all cases this is a safe and effective way to determine the interface from whence the widget came.

getColor()

void getColor (

wColor colorIndex, float rgba[]);

Get the color values that represent a particular state of a widget.

colorIndex, of type wColor, specifies an index into the widget's color LUT. wColor is defined in vwWidget.h.

rgba[] is a float array into which the 4 component color values are placed.

setColor()

inline void setColor (

wColor colorIndex);

Set a widget's current color.

colorIndex specifies an enum of type wColor defined in vwWidget.h. colorIndex is an index into the widget's internal color LUT. Default value is vwWidget::ACTIVE.

registerColor()

void registerColor (

wColor colorIndex, float *rgba);

Add or replace a color in the widget's color list.

colorIndex, of type wColor, specifies an index into the widget's color LUT. wColor is defined in vwWidget.h.

*rgba is a float pointer to an rgba color.

handleWidgets()

static int handleWidgets (

pfGroup * group, vwWidget * wdgPointers[], int wdgTotal, int * click, CAVEID caveID);

User/Widget interaction routine for handling basic widget behavior during wand intersection checking. The return value is the index to *wdgPointers[] of the widget currently intersected by the wand vector. handleWidgets() makes specific calls to isOver(). group and caveID are passed on in these calls. If none of the widgets of interest are being intersected, the return value is -1. In the case of an intersection with a draggable widget (e.g., vwSlider), the return value continues to be the index to that widget pointer as long as CAVEBUTTON1 is True. A button click can be detected by evaluating the post-value of click.

*group specifies the Performer pfGroup at which intersection traversal will begin.

*wdgPointers[] specifies a list of vwWidget pointers that should be checked.

wdgTotal specifies the number of elements in *wdgPointers[].

*click specifies a pointer to an int. If a true click occurs over a clickable widget (e.g., vwButton), during the current cycle, the value pointed to by click is set to True (1), else it is set to False (0).

caveID specifies an enum from cave.h, either CAVE_WAND or CAVE_WAND_NAV. This determines the source of the vector used in isOver(). Default value is CAVE_WAND.

The definition of a click is as follows: getOver() on a particular clickable widget must be True when the left wand button is initially depressed. If the wand button has not been released and depressed again in the meantime and getOver() is True for the same particular widget when the wand button is released, then a click has occurred.

parseWdgConfig()

static vwWidget::wdgStruct * parseWdgConfig (

char *configFileName, char **configHeader, char *my_pfPath, pfDCS **interfaceDCS, int *totalWdgParsed);

Parses an interface configuration file and returns a linked list of type vwWidget::wdgStruct containing the information necessary to construct the widgets of the interface. Retains a copy of the interfaceDCS pfMatrix. This pfMatrix is used in the constructor of dynamic widgets (e.g., vwSliders) to do slider interaction in local coordinate space. See vwSlider::setParentMtx() for caveats.

*configFileName specifies the path and name of the interface configuration file to be used. The interface configuration file defines the number and type of widgets making up the interface to be created. It is made up of two mandatory sections and a third optional section which are described in config.html.

**configHeader specifies a pointer to a char pointer. parseWdgConfig() allocates memory for a string and places the configuration file's header string there. This string can then be used by the application to identify the interface information that has been parsed.

*my_pfPath specifies the path to be used in pfFilePath() for loading the widget geometry.

**interfaceDCS specifies a pointer to a * pfDCS. This pfDCS gets constructed within parseWdgConfig(). It is set with the transformations specified in section one of the configuration file. See config.html for a discussion of this section.

*totalWdgParsed specifies an int pointer who's de-referenced value is set by parseWdgConfig() to the total number of structures in the returned wdgStruct linked list. wdgStruct is defined in vwWidget.h.

isOver()

static int isOver (

pfGroup * group, vwWidget * wdgPointers[], int wdgTotal, CAVEID caveID);

Returns an index to *wdgPointers[] which specifies the widget for which a wand vector intersection is taking place. If no widgets in *wdgPointers[] are currently being intersected, -1 is returned. isOver() is called from within handleWidgets(), but is declared as public to enable more general purpose use.

*group specifies the pfGroup at which intersection traversal will begin.

*wdgPointers[] specifies a list of vwWidget pointers that should be checked.

wdgTotal specifies the total number of widgets referenced in *wdgPointers[].

caveID specifies the source of the position and vector used to determine the position and direction of a pfSegSet. Accepted values are CAVE_WAND or CAVE_WAND_NAV. The correct value for a particular application will depend upon the layout of the scene-graph, the location of the widgets in that scene graph, and the pfGroup used as the origin of intersection traversal. In the case where widgets are not children of the CAVE navigation transform pfDCS (i.e., widgets maintain a fixed position and orientation in the CAVE) it is normally correct to use pfScene as the traversal group source and CAVE_WAND as the source for pfSegSet. If, on the other hand, widgets are transformed by the CAVE navigation transform pfDCS, the correct CAVEID will depend both upon the pfGroup used as the source for intersection traversal, and upon the structure of the scene graph. Default value is CAVE_WAND

isOfType()

inline int isOfType (

wType wdg_type);

Returns True (1), if wdg_type matches the widget's wType, else False (0).

wdg_type specifies a generic widget type enum of type wType. wType is defined in vwWidget.h. Current generic types supported are wButton, wSlider, wFrame, wIncrimentor.

getParentMtx(pfMatrix *mtx)

void getParentMtx (

pfMatrix *mtx);

Copies the static vwWidget parent pfMatrix into mtx. vwWidget's static parent matrix is either a unity matrix or it contains the matrix retrieved from the interface parent pfDCS in vwWidget::parseWdgConfig(). Each time vwWidget::parseWdgConfig() is called, vwWidget's parent matrix is changed to that of the interface created. vwSlider calls getParentMtx() from within its constructor and retains a copy of the affine inverse of this matrix. vwSlider, and possibly other widgets may need the inverse of their interface parent pfDCS's pfMatrix in order to perform correctly.

*mtx specifies a pointer to a pfMatrix.

getSCS()

inline pfSCS * getSCS (

void);

Returns a pointer to a widgets pfSCS. If widget is not a pfSCS, returns NULL.

getDCS()

inline pfDCS * getDCS (

void);

Returns a pointer to a widgets pfDCS. If widget is not a pfDCS, returns NULL.

vwWidget::wdgStruct()

vwWidget::wdgStruct (

void);

Constructor for wdgStruct nested class.

vwWidget::~wdgStruct()

virtual vwWidget::~wdgStruct(

void);

Destructor for wdgStruct nested class.

doSetColor() [Protected]

virtual void doSetColor (

wColor colorIndex);

Sets the color of the pfGeoSet making up the widget geometry to that color specified by colorIndex. doSetColor() is a hook operation called by setColor() and can therefore be modified by subclasses to work with alternative geometries to those used in the development of the base library.

colorIndex specifies an index into the widget's color LUT. wColor is defined in vwWidget.h.

setWType() [Protected]

virtual void setWType (

wType widgetType);

set a widgets wType. Normally called from the constructor of a subclass to vwWidget.

widgetType specifies an enum of type wType. wType is defined in vwWidget.h and enumerates all of the direct widget subclass types.

SEE ALSO

vwSubject, vwMediator