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

<title>Graphics Marker class</title>
<h1><IMG SRC="/iraf/web/images/iraf.gif">  Graphics Marker class</h1>
<p>
<HR>
<p>
A marker is a graphics object implemented by the Gterm-Image widget.
Markers are not real toolkit widgets, but they act much like widgets and
are interfaced as an object class under the Object Manager.  The Marker
class is not a subclass, it is a base class like Widget, but Marker objects
can exist only as children of Gterm widgets.
<p>
Since markers are not independent widgets but rather part of a Gterm widget
instance, the parent Gterm widget is partially responsible for managing
markers.  The Gterm widget implements the following commands for dealing
with markers.
<p>
<pre>
               <a href="gtermclass.html#createMarker">createMarker</a> name [attribute-list]
                 <a href="gtermclass.html#markerInit">markerInit</a>
</pre>
<p>
A new marker is created by sending the createMarker message to the parent
gterm widget.  This creates a marker of the given name and type.
The markerInit command, if sent to a gterm widget, destroys any markers
defined for that widget and reinitializes the marker facility.  Markers
may also be created by action procedures in response to user input events.
<p>
A marker may be destroyed by itself in response to an input event (e.g. the
user presses the delete key), by sending the marker the destroy message
to tell it to destroy itself, by sending a markerInit to the parent gterm
widget, or by destroying the marker object (or any parent) with the server
command <a href="servercom.html#destroyObject">destroyObject</a>.
<p>
Once a marker has been created it behaves as an independent object and
receives and executes messages, responds to events, generates callbacks,
and so on.  The marker class defines the following commands.
<p>
<pre>
                <a href="#makeCopy">makeCopy</a> name
             <a href="#addCallback">addCallback</a> procedure [event [event ...]]
                  <a href="#notify">notify</a> [event-type [param [param ...]]]
                 <a href="#destroy">destroy</a> [nocallback]
<p>
                 <a href="#markpos">markpos</a>
                  <a href="#redraw">redraw</a> [function] [markpos|nomarkpos] [erase|noerase]
<p>
                   <a href="#raise">raise</a> [reference-marker]
                   <a href="#lower">lower</a> [reference-marker]
<p>
                    <a href="#move">move</a> x y
                  <a href="#resize">resize</a> width height
                  <a href="#rotate">rotate</a> angle                # radians
<p>
                     <a href="#setAttribute">set</a> attribute value      # alias for setAttribute
             value = <a href="#getAttribute">get</a> attribute            # alias for getAttribute
<p>
            <a href="#setAttribute">setAttribute</a> attribute value
    value = <a href="#getAttribute">getAttribute</a> attribute
           <a href="#setAttributes">setAttributes</a> attribute-list
           <a href="#getAttributes">getAttributes</a> attribute-list
             <a href="#setVertices">setVertices</a> points first npts
             <a href="#getVertices">getVertices</a> points first npts
<p>
      region = <a href="#getRegion">getRegion</a> [unmap] [coord-type]
                 <a href="#getRect">getRect</a> dx dy dnx dny
</pre>
<p>
Marker positions and dimensions are given in window (raster 0) coordinates. 
<p>
The operators raise, lower, move, resize, and rotate erase the marker,
modify it as indicated, and redraw it with the new attributes.  For finer
control over marker attributes one can use [get|set]Attribute[s] and
[get|set]Vertices to edit the markers directly.  In this case an auto
redraw is not performed (unless the autoRedraw marker attribute is set).
The usual sequence is a markpos to record the marker position, one or more
setAttribute calls to change marker attributes, then a redraw to erase
the old marker and redraw the new one.  Markers have many attributes which
can be set to control things like the position and size, colors, line
widths, fill type and style, font, rubber-band technique, and so on.
Refer to &lt;ObmW/Gterm.h&gt; for a list of marker types and attributes.
<p>
The marker type may be changed at runtime without destroying the marker.
For example a circle can be changed to an ellipse or a rectangle.  This
also works for polygons (the vertex list is preserved and restored when
the marker is changed back to a polygon).
<p>
The current shape of a marker may be queried with getVertices, which
returns the polygon or polyline vertex list in window coordinates.  A more
powerful routine which does something similar is getRegion.  This routine
returns a high level description of the region outlined by the marker,
giving the marker type (rectangle, circle, ellipse etc.), center, width
and height, and so on.  Any position or dimension information may
optionally be transformed back to the original source raster, if the marker
center is in a region of the window which is the destination of an active
mapping.  The unmap option will follow multiple mappings back to the
original mapped source raster.
<p>
The getRect function returns the parameters of the region outlined by a
rectangle marker in a form convenient for use in a Gterm setMapping call
(this is used to display an image within a marker).
<p>
Default translations when pointer is over a marker.
default Marker Translations
<p>
<pre>
        Shift &lt; Btn1Motion &gt;i    m_rotateResize()             
              &lt; Btn1Motion &gt;    m_moveResize()               
          Shift &lt; Btn1Down &gt;    m_raise()  m_markpos()       
                &lt; Btn1Down &gt;    m_raise()  m_markposAdd()    
                  &lt; Btn1Up &gt;    m_redraw() m_destroyNull()   
                &lt; Btn2Down &gt;    m_lower()                    
            &lt; Key &gt; BackSpace   m_deleteDestroy()            
               &lt; Key &gt; Delete   m_deleteDestroy()            
                &lt; KeyPress &gt;    m_input()                    
                  &lt; Motion &gt;    track-cursor()               
</pre>
<p>
MARKER class commands.
<p>
makeCopy</A></h1>
<p>
Copy a marker.  The new marker is initially identical to the
old one, and will not be distinct until, e.g., moved to a new center.
<p>
Usage:
<p>
<pre>
         makeCopy name
</pre>
<p>
<h1><A NAME="addCallback">addCallback</A></h1>
<p>
Post a marker callback to be called when the specified
event or events occurs.  If no events are listed a Notify callback will
be posted.
<p>
Usage:
<p>
<pre>
	addCallback procedure [event [event ...]]
</pre>
<p>
<h1><A NAME="notify">notify</A></h1>
<p>
Generate a Marker pseudo-event, causing any posted client
callback procedures to be called.
<p>
Usage:
<p>
<pre>
        notify [event-type [param [param ...]]]
</pre>
<p>
<h1><A NAME="destroy">destroy</A></h1>
<p>
Destroy a marker.  Just tell the marker to destroy itself.
All cleanup outside the marker facility relies upon the use of callbacks.
This includes our callback markerDestroyCallback below.
<p>
Usage:
<p>
<pre>
        destroy
</pre>
<p>
<h1><A NAME="markpos">markpos</A></h1>
<p>
Mark the current position of a marker for a later redraw.
<p>
Usage:
<p>
<pre>
        markpos
</pre>
<p>
Markpos is used to mark the position of a marker before changing any
marker attributes, so that a later "redraw marked" will erase the old
marker rather than the new one.  This is necessary, for example, if any
marker attributes are changed which affect the size or position of the
marker.
<p>
<h1><A NAME="redraw">redraw</A></h1>
<p>
Redraw a marker.
<p>
Usage:
<p>
<pre>
        redraw [function] [erase|noerase] [markpos|nomarkpos]
</pre>
<p>
By default redraw will erase the old marker at the position indicated by
a previous call to markpos, and redraw the marker with the current
attributes using the drawing function copy (copy source to destination).
Hence the usual usage is "markpos ... change marker attributes ... redraw".
Optional arguments may be given to change the drawing function, enable or
disable erase, or force redraw to do a markpos.  These arguments may be
given in any order.
<p>
The drawing functions are as given in the XLIB documentation, minus the
"GX" prefix.  The most commonly used functions are "copy" and "xor".
A normal marker redraw uses function=copy.
<p>
<h1><A NAME="raise">raise</A></h1>
<p>
Raise a marker, i.e., cause it to be drawn on top of other
markers when overlapping markers are drawn.
<p>
Usage:
<p>
<pre>
        raise [reference-marker]
</pre>
<p>
In a reference marker is named the marker will raise itself above this
marker, otherwise the raised marker becomes the topmost marker.
<p>
<h1><A NAME="lower">lower</A></h1>
<p>
Lower a marker, i.e., cause it to be drawn beneath other
markers when overlapping markers are drawn.
<p>
Usage:
<p>
<pre>
        lower [reference-marker]
</pre>
<p>
In a reference marker is named the marker will lower itself beneath this
marker, otherwise the lowered marker becomes the lowest marker.
<p>
<h1><A NAME="move">move</A></h1>
<p>
Move a marker.
<p>
Usage:
<p>
<pre>
        move x y
</pre>
<p>
Move the marker center to the indicated coordinates in the display window.
<p>
<h1><A NAME="resize">resize</A></h1>
<p>
Resize a marker.
<p>
Usage:
<p>
<pre>
         resize width height
</pre>
<p>
Resize the marker to the indicated size.  By default width and height are
given in pixels.  For a text marker one can append "ch" to indicate that
the units are chars in whatever font is in use, e.g., "40ch" or "40 chars"
is an acceptable value for a text marker dimension.
<p>
<h1><A NAME="rotate">rotate</A></h1>
<p>
Rotate a marker.
<p>
Usage:
<p>
<pre>
         rotate angle
</pre>
<p>
Redraw a marker oriented to the given rotation angle.  The angle is
given in radians.
<p>
<h1><A NAME="getAttribute">getAttribute</A></h1>
<p>
Return the value of a marker attribute.
<p>
Usage:
<p>
<pre>
        value = getAttribute attribute-name
</pre>
<p>
<h1><A NAME="setAttribute">setAttribute</A></h1>
<p>
Set the value of a marker attribute.
<p>
Usage:
<p>
<pre>
        setAttribute attribute-name value
</pre>
<p>
<h1><A NAME="getAttributes">getAttributes</A></h1>
<p>
Return the values of a list of marker attributes.
<p>
Usage:
<p>
<pre>
          getAttributes attribute-list
  i.e.    getAttributes {name value [name value ...]}
    or    getAttributes name value [name value ...]
</pre>
<p>
where "value" is the name of the variable in which the attribute value 
is to be stored.
<p>
<h1><A NAME="setAttributes">setAttributes</A></h1>
<p>
Set the values of a list of marker attributes.
<p>
Usage:
<p>
<pre>
        setAttributes attribute-list
  i.e.  setAttributes {name value [name value ...]}
</pre>
<p>
where "value" is the new value of the associated marker attribute.
<p>
<h1><A NAME="getVertices">getVertices</A></h1>
<p>
Get some or all of the vertices making up the polygon or
polyline representation of a marker.
<p>
Usage:
<p>
<pre>
        getVertices points [first npts]
</pre>
<p>
The polygon or polyline representation of a marker is returned in the
variable "points", as a string of the form { {x y} {x y} ...}.  The first
point is number zero.
<p>
<h1><A NAME="setVertices">setVertices</A></h1>
<p>
Set some or all of the vertices making up the polygon or
polyline representation of a marker.
<p>
Usage:
<p>
<pre>
        setVertices points [first npts]
</pre>
<p>
The polygon or polyline representation of a marker is set using the points
passed in the "points" variable as a string of the form { {x y} {x y} ...}.
If FIRST and NPTS are not specified first is assumed to be zero (the first
point) and NPTS is the length of the points array.
<p>
<h1><A NAME="getRegion">getRegion</A></h1>
<p>
Return as a text string a high level description of the
region defined by a marker.
<p>
Usage:
<p>
<pre>
        region = getRegion [unmap] [coord-type]
</pre>
<p>
The output string defines the marker type and the major marker positional
attributes.  The region description formats for the various marker types
follow.
<p>
<pre>
        text raster x y width height
        line raster x y x y
        polyline raster npts { {x y} {x y} ...}
        rectangle raster x y width height rotangle
        circle raster x y radius
        ellipse raster x y width height rotangle
        polygon raster npts { {x y} {x y} ...}
</pre>
<p>
Here, width and height refer to the distance from the marker center to an
edge, not to the width or height of the whole marker.  This avoids
ambiguities about where the edge of a marker is if the width is even or
odd.  Using the center to edge measurement, the edge is at x +/- width,
y +/- height.
<p>
If the "unmap" flag is given getRegion will attempt to associate the
marker with a mapped raster, reversing any mappings from the screen back
to the original source raster, and returning the raster number and raster
coordinates and marker sizes.  If "unmap" is not given the marker
coordinates will refer to raster 0.  Either pixel ("pixel") or NDC
("ndc") coordinates may be returned, pixel coordinates being the default.
<p>
<h1><A NAME="getRect">getRect</A></h1>
<p>
Return the region enclosed by a rectangle marker.  The rect is
returned in a form convenient for use as the destination rect in a gterm
widget raster mapping.
<p>
Usage:
<p>
<pre>
        getRect dx dy dnx dny
</pre>
<p>
The rect is stored in the output arguments.
<p>