Gterm-Image widget class (a subclass of Widget).


The gterm-image widget is a general 2D graphics-imaging widget providing a wide range of facilities for drawing graphics and text, for image display, and for graphics interaction. Normally the client communicates directly with the Gterm widget to draw graphics, download image data, and so on, using some communications protocol outside the domain of the object manager. Nonetheless so far as possible the facilities of the Gterm widget have also been made available to GUI code via the commands listed here.

The Gterm widget adds the following function to the OBM library.

    ObmPostSetGtermCallback (obm, &setgterm, setgterm_client_data)

This is called by a client application to post a procedure to be called when a gterm widget receives the setGterm command. The calling sequence for setGterm callback is as follows:

                   setgterm (client_data, gterm_widget)

The purpose of this callback is to tell the client which gterm widget is the "active" gterm widget. This is used by clients which only support one active Gterm widget, i.e., which can only direct graphics output to one Gterm widget at a time.

The messages or commands that can be sent to the Gterm widget by GUI code follow.

General commands:

                   setGterm          # make widget the active Gterm

activate deactivate addCallback procedure-name callback-type reset flush

setCursorPos x y [raster] getCursorPos x y setCursorType cursortype bell

Graphics drawing commands:

                  setRaster raster
         raster = getRaster [raster]

setLogRes width height (unimplimented) getLogRes width height (unimplimented) setPhysRes width height (unimplimented) getPhysRes width height (unimplimented) setTextRes rows cols (unimplimented) setDataLevel level (unimplimented) setLineWidth width (unimplimented) setLineStyle style (unimplimented) setColorIndex index (unimplimented) setFillType filltype (unimplimented)

clearScreen drawPolyline vector (unimplimented) drawPolymarker vector (unimplimented) drawPolygon vector (unimplimented) drawMarker x y xsize ysize type (unimplimented)

drawAlphaText x y text (unimplimented) getAlphaTextSize string width height base (unimplimented) startDialog (unimplimented) endDialog (unimplimented) eraseDialog (unimplimented) drawDialogText x y text (unimplimented) getDialogTextSize string width height base (unimplimented)

The coordinates used in the graphics drawing commands are logical coordinates as defined by setLogRes, in the coordinate system of the reference drawing raster as defined by setRaster. The default reference raster is raster zero, the widget's window. Vectors are specified as a list of points, e.g., { {x y} {x y} ... }.

Imaging commands:

              rasterInit
            assignRaster raster drawable (unimplimented)
            createRaster raster type width height depth (unimplimented)
           destroyRaster raster (unimplimented)
    exists = queryRaster raster type width height depth (unimplimented)
     raster = nextRaster [raster] (unimplimented)
     nrasters = nRasters [nrasters] (unimplimented)

setPixel raster x y value value = getPixel raster x y writePixels raster pixels encoding x1 y1 nx ny readPixels raster pixels encoding x1 y1 nx ny refreshPixels raster ct x1 y1 nx ny (unimplimented) pixmap = createPixmap src x y width height (unimplimented) copyPixmap pixmap dst x y width height (unimplimented)

colormap = nextColormap [colormap] (unimplimented) freeColormap colormap (unimplimented) writeColormap colormap first nelem colors (unimplimented) readColormap colormap first nelem colors (unimplimented) loadColormap colormap offset scale

initMappings (unimplimented) mapping = nextMapping [mapping] freeMapping mapping (unimplimented) enableMapping mapping (unimplimented) disableMapping mapping (unimplimented) active = activeMapping mapping (unimplimented) refreshMapping mapping (unimplimented)

raster = selectRaster dras dt dx dy rt rx ry [map] unmapPixel sx sy raster rx ry [rz]

copyRaster rop src st sx sy snx sny dst dt dx dy dnx dny (unimplimented) setMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny getMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny

flip mapping axis [axis...]

Pixel arrays are long strings consisting either of a sequence of numeric pixel values separated by whitespace (space or newline), or a hex encoded sequence of bytes (2 hex digits per 8 bit pixel). Colors are specified as a list of RGB triplets, e.g., { {R G B} {R G B} ... }.

Refer to the documentation for the Gterm widget for a detailed description of rasters, mappings, and colormaps.

Markers:

               createMarker name [attribute-list]
                 markerInit

New markers may be created with createMarker. Once created, a marker functions under the Object Manager as a named object of class "marker". Refer to the marker class for a description of the commands defined for a marker.

gterm Actions List

        ignore
        graphics-input
        graphics-context
        crosshair
        track-cursor
        enter-window
        leave-window
        popup-menu     {not implemented}
        reset
        m_create

Default translations for Gterm window. Omitted for now: Ctrl ~Meta : popup-menu(tekMenu)

default Gterm Translations

               [Btn1Down]:m_create()                   
               [Btn2Down]:crosshair(on)                
             [Btn2Motion]:crosshair(on)                
                 [Btn2Up]:crosshair(off)               
   ~Ctrl ~Meta [Btn3Down]:graphics-context()           
            [EnterWindow]:enter-window()               
            [LeaveWindow]:leave-window()               
               [KeyPress]:graphics-input()             
                 [Motion]:track-cursor()               

GTERM class commands.

setGterm

Set the active Gterm widget. A UI can have more than one gterm widget, but due to restrictions on the client-server interface, it may be possible for only one to receive client output at any one time (any gterm widget can generate input to be sent to the client). If the client has this restriction, the client-server interface code which uses OBM can call the ObmPostSetGtermCallback procedure to post a function to be called when the UI code calls the setGterm procedure.

Usage:

        setGterm

activate

Activate the gterm widget. This causes the next GIN mode setCursorType to warp the pointer into the gterm window.

Usage:

        activate

deactivate

Deactivate the gterm widget. If the cursor has been warped into the window by a previous activate/setCursorType GIN mode, this causes the cursor to be warped back to where it was previously.

Usage:

        deactivate

reset

Reset the gterm widget. This causes a number of state variables affecting graphics drawing options to be set to their default values.

Usage:

        reset

flush

Flush any graphics output and synchronize the state of the widget with what is shown on the display.

Usage:

        flush

The gterm widget uses XLIB, which buffers graphics drawing commands and automatically sends them to the X server when 1) the buffer fills, 2) input is requested from the server. Such buffering of data is necessary for efficient operation and it should rarely be necessary to explicitly flush graphics output since XLIB does this automatically in most cases. An example of when explicitly flushing the ouptut might be necessary is in cases where smooth animation is desired and drawing the graphics in batches could cause the display to appear "jerky".

addCallback

Post a callback for a Gterm widget event.

Usage:

        addCallback procedure-name [callback-type]

The recognized Gterm callbacks are


        input           Called when the graphics-input action is invoked in
                        a translation table.  The default Gterm translation
                        table invokes this action when a KeyPress event occurs
                        in the Gterm window.
                        Callback:        widget-name input-type event-data

        resize          Called when the gterm window is resized.
                        Callback:        widget-name width height

        reset           Called when the "reset" action is invoked.
                        Callback:        widget-name

If no callback is specified the default is "input".

Note that in GUI code one can also use the translation table to directly invoke GUI procedures without need to use the Gterm input mechanism. This is more flexible but we support the Gterm input callback here for applications that use the default translations.

setCursorPos

Warp the cursor (pointer) to the given coordinates. This is a graphics drawing command and if no raster number is specified the current reference drawing raster, as set with setRaster, defines the coordinate system.

Usage:

        setCursorPos x y [raster]

A raster number may optionally given to define the raster coordinate system to be used. raster=0 yields screen coordinates.

getCursorPos

Get the cursor position (raster 0 or screen coordinates).

Usage:

        getCursorPos x y

setCursorType

Set the cursor type.

Usage:

        setCursorType cursor-type

        idle        default cursor
        busy        busy cursor, e.g, when program is busy
        ginMode     graphics input mode cursor, set when program is
                    waiting for graphics input

bell

Gterm widget sound output.

Usage:

        bell

setRaster

Set the number of the raster to be used to define the drawing context (e.g. coordinate system) for graphics and text drawing functions.

Usage:

        setRaster raster-number

getRaster

Get the number of the raster which defines the drawing context, as set in the last setRaster call.

Usage:

        raster = getRaster [raster]

If the name of a variable is given the raster number will be stored directly in that variable.

clearScreen

Clear the "screen", i.e., window. This action clears the drawing window and sets a number of drawing state variables to their default values.

Usage:

        clearScreen

rasterInit

Initialize the raster subsystem, deleting all rasters and mappings and freeing the dynamic part of the colortable.

Usage:

        rasterInit

writePixels

Set the values of some subset of the pixels in a raster. If any mappings are defined on the affected region and are enabled, any destination rasters will be automatically updated as defined by the mapping.

Usage:

        writePixels raster pixels encoding nbits x1 y1 nx ny

        raster       The raster number.
        pixels       The pixel array, encoded as a string.
        encoding     The pixel encoding.  "numeric" means each pixel is
                     encoded as a decimal integer delimited by whitespace.
                     "hex" means the pixel array is hex encoded, 2 bytes
                     per 8 bit pixel, as a printable text string.  The
                     two bytes are defined as follows (v = pixel value):

                          byte1 = ((v >> 4) & 017) in hex [0-9A-F]
                          byte2 = ((v     ) & 017) in hex [0-9A-F]
                        
                     Whitespace in a hex encoded string is ignored.
                     Hex encoding reduces the data volume by about a factor
                     of two (compared to numeric) and is only a factor of
                     two less space efficient than binary.

        nbits        Number of bits per pixel - currently only 8 bit pixels
                     are supported.

        x1,y1,nx,ny  Region of the raster to be written.

Most real-world image processing applications get the Gterm widget handle with setGterm and pass binary data to the widget by calling GtWritePixels directly. This is the most efficient approach for serious image processing where large amounts of data are involved. However, being able to read and write raster pixels directly in a GUI can be useful in specialized applications, e.g., where the image is computed or modified by the GUI.

setPixel

Set the value of a single pixel.

Usage:

        setPixel raster x y value

        raster   The raster number.
        x, y     The pixel to be set.
        value    The pixel value.

This routine is more efficient than writePixels for setting the value of a single pixel, but is a lot less efficient if a block of pixels are to be set.

readPixels

Get the values of some subset of the pixels in a raster.

Usage:

        readPixels raster pixels encoding nbits x1 y1 nx ny

        raster        The raster number.
        pixels        The pixel array, encoded as a string.
        encoding      The pixel encoding.  "numeric" means each pixel is
                      encoded as a decimal integer delimited by whitespace.
                      "hex" means the pixel array is hex encoded, 2 bytes
                      per 8 bit pixel, as a printable text string.  The
                      two bytes are defined as follows (v = pixel value):

                           byte1 = ((v >> 4) & 017) in hex [0-9A-F]
                           byte2 = ((v     ) & 017) in hex [0-9A-F]
                        
                      Whitespace in a hex encoded string is ignored.
                      Hex encoding reduces the data volume by about a factor
                      of two (compared to numeric) and is only a factor of
                      two less space efficient than binary.

        nbits         Number of bits per pixel - currently only 8 bit pixels
                      are supported.

        x1,y1,nx,ny   Region of the raster to be read.

Use readPixels to read a block of pixels, and getPixel to get the value of a single pixel.

getPixel

Get the value of a single pixel.

Usage:

        getPixel raster x y

        raster      The raster number.
        x, y        The pixel to be set.

This routine is more efficient than readPixels for getting the value of a single pixel, but is a lot less efficient if a block of pixels are to be read.

nextMapping

Return the index of the next unused mapping.

Usage:

        nextMapping

Returns the mapping number as the function value.

getMapping

Get a mapping.

Usage:

        getMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny

All parameters except the mapping number are output parameters.

setMapping

Set a mapping.

Usage:

        setMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny

All parameters are input parameters.

loadColormap

Load a colormap.

Usage:

        loadColormap colormap [offset [scale]]

The offset and scale parameters may be used to adjust the brightness and contrast of the image when the colormap is loaded. The normalized colormap has offset=0.5, scale=1.0. Colormap zero is the hardware colormap.

selectRaster

Given the raw screen coordinates SX,SY (or coords in any destination raster), determine the mapping and source raster which are mapped to that pixel and return the raster and mapping numbers and the coordinates of the same pixel in the source raster.

Usage:

        raster = selectRaster dras dt dx dy rt rx ry [map]

where

		dras         display raster
                dt,rt        coordinate type - "pixel" or "ndc"
                dx,dy        display raster coordinates (input)
                rx,ry        source raster coordinates (output)
                map          mapping selected (output)

Note that the coordinates returned by selectRaster are measured (taking a line as an example) from zero at the left edge of the first pixel, to "width" at the right edge of the last pixel. This means that the floating point coordinates of the center of raster pixel N will be N + 0.5. For example, if we input screen coordinates (dras=0), x=117, and no mapping is in effect, the floating point raster coordinates returned will be 117.5. The difference occurs because the input coordinate is a pixel number (integer) while the output coordinate is a floating point coordinate measuring the continuously variable location a pixel. int(x) will convert this coordinate to a raster pixel number.

unmapPixel

unmapPixel is a simplified, less general version of selectRaster which will automatically follow graphics pipelines back to the original mapped raster. If desired the raster pixel value can be returned as well as the raster number and raster pixel coordinates corresponding to a screen (raster 0) pixel.

Usage:

        unmapPixel sx sy raster rx ry [rz]

where

		sx,sy        "screen" (raster 0) coordinates
                raster       original mapped raster (output)
                rx,ry        source raster coordinates (output)
                rz           source raster pixel value (output)

By following graphics pipelines back to the original source raster we mean the following. If raster A is mapped to raster B which is mapped to C (the screen), given a screen coordinate in the mapped region unmapPixel will return the raster number and coordinates for raster A.

flip

Edit a mapping to flip the mapped subimage in X and/or Y.

Usage:

        flip mapping axis [axis]

where axis is "x" or "y". This is a convenience routine for changing only the flip portion of a mapping.

markerInit

Initialize the Marker subsystem for a Gterm widget. This destroys all markers and initializes the marker subsystem.

Usage:

        markerInit

createMarker

Create a new marker.

Usage:

        createMarker name attribute-list
  e.g.  createMarker name {attribute value [attribute value ...]}
    or  createMarker name attribute value [attribute value ...]

Any marker attribute may be assigned a value when the marker is created. Refer to <ObmW/Gterm.h> for a list of marker attribute names. Often the the attributes "type" and "createMode" need to be specified at marker create time.

        type            The marker type: text, rectangle, circle, etc.

        createMode      A marker should be created with createMode=interactive
                        if the user is expected to interactively drag out
                        the marker using the pointer and either the default
                        or an application specified translation table.  A
                        marker can also be created interactively using only
                        the m_create (marker create) action, however m_create
                        does not allow the marker attributes to be set.

There are any number of ways to use a GUI to create a marker under the Object Manager, but an example might be using a translation to call a GUI procedure which issues the createMarker call. For example a pointer down event could translate as "call(newMarker,$name,$x,$y) m_create()" where newMarker is a GUI marker creation procedure which sends a createMarker message to the Gterm widget. The GUI procedure could set the marker attributes as desired, possibly using additional GUI components to define the marker attributes. The m_create action will notice that a createMarker has been executed and will merely activate the marker and give it the pointer focus (i.e. install the marker translations). The user will then use the pointer or keyboard to drag out the marker.

If the marker is created noninteractive the application must set the marker position and size using marker attributes. If the marker is sensitive the user can then use the marker's translations to interactively modify the marker (resize it, move it, etc.). All markers which are visible and sensitive and which have the necessary translations can be interactively modified by the user; the reason for creating a marker in interactive mode is to allow the initial marker position and size to be specified interactively *when* the marker is created, instead of afterwards.

Any number of attributes may be given when the marker is created. Most marker attributes can also be modified after a marker has been created by sending setAttribute messages to the marker.