# Graphics Marker class

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.

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.

                   createMarker name [attribute-list]
                     markerInit

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.

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

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.

                    makeCopy name
                 addCallback procedure [event [event ...]]
                      notify [event-type [param [param ...]]]
                     destroy [nocallback]

                     markpos
                      redraw [function] [markpos|nomarkpos] [erase|noerase]

                       raise [reference-marker]
                       lower [reference-marker]

                        move x y
                      resize width height
                      rotate angle                # radians

                         set attribute value      # alias for setAttribute
                 value = get attribute            # alias for getAttribute

                setAttribute attribute value
        value = getAttribute attribute
               setAttributes attribute-list
               getAttributes attribute-list
                 setVertices points first npts
                 getVertices points first npts

          region = getRegion [unmap] [coord-type]
                     getRect dx dy dnx dny

Marker positions and dimensions are given in window (raster 0) coordinates.

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 <ObmW/Gterm.h> for a list of marker types and attributes.

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

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.

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

Default translations when pointer is over a marker. default Marker Translations

            Shift < Btn1Motion >i    m_rotateResize()
                  < Btn1Motion >    m_moveResize()
              Shift < Btn1Down >    m_raise()  m_markpos()
                    < Btn1Down >    m_raise()  m_markposAdd()
                      < Btn1Up >    m_redraw() m_destroyNull()
                    < Btn2Down >    m_lower()
                < Key > BackSpace   m_deleteDestroy()
                   < Key > Delete   m_deleteDestroy()
                    < KeyPress >    m_input()
                      < Motion >    track-cursor()

MARKER class commands.

makeCopy

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.

Usage:

             makeCopy name

# addCallback

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.

Usage:

    	addCallback procedure [event [event ...]]

# notify

Generate a Marker pseudo-event, causing any posted client callback procedures to be called.

Usage:

            notify [event-type [param [param ...]]]

# destroy

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.

Usage:

            destroy

# markpos

Mark the current position of a marker for a later redraw.

Usage:

            markpos

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.

# redraw

Redraw a marker.

Usage:

            redraw [function] [erase|noerase] [markpos|nomarkpos]

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.

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.

# raise

Raise a marker, i.e., cause it to be drawn on top of other markers when overlapping markers are drawn.

Usage:

            raise [reference-marker]

In a reference marker is named the marker will raise itself above this marker, otherwise the raised marker becomes the topmost marker.

# lower

Lower a marker, i.e., cause it to be drawn beneath other markers when overlapping markers are drawn.

Usage:

            lower [reference-marker]

In a reference marker is named the marker will lower itself beneath this marker, otherwise the lowered marker becomes the lowest marker.

# move

Move a marker.

Usage:

            move x y

Move the marker center to the indicated coordinates in the display window.

# resize

Resize a marker.

Usage:

             resize width height

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.

# rotate

Rotate a marker.

Usage:

             rotate angle

Redraw a marker oriented to the given rotation angle. The angle is given in radians.

# getAttribute

Return the value of a marker attribute.

Usage:

            value = getAttribute attribute-name

# setAttribute

Set the value of a marker attribute.

Usage:

            setAttribute attribute-name value

# getAttributes

Return the values of a list of marker attributes.

Usage:

              getAttributes attribute-list
      i.e.    getAttributes {name value [name value ...]}
        or    getAttributes name value [name value ...]

where "value" is the name of the variable in which the attribute value is to be stored.

# setAttributes

Set the values of a list of marker attributes.

Usage:

            setAttributes attribute-list
      i.e.  setAttributes {name value [name value ...]}

where "value" is the new value of the associated marker attribute.

# getVertices

Get some or all of the vertices making up the polygon or polyline representation of a marker.

Usage:

            getVertices points [first npts]

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.

# setVertices

Set some or all of the vertices making up the polygon or polyline representation of a marker.

Usage:

            setVertices points [first npts]

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.

# getRegion

Return as a text string a high level description of the region defined by a marker.

Usage:

            region = getRegion [unmap] [coord-type]

The output string defines the marker type and the major marker positional attributes. The region description formats for the various marker types follow.

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

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.

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.

# getRect

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.

Usage:

            getRect dx dy dnx dny

The rect is stored in the output arguments.