OpenDX - Documentation
Full Contents QuickStart Guide User's Guide User's Reference
Previous Page Next Page Table of Contents Partial Table of Contents Index Search

SuperviseWindow

Category

Windows

Function

Creates a Display window for an image and captures mouse and keyboard events in that window.

Syntax

where, size, events = SuperviseWindow(name, display, size,
                                      offset, parent, depth, visibility,
                                      pick, sizeFlag, offsetFlag);

Inputs
Name Type Default Description
name string (none) unique name for the window
display string "local host" display on which to create the window
size integer vector [640,480] x,y size of the window
offset integer vector [0,0] offset of window in parent
parent string (root window) parent window
depth integer 8 depth of window
visibility integer 1 visibility of window
pick flag 0 whether to consider only button-down events
sizeFlag flag 0 whether to force the size of an already existing window
offsetFlag flag 0 whether to force the offset of an already existing window

Outputs
Name Type Description
where string where parameter for window
size integer vector or integer list window size
events object mouse or keyboard events

Functional Details

SuperviseWindow, along with the associated module SuperviseState, provides the user with direct control over the effect of mouse and keyboard events in a window containing an image. SuperviseWindow and SuperviseState are used together with the Display tool, as an alternative to the Image tool.

When you include the Image tool in a visual program, mouse and keyboard events are interpreted in a particular way as described in 6.1 , "Using the Image Window" in IBM Visualization Data Explorer User's Guide. In contrast, when the Supervise modules and the Display tool are used in a visual program, you are able to specify how a particular mouse or keyboard event should affect either the object being viewed or the camera used to view it. For example, you could specify that right-mouse drags in a horizontal direction should zoom in on an object, while right-mouse drags in a vertical direction should zoom out.

Not only does this allow you to specify the particular action that should take place given events in the display window, but it also allows your interaction with the image to be separated completely from the Data Explorer user interface. For example, a completely custom user interface could be created with a commercial GUI builder, bypassing the Data Explorer user interface entirely, but still allowing user-interaction with the image.

In order to specify custom interaction modes in a program, it is necessary for you to provide routines which indicate what action is to be taken for a given event. An action can affect either the object (for example rotating it or coloring it red), or the camera (for example zooming in), or both. These sets of user-provided routines are called UserInteractors. UserInteractors let you specify your own direct interactors by specifying a table of callbacks, each implementing a custom interactor.

To start Data Explorer using custom UserInteractors, it is necessary to identify the user-written UserInteractor routines to the Data Explorer executive. This is done by setting the environment variable DX_USER_INTERACTOR_FILE before starting Data Explorer. (You can also load UserInteractors after starting Data Explorer by using the Executive module (Executive in IBM Visualization Data Explorer User's Reference)).

If you do not set the DX_USER_INTERACTOR_FILE environment variable, a set of default interactors are provided automatically by Data Explorer. These interactors provide Rotate, Pan, and Zoom functions.

See SuperviseState for more detailed information on how to specify UserInteractors. SuperviseWindow and SuperviseState should not be used in -image mode of Data Explorer. If used in -image mode, they will compete for ownership of the Image window with the User Interface. Use -edit or -menubar mode instead.

name

is a unique name for the window.

display

is the display on which to create the window and defaults to "local host".

size

is the x,y size of the window, and defaults to 640x480. It can be specified either as an integer vector or as an integer list.

offset

is the offset of the window in the parent window. By default, offset is [0,0]. It can be specified either as an integer vector or as an integer list.

parent

is the parent window "where" parameter; parent defaults to the root window, but can also be an already created window if nested windows are desired.

depth

is the depth (in bits) of the window; depth defaults to 8.

visibility

indicates the visibility of the window:
0 window is closed
1 window is open
2 window is open and always on top

pick

indicates whether only button-down events should be considered. This is useful if the user wants to implement picking in the Display window.

sizeFlag

indicates whether to force the size of an already existing window. The default is 0 (false).

offsetFlag

indicates whether to force the offset of an already existing window. The default is 0 (false).

where

identifies the window. This output must be connected to the where parameter of the Display tool. It would also be used, for example, if nested windows are desired using a SuperviseWindow module with the parent parameter set to something other than the root window.

size

is the current size of the window, and may differ from the size input if you resize the window.

events

encodes mouse or keyboard events. It is an array of integer of integer 4-vectors, where the four integers represent the following:

  • event
  • x
  • y
  • state or keypress, depending on event
event is one of DXEVENT_LEFT, DXEVENT_MIDDLE, DXEVENT_RIGHT, or DXEVENT_KEYPRESS. x and y are the pixel locations of the event. For event = DXEVENT_LEFT, DXEVENT_MIDDLE, DXEVENT_RIGHT, the final integer is "state", which is one of BUTTON_UP, BUTTON_MOTION, or BUTTON_DOWN. For event = DXEVENT_KEYPRESS, the final integer is "keypress" which is the character which was pressed. Note that
#define DXEVENT_LEFT            0x01
#define DXEVENT_MIDDLE          0x02
#define DXEVENT_RIGHT           0x04
#define DXEVENT_KEYPRESS        0x08
#define BUTTON_UP               1
#define BUTTON_DOWN             2
#define BUTTON_MOTION           3

For operations other than picking, the user simply passes events to the events input of SuperviseState, which interprets the mouse or keyboard events and calls the appropriate user routines. For picking, see "Doing Picking".

Example Visual Programs

SIMPLE/Supervise.net
Image_wo_UI.net
IndependentlyArrange.net
InsetImage.net
Also see the demonstrations of custom interactors in /usr/local/dx/samples/supervise.

See Also

SuperviseState, Display, Image


Full Contents QuickStart Guide User's Guide User's Reference

[ OpenDX Home at IBM | OpenDX.org ]