path: root/vendor/x11iraf/obm/docs/gui.doc/gtermclass.html

<title>Gterm-Image widget class</title>
<h1><IMG SRC="/iraf/web/images/iraf.gif">  Gterm-Image widget class (a subclass of Widget).</h1>
<p>
<HR>
<p>
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.
<p>
The Gterm widget adds the following function to the OBM library.
<p>
<pre>
    ObmPostSetGtermCallback (obm, &setgterm, setgterm_client_data)
</pre>
<p>
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:
<p>
<pre>
                   setgterm (client_data, gterm_widget)
</pre>
<p>
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.
<p>
The messages or commands that can be sent to the Gterm widget by GUI
code follow.
<p>
General commands:
<p>
<pre>
                   <a href="#setGterm">setGterm</a>          # make widget the active Gterm
<p>
                   <a href="#activate">activate</a>
                 <a href="#deactivate">deactivate</a>
                <a href="#addCallback">addCallback</a> procedure-name callback-type
                      <a href="#reset">reset</a>
                      <a href="#flush">flush</a>
<p>
               <a href="#setCursorPos">setCursorPos</a> x y [raster]
               <a href="#getCursorPos">getCursorPos</a> x y
              <a href="#setCursorType">setCursorType</a> cursortype
                       <a href="#bell">bell</a>
</pre>
<p>
Graphics drawing commands:
<p>
<pre>
                  <a href="#setRaster">setRaster</a> raster
         raster = <a href="#getRaster">getRaster</a> [raster]
<p>
                  <a href="notyet.html">setLogRes</a> width height (unimplimented)
                  <a href="notyet.html">getLogRes</a> width height (unimplimented)
                 <a href="notyet.html">setPhysRes</a> width height (unimplimented)
                 <a href="notyet.html">getPhysRes</a> width height (unimplimented)
                 <a href="notyet.html">setTextRes</a> rows cols (unimplimented)
               <a href="notyet.html">setDataLevel</a> level (unimplimented)
               <a href="notyet.html">setLineWidth</a> width (unimplimented)
               <a href="notyet.html">setLineStyle</a> style (unimplimented)
              <a href="notyet.html">setColorIndex</a> index (unimplimented)
                <a href="notyet.html">setFillType</a> filltype (unimplimented)
<p>
                <a href="#clearScreen">clearScreen</a>
               <a href="notyet.html">drawPolyline</a> vector (unimplimented)
             <a href="notyet.html">drawPolymarker</a> vector (unimplimented)
                <a href="notyet.html">drawPolygon</a> vector (unimplimented)
                 <a href="notyet.html">drawMarker</a> x y xsize ysize type (unimplimented)
<p>
              <a href="notyet.html">drawAlphaText</a> x y text (unimplimented)
           <a href="notyet.html">getAlphaTextSize</a> string width height base (unimplimented)
                <a href="notyet.html">startDialog</a> (unimplimented)
                  <a href="notyet.html">endDialog</a> (unimplimented)
                <a href="notyet.html">eraseDialog</a> (unimplimented)
             <a href="notyet.html">drawDialogText</a> x y text (unimplimented)
          <a href="notyet.html">getDialogTextSize</a> string width height base (unimplimented)
</pre>
<p>
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} ... }.
<p>
Imaging commands:
<p>
<pre>
              <a href="#rasterInit">rasterInit</a>
            <a href="notyet.html">assignRaster</a> raster drawable (unimplimented)
            <a href="notyet.html">createRaster</a> raster type width height depth (unimplimented)
           <a href="notyet.html">destroyRaster</a> raster (unimplimented)
    exists = <a href="notyet.html">queryRaster</a> raster type width height depth (unimplimented)
     raster = <a href="notyet.html">nextRaster</a> [raster] (unimplimented)
     nrasters = <a href="notyet.html">nRasters</a> [nrasters] (unimplimented)
<p>
                <a href="#setPixel">setPixel</a> raster x y value
        value = <a href="#getPixel">getPixel</a> raster x y
             <a href="#writePixels">writePixels</a> raster pixels encoding x1 y1 nx ny
              <a href="#readPixels">readPixels</a> raster pixels encoding x1 y1 nx ny
           <a href="notyet.html">refreshPixels</a> raster ct x1 y1 nx ny (unimplimented)
   pixmap = <a href="notyet.html">createPixmap</a> src x y width height (unimplimented)
              <a href="notyet.html">copyPixmap</a> pixmap dst x y width height (unimplimented)
<p>
 colormap = <a href="notyet.html">nextColormap</a> [colormap] (unimplimented)
            <a href="notyet.html">freeColormap</a> colormap (unimplimented)
           <a href="notyet.html">writeColormap</a> colormap first nelem colors (unimplimented)
            <a href="notyet.html">readColormap</a> colormap first nelem colors (unimplimented)
            <a href="#loadColormap">loadColormap</a> colormap offset scale
<p>
            <a href="notyet.html">initMappings</a> (unimplimented)
   mapping = <a href="#nextMapping">nextMapping</a> [mapping]
             <a href="notyet.html">freeMapping</a> mapping (unimplimented)
           <a href="notyet.html">enableMapping</a> mapping (unimplimented)
          <a href="notyet.html">disableMapping</a> mapping (unimplimented)
  active = <a href="notyet.html">activeMapping</a> mapping (unimplimented)
          <a href="notyet.html">refreshMapping</a> mapping (unimplimented)
<p>
   raster = <a href="#selectRaster">selectRaster</a> dras dt dx dy rt rx ry [map]
              <a href="#unmapPixel">unmapPixel</a> sx sy raster rx ry [rz]
<p>
              <a href="notyet.html">copyRaster</a> rop src  st sx sy snx sny  dst dt dx dy dnx dny (unimplimented)
              <a href="#setMapping">setMapping</a> mapping rop
                         src st sx sy snx sny  dst dt dx dy dnx dny
              <a href="#getMapping">getMapping</a> mapping rop 
                         src st sx sy snx sny  dst dt dx dy dnx dny
<p>
                    <a href="#flip">flip</a> mapping axis [axis...]
</pre>
<p>
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} ... }.
<p>
Refer to the documentation for the Gterm widget for a detailed description
of rasters, mappings, and colormaps.
<p>
Markers:
<p>
<pre>
               <a href="#createMarker">createMarker</a> name [attribute-list]
                 <a href="#markerInit">markerInit</a>
</pre>
<p>
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.
<p>
gterm Actions List
<p>
<pre>
        ignore
        graphics-input
        graphics-context
        crosshair
        track-cursor
        enter-window
        leave-window
        popup-menu     {not implemented}
        reset
        m_create
</pre>
<p>
Default translations for Gterm window.
Omitted for now: Ctrl ~Meta <Btn3Down>: popup-menu(tekMenu)
<p>
default Gterm Translations
<p>
<pre>
               [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()               
<pre>
<p>
<p>
GTERM class commands.
<p>
<h1><A NAME="setGterm">setGterm</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        setGterm
</pre>
<p>
<h1><A NAME="activate">activate</A></h1>
<p>
Activate the gterm widget.   This causes the next GIN mode
setCursorType to warp the pointer into the gterm window.
<p>
Usage:
<p>
<pre>
        activate
</pre>
<p>
<h1><A NAME="deactivate">deactivate</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        deactivate
</pre>
<p>
<h1><A NAME="reset">reset</A></h1>
<p>
Reset the gterm widget.  This causes a number of state variables
affecting graphics drawing options to be set to their default values.
<p>
Usage:
<p>
<pre>
        reset
</pre>
<p>
<h1><A NAME="flush">flush</A></h1>
<p>
Flush any graphics output and synchronize the state of the widget
with what is shown on the display.
<p>
Usage:
<p>
<pre>
        flush
</pre>
<p>
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".
<p>
<h1><A NAME="addCallback">addCallback</A></h1>
<p>
Post a callback for a Gterm widget event.
<p>
Usage:
<p>
<pre>
        addCallback procedure-name [callback-type]
</pre>
<p>
The recognized Gterm callbacks are
<p>
<pre>

        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

<pre>
<p>
If no callback is specified the default is "input".
<p>
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.
<p>
<h1><A NAME="setCursorPos">setCursorPos</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        setCursorPos x y [raster]
</pre>
<p>
A raster number may optionally given to define the raster coordinate system
to be used.  raster=0 yields screen coordinates.
<p>
<h1><A NAME="getCursorPos">getCursorPos</A></h1>
<p>
Get the cursor position (raster 0 or screen coordinates).
<p>
Usage:
<p>
<pre>
        getCursorPos x y
</pre>
<p>
<h1><A NAME="setCursorType">setCursorType</A></h1>
<p>
Set the cursor type.
<p>
Usage:
<p>
<pre>
        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
</pre>
<p>
<h1><A NAME="bell">bell</A></h1>
<p>
Gterm widget sound output.
<p>
Usage:
<p>
<pre>
        bell
</pre>
<p>
<h1><A NAME="setRaster">setRaster</A></h1>
<p>
Set the number of the raster to be used to define the drawing
context (e.g. coordinate system) for graphics and text drawing functions.
<p>
Usage:
<p>
<pre>
        setRaster raster-number
</pre>
<p>
<h1><A NAME="getRaster">getRaster</A></h1>
<p>
Get the number of the raster which defines the drawing
context, as set in the last setRaster call.
<p>
Usage:
<p>
<pre>
        raster = getRaster [raster]
</pre>
<p>
If the name of a variable is given the raster number will be stored 
directly in that variable.
<p>
<h1><A NAME="clearScreen">clearScreen</A></h1>
<p>
Clear the "screen", i.e., window.  This action clears the
drawing window and sets a number of drawing state variables to their default
values.
<p>
Usage:
<p>
<pre>
        clearScreen
</pre>
<p>
<h1><A NAME="rasterInit">rasterInit</A></h1>
<p>
Initialize the raster subsystem, deleting all rasters and
mappings and freeing the dynamic part of the colortable.
<p>
Usage:
<p>
<pre>
        rasterInit
</pre>
<p>
<h1><A NAME="writePixels">writePixels</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        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.
</pre>
<p>
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.
<p>
<h1><A NAME="setPixel">setPixel</A></h1>
<p>
Set the value of a single pixel.
<p>
Usage:
<p>
<pre>
        setPixel raster x y value

        raster   The raster number.
        x, y     The pixel to be set.
        value    The pixel value.
</pre>
<p>
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.
<p>
<h1><A NAME="readPixels">readPixels</A></h1>
<p>
Get the values of some subset of the pixels in a raster.
<p>
Usage:
<p>
<pre>
        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.
</pre>
<p>
Use readPixels to read a block of pixels, and getPixel to get the value
of a single pixel.
<p>
<h1><A NAME="getPixel">getPixel</A></h1>
<p>
Get the value of a single pixel.
<p>
Usage:
<p>
<pre>
        getPixel raster x y

        raster      The raster number.
        x, y        The pixel to be set.
</pre>
<p>
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.
<p>
<h1><A NAME="nextMapping">nextMapping</A></h1>
<p>
Return the index of the next unused mapping.
<p>
Usage:
<p>
<pre>
        nextMapping
</pre>
<p>
Returns the mapping number as the function value.
<p>
<h1><A NAME="getMapping">getMapping</A></h1>
<p>
Get a mapping.
<p>
Usage:
<p>
<pre>
        getMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny
</pre>
<p>
All parameters except the mapping number are output parameters.
<p>
<h1><A NAME="setMapping">setMapping</A></h1>
<p>
Set a mapping.
<p>
Usage:
<p>
<pre>
        setMapping mapping rop src st sx sy snx sny dst dt dx dy dnx dny
</pre>
<p>
All parameters are input parameters.
<p>
<h1><A NAME="loadColormap">loadColormap</A></h1>
<p>
Load a colormap.
<p>
Usage:
<p>
<pre>
        loadColormap colormap [offset [scale]]
</pre>
<p>
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.
<p>
<h1><A NAME="selectRaster">selectRaster</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        raster = selectRaster dras dt dx dy rt rx ry [map]
</pre>
<p>
where
<p>
<pre>
		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)
</pre>
<p>
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.
<p>
<h1><A NAME="unmapPixel">unmapPixel</A></h1>
<p>
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.
<p>
Usage:
<p>
<pre>
        unmapPixel sx sy raster rx ry [rz]
</pre>
<p>
where
<p>
<pre>
		sx,sy        "screen" (raster 0) coordinates
                raster       original mapped raster (output)
                rx,ry        source raster coordinates (output)
                rz           source raster pixel value (output)
<pre>
<p>
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.
<p>
<h1><A NAME="flip">flip</A></h1>
<p>
Edit a mapping to flip the mapped subimage in X and/or Y.
<p>
Usage:
<p>
<pre>
        flip mapping axis [axis]
</pre>
<p>
where axis is "x" or "y".  This is a convenience routine for changing only
the flip portion of a mapping.
<p>
<h1><A NAME="markerInit">markerInit</A></h1>
<p>
Initialize the Marker subsystem for a Gterm widget.
This destroys all markers and initializes the marker subsystem.
<p>
Usage:
<p>
<pre>
        markerInit
</pre>
<p>
<h1><A NAME="createMarker">createMarker</A></h1>
<p>
Create a new marker.
<p>
Usage:
<p>
<pre>
        createMarker name attribute-list
  e.g.  createMarker name {attribute value [attribute value ...]}
    or  createMarker name attribute value [attribute value ...]
<pre>
<p>
Any marker attribute may be assigned a value when the marker is created.
Refer to &lt;ObmW/Gterm.h&gt; for a list of marker attribute names.  Often the
the attributes "type" and "createMode" need to be specified at marker
create time.
<p>
<pre>
        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.
<pre>
<p>
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.
<p>
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.
<p>
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.