# 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.