diff options
| author | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
|---|---|---|
| committer | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
| commit | fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 (patch) | |
| tree | bdda434976bc09c864f2e4fa6f16ba1952b1e555 /vendor/x11iraf/obm/docs | |
| download | iraf-linux-fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4.tar.gz | |
Initial commit
Diffstat (limited to 'vendor/x11iraf/obm/docs')
62 files changed, 10619 insertions, 0 deletions
diff --git a/vendor/x11iraf/obm/docs/gui.doc/TclQuickRef.html b/vendor/x11iraf/obm/docs/gui.doc/TclQuickRef.html new file mode 100644 index 00000000..3f41eb29 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/TclQuickRef.html @@ -0,0 +1,208 @@ +<title>Tcl Quick Reference</title> + + +<H1><pre>TCL Quick Reference +Based on TCL version 6.4 +Jeff Tranter 12-Aug-1992</pre><h1> + + +<pre> +Basic Language Features + +# comment (continues to end of line) +" " allows embedding whitespace in arguments; substitutions made +{ } group arguments; substitutions not made +[ ] command substitution; replace with result of command +$var variable substitution +; command separator + + +Backslash Substitution + +\b backspace +\[ open bracket +\f form feed +\] close bracket +\n newline +\$ dollar sign +\r carriage return +\<space> space +\t tab +\; semi-colon +\v vertical tab +\" double-quote +\{ left brace +\<newln> newline +\} right brace +\\ backslash +\ddd octal digits + + +Built-in Variables + +env +errorCode +errorInfo + + +Operators (in decreasing order of precedence) + +- ~ ! unary minus, bit-wise NOT, logical NOT +* / % multiply, divide, remainder ++ - add, subtract +<< >> left and right shift +< > <= >= boolean comparisons +== != boolean equal, not equa +& bit-wise AND +^ bit-wise exclusive OR +| bit-wise inclusive OR +&& logical AND +|| logical OR +x?y:z conditional operator + +All operators support integers. +All support floating point except ~, %, <<, >>, &, ^, and | +Boolean operators can also be used on strings. + + +Regular Expressions +regex | regex match either expression +regex* match zero or more of regex +regex+ match one or more of regex +regex? match zero or one of regex +. any single character (except newline) +^ match beginning of line +$ match end of line +\c match character c +c match character c +[] match set of characters +[a-z] match range of characters +[^] match characters not in range or set +() group expressions + + +Keywords + +append varName value [value value ...] +array anymore arrayName searchId +array donesearch arrayName searchId +array names arrayName +array nextelement arrayName searchId +array size arrayName +array startsearch arrayName +break +case string [in] patList body [patList body ...] +case string [in] {patList body [patList body ...] +catch command [varName] +cd [dirName] +close fileId +concat arg [arg ...] +continue +error message [info] [code] +eof fileId +error $errMsg $savedInfo +eval arg [arg ...] +exec arg [arg ...] +exit [returnCode] +expr arg +file atime name +file dirname name +file executable name +file exists name +file extension name +file isdirectory name +file isfile name +file lstat name varName +file mtime name +file owned name +file readable name +file readlink name +file rootname name +file size name +file stat name varName +file tail name +file type name +file writable name +flush fileId +for start test next body +foreach varname list body +format formatString [arg arg ...] +gets fileId [varName] +glob [-nocomplain] filename [filename ...] +global varname [varname ...] +history +history add command [exec] +history change newValue [event] +history event [event] +history info [count] +history keep count +history nextid +history redo [event] +history substitute old new [event] +history words selector [event] +if test [then] trueBody [else] [falseBody] +incr varName [increment] +info args procname +info body procname +info cmdcount +info commands [pattern] +info default procname arg varname +into variable varname +info exists varName +info globals [pattern] +info level [number] +info library +info locals [pattern] +info procs [pattern] +info script +info tclversion +info vars [pattern] +join list [joinString] +lappend varName value [value value ...] +lindex list index +linsert list index element [element element ...] +list arg [arg ...] +llength list +lrange list first last +lreplace list first last [element element ...] +lsearch list pattern +lsort list +open fileName [access] +proc name args body +puts fileId string [nonewline] +pwd +read fileId +read fileId nonewline +read fileId numBytes +regexp [-indices] [-nocase] exp string [matchVar] [subMatchVar subMatchVar ...] +regsub [-all] [-nocase] exp string subSpec varName +rename oldName newName +return [value] +scan string format varname1 [varname2 ...] +seek fileId offset [origin] +set varname [value] +source fileName +split string [splitChars] +string compare string1 string2 +string first string1 string2 +string index string charIndex +string last string1 string2 +string length string +string match pattern string +string range string first last +string tolower string +string toupper string +string trim string [chars] +string trimleft string [chars] +string trimright string [chars] +tell fileId +time command [count] +trace variable name ops command +trace vdelete name ops command +trace vinfo name +unknown cmdName [arg arg ...] +unset name [name name ...] +uplevel [level] command [command ...] +upvar [level] otherVar myVar [otherVar myVar ...] +while test body +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/alphabetic.html b/vendor/x11iraf/obm/docs/gui.doc/alphabetic.html new file mode 100644 index 00000000..0c141617 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/alphabetic.html @@ -0,0 +1,39 @@ +<title>Alphabetized list of GUI commands</title> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<pre> +<a href="gtermclass.html#activate">activate</a> <a href="servercom.html#activate">activate</a> <a href="notyet.html">activeMapping</a> <a href="gmc.html#addCallback">addCallback</a> <a href="gtermclass.html#addCallback">addCallback</a> +<a href="uiparameterclass.html#addCallback">addCallback</a> <a href="widgetclass.html#addCallback">addCallback</a> <a href="widgetclass.html#addEventHandler">addEventHandler</a> <a href="widgetclass.html#append">append</a> <a href="servercom.html#appInitialize">appInitialize</a> +<a href="notyet.html">assignRaster</a> <a href="gtermclass.html#bell">bell</a> <a href="widgetclass.html#do_userproc">call</a> <a href="gtermclass.html#clearScreen">clearScreen</a> <a href="widgetclass.html#configure">configure</a> +<a href="notyet.html">copyPixmap</a> <a href="notyet.html">copyRaster</a> <a href="servercom.html#createBitmap">createBitmap</a> <a href="servercom.html#createCursor">createCursor</a> <a href="gtermclass.html#createMarker">createMarker</a> +<a href="servercom.html#createMenu">createMenu</a> <a href="servercom.html#createObjects">createObjects</a> <a href="notyet.html">createPixmap</a> <a href="servercom.html#createPixmap">createPixmap</a> <a href="notyet.html">createRaster</a> +<a href="gtermclass.html#deactivate">deactivate</a> <a href="servercom.html#deactivate">deactivate</a> <a href="uiparameterclass.html#deleteCallback">deleteCallback</a> <a href="widgetclass.html#deleteCallback">deleteCallback</a> <a href="servercom.html#deleteTimedCallback">deleteTimedCallback</a> +<a href="servercom.html#deleteWorkCallback">deleteWorkCallback</a> <a href="gmc.html#destroy">destroy</a> <a href="servercom.html#destroyMenu">destroyMenu</a> <a href="servercom.html#destroyObject">destroyObject</a> +<a href="notyet.html">destroyRaster</a> <a href="notyet.html">disableMapping</a> <a href="notyet.html">drawAlphaText</a> <a href="notyet.html">drawDialogText</a> <a href="notyet.html">drawMarker</a> +<a href="notyet.html">drawPolygon</a> <a href="notyet.html">drawPolyline</a> <a href="notyet.html">drawPolymarker</a> <a href="servercom.html#createMenu">editMenu</a> <a href="notyet.html">enableMapping</a> +<a href="ximclient.html#encodewcs">encodewcs</a> <a href="notyet.html">endDialog</a> <a href="notyet.html">eraseDialog</a> <a href="ximclient.html#fitFrame">fitFrame</a> <a href="gtermclass.html#flip">flip</a> +<a href="ximclient.html#flip">flip</a> <a href="gtermclass.html#flush">flush</a> <a href="notyet.html">freeColormap</a> <a href="notyet.html">freeMapping</a> <a href="clientclass.html#gcmd">gcmd</a> +<a href="gmc.html#getAttribute">get</a> <a href="widgetclass.html#get">get</a> <a href="notyet.html">getAlphaTextSize</a> <a href="gmc.html#getAttribute">getAttribute</a> +<a href="gmc.html#getAttributes">getAttributes</a> <a href="gtermclass.html#getCursorPos">getCursorPos</a> <a href="notyet.html">getDialogTextSize</a> <a href="ximclient.html#getFrame">getFrame</a> +<a href="widgetclass.html#getItem">getItem</a> <a href="notyet.html">getLogRes</a> <a href="gtermclass.html#getMapping">getMapping</a> <a href="notyet.html">getPhysRes</a> <a href="gtermclass.html#getPixel">getPixel</a> +<a href="gtermclass.html#getRaster">getRaster</a> <a href="gmc.html#getRect">getRect</a> <a href="gmc.html#getRegion">getRegion</a> <a href="servercom.html#getResource">getResource</a> <a href="servercom.html#getResources">getResources</a> +<a href="uiparameterclass.html#getValue">getValue</a> <a href="gmc.html#getVertices">getVertices</a> <a href="clientclass.html#gkey">gkey</a> <a href="widgetclass.html#highlight">highlight</a> <a href="notyet.html">initMappings</a> +<a href="widgetclass.html#isRealized">isRealized</a> <a href="widgetclass.html#isSensitive">isSensitive</a> <a href="clientclass.html#literal">literal</a> <a href="gtermclass.html#loadColormap">loadColormap</a> <a href="gmc.html#lower">lower</a> +<a href="gmc.html#makeCopy">makeCopy</a> <a href="widgetclass.html#manage">manage</a> <a href="widgetclass.html#map">map</a> <a href="gtermclass.html#markerInit">markerInit</a> <a href="gmc.html#markpos">markpos</a> +<a href="ximclient.html#matchFrames">matchFrames</a> <a href="gmc.html#move">move</a> <a href="widgetclass.html#move">move</a> <a href="notyet.html">nextColormap</a> <a href="ximclient.html#nextFrame">nextFrame</a> +<a href="gtermclass.html#nextMapping">nextMapping</a> <a href="notyet.html">nextRaster</a> <a href="gmc.html#notify">notify</a> <a href="uiparameterclass.html#notify">notify</a> <a href="notyet.html">nRasters</a> +<a href="ximclient.html#pan">pan</a> <a href="widgetclass.html#do_popdown">popdown</a> <a href="widgetclass.html#popdown">popdown</a> <a href="widgetclass.html#do_popup">popup</a> <a href="widgetclass.html#popup">popup</a> +<a href="widgetclass.html#popupSpringLoaded">popupSpringLoaded</a> <a href="servercom.html#postActivateCallback">postActivateCallback</a> <a href="servercom.html#postTimedCallback">postTimedCallback</a> +<a href="servercom.html#postWorkCallback">postWorkCallback</a> <a href="ximclient.html#prevFrame">prevFrame</a> <a href="servercom.html#print">print</a> <a href="notyet.html">queryRaster</a> +<a href="ximclient.html#Quit">Quit</a> <a href="gmc.html#raise">raise</a> <a href="gtermclass.html#rasterInit">rasterInit</a> <a href="notyet.html">readColormap</a> <a href="gtermclass.html#readPixels">readPixels</a> +<a href="widgetclass.html#realize">realize</a> <a href="gmc.html#redraw">redraw</a> <a href="notyet.html">refreshMapping</a> <a href="notyet.html">refreshPixels</a> <a href="servercom.html#resetReset">reset-server</a> +<a href="gtermclass.html#reset">reset</a> <a href="gmc.html#resize">resize</a> <a href="widgetclass.html#resize">resize</a> <a href="ximclient.html#retCursorVal">retCursorVal</a> <a href="gmc.html#rotate">rotate</a> +<a href="gtermclass.html#selectRaster">selectRaster</a> <a href="servercom.html#send">send</a> <a href="gmc.html#setAttribute">set</a> <a href="widgetclass.html#set">set</a> <a href="gmc.html#setAttribute">setAttribute</a> +<a href="gmc.html#setAttributes">setAttributes</a> <a href="notyet.html">setColorIndex</a> <a href="ximclient.html#setColormap">setColormap</a> <a href="gtermclass.html#setCursorPos">setCursorPos</a> <a href="gtermclass.html#setCursorType">setCursorType</a> +<a href="notyet.html">setDataLevel</a> <a href="notyet.html">setFillType</a> <a href="ximclient.html#setFrame">setFrame</a> <a href="gtermclass.html#setGterm">setGterm</a> <a href="notyet.html">setLineStyle</a> +<a href="notyet.html">setLineWidth</a> <a href="widgetclass.html#setList">setList</a> <a href="notyet.html">setLogRes</a> <a href="gtermclass.html#setMapping">setMapping</a> <a href="notyet.html">setPhysRes</a> +<a href="gtermclass.html#setPixel">setPixel</a> <a href="gtermclass.html#setRaster">setRaster</a> <a href="widgetclass.html#setSensitive">setSensitive</a> <a href="notyet.html">setTextRes</a> <a href="uiparameterclass.html#setValue">setValue</a> +<a href="gmc.html#setVertices">setVertices</a> <a href="notyet.html">startDialog</a> <a href="widgetclass.html#unhighlight">unhighlight</a> <a href="widgetclass.html#unmanage">unmanage</a> <a href="widgetclass.html#unmap">unmap</a> +<a href="gtermclass.html#unmapPixel">unmapPixel</a> <a href="widgetclass.html#unrealize">unrealize</a> <a href="widgetclass.html#userEventHandler">userEventHandler</a> <a href="ximclient.html#windowColormap">windowColormap</a> +<a href="notyet.html">writeColormap</a> <a href="gtermclass.html#writePixels">writePixels</a> <a href="ximclient.html#zoom">zoom</a> <a href="ximclient.html#zoom">zoomAbs</a> +</pre> + diff --git a/vendor/x11iraf/obm/docs/gui.doc/athena.gif b/vendor/x11iraf/obm/docs/gui.doc/athena.gif Binary files differnew file mode 100644 index 00000000..56e74e96 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/athena.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/athena.html b/vendor/x11iraf/obm/docs/gui.doc/athena.html new file mode 100644 index 00000000..dcd3decf --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/athena.html @@ -0,0 +1,73 @@ +<title>Athena Widgets</title> +<h1><IMG SRC="irafgui.gif"> Athena Widgets</h1> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +The Athena widgets were written at MIT. Each of the widget names is a +hypertext link to a page describing the widget and including an example. +<p> +<h2>Simple Widgets</h2> +<dl> +<dt><a href="commandwidget.html">Command</a> +<dd>A push button that, when selected, may cause a specific action +to take place. This widget can display a multi-line string or a bitmap image. +<dt><a href="gripwidget.html">Grip</a> +<dd>A rectangle that, when selected, will cause an action to take +place. +<dt><a href="labelwidget.html">Label</a> +<dd>A rectangle that may contain one or more lines of text or a bitmap image. +<dt><a href="listwidget.html">List</a> +<dd>A list of text strings presented in row column format that may be +individually selected. When an element is selected an action may take place. +<dt><a href="pannerwidget.html">Panner</a> +<dd>A rectangular area containing a <i>slider</i> that may be moved in two +dimensions. Notification of movement may be continuous or discrete. +<dt><a href="repeaterwidget.html">Repeater</a> +<dd>A push button that triggers an action at an increasing rate when selected. +<dt><a href="scrollbarwidget.html">Scrollbar</a> +<dd>A rectangular area containg a <i>thumb</i> that, when slid along one +dimension, may cause a specific action to take place. The Scrollbar may +be oriented horixontall or vertically. +<dt><a href="simplewidget.html">Simple</a> +<dd>The vase class for most of the simple widgets. Provides a rectangular +area with a settable mouse cursor and special border. +<dt><a href="stripchartwidget.html">StripChart</a> +<dd>A real time data graph that will automatically update and scroll. +<dt><a href="togglewidget.html">Toggle</a> +<dd>A push button [see Command] that contains state information. Toggles +may also be used as radio buttons to implement a "one of many" group of +buttons. +</dl> +<h2>Text Widgets</h2> +<dl> +<dt><a href="textwidget.html">Text</a> +<dd>Basic text widget supports edit commands. +<dt><a href="asciitextwidget.html">AsciiText</a> +<dd>This widget contains a text widget and also includes AsciiSrc and +and AsciiSink widgets. +</dl> +<h2>Composite and Constraint Widgets</h2> +<dl> +<dt><a href="boxwidget.html">Box</a> +<dd>This widget will pack its children as tightly as possible in +non-overlapping rows. +<dt><a href="dialogwidget.html">Dialog</a> +<dd>An implementation of a commonly used interaction semantic to +prompt for auxiliary input from the user, such as a filename. +<dt><a href="formwidget.html">Form</a> +<dd>A more sophisticated layout widget that allows the children to specify +their positions relative to the other children, or to the edges of the form. +<dt><a href="panedwidget.html">Paned</a> +<dd>Allows children to be tiled vertically or horizontally. Controls are also +provided to allow the user to dynamically resize the individual panes. +<dt><a href="portholewidget.html">Porthole</a> +<dd>Allows viewing of a managed child which is as large as, or larger than its +parent, typically under control of a Panner widget. +<dt><a href="treewidget.html">Tree</a> +<dd>Provides geometry management of widgets arranged in a directed, acyclic +graph. +<dt><a href="viewportwidget.html">Viewport</a> +<dd>Consists of a frame, one of two scrollbars, and an inner window. The +inner window can contain all the data that is to be displayed. This inner +window will be clipped by the frame with the scrollbars controlling which +section of the inner window is currently visible. +</dl> diff --git a/vendor/x11iraf/obm/docs/gui.doc/blueline.gif b/vendor/x11iraf/obm/docs/gui.doc/blueline.gif Binary files differnew file mode 100644 index 00000000..d911fe03 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/blueline.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/book.p1.ps.gz b/vendor/x11iraf/obm/docs/gui.doc/book.p1.ps.gz Binary files differnew file mode 100644 index 00000000..360e4950 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/book.p1.ps.gz diff --git a/vendor/x11iraf/obm/docs/gui.doc/clientclass.html b/vendor/x11iraf/obm/docs/gui.doc/clientclass.html new file mode 100644 index 00000000..407c177b --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/clientclass.html @@ -0,0 +1,75 @@ +<title>CLIENT class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> CLIENT class</h1> +<p> +<HR> +<p> +The client is the client application, which provides the functionality +underlying the UI. When a message is sent to the client object it usually +results in a message being sent to the client *application*, usually an +external program communicating via IPC, which has little or no knowledge +of the UI. The client application receives and executes commands delivered +by the UI via the client object. Output from the client may or may not +come back to the object manager. That portion of the output which comes +back to the object manager is in the form of assignments of string values +to <a href="uiparameterclass.html">UI parameter-class objects</a> (another +way of thinking of this is that +messages or events are sent to and acted upon by the parameter objects). +Hence, the client object is output only so far as the client application +is concerned. +<p> +The Client-class commands are used to send a message to the client. +<p> +<pre> + <a href="#gkey">gkey</a> <key> + <a href="#gcmd">gcmd</a> <command-string> + <a href="#literal">literal</a> <command> +</pre> +<p> +or just <command>, e.g., "send client <command>" will work in most cases. +<p> +<a href="#gkey">GKEY</a> sends an IRAF graphics keystroke. +<a href="#gcmd">GCMD</a> sends an +IRAF graphics colon command. <a href="#literal">LITERAL</a> sends a literal +command string to the +client. The keyword "literal" may optionally be omitted, i.e., "send client +foo" and "send client literal foo" are the same. The keyword "literal" may +be used to ensure that the client command string which follows will not +be interpreted as a Client-class command (such as gkey, gcmd, or literal). +<p> +<p> +<h1><A NAME="gcmd">gcmd</A></h1> +<p> +Send a graphics command string to the client application. +A graphics command string is a graphics cursor value with the key set +to `:' and the command string given as the string part of the cursor +value. The protocol module which posted the client output procedure is +responsible for encoding and sending the cursor command. +<p> +Usage: +<p> +<pre> + gcmd <command-string> +</pre> +<p> +<h1><A NAME="gkey">gkey</A></h1> +<p> +Send a graphics key event to the client application. +A graphics key event is a graphics cursor value with the key set to some +integer value and a null string part. +<p> +Usage: +<p> +<pre> +gkey <key> +</pre> +<p> +<h1><A NAME="literal">literal</A></h1> +<p> +Send a literal command to the client application. +<p> +Usage: +<p> +<pre> + literal <command> +</pre> + diff --git a/vendor/x11iraf/obm/docs/gui.doc/coloredline.gif b/vendor/x11iraf/obm/docs/gui.doc/coloredline.gif Binary files differnew file mode 100644 index 00000000..f08eb184 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/coloredline.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/einstein.html b/vendor/x11iraf/obm/docs/gui.doc/einstein.html new file mode 100644 index 00000000..1d6e1927 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/einstein.html @@ -0,0 +1,5 @@ +<title>Einstein</title> +<p> +<a href="notyet.html"><IMG align=middle SRC="einstein.gif"></a> +Yep, that's uncle Albert! +<p> diff --git a/vendor/x11iraf/obm/docs/gui.doc/example.html b/vendor/x11iraf/obm/docs/gui.doc/example.html new file mode 100644 index 00000000..40b0b4cd --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/example.html @@ -0,0 +1,6 @@ +<title>Example: Imbrowse</title> +<h2><IMG SRC="irafgui.gif"> Example: Imbrowse</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +<a href="exampmap"><IMG SRC="imbrowse.gif" ISMAP></a> +<p> diff --git a/vendor/x11iraf/obm/docs/gui.doc/exampmap b/vendor/x11iraf/obm/docs/gui.doc/exampmap new file mode 100644 index 00000000..d2284a37 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/exampmap @@ -0,0 +1,30 @@ + +default imbrowsemap/none.html + +# The ellipse containing "panel" +rect imbrowsemap/panel.html 287,19 366,56 + +# The ellipse containing "objView" +rect imbrowsemap/objView.html 226,98 312,130 + +# The ellipse containing "controlForm" +rect imbrowsemap/controlForm.html 266,154 382,186 + +# The ellipse containing "headerText" +rect imbrowsemap/headerText.html 336,96 450,130 + +# The ellipse containing "sectionBox" +rect imbrowsemap/sectionBox.html 461,99 577,131 + +# The ellipse containing "statusBox" +rect imbrowsemap/statusBox.html 75,158 202,190 + +# The ellipse containing "dirSelect" +rect imbrowsemap/dirSelect.html 7,280 95,320 + +# The ellipse containing "dirName" +rect imbrowsemap/dirName.html 74,342 167,380 + +# The ellipse containing "imageButton" +rect imbrowsemap/imageButton.html 171,280 298,315 + diff --git a/vendor/x11iraf/obm/docs/gui.doc/gmc.html b/vendor/x11iraf/obm/docs/gui.doc/gmc.html new file mode 100644 index 00000000..9e124846 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/gmc.html @@ -0,0 +1,402 @@ +<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 <ObmW/Gterm.h> 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 < 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() +</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> diff --git a/vendor/x11iraf/obm/docs/gui.doc/gterm.gif b/vendor/x11iraf/obm/docs/gui.doc/gterm.gif Binary files differnew file mode 100644 index 00000000..042debf5 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/gterm.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/gtermclass.html b/vendor/x11iraf/obm/docs/gui.doc/gtermclass.html new file mode 100644 index 00000000..5fcdab10 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/gtermclass.html @@ -0,0 +1,694 @@ +<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 <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. +<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. + diff --git a/vendor/x11iraf/obm/docs/gui.doc/gui.html b/vendor/x11iraf/obm/docs/gui.doc/gui.html new file mode 100644 index 00000000..d7e20546 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/gui.html @@ -0,0 +1,93 @@ +<html> +<body bgcolor=#FFFFFF> + +<title>IRAF Object Manager</title> +<h1>IRAF Object Manager</h1> +<HR> +<p> +An Object Manager (OBM) user interface (UI) consists of one or more windows +containing an arbitrary hierarchy of widgets. These widgets and their +runtime actions are defined by an interpreted text program uploaded +by the client application, which does not itself deal directly with +the window user interface. Currently, this interpreted program is written +in Tcl. +<p> +The object manager provides a higher level of abstraction for dealing +with widgets and other UI objects. The main function of the object +manager is to deliver messages to UI objects. Each instance of a widget, +the client programs, and the OBM itself are +objects in the UI. The UI contains other types of objects however, +including the client object (client application), the server object +(the object manager itself), and the application specific UI parameters, +each of which is an object with a callback list of UI procedures to be +called when the parameter value changes. All of these UI objects can +receive messages and take actions as a result. Messages may come from the +client application, or as a result of actions executed by the interpreted +UI code in response to graphics events. +<p> +<h2>Object classes:</h2> +<p> +<pre> +<a href="Client.html">Client</a> the client application +<a href="Server.html">Server</a> the object manager itself +<a href="widgetclass.html">Widget</a> widgets +<a href="uiparameterclass.html">ParameterUI</a> control parameter +<a href="gtermclass.html">Gterm</a> graphics/imaging widget +<a href="gmc.html">Graphics Markers</a> marker widgets +<a href="ximclient.html">Image Client</a> imageing widget +<p> +<a href="notyet.html">Various Xt and Athena widgets</a> + {box, shell, label, command, text, list, etc.} +</pre> +<p> +To locate specific IRAF GUI commands quickly, here is an +<pre> + <a href="alphabetic.html">alphabetized list of IRAF GUI commands</a> +</pre> +<p> +Sophisticated graphics applications will download a UI during initialization +to define a custom graphics user interface. This is done by sending a +message to the object manager. Naive applications assume a simple graphics +terminal and do not download a UI; in this case, a default UI is created +for the application when the UI is enabled with ObmEnable. The default +UI is a single top level shell window containing a single gterm (graphics +terminal) widget. +<p> +<pre> + <a href="servercom.html#resetReset">reset-server</a> + <a href="servercom.html#appInitialize">appInitialize</a> appname,appclass,resources + <a href="servercom.html#createObjects">createObjects</a> [resource-name] + (UI specific code) + <a href="servercom.html#activate">activate</a> +</pre> +<p> +A UI specification consists of a sequence of commands to be executed by +the server object. This is downloaded by the client as a message for the +server object. The commands should include "reset-server" (this must be +the first executable command), "appInitialize" (defines the UI objects and +their resources), and "createObjects" (creates the objects and the widget +tree), followed by any UI specific commands to define and register UI +callback procedures. Finally, "activate" is executed to activate the new +user interface. +<p> +Class descriptors for all UI object classes. In the following, only the +class initializer function needs to be set statically, since the class +initializer function will initialize the remaining fields of the class +descriptor at run time when the object manager is opened. +<p> +<pre> + Server Client Parameter Gterm Core + Object Widget Command Grip Label + List Scrollbar StripChart Toggle SimpleMenu + Sme SmeBSB SmeLine MenuButton AsciiText + Box Dialog Form Paned Viewport + + Shell + OverrideShell + WMShell + TransientShell + TopLevelShell + ApplicationShell +</pre> +</body> +</html> diff --git a/vendor/x11iraf/obm/docs/gui.doc/guiintro.html b/vendor/x11iraf/obm/docs/gui.doc/guiintro.html new file mode 100644 index 00000000..81511434 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/guiintro.html @@ -0,0 +1,9 @@ +<title>Introduction and Overview</title> +<h2><IMG SRC="irafgui.gif"> Introduction and Overview</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<h3>Design Philosophy</h3> +<p> +<h3>Basic Tools</h3> +<p> +<h3><a href="example.html">An Example</a></h3> +<p> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowse.gif b/vendor/x11iraf/obm/docs/gui.doc/imbrowse.gif Binary files differnew file mode 100644 index 00000000..af1e7c0a --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowse.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/controlForm.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/controlForm.html new file mode 100644 index 00000000..88e74c83 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/controlForm.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the controlForm</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirName.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirName.html new file mode 100644 index 00000000..4c4b3cb3 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirName.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the dirName</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirSelect.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirSelect.html new file mode 100644 index 00000000..fe8f8f40 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/dirSelect.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the dirSelect</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/headerText.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/headerText.html new file mode 100644 index 00000000..a132c5f3 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/headerText.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the headerText</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/imageButton.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/imageButton.html new file mode 100644 index 00000000..12595f3c --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/imageButton.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the imageButton</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/none.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/none.html new file mode 100644 index 00000000..9cd7d5e3 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/none.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse none</title> +<h2><IMG SRC="irafgui.gif"> You selected none of the ellipses</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/objView.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/objView.html new file mode 100644 index 00000000..a830a57a --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/objView.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the objView</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/panel.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/panel.html new file mode 100644 index 00000000..b6b0ff2e --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/panel.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the panel</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/sectionBox.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/sectionBox.html new file mode 100644 index 00000000..60895b18 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/sectionBox.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the sectionBox</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/statusBox.html b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/statusBox.html new file mode 100644 index 00000000..061f5045 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imbrowsemap/statusBox.html @@ -0,0 +1,3 @@ +<title>Example: Imbrowse panel</title> +<h2><IMG SRC="irafgui.gif"> You selected the statusBox</h2> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> diff --git a/vendor/x11iraf/obm/docs/gui.doc/imtool.gif b/vendor/x11iraf/obm/docs/gui.doc/imtool.gif Binary files differnew file mode 100644 index 00000000..a29811ef --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/imtool.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/intro.gif b/vendor/x11iraf/obm/docs/gui.doc/intro.gif Binary files differnew file mode 100644 index 00000000..7f7af646 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/intro.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/irafgui.gif b/vendor/x11iraf/obm/docs/gui.doc/irafgui.gif Binary files differnew file mode 100644 index 00000000..032c72d5 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/irafgui.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/llama.gif b/vendor/x11iraf/obm/docs/gui.doc/llama.gif Binary files differnew file mode 100644 index 00000000..be0ceef4 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/llama.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/marker.gif b/vendor/x11iraf/obm/docs/gui.doc/marker.gif Binary files differnew file mode 100644 index 00000000..639b19bd --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/marker.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/newgui.html b/vendor/x11iraf/obm/docs/gui.doc/newgui.html new file mode 100644 index 00000000..36e7ec1a --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/newgui.html @@ -0,0 +1,18 @@ +<title>IRAF GUI Documentation</title> +<h1><IMG SRC="irafgui.gif"> IRAF Graphical User Interfaces</h1> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +This hypertext work is introductory documentation for the IRAF graphical +user interface facility introduced with IRAF version 2.10.3. Questions +can be directed, via electronic mail, to iraf.noao.edu or posted to the +newsgroup adass.iraf.programmer. +<p> +<pre> +<a href="guiintro.html"><IMG ALIGN=MIDDLE SRC="intro.gif"></a> An introduction and overview + +<a href="widgets.html"><IMG ALIGN=MIDDLE SRC="widgets.gif"></a> The widgets and how they work + +<a href="tcl.html"><IMG ALIGN=MIDDLE SRC="tcl.gif"></a> The language used to build GUIs + +<a href="notyet2.html"><IMG ALIGN=MIDDLE SRC="softgui.gif"></a> Software - GUI communication +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/notyet.html b/vendor/x11iraf/obm/docs/gui.doc/notyet.html new file mode 100644 index 00000000..9a292a44 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/notyet.html @@ -0,0 +1,5 @@ +<title>NOTYET</title> +<p> +<a href="einstein.html"><IMG align=middle SRC="einstein.gif"></a> +The info you requested is not yet available. +<p> diff --git a/vendor/x11iraf/obm/docs/gui.doc/notyet2.html b/vendor/x11iraf/obm/docs/gui.doc/notyet2.html new file mode 100644 index 00000000..2a6e3dca --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/notyet2.html @@ -0,0 +1,5 @@ +<title>NOTYET</title> +<p> +<IMG align=middle SRC="llama.gif"> +The info you requested is not yet available. +<p> diff --git a/vendor/x11iraf/obm/docs/gui.doc/otherwidgets.html b/vendor/x11iraf/obm/docs/gui.doc/otherwidgets.html new file mode 100644 index 00000000..f477fdc7 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/otherwidgets.html @@ -0,0 +1,10 @@ +<title>Other Widgets</title> +<h1><IMG SRC="irafgui.gif"> Other Widgets</h1> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +There are a few more widgets to be aware of, these are the parameter +widgets, .... +<p> +<pre> +<a href="parameterwidgets.html">Parameter Widget</a> +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/params.gif b/vendor/x11iraf/obm/docs/gui.doc/params.gif Binary files differnew file mode 100644 index 00000000..053f424b --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/params.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/redline.gif b/vendor/x11iraf/obm/docs/gui.doc/redline.gif Binary files differnew file mode 100644 index 00000000..574a6c8a --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/redline.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/serverclass.html b/vendor/x11iraf/obm/docs/gui.doc/serverclass.html new file mode 100644 index 00000000..3fdaec2a --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/serverclass.html @@ -0,0 +1,38 @@ +<title>SERVER class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> SERVER class</h1> +<p> +<HR> +<p> +The server, or object manager, is the control center of the user interface. +The server object provides a Tcl interpreter calling custom object manager +commands. These are used to define and initialize the user interface, and +execute UI action procedures at runtime. +<p> +<pre> + <a href="servercom.html#resetReset">reset-server</a> + <a href="servercom.html#appInitialize">appInitialize</a> appname,appclass,resources + <a href="servercom.html#createObjects">createObjects</a> [resource-name] + <a href="servercom.html#destroyObject">destroyObject</a> object + <a href="servercom.html#activate">activate</a> + <a href="servercom.html#deactivate">deactivate</a> [unmap] +<p> + value = <a href="servercom.html#getResource">getResource</a> resource-name [default-value [class]]</a> + <a href="servercom.html#getResources">getResources</a> resource-list +<p> + <a href="servercom.html#createMenu">createMenu</a> menu-name parent item-list + <a href="servercom.html#createMenu">editMenu</a> menu-name parent item-list + <a href="servercom.html#destroyMenu">destroyMenu</a> menu-name +<p> + <a href="servercom.html#createBitmap">createBitmap</a> name width height data + <a href="servercom.html#createCursor">createCursor</a> name source mask fg_color bg_color x_hot y_hot + <a href="servercom.html#createPixmap">createPixmap</a> name width height depth fg_color bg_color data +<p> + <a href="servercom.html#print">print</a> arg [arg ...] # debug messages + <a href="servercom.html#send">send</a> object message +<p> + <a href="servercom.html#postActivateCallback">postActivateCallback</a> procedure +id = <a href="servercom.html#postTimedCallback">postTimedCallback</a> procedure msec [client-data] + <a href="servercom.html#deleteTimedCallback">deleteTimedCallback</a> id + id = <a href="servercom.html#postWorkCallback">postWorkCallback</a> procedure [client-data] + <a href="servercom.html#deleteWorkCallback">deleteWorkCallback</a> id +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/servercom.html b/vendor/x11iraf/obm/docs/gui.doc/servercom.html new file mode 100644 index 00000000..16c4c24e --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/servercom.html @@ -0,0 +1,375 @@ +<h1><A NAME="serverReset">serverReset</A></h1> +<p> +The "reset-server" command is implemented as a special case in ServerEvaluate. +After doing a true reset ServerEvaluate calls Tcl_Eval to evaluate the full +message which still contains the reset-server command. We want to ignore +this the second time, so we treat the command here as a no-op. +<p> +Usage: +<p> +<pre> + reset-server +</pre> +<p> +Note: for reset-server to be recognized by ServerEvaluate and really reset +things, it must be the first command in a message to the server. +<p> +<h1><A NAME="appInitialize>appInitialize</A></h1> +<p> +TCL command to initialize the server for a new application, setting the +application name and loading the application resources. +<p> +Usage: +<p> +<pre> + appInitialize appname, appclass, resources +</pre> +<p> +<h1><A NAME ="createObjects">createObjects</A></h1> +<p> +TCL command to create the tree of UI objects comprising the user interface. +The object tree is defined by a string valued resource. If no resource is +named the default "objects" resource will be used. +<p> +Usage: +<p> +<pre> + createObjects [resource-name] +</pre> +<h1><A NAME="destroyObject">destroyObject</A></h1> +<p> +Destroy an object and all of its children. +<p> +Usage: +<pre> + destroyObject object-name +</pre> +<p> +<h1><A NAME="activate">activate</A></h1> +Activate the user interface. When called the first time the user interface +is created and activated, thereafter the UI is merely reactivated (e.g. +mapped if unmapped). +<p> +Usage: +<p> +<pre> + activate +</pre> +<p> +<h1><A NAME="deactivate">deactivate</A></h1> +<p> +Deactivate the user interface. Optionally unmaps the UI and calls the Obm +client back to let it know that the UI has been deactivated. +<p> +Usage: +<p> +<pre> + deactivate [unmap] +</pre> +<p> +<h1><A NAME="getResource">getResource</A></h1> +<p> +Get the string value of the specified application resource (window +system parameter). This allows use of the resource mechanism to supply +default values for GUI parameters. +<p> +Usage: +<p> +<pre> + value = getResource resource-name [class [default-value]] +</pre> +<p> +In the simplest case one merely requests a resource by name and the +string value is returned as the function value. If the resource has +an entry in the fallback resources for the application (appInitialize +resource list) then a value is guaranteed to be returned. +<p> +If the Class name for the resource is given then a class default value +will be returned if no entry is found for the name resource instance. This +is useful when there are a number of resources of the same type (same class). +If most or all resources in the same class have the same default value one +need only make one entry for the Class in the application defaults resource +list. It is up to the application developer to define the class name of a +resource - the class name can be any string. Examples are "Font", "Cursor", +etc. By convention the first character of a class name is capitalized, while +instance names begin with a lower case letter. +<p> +If there is an entry for the named resource in the resource list passed to +appInitialize then a value string is guaranteed to be returned. This will be +either the appInitialize default, or a value specified by the system or the +user in an X resources file. If one is not certain a default value is defined +somewhere, a default value should be specified in the getResource call as +shown above. +<p> +See also getResources, used to get multiple resources in one call. +<p> +<h1><A NAME="getResources">getResources</A></h1> +<p> +Get the string values of a list of resources. +<p> +Usage: +<p> +<pre> + getResources resource-list +</pre> +<p> +e.g. +<pre> + getResources { + { resource [variable class [default-value]]] } + { resource [variable class [default-value]]] } + (etc.) + } +</pre> +<p> +<h1><A NAME="createMenu">createMenu, editMenu</A></h1> +<p> +Create or modify a menu. The editMenu function is an alias for createMenu. +<p> +Usage: +<pre> + createMenu menu-name parent item-list +</pre> +<p> +e.g., +<pre> + createMenu menu-name parent { + { label function data [options...] } + { label function data [options...] } + (etc.) + } +</pre> +<p> +where +<p> +<pre> + menu-name is the object name for the menu popup shell + parent is the parent widget of the menu shell + label is a menu item label + function is the function to be performed when the menu + item is selected, e.g., f.exec, f.data, f.space, or f.line. + data is function dependent data + options are option-name option-value pairs, as specified + below. +</pre> +<p> +In the item list the fields label and option-value may be any Tcl expression. +Expressions are evaluated in the server context. The data field is a Tcl +script to be executed when the menu item is selected. +<p> +Options are specified as "option option-value". The menu item options are +as follows. +<p> +<pre> + bitmap A bitmap to be displayed left justified in the label field + (e.g. to indicate a parameter setting). + sensitive Specifies whether the menu item is active (sensitive=true) + or inactive (sensitive=false, item grayed out). + accelerator Specifies an input translation (accelerator, e.g., + keyboard event) which can be used to execute the + menu item. +</pre> +<p> +The option-value field may be any Tcl expression. +<p> +Example: +<p> +<pre> + createMenu fileMenu toplevel { + { "File Menu" f.title} + { Open f.exec openFile} + { Save f.exec saveFile} + { Load f.menu loadMenu} + { no-label f.line } + { Quit f.exec "send client Quit" } + } +</pre> +<p> +The first createMenu is called for a given menu the menu is created, added +to the menu list, and all window system widgets are created for the menu. +Subsequent calls will result in only the changed parts of the menu being +altered provided the changes are not great. Hence this routine can be called +to efficiently modify a menu when minor runtime changes occur, e.g., an +item label or action changes, the item value changes state, and so on, +without need for the GUI code to know how to make the necessary detailed +changes to the widgets used to implement the menu. +<p> +<h1><A NAME="destroyMenu">destroyMenu</A></h1> +<p> +Destroy a menu. This can be used to free up the resources used by a +menu, e.g., if the menu is not expected to be needed again for a while. +<p> +Usage: +<p> +<pre> + destroyMenu menu-name +</pre> +<p> +<h1><A NAME="createBitmap">createBitmap</A></h1> +<p> +Create a named bitmap. This replaces any old bitmap of the same name. The +new bitmap is cached in server memory; when a widget bitmap resource is set, +the bitmap cache will be searched for the named bitmap before asking Xlib +to find the bitmap. +<p> +Usage: +<p> +<pre> + createBitmap name width height data +</pre> +<p> +e.g., +<p> +<pre> + createBitmap foo 16 16 { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +<p> +<h1><A NAME="createCursor">createCursor</A></h1> +<p> +Create a cursor from bitmap data. The cursor is entered into the server's +cursor cache and will override any existing entry of the same name. +<p> +Usage: +<p> +<pre> + createCursor name source mask fg_color bg_color x_hot y_hot +</pre> +<p> +e.g., +<p> +<pre> + createCursor foo bitmap1 bitmap2 black white 8 8 +</pre> +<p> +The named bitmaps must be created first with createBitmap. +<p> +<h1><A NAME="createPixmap">createPixmap</A></h1> +<p> +Create a named pixmap. This replaces any old pixmap of the same name. The +new pixmap is cached in server memory; when a widget pixmap resource is set, +the pixmap cache will be searched for the named pixmap before asking Xlib +to find the pixmap. +<p> +Usage: +<p> +<pre> + createPixmap name width height depth fg_color bg_color data +</pre> +<p> +e.g., +<p> +<pre> + createPixmap foo 16 16 8 black white { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +</pre> +<p> +<h1><A NAME="print">print</A></h1> +<p> +Print a string on the standard output. This is used mainly for debugging +user interfaces. +<p> +Usage: +<p> +<pre> + print arg [arg ...] +</pre> +<p> +<h1><A NAME="send">send</A></h1> +<p> +Send a message to an object. The object interprets the message and returns +a function value as the string result of the TCL command. +<p> +Usage +<p> +<pre> + send <object> <message> +</pre> +<p> +<h1><A NAME="postActivateCallback">postActivateCallback</A></h1> +<p> +Post a callback procedure to be called when the UI is activated. The UI is +activated when it is first downloaded to server, but it may also be +activated (reactivated) after the application has exited and is later +restarted, or when the UI is deactivated and reactivated. Note +that the UI state vis-a-vis the external world (client application) may +no longer be accurate after it has been idle for a time and then reactivated. +<p> +Usage: +<p> +<pre> + postActivateCallback <procedure> +</pre> +<p> +<p> +<h1><A NAME="postTimedCallback">postTimedCallback</A></h1> +<p> +Post a callback to call the named procedure back after a specified delay +in milliseconds. +<p> +Usage: +<p> +<pre> + id = postTimedCallback procedure msec [client-data] +</pre> +<p> +After the specified delay the user callback procedure will be called with +client_data (if given) as the single argument. Only one call will be made; +the client must repost the callback in each call if the procedure is to be +repeatedly executed. +<p> +An ID value is returned which may be passed to deleteTimedCallback to delete +the timer. +<p> +<h1><A NAME="deleteTimedCallback">deleteTimedCallback</A></h1> +<p> +Delete a timer callback procedure. This procedure is typically used to +break a timer loop, where the timer procedure repeatedly reposts itself at +the end of each interval. +<p> +Usage: +<p> +<pre> + deleteTimedCallback id +</pre> +<p> +The ID string is returned by postTimedCallback when a timer is posted. +<p> +<h1><A NAME="postWorkCallback">postWorkCallback</A></h1> +<p> +Post a callback for a procedure to be called when the server is idle. +Work procedures are used to perform computations in the background while +the user interface remains active and able to respond to input events. +This works only if the user work procedure does its job in small increments, +doing only a small amount of processing in each call. The work procedure +will be called repeatedly until it returns a status indicating that it has +finished its task. +<p> +Usage: +<p> +<pre> + id = postWorkCallback procedure [client-data] +</pre> +<p> +When the server has nothing else to do the user work procedure will be +called with client_data (if given) as the single argument. The work procedure +should return the string "done" when all processing is finished, or any other +string if the procedure is to be called again. +<p> +An ID value is returned which may be passed to deleteWorkCallback to delete +the work procedure. +<p> +<h1><A NAME="deleteWorkCallback">deleteWorkCallback</A></h1> +<p> +Delete a work callback procedure. +<p> +Usage: +<p> +<pre> + deleteWorkCallback id +</pre> +<p> +The ID string is returned by postWorkCallback when a work procedure is posted. diff --git a/vendor/x11iraf/obm/docs/gui.doc/softgui.gif b/vendor/x11iraf/obm/docs/gui.doc/softgui.gif Binary files differnew file mode 100644 index 00000000..7e287b10 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/softgui.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/tcl.gif b/vendor/x11iraf/obm/docs/gui.doc/tcl.gif Binary files differnew file mode 100644 index 00000000..804a4afb --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/tcl.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/tcl.html b/vendor/x11iraf/obm/docs/gui.doc/tcl.html new file mode 100644 index 00000000..259192f2 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/tcl.html @@ -0,0 +1,7 @@ +<title>Tcl page</title> +<h1>Tcl page</h1> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +<a href="book.p1.ps"><h2>John Ousterhout's Tcl book</a> (over 700 Kbytes of PostScript)</h2> +<p> +<a href="TclQuickRef.html"><h2>Tcl Quick Reference</h2></a> diff --git a/vendor/x11iraf/obm/docs/gui.doc/uiparameterclass.html b/vendor/x11iraf/obm/docs/gui.doc/uiparameterclass.html new file mode 100644 index 00000000..fe189fc5 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/uiparameterclass.html @@ -0,0 +1,107 @@ +<title>UI PARAMETER class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> UI PARAMETER class</h1> +<p> +<HR> +<p> +The UI parameter class is used for client-UI communications. The client +does not control the user interface directly, rather the UI defines a set +of abstract UI parameters, and during execution the client application +assigns values to these parameters. These UI parameters should be thought +of as describing the runtime state of the client as viewed by the GUI. +The GUI is free to interpret this state information in any way, including +ignoring it. Many GUIs can be written which use the same client state +as described by the UI parameters. +<p> +Assigning a value to a UI parameter causes the new value to be stored, and +any parameter action procedures registered by the UI to be called. +The action or actions [if any] taken when a parameter value changes are +arbitrary, e.g. the action might be something as simple as changing a +displayed value of a UI widget, or something more complex like displaying +a popup. +<p> +UI Parameter class commands: +<p> +<pre> + <a href="#getValue">getValue</a> + <a href="#setValue">setValue</a> <new-value> + <a href="#addCallback">addCallback</a> <procedure-name> + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#notify">notify</a> +</pre> +<p> +The most common usage is for the GUI to post one or more callbacks for +each UI parameter. When the UI parameter value is changed [with setValue, +e.g. by the client] the GUI callback procedures are called with the old +and new UI parameter values on the command line. addCallback is used to +add a callback procedure, and deleteCallback to delete one. Multiple +callbacks may be registered for a single UI parameter. notify is used +to simulate a parameter value change, causing any callback procedures to +be invoked. +<p> +The callback procedure is called as follows: +<p> +<pre> + user-procedure param-name {old-value} {new-value} +</pre> +<p> +The important thing to note here is that the old and new value strings +are quoted with braces. This prevents any interpretation of the string +by Tcl when the callback is executed, which is necessary because the +strings can contain arbitrary data. When Tcl calls the callback the +first level of braces will be stripped off, leaving old-value and new-value +each as a single string argument. +<p> +<p> +<h2><A NAME="setValue">setValue</A></h2> +<p> +Set the value of a parameter, and notify all clients +via the posted callback procedures that the parameter value has changed. +<p> +Usage: +<p> +<pre> + setValue <new-value> +</pre> +<p> +<h2><A NAME="getValue">getValue</A></h2> +<p> +Get the value of a parameter. +<p> +Usage: +<p> +<pre> + getValue +</pre> +<p> +<h2><A NAME="notify">notify</A></h2> +<p> +Notify the registered clients of a parameter as if the +value had changed. +<p> +Usage: +<p> +<pre> + notify +</pre> +<p> +<h2><A NAME="addCallback">addCallback</A></h2> +<p> +Add a callback procedure to the callback list for +a parameter. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> +</pre> +<p> +<h2><A NAME="deleteCallback">deleteCallback</A></h2> +<p> +Delete a callback procedure previously registered +for a parameter. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/widgetclass.html b/vendor/x11iraf/obm/docs/gui.doc/widgetclass.html new file mode 100644 index 00000000..78d534db --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/widgetclass.html @@ -0,0 +1,450 @@ +<title>WIDGET class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> WIDGET class</h1> +<p> +<HR> +<p> +The Widget class is the generic or base class for the window system +toolkit widgets supported by the object manager. The Widget class +supports a number of different Xt widget classes using a table driven +approach to describe each widget. Any widget may be created, destroyed, +and manipulated in various ways using only the generic Widget class +procedures and Widget-specific resources. The Widget class may be +subclassed to support complex Widgets that require custom class-specific +commands for use by the GUI code. +<p> +Generic Widget-class commands: +<p> +<pre> + <a href="#set">set</a> <resource-name> <value> + <a href="#get">get</a> <resource-name> +<p> + <a href="#addCallback">addCallback</a> <procedure-name> [<callback-name>] + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#setSensitive">setSensitive</a> <sensitive> + <a href="#isSensitive">isSensitive</a> +<p> + <a href="#realize">realize</a> + <a href="#unrealize">unrealize</a> + <a href="#isRealized">isRealizeed</a> + <a href="#map">map</a> + <a href="#unmap">unmap</a> + <a href="#manage">manage</a> child [child ...] + <a href="#unmanage">unmanage</a> child [child ...] + <a href="#popup">popup</a> [grab-kind] + <a href="#popdown">popdown</a> + <a href="#popupSpringLoaded">popupSpringLoaded</a> +<p> + <a href="#move">move</a> <x> <y> + <a href="#resize">resize</a> <width> <height> <border-width> + <a href="#configure">configure</a> <x> <y> <width> <height> <border-width> +</pre> +<p> +The most important Widget commands are set/get resource, and the +callbacks. The widget sensitivity can be set and queried using set/get +resource, but special procedures are provided to make this common operation +more convenient. +<p> +Class specific functions: +<p> +<pre> + <a href="#append">append</a> text # text widget + <a href="#setList">setList</a> list [resize] # list widget + value = <a href="#getItem">getItem</a> itemno + <a href="#highlight">highlight</a> itemno + <a href="#unhighlight">unhighlight</a> +</pre> +<p> +Ideally the widget class should be subclassed for widgets that require +class-specific functions, but in simple cases involving standard widgets +the support is built into the widget class code as a special case. +<p> +Special actions (used in translations): +<p> +<pre> + <a href="#do_userproc">call</a> (proc [,arg, ...]) + <a href="#do_popup">popup</a> (menu-name [xoffset [yoffset]]) + <a href="#do_popdown">popdown</a> (menu-name) +</pre> +<p> +The "call" action is a very general mechanism which allows any GUI procedure +to be registered with any translation using the X translation table +mechanism. The popup and popdown actions are used for popup menus. The +menu will be popped up at the event coordinates plus the optional offsets +if given. +<p> +Event handling: +<p> +<pre> + <a href="#addEventHandler">addEventHandler</a> <procname> <event-mask> [<event-mask>...] +</pre> +<p> +Event callback: +<p> +<pre> + <a href="#userEventHandler">userEventHandler</a> widget event-type time wx wy rx ry other +</pre> +<p> +In most cases translations are preferable to events, but a GUI can capture +raw events if it wishes by adding event handlers. Nearly all of the X +event types are supported. The callback syntax employs a number of +standard arguments, followed by a number of event-specific arguments. +<p> +<h1><A NAME="addCallback">addCallback</A></h1> +<p> +Add a callback procedure to the callback list for +a widget. If no callback name is given, "callback" is assumed. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> [<callback-name>] +</pre> +<p> +Specific widgets only support certain types of callbacks. There is no +checking that the callback type specified is supported by a widget; the +wrong type of callback can be registered, but it will never be called. +<p> +<h1><A NAME="deleteCallback">deleteCallback</A></h1> +<p> +Delete a callback procedure previously registered +for a widget. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<p> +<h1><A NAME="do_userproc">do_userproc (call)</A></h1> +<p> +Translation action procedure used to call general user +action procedures in the interpreter. The name of the user procedure to +be called is given as the first argument in the translation. For example, +the translation "call(foo,a,b,c)" would cause procedure foo to be called +with the arguments (a,b,c). The following arguments are special: +<p> +<pre> + Argument Replaced by +<p> + $name object name of widget + $time event->time + $x event->x + $y event->y + $x_root event->x_root + $y_root event->y_root +</pre> +<p> +The "user procedure" can be any server procedure. +<p> +<h1><A NAME="do_popup">do_popup</A></h1> +<p> +Popup a menu (or other spring loaded popup) at the location +of the event which triggered this action. +<p> +Usage: +<p> +<pre> + popup(menu-name [xoffset [yoffset]]) +</pre> +<p> +<h1><A NAME="do_popdown">do_popdown</A></h1> +<p> +Pop down a menu. +<p> +Usage: +<p> +<pre> + popdown(menu-name) +</pre> +<p> +<h1><A NAME="set">set</A></h1> +<p> +Set a widget resource. +<p> +Usage: +<p> +<pre> + set <resource-name> <value> +</pre> +<p> +<h1><A NAME="get">get</A></h1> +<p> +Get a widget resource value as a string. +<p> +Usage: +<p> +<pre> + get <resource-name> +</pre> +<p> +<h1><A NAME="append">append</A></h1> +<p> +Append data to a text widget. +<p> +Usage: +<p> +<pre> + append <text> +</pre> +<p> +<h1><A NAME="setList">setList</A></h1> +<p> +Set the item list of a list widget. +<p> +Usage: +<p> +<pre> + setList list [resize] +</pre> +<p> +The list is a simple list of strings, passed as a single string argument to +setList (quotes, braces, etc. may be used to quote strings containing +special characters). +<p> +<h1><A NAME="getItem">getItem</A></h1> +<p> +Get an item in a list widget. +<p> +Usage: +<p> +<pre> + value = getItem itemno +</pre> +<p> +If ITEMNO is a number the indicated list item is returned, or the string +"EOF" if the requested item is beyond the end of the list. Otherwise the +currently selected item is returned, and the index of the item is returned +in the output variable ITEMNO. If no item is currently selected ITEMNO +will be set to "none" on output. +<p> +<h1><A NAME="highlight">highlight</A></h1> +<p> +Highlight an item in a list widget. +<p> +Usage: +<p> +<pre> + highlight itemno +</pre> +<p> +The indicated item of the list is highlighted as if the item had been +selected by the user. Any previously highlighted item is unhighlighted. +<p> +<h1><A NAME="unhighlight">unhighlight</A></h1> +<p> +Unhighlight the currently highlighted item in a +list widget. +<p> +Usage: +<p> +<pre> + unhighlight +</pre> +<p> +Any currently highlighted item in the list widget is unhighlighted. +<p> +<h1><A NAME="realize">realize</A></h1> +<p> +Realize a widget. This activates and assigns windows for +a widget and all of its descendants. Realizing a widget does not in itself +cause it to appear on the screen. +<p> +Usage: +<p> +<pre> + realize +</pre> +<p> +<h1><A NAME="unrealize">unrealize</A></h1> +<p> +Unrealize a widget. This destroys the windows assigned +to a widget and all of its descendants. +<p> +Usage: +<p> +<pre> + unrealize +</pre> +<p> +<h1><A NAME="isRealized">isRealized</A></h1> +<p> +Test whether a widget is realized. +<p> +Usage: +<p> +<pre> + isRealized +</pre> +<p> +<h1><A NAME="map">map</A></h1> +<p> +Map a widget. +<p> +Usage: +<p> +<pre> + map +</pre> +<p> +<h1><A NAME="unmap">unmap</A></h1> +<p> +Unmap a widget. +<p> +Usage: +<p> +<pre> + unmap +</pre> +<p> +<h1><A NAME="manage">manage</A></h1> +<p> +Manage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Managing the +children makes them appear in the window, possibly causing the other +children to be rearranged in the window. +<p> +Usage: +<p> +<pre> + manage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h1><A NAME="unmanage">unmanage</A></h1> +<p> +Unmanage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Unmanaging the +children makes them disappear from the window and be removed from geometry +management, possibly causing the other children to be rearranged in the +window. +<p> +Usage: +<p> +<pre> + unmanage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h1><A NAME="popup">popup</A></h1> +<p> +Popup a shell widget. If no grab is indicated the popup +can remain up while other windows accept input. +<p> +Usage: +<p> +<pre> + popup [grab-kind] +</pre> +<p> +<h1><A NAME="popdown">popdown</A></h1> +<p> +Popdown a shell widget. +<p> +Usage: +<p> +<pre> + popdown +</pre> +<p> +<h1><A NAME="popupSpringLoaded">popupSpringLoaded</A></h1> +<p> +Popup a shell widget, e.g., a popup menu. +This implies an exclusive grab. +<p> +Usage: +<p> +<pre> + popupSpringLoaded +</pre> +<p> +<h1><A NAME="move">move</A></h1> +<p> +Move a widget to the given window relative coordinates. +<p> +Usage: +<p> +<pre> + move <x> <y> +</pre> +<p> +<h1><A NAME="resize">resize</A></h1> +<p> +Resize a widget. +<p> +Usage: +<p> +<pre> + resize <width> <height> <border-width> +</pre> +<p> +<h1><A NAME="configure">configure</A></h1> +<p> +Configure a widget, i.e., execute a simultaneous +move and resize. +<p> +Usage: +<p> +<pre> + configure <x> <y> <width> <height> <border-width> +</pre> +<p> +<h1><A NAME="setSensitive">setSensitive</A></h1> +<p> +Set the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + setSensitive <sensitive> +</pre> +<p> +<h1><A NAME="isSensitive">isSensitive</A></h1> +<p> +Test the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + isSensitive +</pre> +<p> +<h1><A NAME="addEventHandler">addEventHandler</A></h1> +<p> +Add a custom event handler to a widget. A list +of event masks is given to define the classes of events the user supplied +event handling procedure is to receive. +<p> +Usage: +<p> +<pre> + addEventHandler <procname> <event-mask> [<event-mask>...] +</pre> +<p> +<h1><A NAME="removeEventHandler">removeEventHandler</A></h1> +<p> +Remove an event handler previously posted +with addEventHandler, above. +<p> +Usage: +<p> +<pre> + removeEventHandler procname +</pre> +<p> +<h1><A NAME="event">event</A></h1> +<p> +Generic event handler called when a widget event handler +posted by addEventHandler is called. +<p> +The user event handler is called as +<p> +<pre> + userEventHandler widget event-type time wx wy rx ry other +</pre> +<p> +where "other" is an event-type specific list of fields describing the +the event. diff --git a/vendor/x11iraf/obm/docs/gui.doc/widgets.gif b/vendor/x11iraf/obm/docs/gui.doc/widgets.gif Binary files differnew file mode 100644 index 00000000..17f9371e --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/widgets.gif diff --git a/vendor/x11iraf/obm/docs/gui.doc/widgets.html b/vendor/x11iraf/obm/docs/gui.doc/widgets.html new file mode 100644 index 00000000..af80a997 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/widgets.html @@ -0,0 +1,14 @@ +<title>The Widgets</title> +<h1><IMG SRC="irafgui.gif"> Widgets</h1> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<p> +The basic widgets available to the IRAF GUI implimenter are the Athena +Widgets, the gterm widget, the image display widget, and markers. +<p> +<pre> +<a href="athena.html"><IMG ALIGN=MIDDLE SRC="athena.gif"></a> Athena widgets <a href="notyet2.html"><IMG ALIGN=MIDDLE SRC="gterm.gif"></a> Gterm widget + +<a href="notyet2.html"><IMG ALIGN=MIDDLE SRC="imtool.gif"></a> Imtool widget <a href="notyet2.html"><IMG ALIGN=MIDDLE SRC="marker.gif"></a> Marker widgets + +<a href="parameterwidget.html"><IMG ALIGN=MIDDLE SRC="params.gif"></a> Parameters +</pre> diff --git a/vendor/x11iraf/obm/docs/gui.doc/ximclient.html b/vendor/x11iraf/obm/docs/gui.doc/ximclient.html new file mode 100644 index 00000000..12eac899 --- /dev/null +++ b/vendor/x11iraf/obm/docs/gui.doc/ximclient.html @@ -0,0 +1,194 @@ +<title>XIMCLIENT</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> XIMCLIENT</h1> +<p> +<HR> +<p> +The Ximtool "client" object. This code implements an OBM client and +responds to messages sent to the client object by the GUI code executing +under the object manager. +<p> +Client commands: +<p> +<pre> + <a href="#setFrame">setFrame</a> frameno + frameno = <a href="#getFrame">getFrame</a> [raster] + <a href="#nextFrame">nextFrame</a> + <a href="#prevFrame">prevFrame</a> + <a href="#matchFrames">matchFrames</a> [frame] + <a href="#fitFrame">fitFrame</a> + + <a href="#setColormap">setColormap</a> colormap + <a href="#windowColormap">windowColormap</a> offset scale + <a href="#zoom">zoom</a> [mag | xmag ymag [ xcen ycen ]] + <a href="#zoom">zoomAbs</a> [mag | xmag ymag [ xcen ycen ]] + <a href="#pan">pan</a> xcen ycen + <a href="#flip">flip</a> axis [axis ...] + + + wcsstr = <a href="#encodewcs">encodewcs</a> sx sy sz + <a href="#retCursorVal">retCursorVal</a> sx sy [frame [wcs [key [strval]]]] + + <a href="#Quit">Quit</a> +</pre> +<p> +XIMTOOL CLIENT commands. +<p> +<h1><A NAME="Quit">Quit</A></h1> +<p> +Exit ximtool. +<p> +Usage: +<p> +<pre> + Quit +</pre> +<p> +<h1><A NAME="setFrame">setFrame</A></h1> +<p> +Set the frame to be displayed. +<p> +Usage: +<p> +<pre> + setFrame <frameno> +</pre> +<p> +<h1><A NAME="getFrame">getFrame</A></h1> +<p> +Get the frame number. +<p> +Usage: +<p> +<pre> + getFrame [raster] +</pre> +<p> +This routine has two forms. When called with no argument getFrame returns +the current display frame. When called with a raster number getFrame +returns the frame number with which the raster is associated. +<p> +<h1><A NAME="nextFrame">nextFrame</A></h1> +<p> +Display the next frame in sequence. +<p> +Usage: +<p> +<pre> + nextFrame +</pre> +<p> +<h1><A NAME="prevFrame">prevFrame</A></h1> +<p> +Display the previous frame in sequence. +<p> +Usage: +<p> +<pre> + prevFrame +</pre> +<p> +<h1><A NAME="matchFrames">matchFrames</A></h1> +<p> +Set the enhancement of all frames to match the current +display frame. +<p> +Usage: +<p> +<pre> + matchFrames [frame] +</pre> +<p> +<h1><A NAME="fitFrame">fitFrame</A></h1> +<p> +Attempt to make the display window the same size as the frame +buffer. +<p> +Usage: +<p> +<pre> + fitFrame +</pre> +<p> +<h1><A NAME="setColormap">setColormap</A></h1> +<p> +Set the colormap for the current display frame. +<p> +Usage: +<p> +<pre> + setColormap <colormap> +</pre> +<p> +<h1><A NAME="windowColormap">windowColormap</A></h1> +<p> +Set the colormap for the current display frame. +<p> +Usage: +<p> +<pre> + windowColormap <offset> <scale> +</pre> +<p> +<h1><A NAME="zoom">zoom, zoomAbs</A></h1> +<p> +Set the zoom factors for the current frame to the given values. +A zoom factor > 1 enlarges the image, < 1 shrinks the image, 1.0 maps +one source pixel to one destination pixel. +<p> +Usage: +<p> +<pre> + zoom <xymag> 1 argument + zoom <xmag> <ymag> 2 arguments + zoom <xmag> <ymag> <xcen> <ycen> 4 arguments +</pre> +<p> +When called as "zoom" the magnification is relative to the fixed scaling, +if any, used to scale the frame to fit the display window at mag=1.0. +When called as zoomAbs" the magnification given is the actual scale factor +used to map raster pixels to display pixels. +<p> +<h1><A NAME="pan">pan</A></h1> +<p> +Pan the current frame, i.e., change the view center. +<p> +Usage: +<p> +<pre> + pan <xcen> <ycen> +</pre> +<p> +<h1><A NAME="flip">flip</A></h1> +<p> +Flip the current display frame in the indicated axis or axes. +<p> +Usage: +<p> +<pre> + flip [axis [axis ...]] +</pre> +<p> +<h1><A NAME="retCursorVal">retCursorVal</A></h1> +<p> +Return a cursor value to the ximtool client process. This +should be executed by the GUI to terminate a cursor read. +<p> +Usage: +<p> +<pre> + retCursorVal sx sy [frame [wcs [key [strval]]]] +</pre> +<p> +<h1><A NAME="encodewcs">encodewcs</A></h1> +<p> +Convert raw screen coordinates x,y,z (z=pixel value) to +world coordinates using the WCS passed to ximtool by the client application +when the frame was loaded. The encoded description of the current position +and pixel value is returned to the GUI as a string value. +<p> +Usage: +<p> +<pre> + string = encodewcs sx sy sz +</pre> +<p> diff --git a/vendor/x11iraf/obm/docs/obm/Client.html b/vendor/x11iraf/obm/docs/obm/Client.html new file mode 100644 index 00000000..407c177b --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Client.html @@ -0,0 +1,75 @@ +<title>CLIENT class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> CLIENT class</h1> +<p> +<HR> +<p> +The client is the client application, which provides the functionality +underlying the UI. When a message is sent to the client object it usually +results in a message being sent to the client *application*, usually an +external program communicating via IPC, which has little or no knowledge +of the UI. The client application receives and executes commands delivered +by the UI via the client object. Output from the client may or may not +come back to the object manager. That portion of the output which comes +back to the object manager is in the form of assignments of string values +to <a href="uiparameterclass.html">UI parameter-class objects</a> (another +way of thinking of this is that +messages or events are sent to and acted upon by the parameter objects). +Hence, the client object is output only so far as the client application +is concerned. +<p> +The Client-class commands are used to send a message to the client. +<p> +<pre> + <a href="#gkey">gkey</a> <key> + <a href="#gcmd">gcmd</a> <command-string> + <a href="#literal">literal</a> <command> +</pre> +<p> +or just <command>, e.g., "send client <command>" will work in most cases. +<p> +<a href="#gkey">GKEY</a> sends an IRAF graphics keystroke. +<a href="#gcmd">GCMD</a> sends an +IRAF graphics colon command. <a href="#literal">LITERAL</a> sends a literal +command string to the +client. The keyword "literal" may optionally be omitted, i.e., "send client +foo" and "send client literal foo" are the same. The keyword "literal" may +be used to ensure that the client command string which follows will not +be interpreted as a Client-class command (such as gkey, gcmd, or literal). +<p> +<p> +<h1><A NAME="gcmd">gcmd</A></h1> +<p> +Send a graphics command string to the client application. +A graphics command string is a graphics cursor value with the key set +to `:' and the command string given as the string part of the cursor +value. The protocol module which posted the client output procedure is +responsible for encoding and sending the cursor command. +<p> +Usage: +<p> +<pre> + gcmd <command-string> +</pre> +<p> +<h1><A NAME="gkey">gkey</A></h1> +<p> +Send a graphics key event to the client application. +A graphics key event is a graphics cursor value with the key set to some +integer value and a null string part. +<p> +Usage: +<p> +<pre> +gkey <key> +</pre> +<p> +<h1><A NAME="literal">literal</A></h1> +<p> +Send a literal command to the client application. +<p> +Usage: +<p> +<pre> + literal <command> +</pre> + diff --git a/vendor/x11iraf/obm/docs/obm/Gterm.html b/vendor/x11iraf/obm/docs/obm/Gterm.html new file mode 100644 index 00000000..5fcdab10 --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Gterm.html @@ -0,0 +1,694 @@ +<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 <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. +<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. + diff --git a/vendor/x11iraf/obm/docs/obm/Marker.html b/vendor/x11iraf/obm/docs/obm/Marker.html new file mode 100644 index 00000000..9e124846 --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Marker.html @@ -0,0 +1,402 @@ +<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 <ObmW/Gterm.h> 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 < 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() +</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> diff --git a/vendor/x11iraf/obm/docs/obm/Parameter.html b/vendor/x11iraf/obm/docs/obm/Parameter.html new file mode 100644 index 00000000..fe189fc5 --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Parameter.html @@ -0,0 +1,107 @@ +<title>UI PARAMETER class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> UI PARAMETER class</h1> +<p> +<HR> +<p> +The UI parameter class is used for client-UI communications. The client +does not control the user interface directly, rather the UI defines a set +of abstract UI parameters, and during execution the client application +assigns values to these parameters. These UI parameters should be thought +of as describing the runtime state of the client as viewed by the GUI. +The GUI is free to interpret this state information in any way, including +ignoring it. Many GUIs can be written which use the same client state +as described by the UI parameters. +<p> +Assigning a value to a UI parameter causes the new value to be stored, and +any parameter action procedures registered by the UI to be called. +The action or actions [if any] taken when a parameter value changes are +arbitrary, e.g. the action might be something as simple as changing a +displayed value of a UI widget, or something more complex like displaying +a popup. +<p> +UI Parameter class commands: +<p> +<pre> + <a href="#getValue">getValue</a> + <a href="#setValue">setValue</a> <new-value> + <a href="#addCallback">addCallback</a> <procedure-name> + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#notify">notify</a> +</pre> +<p> +The most common usage is for the GUI to post one or more callbacks for +each UI parameter. When the UI parameter value is changed [with setValue, +e.g. by the client] the GUI callback procedures are called with the old +and new UI parameter values on the command line. addCallback is used to +add a callback procedure, and deleteCallback to delete one. Multiple +callbacks may be registered for a single UI parameter. notify is used +to simulate a parameter value change, causing any callback procedures to +be invoked. +<p> +The callback procedure is called as follows: +<p> +<pre> + user-procedure param-name {old-value} {new-value} +</pre> +<p> +The important thing to note here is that the old and new value strings +are quoted with braces. This prevents any interpretation of the string +by Tcl when the callback is executed, which is necessary because the +strings can contain arbitrary data. When Tcl calls the callback the +first level of braces will be stripped off, leaving old-value and new-value +each as a single string argument. +<p> +<p> +<h2><A NAME="setValue">setValue</A></h2> +<p> +Set the value of a parameter, and notify all clients +via the posted callback procedures that the parameter value has changed. +<p> +Usage: +<p> +<pre> + setValue <new-value> +</pre> +<p> +<h2><A NAME="getValue">getValue</A></h2> +<p> +Get the value of a parameter. +<p> +Usage: +<p> +<pre> + getValue +</pre> +<p> +<h2><A NAME="notify">notify</A></h2> +<p> +Notify the registered clients of a parameter as if the +value had changed. +<p> +Usage: +<p> +<pre> + notify +</pre> +<p> +<h2><A NAME="addCallback">addCallback</A></h2> +<p> +Add a callback procedure to the callback list for +a parameter. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> +</pre> +<p> +<h2><A NAME="deleteCallback">deleteCallback</A></h2> +<p> +Delete a callback procedure previously registered +for a parameter. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> diff --git a/vendor/x11iraf/obm/docs/obm/Server.html b/vendor/x11iraf/obm/docs/obm/Server.html new file mode 100644 index 00000000..3fdaec2a --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Server.html @@ -0,0 +1,38 @@ +<title>SERVER class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> SERVER class</h1> +<p> +<HR> +<p> +The server, or object manager, is the control center of the user interface. +The server object provides a Tcl interpreter calling custom object manager +commands. These are used to define and initialize the user interface, and +execute UI action procedures at runtime. +<p> +<pre> + <a href="servercom.html#resetReset">reset-server</a> + <a href="servercom.html#appInitialize">appInitialize</a> appname,appclass,resources + <a href="servercom.html#createObjects">createObjects</a> [resource-name] + <a href="servercom.html#destroyObject">destroyObject</a> object + <a href="servercom.html#activate">activate</a> + <a href="servercom.html#deactivate">deactivate</a> [unmap] +<p> + value = <a href="servercom.html#getResource">getResource</a> resource-name [default-value [class]]</a> + <a href="servercom.html#getResources">getResources</a> resource-list +<p> + <a href="servercom.html#createMenu">createMenu</a> menu-name parent item-list + <a href="servercom.html#createMenu">editMenu</a> menu-name parent item-list + <a href="servercom.html#destroyMenu">destroyMenu</a> menu-name +<p> + <a href="servercom.html#createBitmap">createBitmap</a> name width height data + <a href="servercom.html#createCursor">createCursor</a> name source mask fg_color bg_color x_hot y_hot + <a href="servercom.html#createPixmap">createPixmap</a> name width height depth fg_color bg_color data +<p> + <a href="servercom.html#print">print</a> arg [arg ...] # debug messages + <a href="servercom.html#send">send</a> object message +<p> + <a href="servercom.html#postActivateCallback">postActivateCallback</a> procedure +id = <a href="servercom.html#postTimedCallback">postTimedCallback</a> procedure msec [client-data] + <a href="servercom.html#deleteTimedCallback">deleteTimedCallback</a> id + id = <a href="servercom.html#postWorkCallback">postWorkCallback</a> procedure [client-data] + <a href="servercom.html#deleteWorkCallback">deleteWorkCallback</a> id +</pre> diff --git a/vendor/x11iraf/obm/docs/obm/Widget.html b/vendor/x11iraf/obm/docs/obm/Widget.html new file mode 100644 index 00000000..78d534db --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/Widget.html @@ -0,0 +1,450 @@ +<title>WIDGET class</title> +<h1><IMG SRC="/iraf/web/images/iraf.gif"> WIDGET class</h1> +<p> +<HR> +<p> +The Widget class is the generic or base class for the window system +toolkit widgets supported by the object manager. The Widget class +supports a number of different Xt widget classes using a table driven +approach to describe each widget. Any widget may be created, destroyed, +and manipulated in various ways using only the generic Widget class +procedures and Widget-specific resources. The Widget class may be +subclassed to support complex Widgets that require custom class-specific +commands for use by the GUI code. +<p> +Generic Widget-class commands: +<p> +<pre> + <a href="#set">set</a> <resource-name> <value> + <a href="#get">get</a> <resource-name> +<p> + <a href="#addCallback">addCallback</a> <procedure-name> [<callback-name>] + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#setSensitive">setSensitive</a> <sensitive> + <a href="#isSensitive">isSensitive</a> +<p> + <a href="#realize">realize</a> + <a href="#unrealize">unrealize</a> + <a href="#isRealized">isRealizeed</a> + <a href="#map">map</a> + <a href="#unmap">unmap</a> + <a href="#manage">manage</a> child [child ...] + <a href="#unmanage">unmanage</a> child [child ...] + <a href="#popup">popup</a> [grab-kind] + <a href="#popdown">popdown</a> + <a href="#popupSpringLoaded">popupSpringLoaded</a> +<p> + <a href="#move">move</a> <x> <y> + <a href="#resize">resize</a> <width> <height> <border-width> + <a href="#configure">configure</a> <x> <y> <width> <height> <border-width> +</pre> +<p> +The most important Widget commands are set/get resource, and the +callbacks. The widget sensitivity can be set and queried using set/get +resource, but special procedures are provided to make this common operation +more convenient. +<p> +Class specific functions: +<p> +<pre> + <a href="#append">append</a> text # text widget + <a href="#setList">setList</a> list [resize] # list widget + value = <a href="#getItem">getItem</a> itemno + <a href="#highlight">highlight</a> itemno + <a href="#unhighlight">unhighlight</a> +</pre> +<p> +Ideally the widget class should be subclassed for widgets that require +class-specific functions, but in simple cases involving standard widgets +the support is built into the widget class code as a special case. +<p> +Special actions (used in translations): +<p> +<pre> + <a href="#do_userproc">call</a> (proc [,arg, ...]) + <a href="#do_popup">popup</a> (menu-name [xoffset [yoffset]]) + <a href="#do_popdown">popdown</a> (menu-name) +</pre> +<p> +The "call" action is a very general mechanism which allows any GUI procedure +to be registered with any translation using the X translation table +mechanism. The popup and popdown actions are used for popup menus. The +menu will be popped up at the event coordinates plus the optional offsets +if given. +<p> +Event handling: +<p> +<pre> + <a href="#addEventHandler">addEventHandler</a> <procname> <event-mask> [<event-mask>...] +</pre> +<p> +Event callback: +<p> +<pre> + <a href="#userEventHandler">userEventHandler</a> widget event-type time wx wy rx ry other +</pre> +<p> +In most cases translations are preferable to events, but a GUI can capture +raw events if it wishes by adding event handlers. Nearly all of the X +event types are supported. The callback syntax employs a number of +standard arguments, followed by a number of event-specific arguments. +<p> +<h1><A NAME="addCallback">addCallback</A></h1> +<p> +Add a callback procedure to the callback list for +a widget. If no callback name is given, "callback" is assumed. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> [<callback-name>] +</pre> +<p> +Specific widgets only support certain types of callbacks. There is no +checking that the callback type specified is supported by a widget; the +wrong type of callback can be registered, but it will never be called. +<p> +<h1><A NAME="deleteCallback">deleteCallback</A></h1> +<p> +Delete a callback procedure previously registered +for a widget. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<p> +<h1><A NAME="do_userproc">do_userproc (call)</A></h1> +<p> +Translation action procedure used to call general user +action procedures in the interpreter. The name of the user procedure to +be called is given as the first argument in the translation. For example, +the translation "call(foo,a,b,c)" would cause procedure foo to be called +with the arguments (a,b,c). The following arguments are special: +<p> +<pre> + Argument Replaced by +<p> + $name object name of widget + $time event->time + $x event->x + $y event->y + $x_root event->x_root + $y_root event->y_root +</pre> +<p> +The "user procedure" can be any server procedure. +<p> +<h1><A NAME="do_popup">do_popup</A></h1> +<p> +Popup a menu (or other spring loaded popup) at the location +of the event which triggered this action. +<p> +Usage: +<p> +<pre> + popup(menu-name [xoffset [yoffset]]) +</pre> +<p> +<h1><A NAME="do_popdown">do_popdown</A></h1> +<p> +Pop down a menu. +<p> +Usage: +<p> +<pre> + popdown(menu-name) +</pre> +<p> +<h1><A NAME="set">set</A></h1> +<p> +Set a widget resource. +<p> +Usage: +<p> +<pre> + set <resource-name> <value> +</pre> +<p> +<h1><A NAME="get">get</A></h1> +<p> +Get a widget resource value as a string. +<p> +Usage: +<p> +<pre> + get <resource-name> +</pre> +<p> +<h1><A NAME="append">append</A></h1> +<p> +Append data to a text widget. +<p> +Usage: +<p> +<pre> + append <text> +</pre> +<p> +<h1><A NAME="setList">setList</A></h1> +<p> +Set the item list of a list widget. +<p> +Usage: +<p> +<pre> + setList list [resize] +</pre> +<p> +The list is a simple list of strings, passed as a single string argument to +setList (quotes, braces, etc. may be used to quote strings containing +special characters). +<p> +<h1><A NAME="getItem">getItem</A></h1> +<p> +Get an item in a list widget. +<p> +Usage: +<p> +<pre> + value = getItem itemno +</pre> +<p> +If ITEMNO is a number the indicated list item is returned, or the string +"EOF" if the requested item is beyond the end of the list. Otherwise the +currently selected item is returned, and the index of the item is returned +in the output variable ITEMNO. If no item is currently selected ITEMNO +will be set to "none" on output. +<p> +<h1><A NAME="highlight">highlight</A></h1> +<p> +Highlight an item in a list widget. +<p> +Usage: +<p> +<pre> + highlight itemno +</pre> +<p> +The indicated item of the list is highlighted as if the item had been +selected by the user. Any previously highlighted item is unhighlighted. +<p> +<h1><A NAME="unhighlight">unhighlight</A></h1> +<p> +Unhighlight the currently highlighted item in a +list widget. +<p> +Usage: +<p> +<pre> + unhighlight +</pre> +<p> +Any currently highlighted item in the list widget is unhighlighted. +<p> +<h1><A NAME="realize">realize</A></h1> +<p> +Realize a widget. This activates and assigns windows for +a widget and all of its descendants. Realizing a widget does not in itself +cause it to appear on the screen. +<p> +Usage: +<p> +<pre> + realize +</pre> +<p> +<h1><A NAME="unrealize">unrealize</A></h1> +<p> +Unrealize a widget. This destroys the windows assigned +to a widget and all of its descendants. +<p> +Usage: +<p> +<pre> + unrealize +</pre> +<p> +<h1><A NAME="isRealized">isRealized</A></h1> +<p> +Test whether a widget is realized. +<p> +Usage: +<p> +<pre> + isRealized +</pre> +<p> +<h1><A NAME="map">map</A></h1> +<p> +Map a widget. +<p> +Usage: +<p> +<pre> + map +</pre> +<p> +<h1><A NAME="unmap">unmap</A></h1> +<p> +Unmap a widget. +<p> +Usage: +<p> +<pre> + unmap +</pre> +<p> +<h1><A NAME="manage">manage</A></h1> +<p> +Manage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Managing the +children makes them appear in the window, possibly causing the other +children to be rearranged in the window. +<p> +Usage: +<p> +<pre> + manage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h1><A NAME="unmanage">unmanage</A></h1> +<p> +Unmanage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Unmanaging the +children makes them disappear from the window and be removed from geometry +management, possibly causing the other children to be rearranged in the +window. +<p> +Usage: +<p> +<pre> + unmanage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h1><A NAME="popup">popup</A></h1> +<p> +Popup a shell widget. If no grab is indicated the popup +can remain up while other windows accept input. +<p> +Usage: +<p> +<pre> + popup [grab-kind] +</pre> +<p> +<h1><A NAME="popdown">popdown</A></h1> +<p> +Popdown a shell widget. +<p> +Usage: +<p> +<pre> + popdown +</pre> +<p> +<h1><A NAME="popupSpringLoaded">popupSpringLoaded</A></h1> +<p> +Popup a shell widget, e.g., a popup menu. +This implies an exclusive grab. +<p> +Usage: +<p> +<pre> + popupSpringLoaded +</pre> +<p> +<h1><A NAME="move">move</A></h1> +<p> +Move a widget to the given window relative coordinates. +<p> +Usage: +<p> +<pre> + move <x> <y> +</pre> +<p> +<h1><A NAME="resize">resize</A></h1> +<p> +Resize a widget. +<p> +Usage: +<p> +<pre> + resize <width> <height> <border-width> +</pre> +<p> +<h1><A NAME="configure">configure</A></h1> +<p> +Configure a widget, i.e., execute a simultaneous +move and resize. +<p> +Usage: +<p> +<pre> + configure <x> <y> <width> <height> <border-width> +</pre> +<p> +<h1><A NAME="setSensitive">setSensitive</A></h1> +<p> +Set the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + setSensitive <sensitive> +</pre> +<p> +<h1><A NAME="isSensitive">isSensitive</A></h1> +<p> +Test the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + isSensitive +</pre> +<p> +<h1><A NAME="addEventHandler">addEventHandler</A></h1> +<p> +Add a custom event handler to a widget. A list +of event masks is given to define the classes of events the user supplied +event handling procedure is to receive. +<p> +Usage: +<p> +<pre> + addEventHandler <procname> <event-mask> [<event-mask>...] +</pre> +<p> +<h1><A NAME="removeEventHandler">removeEventHandler</A></h1> +<p> +Remove an event handler previously posted +with addEventHandler, above. +<p> +Usage: +<p> +<pre> + removeEventHandler procname +</pre> +<p> +<h1><A NAME="event">event</A></h1> +<p> +Generic event handler called when a widget event handler +posted by addEventHandler is called. +<p> +The user event handler is called as +<p> +<pre> + userEventHandler widget event-type time wx wy rx ry other +</pre> +<p> +where "other" is an event-type specific list of fields describing the +the event. diff --git a/vendor/x11iraf/obm/docs/obm/alphabetic.html b/vendor/x11iraf/obm/docs/obm/alphabetic.html new file mode 100644 index 00000000..0c141617 --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/alphabetic.html @@ -0,0 +1,39 @@ +<title>Alphabetized list of GUI commands</title> +<IMG SRC="/iraf/web/projects/x11iraf/docs/gui.doc/blueline.gif"> +<pre> +<a href="gtermclass.html#activate">activate</a> <a href="servercom.html#activate">activate</a> <a href="notyet.html">activeMapping</a> <a href="gmc.html#addCallback">addCallback</a> <a href="gtermclass.html#addCallback">addCallback</a> +<a href="uiparameterclass.html#addCallback">addCallback</a> <a href="widgetclass.html#addCallback">addCallback</a> <a href="widgetclass.html#addEventHandler">addEventHandler</a> <a href="widgetclass.html#append">append</a> <a href="servercom.html#appInitialize">appInitialize</a> +<a href="notyet.html">assignRaster</a> <a href="gtermclass.html#bell">bell</a> <a href="widgetclass.html#do_userproc">call</a> <a href="gtermclass.html#clearScreen">clearScreen</a> <a href="widgetclass.html#configure">configure</a> +<a href="notyet.html">copyPixmap</a> <a href="notyet.html">copyRaster</a> <a href="servercom.html#createBitmap">createBitmap</a> <a href="servercom.html#createCursor">createCursor</a> <a href="gtermclass.html#createMarker">createMarker</a> +<a href="servercom.html#createMenu">createMenu</a> <a href="servercom.html#createObjects">createObjects</a> <a href="notyet.html">createPixmap</a> <a href="servercom.html#createPixmap">createPixmap</a> <a href="notyet.html">createRaster</a> +<a href="gtermclass.html#deactivate">deactivate</a> <a href="servercom.html#deactivate">deactivate</a> <a href="uiparameterclass.html#deleteCallback">deleteCallback</a> <a href="widgetclass.html#deleteCallback">deleteCallback</a> <a href="servercom.html#deleteTimedCallback">deleteTimedCallback</a> +<a href="servercom.html#deleteWorkCallback">deleteWorkCallback</a> <a href="gmc.html#destroy">destroy</a> <a href="servercom.html#destroyMenu">destroyMenu</a> <a href="servercom.html#destroyObject">destroyObject</a> +<a href="notyet.html">destroyRaster</a> <a href="notyet.html">disableMapping</a> <a href="notyet.html">drawAlphaText</a> <a href="notyet.html">drawDialogText</a> <a href="notyet.html">drawMarker</a> +<a href="notyet.html">drawPolygon</a> <a href="notyet.html">drawPolyline</a> <a href="notyet.html">drawPolymarker</a> <a href="servercom.html#createMenu">editMenu</a> <a href="notyet.html">enableMapping</a> +<a href="ximclient.html#encodewcs">encodewcs</a> <a href="notyet.html">endDialog</a> <a href="notyet.html">eraseDialog</a> <a href="ximclient.html#fitFrame">fitFrame</a> <a href="gtermclass.html#flip">flip</a> +<a href="ximclient.html#flip">flip</a> <a href="gtermclass.html#flush">flush</a> <a href="notyet.html">freeColormap</a> <a href="notyet.html">freeMapping</a> <a href="clientclass.html#gcmd">gcmd</a> +<a href="gmc.html#getAttribute">get</a> <a href="widgetclass.html#get">get</a> <a href="notyet.html">getAlphaTextSize</a> <a href="gmc.html#getAttribute">getAttribute</a> +<a href="gmc.html#getAttributes">getAttributes</a> <a href="gtermclass.html#getCursorPos">getCursorPos</a> <a href="notyet.html">getDialogTextSize</a> <a href="ximclient.html#getFrame">getFrame</a> +<a href="widgetclass.html#getItem">getItem</a> <a href="notyet.html">getLogRes</a> <a href="gtermclass.html#getMapping">getMapping</a> <a href="notyet.html">getPhysRes</a> <a href="gtermclass.html#getPixel">getPixel</a> +<a href="gtermclass.html#getRaster">getRaster</a> <a href="gmc.html#getRect">getRect</a> <a href="gmc.html#getRegion">getRegion</a> <a href="servercom.html#getResource">getResource</a> <a href="servercom.html#getResources">getResources</a> +<a href="uiparameterclass.html#getValue">getValue</a> <a href="gmc.html#getVertices">getVertices</a> <a href="clientclass.html#gkey">gkey</a> <a href="widgetclass.html#highlight">highlight</a> <a href="notyet.html">initMappings</a> +<a href="widgetclass.html#isRealized">isRealized</a> <a href="widgetclass.html#isSensitive">isSensitive</a> <a href="clientclass.html#literal">literal</a> <a href="gtermclass.html#loadColormap">loadColormap</a> <a href="gmc.html#lower">lower</a> +<a href="gmc.html#makeCopy">makeCopy</a> <a href="widgetclass.html#manage">manage</a> <a href="widgetclass.html#map">map</a> <a href="gtermclass.html#markerInit">markerInit</a> <a href="gmc.html#markpos">markpos</a> +<a href="ximclient.html#matchFrames">matchFrames</a> <a href="gmc.html#move">move</a> <a href="widgetclass.html#move">move</a> <a href="notyet.html">nextColormap</a> <a href="ximclient.html#nextFrame">nextFrame</a> +<a href="gtermclass.html#nextMapping">nextMapping</a> <a href="notyet.html">nextRaster</a> <a href="gmc.html#notify">notify</a> <a href="uiparameterclass.html#notify">notify</a> <a href="notyet.html">nRasters</a> +<a href="ximclient.html#pan">pan</a> <a href="widgetclass.html#do_popdown">popdown</a> <a href="widgetclass.html#popdown">popdown</a> <a href="widgetclass.html#do_popup">popup</a> <a href="widgetclass.html#popup">popup</a> +<a href="widgetclass.html#popupSpringLoaded">popupSpringLoaded</a> <a href="servercom.html#postActivateCallback">postActivateCallback</a> <a href="servercom.html#postTimedCallback">postTimedCallback</a> +<a href="servercom.html#postWorkCallback">postWorkCallback</a> <a href="ximclient.html#prevFrame">prevFrame</a> <a href="servercom.html#print">print</a> <a href="notyet.html">queryRaster</a> +<a href="ximclient.html#Quit">Quit</a> <a href="gmc.html#raise">raise</a> <a href="gtermclass.html#rasterInit">rasterInit</a> <a href="notyet.html">readColormap</a> <a href="gtermclass.html#readPixels">readPixels</a> +<a href="widgetclass.html#realize">realize</a> <a href="gmc.html#redraw">redraw</a> <a href="notyet.html">refreshMapping</a> <a href="notyet.html">refreshPixels</a> <a href="servercom.html#resetReset">reset-server</a> +<a href="gtermclass.html#reset">reset</a> <a href="gmc.html#resize">resize</a> <a href="widgetclass.html#resize">resize</a> <a href="ximclient.html#retCursorVal">retCursorVal</a> <a href="gmc.html#rotate">rotate</a> +<a href="gtermclass.html#selectRaster">selectRaster</a> <a href="servercom.html#send">send</a> <a href="gmc.html#setAttribute">set</a> <a href="widgetclass.html#set">set</a> <a href="gmc.html#setAttribute">setAttribute</a> +<a href="gmc.html#setAttributes">setAttributes</a> <a href="notyet.html">setColorIndex</a> <a href="ximclient.html#setColormap">setColormap</a> <a href="gtermclass.html#setCursorPos">setCursorPos</a> <a href="gtermclass.html#setCursorType">setCursorType</a> +<a href="notyet.html">setDataLevel</a> <a href="notyet.html">setFillType</a> <a href="ximclient.html#setFrame">setFrame</a> <a href="gtermclass.html#setGterm">setGterm</a> <a href="notyet.html">setLineStyle</a> +<a href="notyet.html">setLineWidth</a> <a href="widgetclass.html#setList">setList</a> <a href="notyet.html">setLogRes</a> <a href="gtermclass.html#setMapping">setMapping</a> <a href="notyet.html">setPhysRes</a> +<a href="gtermclass.html#setPixel">setPixel</a> <a href="gtermclass.html#setRaster">setRaster</a> <a href="widgetclass.html#setSensitive">setSensitive</a> <a href="notyet.html">setTextRes</a> <a href="uiparameterclass.html#setValue">setValue</a> +<a href="gmc.html#setVertices">setVertices</a> <a href="notyet.html">startDialog</a> <a href="widgetclass.html#unhighlight">unhighlight</a> <a href="widgetclass.html#unmanage">unmanage</a> <a href="widgetclass.html#unmap">unmap</a> +<a href="gtermclass.html#unmapPixel">unmapPixel</a> <a href="widgetclass.html#unrealize">unrealize</a> <a href="widgetclass.html#userEventHandler">userEventHandler</a> <a href="ximclient.html#windowColormap">windowColormap</a> +<a href="notyet.html">writeColormap</a> <a href="gtermclass.html#writePixels">writePixels</a> <a href="ximclient.html#zoom">zoom</a> <a href="ximclient.html#zoom">zoomAbs</a> +</pre> + diff --git a/vendor/x11iraf/obm/docs/obm/index.html b/vendor/x11iraf/obm/docs/obm/index.html new file mode 100644 index 00000000..b7e531ca --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/index.html @@ -0,0 +1,2515 @@ +<html> +<body bgcolor=#FFFFFF> +<title>IRAF Object Manager Tutorial</title> + +<center> +<h1>IRAF Object Manager Tutorial</h1> +</center> +<hr noshade=5> + +<h2>Contents</h2> +<ul> +<li><a href="#1">1. Introduction</a> +<li><a href="#2">2. System Architecture</a> +<li><a href="#3">3. The Client Process</a> + <ul> + <li><a href="#3.1">3.1 IRAF Graphics Task</a> + <ul> + <li><a href="#3.1.1">3.1.1 XGterm</a> + </ul> + <li><a href="#3.2">3.2 Standalone Task</a> + <li><a href="#3.3">3.3 OBM Shell</a> + <li><a href="#3.4">3.4 Named External Clients</a> + </ul> +<li><a href="#4">4. UI Definition File</a> + <ul> + <li><a href="#4.1">4.1 Example Interface</a> + </ul> +<li><a href="#5">5. Widget Toolkit</a> +<li><a href="#6">6. Object Classes</a> + <ul> + <li><a href="#6.1">6.1 Client</a> + <ul> + <li><a href="#6.1.1">6.1.1 Command Summary</a> + </ul> + <li><a href="#6.2">6.2 Server</a> + <ul> + <li><a href="#6.2.1">6.2.1 Command Summary</a> + </ul> + <li><a href="#6.3">6.3 Gterm</a> + <ul> + <li><a href="#6.3.1">6.3.1 Command Summary</a> + </ul> + <li><a href="#6.4">6.4 HTML</a> + <ul> + <li><a href="#6.4.1">6.4.1 Command Summary</a> + </ul> + <li><a href="#6.5">6.5 Markers</a> + <ul> + <li><a href="#6.5.1">6.5.1 Command Summary</a> + </ul> + <li><a href="#6.6">6.6 Widget</a> + <ul> + <li><a href="#6.6.1">6.6.1 Command Summary</a> + </ul> + <li><a href="#6.7">6.7 Parameter</a> + <ul> + <li><a href="#6.7.1">6.7.1 Command Summary</a> + </ul> + </ul> +</ul> + +<hr noshade=5> + +<a name="1"></a> +<h3>1. Introduction</h3> +<p> +An Object Manager (OBM) user interface (UI) consists of one or more windows +containing an arbitrary hierarchy of widgets. These widgets and their +runtime actions are defined by an interpreted text program uploaded +by the client application, which does not itself deal directly with the +window user interface. This interpreted program is currently written +as a Tcl script. +<p> +The OBM provides a high level abstraction for dealing with widgets and +other UI objects. The main function of the object manager is to deliver +messages to UI objects. Each instance of a widget is an object in the +interface. The UI contains other types of objects as well, including the +client object (client application), the server object (the object manager +itself), and the application specific UI parameters, each of which is an +object with a callback list of procedures to be called when the parameter +value changes. All of these UI objects can receive messages and take actions +as a result. Messages may come from the client application, or as a result +of actions executed by the interpreted UI code in response to graphics events. +<hr noshade=5> +<p> +<a name="2"></a> +<h3>2. System Architecture</h3> +<p> +For a complete description of the OBM system architecture see Tody, D, +ADASS Proceedings 1994. A <a href="todyd.ps">postscript version of this +paper</a> is also vailable. +<p> +<hr noshade=5> +<p> +<a name="3"></a> +<h3>3. The Client Process</h3> +<p> + The primary advantage of the OBM architecture over traditional GUI +design is the separation of the user interface from the executable client +code, meaning that either can be completely rewritten or developed separately +without affecting the other so long as the messaging between the two +remains the same. The client itself is responsible for initializing the OBM +toolkit and uploading the UI definition file, after that it usually enters +an event loop of some kind (e.g. an iraf graphics cursor loop, or X event +handler) to process actions defined in the client callbacks. +<p> + It's important that the client program maintain the state of the +application rather than the UI file. For example, a text widget in the +interface may instruct the client to load a file, however if this cannot +be done the interface should not have independently reset labels or +whatever assuming the action was done at all. Instead, the client program +uses the Parameter Class objects in the interface to update the state of +the GUI as a result of some action (whose origins may not have been in the +GUI at all). So for example a sequence of events could be something like + +<ul><ul> +<li> User selects a widget in the interface, it's callback sends a + message to the client directing some action be taken +<li> Client receives the message and performs an action in the client +<li> If action fails, (optionally) notify GUI of failure (e.g. send a + message to an 'alert' parameter to popup a dialog box, beep the + terminal, etc) +<li> If action succeeds, notify GUI of new state (e.g. send a message + to the 'filename' Parameter object containing the new file name). +<li> Callback on the 'filename' parameter then updates the status bar + widget with the name of the new active file. +</ul></ul> + +<p> + The messaging between the client and UI depend on the details of how +the client is implemented. In general any callback procedure in the UI can +send a message to any other object in the interface, but the client should +generally communicate only via the Parameter objects to avoid side effects +and maintain a clear separation between the UI and the client code. + +<a name="3.1"></a> +<h3>3.1 IRAF Graphics Task</h3> + +<a name="3.1.1"></a> +<h3>3.1.1 XGterm</h3> + +<a name="3.2"></a> +<h3>3.2 Standalone Task</h3> + +<a name="3.3"></a> +<h3>3.3 OBM Shell</h3> +<p> + The <i>obmsh</i> is a unix shell interpreter for GUI scripts. It is +a minimal standalone client with a single callback to exit the application, +otherwise it's only job is to activate the GUI file. Any messages sent to +the client (except a 'quit') are simply absorbed by the client +<p> + Despite the apparent lack of functionality this is sometimes all +that is required for an interface that can operate independently. Remember +that the Tcl scripting language has it's own facilities for file I/O, +process execution, etc, all of which are still available in the GUI. In +the case of IRAF tasks it's an interface violation to use these facilities +directly, however they still allow for the easy creation of a GUI which +requires no real underlying client (e.g. a tcl debug shell, a calculator +application, task launcher, etc). + +<a name="3.4"></a> +<h3>3.4 Named External Clients</h3> + +<p> +<p> +<hr noshade=5> +<p> +<a name="4"></a> +<h3>4. UI Definition File</h3> +<p> +A UI definition consists of a sequence of commands to be executed by the +server object using Tcl is used as an embedded interpreter within the OBM. +The Tcl script contains several required OBM-specific functions (in +addition to the user-defined callbacks) which is uploaded by the client +as a message for the server object. +<pre> + <a href="#resetReset">reset-server</a> + <a href="#appInitialize">appInitialize</a> appName appClass Resources + <a href="#createObjects">createObjects</a> [name] + <a href="#activate">activate</a> +</pre> +<p> +All UI files must begin with a <b>reset-server</b> command to initialize +the OBM. An <b>appInitialize</b> call is then made to define all of the +widgets and resources used in the interface, initializing the interface +used by the application. The <b>createObjects</b> function then actually +creates the widgets in the server, more specifically it creates the widgets +defined by the named <i>objects</i> resource. Lastly, the <b>activate</b> +call is used to activate the interface, i.e. put it on the screen. + +<p> +<a name="4.1"></a> +<h3>4.1 Example</h3> +A complete "hello, world" GUI definition might look something like: +<pre> + 1) <b>reset-server</b> + 2) <b>appInitialize</b> <i>hello Hello</i> { + 3) *objects:\ + 4) toplevel Form helloForm\ + 5) helloForm Label helloLabel\ + 6) helloForm Command quitButton + 7) + 8) *background: gray + 9) *helloLabel.label: Hello, world! + 10) *quitButton.fromHoriz: helloLabel + 11) *quitButton.label: Quit + 12) } + 13) + 14) <b>createObjects</b> + 15) <b>activate</b> + 16) + 17) <b>proc</b> Quit <b>args</b> { + 18) <b>send client gkey</b> q + 19) <b>deactivate unmap</b> + 20) } ; <b>send</b> quitButton <b>addCallback</b> Quit +</pre> + +where a line-by-line analysis of the GUI shows: + +<dl> +<dt>Line 1: <dd>- The <b>reset-server</b> command must be the first line in +the UI file since it's primary purpose is to initialize the OBM (i.e. a +call to the <i>ObmInitialize()</i> procedure). Subsequent calls (in the +same UI file or a different UI) are effectively a no-op. +<dt>Lines 2-12: <dd>- The <b>appInitialize</b> command defines the widgets +and resources to be used in the interface. The first argument gives the +name of the application, the second argument is the application class name +for purposes of specifying resources in the environment, and the last +argument is a Tcl list (hence the braces) of resources for the application. +<p> +The primary purpose of the call is to initialize the X11 part of the system +by defining the application context and the list of fallback resources. The +<i>objects</i> resource is a required element listing the widget hierarchy +to be used. Remaining resources are used to specify labels, colors, layout, +etc and serve as an app-defaults file for the GUI, interacting with the +normal resource database in the usual way. For example, a user's .Xdefaults +file may specify a "<b>font</b>" resource, unless this is overridden in +some way in the UI file this is the font that will be used. Resources may +be specified with either "loose" (i.e. the '*') or "tight" (i.e. the '.') +bindings with as much detail as is needed. +<dt>Line 14: <dd>- The <b>createObjects</b> command is what actually calls +each widget's Initialize() method to create the widget in the application +and in the X11 server. +<p> +With no argument, the default value used is simply +the <b>objects</b> resource. However, it's possible to specify a named +argument and make repeated calls to <b>createObjects</b> to build any number +widget trees prior to activating the interface. This can be useful for +example to specify a "main_objects" resource contains all the widgets for +the main panel, and a "help_objects" specfiying widgets used for the UI +help panel, which makes the definition file easier to organize. In the +past however UI files were written with a single long list (easily many +hundreds of lines) of objects followed by an even longer list of their +resources under a single <b>appInitialize</b> call, creating a monolithic +and unmanageably GUI definition file. Later on we'll see how complex GUIs +can be divided into separate pieces making it easier to reuse code and +manage the interface more efficiently. +<dt>Line 15: <dd>- The <b>activate</b> command is what creates the interface +on the screen, i.e. it calls the Realize() method for each widget to +instantiate it in the server and draw the window. +<dt>Lines 17-19: <dd>- Lastly we have the user-defined callback procedures. +On line 17 we define a procedure <i>Quit</i> which we use to shut down the +interface and client application. The body of the procedure first sends the +client object the graphics keystroke 'q' to shut down the client, then calls +the <b>deactivate</b> command to close the interface. On the last line +we send a message to the <i>quitButton</i> widget telling it to add this +procedure to it's callback list, so when the Button is selected this +procedure will be called as a result. +</dl> +<p> +<hr noshade=6> + +<a name="5"></a> +<h3>5. Widget Toolkit</h3> +<p> +<p> +<hr noshade=6> + +<a name="6"></a> +<h3>5. Object Classes</h3> +<p> +The following OBM object classes are currently defined: +<pre> + <a href="#6.1">Client</a> The Client application + <a href="#6.2">Server</a> The OBM itself + <a href="#6.3">Gterm</a> Gterm graphics/imaging widget class + <a href="#6.4">HTML</a> HTML widget class + <a href="#6.5">Markers</a> Gterm markers class + <a href="#6.6">Widget</a> General widget class + <a href="#6.7">Parameter</a> UI Parameter class +<p> + Various Xt and Athena widgets + <i>{box, shell, label, command, text, list, etc.}</i> + Misc Other X11 Widgets + <i>{Layout, Tabs, ListTree, etc}</i> +</pre> +<p> +OBM client applications will upload a UI during initialization to define a +custom graphics user interface. This is done by sending a message to the +object manager. Non-GUI applications assume a simple graphics +terminal and do not upload a UI; instead, a default UI is created +for the application consisting of a single top level shell containing a +Gterm (Tek 4012 graphics/imaging) widget. +<p> + +<hr noshade=5> + +<a name="5.1"></a> +<h3>5.1 Client</h3> +<p> +The client is the client application, which provides the functionality +underlying the UI. When a message is sent to the client object it usually +results in a message being sent to the client *application*, usually an +external program communicating via IPC, which has little or no knowledge +of the UI. The client application receives and executes commands delivered +by the UI via the client object. Output from the client may or may not +come back to the object manager. That portion of the output which comes +back to the object manager is in the form of assignments of string values +to <a href="#5.7.html">UI Parameter class objects</a> (another way of thinking +of this is that messages or events are sent to and acted upon by the parameter +objects). Hence, the client object is output only so far as the client +application is concerned. +<p> +The Client-class commands are used to send a message to the client. +<p> +<pre> + <a href="#gkey">gkey</a> <key> + <a href="#gcmd">gcmd</a> <command-string> + <a href="#literal">literal</a> <command> +</pre> +<p> +or just <command>, e.g., "send client <command>" will work in most cases. +<p> +<a href="#gkey">GKEY</a> sends an IRAF graphics keystroke. +<a href="#gcmd">GCMD</a> sends an +IRAF graphics colon command. <a href="#literal">LITERAL</a> sends a literal +command string to the +client. The keyword "literal" may optionally be omitted, i.e., "send client +foo" and "send client literal foo" are the same. The keyword "literal" may +be used to ensure that the client command string which follows will not +be interpreted as a Client-class command (such as gkey, gcmd, or literal). +<p> +<a name="5.1.1"></a> +<h2>5.1.1 Command Summary</h2> +<p> +<h3><A NAME="gcmd">gcmd</A></h3> +<p> +Send a graphics command string to the client application. +A graphics command string is a graphics cursor value with the key set +to `:' and the command string given as the string part of the cursor +value. The protocol module which posted the client output procedure is +responsible for encoding and sending the cursor command. +<p> +Usage: +<p> +<pre> + gcmd <command-string> +</pre> +<p> +<h3><A NAME="gkey">gkey</A></h3> +<p> +Send a graphics key event to the client application. +A graphics key event is a graphics cursor value with the key set to some +integer value and a null string part. +<p> +Usage: +<p> +<pre> +gkey <key> +</pre> +<p> +<h3><A NAME="literal">literal</A></h3> +<p> +Send a literal command to the client application. +<p> +Usage: +<p> +<pre> + literal <command> +</pre> + +<hr noshade=5> + +<a name="6.2"></a> +<h3>6.2 Server</h3> +<p> +The server, or object manager, is the control center of the user interface. +The server object provides a Tcl interpreter calling custom object manager +commands. These are used to define and initialize the user interface, and +execute UI action procedures at runtime. +<p> +<pre> + <a href="#resetReset">reset-server</a> + <a href="#appInitialize">appInitialize</a> appname,appclass,resources + <a href="#createObjects">createObjects</a> [resource-name] + <a href="#destroyObject">destroyObject</a> object + <a href="#activate">activate</a> + <a href="#deactivate">deactivate</a> [unmap] +<p> + value = <a href="#getResource">getResource</a> resource-name [default-value [class]]</a> + <a href="#getResources">getResources</a> resource-list +<p> + <a href="#createMenu">createMenu</a> menu-name parent item-list + <a href="#createMenu">editMenu</a> menu-name parent item-list + <a href="#destroyMenu">destroyMenu</a> menu-name +<p> + <a href="#createBitmap">createBitmap</a> name width height data + <a href="#createCursor">createCursor</a> name source mask fg_color bg_color x_hot y_hot + <a href="#createPixmap">createPixmap</a> name width height depth fg_color bg_color data +<p> + <a href="#print">print</a> arg [arg ...] # debug messages + <a href="#send">send</a> object message +<p> + <a href="#postActivateCallback">postActivateCallback</a> procedure +id = <a href="#postTimedCallback">postTimedCallback</a> procedure msec [client-data] + <a href="#deleteTimedCallback">deleteTimedCallback</a> id + id = <a href="#postWorkCallback">postWorkCallback</a> procedure [client-data] + <a href="#deleteWorkCallback">deleteWorkCallback</a> id +</pre> + +<a name="6.2.1"></a> +<h2>6.2.1 Command Summary</h2> +<p> +<h3><A NAME="serverReset">serverReset</A></h3> +<p> +The "reset-server" command is implemented as a special case in ServerEvaluate. +After doing a true reset ServerEvaluate calls Tcl_Eval to evaluate the full +message which still contains the reset-server command. We want to ignore +this the second time, so we treat the command here as a no-op. +<p> +Usage: +<p> +<pre> + reset-server +</pre> +<p> +Note: for reset-server to be recognized by ServerEvaluate and really reset +things, it must be the first command in a message to the server. +<p> +<h3><A NAME="appInitialize>appInitialize</A></h3> +<p> +TCL command to initialize the server for a new application, setting the +application name and loading the application resources. +<p> +Usage: +<p> +<pre> + appInitialize appname, appclass, resources +</pre> +<p> +<h3><A NAME ="createObjects">createObjects</A></h3> +<p> +TCL command to create the tree of UI objects comprising the user interface. +The object tree is defined by a string valued resource. If no resource is +named the default "objects" resource will be used. +<p> +Usage: +<p> +<pre> + createObjects [resource-name] +</pre> +<h3><A NAME="destroyObject">destroyObject</A></h3> +<p> +Destroy an object and all of its children. +<p> +Usage: +<pre> + destroyObject object-name +</pre> +<p> +<h3><A NAME="activate">activate</A></h3> +Activate the user interface. When called the first time the user interface +is created and activated, thereafter the UI is merely reactivated (e.g. +mapped if unmapped). +<p> +Usage: +<p> +<pre> + activate +</pre> +<p> +<h3><A NAME="deactivate">deactivate</A></h3> +<p> +Deactivate the user interface. Optionally unmaps the UI and calls the Obm +client back to let it know that the UI has been deactivated. +<p> +Usage: +<p> +<pre> + deactivate [unmap] +</pre> +<p> +<h3><A NAME="getResource">getResource</A></h3> +<p> +Get the string value of the specified application resource (window +system parameter). This allows use of the resource mechanism to supply +default values for GUI parameters. +<p> +Usage: +<p> +<pre> + value = getResource resource-name [class [default-value]] +</pre> +<p> +In the simplest case one merely requests a resource by name and the +string value is returned as the function value. If the resource has +an entry in the fallback resources for the application (appInitialize +resource list) then a value is guaranteed to be returned. +<p> +If the Class name for the resource is given then a class default value +will be returned if no entry is found for the name resource instance. This +is useful when there are a number of resources of the same type (same class). +If most or all resources in the same class have the same default value one +need only make one entry for the Class in the application defaults resource +list. It is up to the application developer to define the class name of a +resource - the class name can be any string. Examples are "Font", "Cursor", +etc. By convention the first character of a class name is capitalized, while +instance names begin with a lower case letter. +<p> +If there is an entry for the named resource in the resource list passed to +appInitialize then a value string is guaranteed to be returned. This will be +either the appInitialize default, or a value specified by the system or the +user in an X resources file. If one is not certain a default value is defined +somewhere, a default value should be specified in the getResource call as +shown above. +<p> +See also getResources, used to get multiple resources in one call. +<p> +<h3><A NAME="getResources">getResources</A></h3> +<p> +Get the string values of a list of resources. +<p> +Usage: +<p> +<pre> + getResources resource-list +</pre> +<p> +e.g. +<pre> + getResources { + { resource [variable class [default-value]]] } + { resource [variable class [default-value]]] } + (etc.) + } +</pre> +<p> +<h3><A NAME="createMenu">createMenu, editMenu</A></h3> +<p> +Create or modify a menu. The editMenu function is an alias for createMenu. +<p> +Usage: +<pre> + createMenu menu-name parent item-list +</pre> +<p> +e.g., +<pre> + createMenu menu-name parent { + { label function data [options...] } + { label function data [options...] } + (etc.) + } +</pre> +<p> +where +<p> +<pre> + menu-name is the object name for the menu popup shell + parent is the parent widget of the menu shell + label is a menu item label + function is the function to be performed when the menu + item is selected, e.g., f.exec, f.data, f.space, or f.line. + data is function dependent data + options are option-name option-value pairs, as specified + below. +</pre> +<p> +In the item list the fields label and option-value may be any Tcl expression. +Expressions are evaluated in the server context. The data field is a Tcl +script to be executed when the menu item is selected. +<p> +Options are specified as "option option-value". The menu item options are +as follows. +<p> +<pre> + bitmap A bitmap to be displayed left justified in the label field + (e.g. to indicate a parameter setting). + sensitive Specifies whether the menu item is active (sensitive=true) + or inactive (sensitive=false, item grayed out). + accelerator Specifies an input translation (accelerator, e.g., + keyboard event) which can be used to execute the + menu item. +</pre> +<p> +The option-value field may be any Tcl expression. +<p> +Example: +<p> +<pre> + createMenu fileMenu toplevel { + { "File Menu" f.title} + { Open f.exec openFile} + { Save f.exec saveFile} + { Load f.menu loadMenu} + { no-label f.line } + { Quit f.exec "send client Quit" } + } +</pre> +<p> +The first createMenu is called for a given menu the menu is created, added +to the menu list, and all window system widgets are created for the menu. +Subsequent calls will result in only the changed parts of the menu being +altered provided the changes are not great. Hence this routine can be called +to efficiently modify a menu when minor runtime changes occur, e.g., an +item label or action changes, the item value changes state, and so on, +without need for the GUI code to know how to make the necessary detailed +changes to the widgets used to implement the menu. +<p> +<h3><A NAME="destroyMenu">destroyMenu</A></h3> +<p> +Destroy a menu. This can be used to free up the resources used by a +menu, e.g., if the menu is not expected to be needed again for a while. +<p> +Usage: +<p> +<pre> + destroyMenu menu-name +</pre> +<p> +<h3><A NAME="createBitmap">createBitmap</A></h3> +<p> +Create a named bitmap. This replaces any old bitmap of the same name. The +new bitmap is cached in server memory; when a widget bitmap resource is set, +the bitmap cache will be searched for the named bitmap before asking Xlib +to find the bitmap. +<p> +Usage: +<p> +<pre> + createBitmap name width height data +</pre> +<p> +e.g., +<p> +<pre> + createBitmap foo 16 16 { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +<p> +<h3><A NAME="createCursor">createCursor</A></h3> +<p> +Create a cursor from bitmap data. The cursor is entered into the server's +cursor cache and will override any existing entry of the same name. +<p> +Usage: +<p> +<pre> + createCursor name source mask fg_color bg_color x_hot y_hot +</pre> +<p> +e.g., +<p> +<pre> + createCursor foo bitmap1 bitmap2 black white 8 8 +</pre> +<p> +The named bitmaps must be created first with createBitmap. +<p> +<h3><A NAME="createPixmap">createPixmap</A></h3> +<p> +Create a named pixmap. This replaces any old pixmap of the same name. The +new pixmap is cached in server memory; when a widget pixmap resource is set, +the pixmap cache will be searched for the named pixmap before asking Xlib +to find the pixmap. +<p> +Usage: +<p> +<pre> + createPixmap name width height depth fg_color bg_color data +</pre> +<p> +e.g., +<p> +<pre> + createPixmap foo 16 16 8 black white { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +</pre> +<p> +<h3><A NAME="print">print</A></h3> +<p> +Print a string on the standard output. This is used mainly for debugging +user interfaces. +<p> +Usage: +<p> +<pre> + print arg [arg ...] +</pre> +<p> +<h3><A NAME="send">send</A></h3> +<p> +Send a message to an object. The object interprets the message and returns +a function value as the string result of the TCL command. +<p> +Usage +<p> +<pre> + send <object> <message> +</pre> +<p> +<h3><A NAME="postActivateCallback">postActivateCallback</A></h3> +<p> +Post a callback procedure to be called when the UI is activated. The UI is +activated when it is first downloaded to server, but it may also be +activated (reactivated) after the application has exited and is later +restarted, or when the UI is deactivated and reactivated. Note +that the UI state vis-a-vis the external world (client application) may +no longer be accurate after it has been idle for a time and then reactivated. +<p> +Usage: +<p> +<pre> + postActivateCallback <procedure> +</pre> +<p> +<p> +<h3><A NAME="postTimedCallback">postTimedCallback</A></h3> +<p> +Post a callback to call the named procedure back after a specified delay +in milliseconds. +<p> +Usage: +<p> +<pre> + id = postTimedCallback procedure msec [client-data] +</pre> +<p> +After the specified delay the user callback procedure will be called with +client_data (if given) as the single argument. Only one call will be made; +the client must repost the callback in each call if the procedure is to be +repeatedly executed. +<p> +An ID value is returned which may be passed to deleteTimedCallback to delete +the timer. +<p> +<h3><A NAME="deleteTimedCallback">deleteTimedCallback</A></h3> +<p> +Delete a timer callback procedure. This procedure is typically used to +break a timer loop, where the timer procedure repeatedly reposts itself at +the end of each interval. +<p> +Usage: +<p> +<pre> + deleteTimedCallback id +</pre> +<p> +The ID string is returned by postTimedCallback when a timer is posted. +<p> +<h3><A NAME="postWorkCallback">postWorkCallback</A></h3> +<p> +Post a callback for a procedure to be called when the server is idle. +Work procedures are used to perform computations in the background while +the user interface remains active and able to respond to input events. +This works only if the user work procedure does its job in small increments, +doing only a small amount of processing in each call. The work procedure +will be called repeatedly until it returns a status indicating that it has +finished its task. +<p> +Usage: +<p> +<pre> + id = postWorkCallback procedure [client-data] +</pre> +<p> +When the server has nothing else to do the user work procedure will be +called with client_data (if given) as the single argument. The work procedure +should return the string "done" when all processing is finished, or any other +string if the procedure is to be called again. +<p> +An ID value is returned which may be passed to deleteWorkCallback to delete +the work procedure. +<p> +<h3><A NAME="deleteWorkCallback">deleteWorkCallback</A></h3> +<p> +Delete a work callback procedure. +<p> +Usage: +<p> +<pre> + deleteWorkCallback id +</pre> +<p> +The ID string is returned by postWorkCallback when a work procedure is posted. + +<hr noshade=5> + +<a name="6.3"></a> +<h3>6.3 Gterm</h3> +<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 + <a href="notyet.html">getLogRes</a> width height + <a href="notyet.html">setPhysRes</a> width height + <a href="notyet.html">getPhysRes</a> width height + <a href="notyet.html">setTextRes</a> rows cols + <a href="notyet.html">setDataLevel</a> level + <a href="notyet.html">setLineWidth</a> width + <a href="notyet.html">setLineStyle</a> style + <a href="notyet.html">setColorIndex</a> index + <a href="notyet.html">setFillType</a> filltype +<p> + <a href="#clearScreen">clearScreen</a> + <a href="notyet.html">drawPolyline</a> vector + <a href="notyet.html">drawPolymarker</a> vector + <a href="notyet.html">drawPolygon</a> vector + <a href="notyet.html">drawMarker</a> x y xsize ysize type +<p> + <a href="notyet.html">drawAlphaText</a> x y text + <a href="notyet.html">getAlphaTextSize</a> string width height base + <a href="notyet.html">startDialog</a> + <a href="notyet.html">endDialog</a> + <a href="notyet.html">eraseDialog</a> + <a href="notyet.html">drawDialogText</a> x y text + <a href="notyet.html">getDialogTextSize</a> string width height base +</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 + <a href="notyet.html">createRaster</a> raster type width height depth + <a href="notyet.html">destroyRaster</a> raster + exists = <a href="notyet.html">queryRaster</a> raster type width height depth + raster = <a href="notyet.html">nextRaster</a> [raster] + nrasters = <a href="notyet.html">nRasters</a> [nrasters] +<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 + pixmap = <a href="notyet.html">createPixmap</a> src x y width height + <a href="notyet.html">copyPixmap</a> pixmap dst x y width height +<p> + colormap = <a href="notyet.html">nextColormap</a> [colormap] + <a href="notyet.html">freeColormap</a> colormap + <a href="notyet.html">writeColormap</a> colormap first nelem colors + <a href="notyet.html">readColormap</a> colormap first nelem colors + <a href="#loadColormap">loadColormap</a> colormap offset scale +<p> + <a href="notyet.html">initMappings</a> + mapping = <a href="#nextMapping">nextMapping</a> [mapping] + <a href="notyet.html">freeMapping</a> mapping + <a href="notyet.html">enableMapping</a> mapping + <a href="notyet.html">disableMapping</a> mapping + active = <a href="notyet.html">activeMapping</a> mapping + <a href="notyet.html">refreshMapping</a> mapping +<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 + <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> +<a name="6.3.1"></a> +<h2>6.3.1 GTERM class commands</h2> +<p> +<h3><A NAME="setGterm">setGterm</A></h3> +<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> +<h3><A NAME="activate">activate</A></h3> +<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> +<h3><A NAME="deactivate">deactivate</A></h3> +<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> +<h3><A NAME="reset">reset</A></h3> +<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> +<h3><A NAME="flush">flush</A></h3> +<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> +<h3><A NAME="addCallback">addCallback</A></h3> +<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> +<h3><A NAME="setCursorPos">setCursorPos</A></h3> +<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> +<h3><A NAME="getCursorPos">getCursorPos</A></h3> +<p> +Get the cursor position (raster 0 or screen coordinates). +<p> +Usage: +<p> +<pre> + getCursorPos x y +</pre> +<p> +<h3><A NAME="setCursorType">setCursorType</A></h3> +<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> +<h3><A NAME="bell">bell</A></h3> +<p> +Gterm widget sound output. +<p> +Usage: +<p> +<pre> + bell +</pre> +<p> +<h3><A NAME="setRaster">setRaster</A></h3> +<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> +<h3><A NAME="getRaster">getRaster</A></h3> +<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> +<h3><A NAME="clearScreen">clearScreen</A></h3> +<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> +<h3><A NAME="rasterInit">rasterInit</A></h3> +<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> +<h3><A NAME="writePixels">writePixels</A></h3> +<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> +<h3><A NAME="setPixel">setPixel</A></h3> +<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> +<h3><A NAME="readPixels">readPixels</A></h3> +<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> +<h3><A NAME="getPixel">getPixel</A></h3> +<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> +<h3><A NAME="nextMapping">nextMapping</A></h3> +<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> +<h3><A NAME="getMapping">getMapping</A></h3> +<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> +<h3><A NAME="setMapping">setMapping</A></h3> +<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> +<h3><A NAME="loadColormap">loadColormap</A></h3> +<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> +<h3><A NAME="selectRaster">selectRaster</A></h3> +<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> +<h3><A NAME="unmapPixel">unmapPixel</A></h3> +<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> +<h3><A NAME="flip">flip</A></h3> +<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> +<h3><A NAME="markerInit">markerInit</A></h3> +<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> +<h3><A NAME="createMarker">createMarker</A></h3> +<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 <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. +<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. + +<hr noshade=5> + +<a name="6.4"></a> +<h3>6.4 HTML</h3> + +The HTML (hypertext markup language) widget displays a block of HTML +formatted text, the "document" to be displayed. The text consists of a +mixture of text to be displayed and embedded formatting directives. The +text may also contain "hot links" pointing to other HTML-formatted +documents. + +<pre> + setText text [target [header_text [footer_text]]] + text = getText [format [font]] + retestAnchors + + id = positionToId x y + idToPosition id x y + anchorToPosition name x y + id = anchorToId name + gotoId id + + n = getHRefs list + n = getImageSrcs list + n = getLinks list + + setSelection start end + text = getSelection start end + clearSelection + + searchText pattern start end [direction [search_type]] + + addCallback procedure-name [callback-type] + deleteCallback procedure-name [callback-type] +</pre> + +The possible callback types and their callback arguments are as follows. + +<pre> + anchor widget cbtype event text href element_id + testAnchor widget cbtype href + submitForm widget cbtype event attrs href method enctype encentity + link widget cbtype href role + pointerMotion widget cbtype href +</pre> + +See the comments below for further details on the callback types and their +arguments. + +<p> +<a name="6.4.1"></a> +<h2>6.4.1 Command Summary</h2> +<p> + +<hr noshade=5> + +<a name="6.5"></a> +<h3>6.5 Markers</h3> +<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="#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 <ObmW/Gterm.h> 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 <Btn1Motion> 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() +</pre> +<p> +<a name="6.5.1"></a> +<h2>6.5.1 Command Summary</h2> +<p> +<h3>makeCopy</A></h3> +<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> +<h3><A NAME="addCallback">addCallback</A></h3> +<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> +<h3><A NAME="notify">notify</A></h3> +<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> +<h3><A NAME="destroy">destroy</A></h3> +<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> +<h3><A NAME="markpos">markpos</A></h3> +<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> +<h3><A NAME="redraw">redraw</A></h3> +<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> +<h3><A NAME="raise">raise</A></h3> +<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> +<h3><A NAME="lower">lower</A></h3> +<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> +<h3><A NAME="move">move</A></h3> +<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> +<h3><A NAME="resize">resize</A></h3> +<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> +<h3><A NAME="rotate">rotate</A></h3> +<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> +<h3><A NAME="getAttribute">getAttribute</A></h3> +<p> +Return the value of a marker attribute. +<p> +Usage: +<p> +<pre> + value = getAttribute attribute-name +</pre> +<p> +<h3><A NAME="setAttribute">setAttribute</A></h3> +<p> +Set the value of a marker attribute. +<p> +Usage: +<p> +<pre> + setAttribute attribute-name value +</pre> +<p> +<h3><A NAME="getAttributes">getAttributes</A></h3> +<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> +<h3><A NAME="setAttributes">setAttributes</A></h3> +<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> +<h3><A NAME="getVertices">getVertices</A></h3> +<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> +<h3><A NAME="setVertices">setVertices</A></h3> +<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> +<h3><A NAME="getRegion">getRegion</A></h3> +<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> +<h3><A NAME="getRect">getRect</A></h3> +<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> + +<hr noshade=5> + +<a name="6.6"></a> +<h3>6.6 Widget</h3> +<p> +The Widget class is the generic or base class for the window system +toolkit widgets supported by the object manager. The Widget class +supports a number of different Xt widget classes using a table driven +approach to describe each widget. Any widget may be created, destroyed, +and manipulated in various ways using only the generic Widget class +procedures and Widget-specific resources. The Widget class may be +subclassed to support complex Widgets that require custom class-specific +commands for use by the GUI code. +<p> +Generic Widget-class commands: +<p> +<pre> + <a href="#set">set</a> <resource-name> <value> + <a href="#get">get</a> <resource-name> +<p> + <a href="#addCallback">addCallback</a> <procedure-name> [<callback-name>] + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#setSensitive">setSensitive</a> <sensitive> + <a href="#isSensitive">isSensitive</a> +<p> + <a href="#realize">realize</a> + <a href="#unrealize">unrealize</a> + <a href="#isRealized">isRealizeed</a> + <a href="#map">map</a> + <a href="#unmap">unmap</a> + <a href="#manage">manage</a> child [child ...] + <a href="#unmanage">unmanage</a> child [child ...] + <a href="#popup">popup</a> [grab-kind] + <a href="#popdown">popdown</a> + <a href="#popupSpringLoaded">popupSpringLoaded</a> +<p> + <a href="#move">move</a> <x> <y> + <a href="#resize">resize</a> <width> <height> <border-width> + <a href="#configure">configure</a> <x> <y> <width> <height> <border-width> +</pre> +<p> +The most important Widget commands are set/get resource, and the +callbacks. The widget sensitivity can be set and queried using set/get +resource, but special procedures are provided to make this common operation +more convenient. +<p> +Class specific functions: +<p> +<pre> + <a href="#append">append</a> text # text widget + <a href="#setList">setList</a> list [resize] # list widget + value = <a href="#getItem">getItem</a> itemno + <a href="#highlight">highlight</a> itemno + <a href="#unhighlight">unhighlight</a> +</pre> +<p> +Ideally the widget class should be subclassed for widgets that require +class-specific functions, but in simple cases involving standard widgets +the support is built into the widget class code as a special case. +<p> +Special actions (used in translations): +<p> +<pre> + <a href="#do_userproc">call</a> (proc [,arg, ...]) + <a href="#do_popup">popup</a> (menu-name [xoffset [yoffset]]) + <a href="#do_popdown">popdown</a> (menu-name) +</pre> +<p> +The "call" action is a very general mechanism which allows any GUI procedure +to be registered with any translation using the X translation table +mechanism. The popup and popdown actions are used for popup menus. The +menu will be popped up at the event coordinates plus the optional offsets +if given. +<p> +Event handling: +<p> +<pre> + <a href="#addEventHandler">addEventHandler</a> <procname> <event-mask> [<event-mask>...] +</pre> +<p> +Event callback: +<p> +<pre> + <a href="#userEventHandler">userEventHandler</a> widget event-type time wx wy rx ry other +</pre> +<p> +In most cases translations are preferable to events, but a GUI can capture +raw events if it wishes by adding event handlers. Nearly all of the X +event types are supported. The callback syntax employs a number of +standard arguments, followed by a number of event-specific arguments. +<p> +<h3><A NAME="addCallback">addCallback</A></h3> +<p> +Add a callback procedure to the callback list for +a widget. If no callback name is given, "callback" is assumed. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> [<callback-name>] +</pre> +<p> +Specific widgets only support certain types of callbacks. There is no +checking that the callback type specified is supported by a widget; the +wrong type of callback can be registered, but it will never be called. +<p> +<h3><A NAME="deleteCallback">deleteCallback</A></h3> +<p> +Delete a callback procedure previously registered +for a widget. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<p> +<h3><A NAME="do_userproc">do_userproc (call)</A></h3> +<p> +Translation action procedure used to call general user +action procedures in the interpreter. The name of the user procedure to +be called is given as the first argument in the translation. For example, +the translation "call(foo,a,b,c)" would cause procedure foo to be called +with the arguments (a,b,c). The following arguments are special: +<p> +<pre> + Argument Replaced by +<p> + $name object name of widget + $time event->time + $x event->x + $y event->y + $x_root event->x_root + $y_root event->y_root +</pre> +<p> +The "user procedure" can be any server procedure. +<p> +<h3><A NAME="do_popup">do_popup</A></h3> +<p> +Popup a menu (or other spring loaded popup) at the location +of the event which triggered this action. +<p> +Usage: +<p> +<pre> + popup(menu-name [xoffset [yoffset]]) +</pre> +<p> +<h3><A NAME="do_popdown">do_popdown</A></h3> +<p> +Pop down a menu. +<p> +Usage: +<p> +<pre> + popdown(menu-name) +</pre> +<p> +<h3><A NAME="set">set</A></h3> +<p> +Set a widget resource. +<p> +Usage: +<p> +<pre> + set <resource-name> <value> +</pre> +<p> +<h3><A NAME="get">get</A></h3> +<p> +Get a widget resource value as a string. +<p> +Usage: +<p> +<pre> + get <resource-name> +</pre> +<p> +<h3><A NAME="append">append</A></h3> +<p> +Append data to a text widget. +<p> +Usage: +<p> +<pre> + append <text> +</pre> +<p> +<h3><A NAME="setList">setList</A></h3> +<p> +Set the item list of a list widget. +<p> +Usage: +<p> +<pre> + setList list [resize] +</pre> +<p> +The list is a simple list of strings, passed as a single string argument to +setList (quotes, braces, etc. may be used to quote strings containing +special characters). +<p> +<h3><A NAME="getItem">getItem</A></h3> +<p> +Get an item in a list widget. +<p> +Usage: +<p> +<pre> + value = getItem itemno +</pre> +<p> +If ITEMNO is a number the indicated list item is returned, or the string +"EOF" if the requested item is beyond the end of the list. Otherwise the +currently selected item is returned, and the index of the item is returned +in the output variable ITEMNO. If no item is currently selected ITEMNO +will be set to "none" on output. +<p> +<h3><A NAME="highlight">highlight</A></h3> +<p> +Highlight an item in a list widget. +<p> +Usage: +<p> +<pre> + highlight itemno +</pre> +<p> +The indicated item of the list is highlighted as if the item had been +selected by the user. Any previously highlighted item is unhighlighted. +<p> +<h3><A NAME="unhighlight">unhighlight</A></h3> +<p> +Unhighlight the currently highlighted item in a +list widget. +<p> +Usage: +<p> +<pre> + unhighlight +</pre> +<p> +Any currently highlighted item in the list widget is unhighlighted. +<p> +<h3><A NAME="realize">realize</A></h3> +<p> +Realize a widget. This activates and assigns windows for +a widget and all of its descendants. Realizing a widget does not in itself +cause it to appear on the screen. +<p> +Usage: +<p> +<pre> + realize +</pre> +<p> +<h3><A NAME="unrealize">unrealize</A></h3> +<p> +Unrealize a widget. This destroys the windows assigned +to a widget and all of its descendants. +<p> +Usage: +<p> +<pre> + unrealize +</pre> +<p> +<h3><A NAME="isRealized">isRealized</A></h3> +<p> +Test whether a widget is realized. +<p> +Usage: +<p> +<pre> + isRealized +</pre> +<p> +<h3><A NAME="map">map</A></h3> +<p> +Map a widget. +<p> +Usage: +<p> +<pre> + map +</pre> +<p> +<h3><A NAME="unmap">unmap</A></h3> +<p> +Unmap a widget. +<p> +Usage: +<p> +<pre> + unmap +</pre> +<p> +<h3><A NAME="manage">manage</A></h3> +<p> +Manage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Managing the +children makes them appear in the window, possibly causing the other +children to be rearranged in the window. +<p> +Usage: +<p> +<pre> + manage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h3><A NAME="unmanage">unmanage</A></h3> +<p> +Unmanage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Unmanaging the +children makes them disappear from the window and be removed from geometry +management, possibly causing the other children to be rearranged in the +window. +<p> +Usage: +<p> +<pre> + unmanage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h3><A NAME="popup">popup</A></h3> +<p> +Popup a shell widget. If no grab is indicated the popup +can remain up while other windows accept input. +<p> +Usage: +<p> +<pre> + popup [grab-kind] +</pre> +<p> +<h3><A NAME="popdown">popdown</A></h3> +<p> +Popdown a shell widget. +<p> +Usage: +<p> +<pre> + popdown +</pre> +<p> +<h3><A NAME="popupSpringLoaded">popupSpringLoaded</A></h3> +<p> +Popup a shell widget, e.g., a popup menu. +This implies an exclusive grab. +<p> +Usage: +<p> +<pre> + popupSpringLoaded +</pre> +<p> +<h3><A NAME="move">move</A></h3> +<p> +Move a widget to the given window relative coordinates. +<p> +Usage: +<p> +<pre> + move <x> <y> +</pre> +<p> +<h3><A NAME="resize">resize</A></h3> +<p> +Resize a widget. +<p> +Usage: +<p> +<pre> + resize <width> <height> <border-width> +</pre> +<p> +<h3><A NAME="configure">configure</A></h3> +<p> +Configure a widget, i.e., execute a simultaneous +move and resize. +<p> +Usage: +<p> +<pre> + configure <x> <y> <width> <height> <border-width> +</pre> +<p> +<h3><A NAME="setSensitive">setSensitive</A></h3> +<p> +Set the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + setSensitive <sensitive> +</pre> +<p> +<h3><A NAME="isSensitive">isSensitive</A></h3> +<p> +Test the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + isSensitive +</pre> +<p> +<h3><A NAME="addEventHandler">addEventHandler</A></h3> +<p> +Add a custom event handler to a widget. A list +of event masks is given to define the classes of events the user supplied +event handling procedure is to receive. +<p> +Usage: +<p> +<pre> + addEventHandler <procname> <event-mask> [<event-mask>...] +</pre> +<p> +<h3><A NAME="removeEventHandler">removeEventHandler</A></h3> +<p> +Remove an event handler previously posted +with addEventHandler, above. +<p> +Usage: +<p> +<pre> + removeEventHandler procname +</pre> +<p> +<h3><A NAME="event">event</A></h3> +<p> +Generic event handler called when a widget event handler +posted by addEventHandler is called. +<p> +The user event handler is called as +<p> +<pre> + userEventHandler widget event-type time wx wy rx ry other +</pre> +<p> +where "other" is an event-type specific list of fields describing the +the event. +<hr noshade=5> + +<a name="6.7"></a> +<h3>6.7 Parameter</h3> +<p> +The UI parameter class is used for client-UI communications. The client +does not control the user interface directly, rather the UI defines a set +of abstract UI parameters, and during execution the client application +assigns values to these parameters. These UI parameters should be thought +of as describing the runtime state of the client as viewed by the GUI. +The GUI is free to interpret this state information in any way, including +ignoring it. Many GUIs can be written which use the same client state +as described by the UI parameters. +<p> +Assigning a value to a UI parameter causes the new value to be stored, and +any parameter action procedures registered by the UI to be called. +The action or actions [if any] taken when a parameter value changes are +arbitrary, e.g. the action might be something as simple as changing a +displayed value of a UI widget, or something more complex like displaying +a popup. +<p> +<h2>UI Parameter class commands:</h2> +<p> +<pre> + <a href="#getValue">getValue</a> + <a href="#setValue">setValue</a> <new-value> + <a href="#addCallback">addCallback</a> <procedure-name> + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#notify">notify</a> +</pre> +<p> +The most common usage is for the GUI to post one or more callbacks for +each UI parameter. When the UI parameter value is changed [with setValue, +e.g. by the client] the GUI callback procedures are called with the old +and new UI parameter values on the command line. addCallback is used to +add a callback procedure, and deleteCallback to delete one. Multiple +callbacks may be registered for a single UI parameter. notify is used +to simulate a parameter value change, causing any callback procedures to +be invoked. +<p> +The callback procedure is called as follows: +<p> +<pre> + user-procedure param-name {old-value} {new-value} +</pre> +<p> +The important thing to note here is that the old and new value strings +are quoted with braces. This prevents any interpretation of the string +by Tcl when the callback is executed, which is necessary because the +strings can contain arbitrary data. When Tcl calls the callback the +first level of braces will be stripped off, leaving old-value and new-value +each as a single string argument. +<p> +<p> +<h2><A NAME="setValue">setValue</A></h2> +<p> +Set the value of a parameter, and notify all clients +via the posted callback procedures that the parameter value has changed. +<p> +Usage: +<p> +<pre> + setValue <new-value> +</pre> +<p> +<h2><A NAME="getValue">getValue</A></h2> +<p> +Get the value of a parameter. +<p> +Usage: +<p> +<pre> + getValue +</pre> +<p> +<h2><A NAME="notify">notify</A></h2> +<p> +Notify the registered clients of a parameter as if the +value had changed. +<p> +Usage: +<p> +<pre> + notify +</pre> +<p> +<h2><A NAME="addCallback">addCallback</A></h2> +<p> +Add a callback procedure to the callback list for +a parameter. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> +</pre> +<p> +<h2><A NAME="deleteCallback">deleteCallback</A></h2> +<p> +Delete a callback procedure previously registered +for a parameter. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<hr noshade=5> + +<hr noshade=5> +</body> +</html> diff --git a/vendor/x11iraf/obm/docs/obm/obm.html b/vendor/x11iraf/obm/docs/obm/obm.html new file mode 100644 index 00000000..b7e531ca --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/obm.html @@ -0,0 +1,2515 @@ +<html> +<body bgcolor=#FFFFFF> +<title>IRAF Object Manager Tutorial</title> + +<center> +<h1>IRAF Object Manager Tutorial</h1> +</center> +<hr noshade=5> + +<h2>Contents</h2> +<ul> +<li><a href="#1">1. Introduction</a> +<li><a href="#2">2. System Architecture</a> +<li><a href="#3">3. The Client Process</a> + <ul> + <li><a href="#3.1">3.1 IRAF Graphics Task</a> + <ul> + <li><a href="#3.1.1">3.1.1 XGterm</a> + </ul> + <li><a href="#3.2">3.2 Standalone Task</a> + <li><a href="#3.3">3.3 OBM Shell</a> + <li><a href="#3.4">3.4 Named External Clients</a> + </ul> +<li><a href="#4">4. UI Definition File</a> + <ul> + <li><a href="#4.1">4.1 Example Interface</a> + </ul> +<li><a href="#5">5. Widget Toolkit</a> +<li><a href="#6">6. Object Classes</a> + <ul> + <li><a href="#6.1">6.1 Client</a> + <ul> + <li><a href="#6.1.1">6.1.1 Command Summary</a> + </ul> + <li><a href="#6.2">6.2 Server</a> + <ul> + <li><a href="#6.2.1">6.2.1 Command Summary</a> + </ul> + <li><a href="#6.3">6.3 Gterm</a> + <ul> + <li><a href="#6.3.1">6.3.1 Command Summary</a> + </ul> + <li><a href="#6.4">6.4 HTML</a> + <ul> + <li><a href="#6.4.1">6.4.1 Command Summary</a> + </ul> + <li><a href="#6.5">6.5 Markers</a> + <ul> + <li><a href="#6.5.1">6.5.1 Command Summary</a> + </ul> + <li><a href="#6.6">6.6 Widget</a> + <ul> + <li><a href="#6.6.1">6.6.1 Command Summary</a> + </ul> + <li><a href="#6.7">6.7 Parameter</a> + <ul> + <li><a href="#6.7.1">6.7.1 Command Summary</a> + </ul> + </ul> +</ul> + +<hr noshade=5> + +<a name="1"></a> +<h3>1. Introduction</h3> +<p> +An Object Manager (OBM) user interface (UI) consists of one or more windows +containing an arbitrary hierarchy of widgets. These widgets and their +runtime actions are defined by an interpreted text program uploaded +by the client application, which does not itself deal directly with the +window user interface. This interpreted program is currently written +as a Tcl script. +<p> +The OBM provides a high level abstraction for dealing with widgets and +other UI objects. The main function of the object manager is to deliver +messages to UI objects. Each instance of a widget is an object in the +interface. The UI contains other types of objects as well, including the +client object (client application), the server object (the object manager +itself), and the application specific UI parameters, each of which is an +object with a callback list of procedures to be called when the parameter +value changes. All of these UI objects can receive messages and take actions +as a result. Messages may come from the client application, or as a result +of actions executed by the interpreted UI code in response to graphics events. +<hr noshade=5> +<p> +<a name="2"></a> +<h3>2. System Architecture</h3> +<p> +For a complete description of the OBM system architecture see Tody, D, +ADASS Proceedings 1994. A <a href="todyd.ps">postscript version of this +paper</a> is also vailable. +<p> +<hr noshade=5> +<p> +<a name="3"></a> +<h3>3. The Client Process</h3> +<p> + The primary advantage of the OBM architecture over traditional GUI +design is the separation of the user interface from the executable client +code, meaning that either can be completely rewritten or developed separately +without affecting the other so long as the messaging between the two +remains the same. The client itself is responsible for initializing the OBM +toolkit and uploading the UI definition file, after that it usually enters +an event loop of some kind (e.g. an iraf graphics cursor loop, or X event +handler) to process actions defined in the client callbacks. +<p> + It's important that the client program maintain the state of the +application rather than the UI file. For example, a text widget in the +interface may instruct the client to load a file, however if this cannot +be done the interface should not have independently reset labels or +whatever assuming the action was done at all. Instead, the client program +uses the Parameter Class objects in the interface to update the state of +the GUI as a result of some action (whose origins may not have been in the +GUI at all). So for example a sequence of events could be something like + +<ul><ul> +<li> User selects a widget in the interface, it's callback sends a + message to the client directing some action be taken +<li> Client receives the message and performs an action in the client +<li> If action fails, (optionally) notify GUI of failure (e.g. send a + message to an 'alert' parameter to popup a dialog box, beep the + terminal, etc) +<li> If action succeeds, notify GUI of new state (e.g. send a message + to the 'filename' Parameter object containing the new file name). +<li> Callback on the 'filename' parameter then updates the status bar + widget with the name of the new active file. +</ul></ul> + +<p> + The messaging between the client and UI depend on the details of how +the client is implemented. In general any callback procedure in the UI can +send a message to any other object in the interface, but the client should +generally communicate only via the Parameter objects to avoid side effects +and maintain a clear separation between the UI and the client code. + +<a name="3.1"></a> +<h3>3.1 IRAF Graphics Task</h3> + +<a name="3.1.1"></a> +<h3>3.1.1 XGterm</h3> + +<a name="3.2"></a> +<h3>3.2 Standalone Task</h3> + +<a name="3.3"></a> +<h3>3.3 OBM Shell</h3> +<p> + The <i>obmsh</i> is a unix shell interpreter for GUI scripts. It is +a minimal standalone client with a single callback to exit the application, +otherwise it's only job is to activate the GUI file. Any messages sent to +the client (except a 'quit') are simply absorbed by the client +<p> + Despite the apparent lack of functionality this is sometimes all +that is required for an interface that can operate independently. Remember +that the Tcl scripting language has it's own facilities for file I/O, +process execution, etc, all of which are still available in the GUI. In +the case of IRAF tasks it's an interface violation to use these facilities +directly, however they still allow for the easy creation of a GUI which +requires no real underlying client (e.g. a tcl debug shell, a calculator +application, task launcher, etc). + +<a name="3.4"></a> +<h3>3.4 Named External Clients</h3> + +<p> +<p> +<hr noshade=5> +<p> +<a name="4"></a> +<h3>4. UI Definition File</h3> +<p> +A UI definition consists of a sequence of commands to be executed by the +server object using Tcl is used as an embedded interpreter within the OBM. +The Tcl script contains several required OBM-specific functions (in +addition to the user-defined callbacks) which is uploaded by the client +as a message for the server object. +<pre> + <a href="#resetReset">reset-server</a> + <a href="#appInitialize">appInitialize</a> appName appClass Resources + <a href="#createObjects">createObjects</a> [name] + <a href="#activate">activate</a> +</pre> +<p> +All UI files must begin with a <b>reset-server</b> command to initialize +the OBM. An <b>appInitialize</b> call is then made to define all of the +widgets and resources used in the interface, initializing the interface +used by the application. The <b>createObjects</b> function then actually +creates the widgets in the server, more specifically it creates the widgets +defined by the named <i>objects</i> resource. Lastly, the <b>activate</b> +call is used to activate the interface, i.e. put it on the screen. + +<p> +<a name="4.1"></a> +<h3>4.1 Example</h3> +A complete "hello, world" GUI definition might look something like: +<pre> + 1) <b>reset-server</b> + 2) <b>appInitialize</b> <i>hello Hello</i> { + 3) *objects:\ + 4) toplevel Form helloForm\ + 5) helloForm Label helloLabel\ + 6) helloForm Command quitButton + 7) + 8) *background: gray + 9) *helloLabel.label: Hello, world! + 10) *quitButton.fromHoriz: helloLabel + 11) *quitButton.label: Quit + 12) } + 13) + 14) <b>createObjects</b> + 15) <b>activate</b> + 16) + 17) <b>proc</b> Quit <b>args</b> { + 18) <b>send client gkey</b> q + 19) <b>deactivate unmap</b> + 20) } ; <b>send</b> quitButton <b>addCallback</b> Quit +</pre> + +where a line-by-line analysis of the GUI shows: + +<dl> +<dt>Line 1: <dd>- The <b>reset-server</b> command must be the first line in +the UI file since it's primary purpose is to initialize the OBM (i.e. a +call to the <i>ObmInitialize()</i> procedure). Subsequent calls (in the +same UI file or a different UI) are effectively a no-op. +<dt>Lines 2-12: <dd>- The <b>appInitialize</b> command defines the widgets +and resources to be used in the interface. The first argument gives the +name of the application, the second argument is the application class name +for purposes of specifying resources in the environment, and the last +argument is a Tcl list (hence the braces) of resources for the application. +<p> +The primary purpose of the call is to initialize the X11 part of the system +by defining the application context and the list of fallback resources. The +<i>objects</i> resource is a required element listing the widget hierarchy +to be used. Remaining resources are used to specify labels, colors, layout, +etc and serve as an app-defaults file for the GUI, interacting with the +normal resource database in the usual way. For example, a user's .Xdefaults +file may specify a "<b>font</b>" resource, unless this is overridden in +some way in the UI file this is the font that will be used. Resources may +be specified with either "loose" (i.e. the '*') or "tight" (i.e. the '.') +bindings with as much detail as is needed. +<dt>Line 14: <dd>- The <b>createObjects</b> command is what actually calls +each widget's Initialize() method to create the widget in the application +and in the X11 server. +<p> +With no argument, the default value used is simply +the <b>objects</b> resource. However, it's possible to specify a named +argument and make repeated calls to <b>createObjects</b> to build any number +widget trees prior to activating the interface. This can be useful for +example to specify a "main_objects" resource contains all the widgets for +the main panel, and a "help_objects" specfiying widgets used for the UI +help panel, which makes the definition file easier to organize. In the +past however UI files were written with a single long list (easily many +hundreds of lines) of objects followed by an even longer list of their +resources under a single <b>appInitialize</b> call, creating a monolithic +and unmanageably GUI definition file. Later on we'll see how complex GUIs +can be divided into separate pieces making it easier to reuse code and +manage the interface more efficiently. +<dt>Line 15: <dd>- The <b>activate</b> command is what creates the interface +on the screen, i.e. it calls the Realize() method for each widget to +instantiate it in the server and draw the window. +<dt>Lines 17-19: <dd>- Lastly we have the user-defined callback procedures. +On line 17 we define a procedure <i>Quit</i> which we use to shut down the +interface and client application. The body of the procedure first sends the +client object the graphics keystroke 'q' to shut down the client, then calls +the <b>deactivate</b> command to close the interface. On the last line +we send a message to the <i>quitButton</i> widget telling it to add this +procedure to it's callback list, so when the Button is selected this +procedure will be called as a result. +</dl> +<p> +<hr noshade=6> + +<a name="5"></a> +<h3>5. Widget Toolkit</h3> +<p> +<p> +<hr noshade=6> + +<a name="6"></a> +<h3>5. Object Classes</h3> +<p> +The following OBM object classes are currently defined: +<pre> + <a href="#6.1">Client</a> The Client application + <a href="#6.2">Server</a> The OBM itself + <a href="#6.3">Gterm</a> Gterm graphics/imaging widget class + <a href="#6.4">HTML</a> HTML widget class + <a href="#6.5">Markers</a> Gterm markers class + <a href="#6.6">Widget</a> General widget class + <a href="#6.7">Parameter</a> UI Parameter class +<p> + Various Xt and Athena widgets + <i>{box, shell, label, command, text, list, etc.}</i> + Misc Other X11 Widgets + <i>{Layout, Tabs, ListTree, etc}</i> +</pre> +<p> +OBM client applications will upload a UI during initialization to define a +custom graphics user interface. This is done by sending a message to the +object manager. Non-GUI applications assume a simple graphics +terminal and do not upload a UI; instead, a default UI is created +for the application consisting of a single top level shell containing a +Gterm (Tek 4012 graphics/imaging) widget. +<p> + +<hr noshade=5> + +<a name="5.1"></a> +<h3>5.1 Client</h3> +<p> +The client is the client application, which provides the functionality +underlying the UI. When a message is sent to the client object it usually +results in a message being sent to the client *application*, usually an +external program communicating via IPC, which has little or no knowledge +of the UI. The client application receives and executes commands delivered +by the UI via the client object. Output from the client may or may not +come back to the object manager. That portion of the output which comes +back to the object manager is in the form of assignments of string values +to <a href="#5.7.html">UI Parameter class objects</a> (another way of thinking +of this is that messages or events are sent to and acted upon by the parameter +objects). Hence, the client object is output only so far as the client +application is concerned. +<p> +The Client-class commands are used to send a message to the client. +<p> +<pre> + <a href="#gkey">gkey</a> <key> + <a href="#gcmd">gcmd</a> <command-string> + <a href="#literal">literal</a> <command> +</pre> +<p> +or just <command>, e.g., "send client <command>" will work in most cases. +<p> +<a href="#gkey">GKEY</a> sends an IRAF graphics keystroke. +<a href="#gcmd">GCMD</a> sends an +IRAF graphics colon command. <a href="#literal">LITERAL</a> sends a literal +command string to the +client. The keyword "literal" may optionally be omitted, i.e., "send client +foo" and "send client literal foo" are the same. The keyword "literal" may +be used to ensure that the client command string which follows will not +be interpreted as a Client-class command (such as gkey, gcmd, or literal). +<p> +<a name="5.1.1"></a> +<h2>5.1.1 Command Summary</h2> +<p> +<h3><A NAME="gcmd">gcmd</A></h3> +<p> +Send a graphics command string to the client application. +A graphics command string is a graphics cursor value with the key set +to `:' and the command string given as the string part of the cursor +value. The protocol module which posted the client output procedure is +responsible for encoding and sending the cursor command. +<p> +Usage: +<p> +<pre> + gcmd <command-string> +</pre> +<p> +<h3><A NAME="gkey">gkey</A></h3> +<p> +Send a graphics key event to the client application. +A graphics key event is a graphics cursor value with the key set to some +integer value and a null string part. +<p> +Usage: +<p> +<pre> +gkey <key> +</pre> +<p> +<h3><A NAME="literal">literal</A></h3> +<p> +Send a literal command to the client application. +<p> +Usage: +<p> +<pre> + literal <command> +</pre> + +<hr noshade=5> + +<a name="6.2"></a> +<h3>6.2 Server</h3> +<p> +The server, or object manager, is the control center of the user interface. +The server object provides a Tcl interpreter calling custom object manager +commands. These are used to define and initialize the user interface, and +execute UI action procedures at runtime. +<p> +<pre> + <a href="#resetReset">reset-server</a> + <a href="#appInitialize">appInitialize</a> appname,appclass,resources + <a href="#createObjects">createObjects</a> [resource-name] + <a href="#destroyObject">destroyObject</a> object + <a href="#activate">activate</a> + <a href="#deactivate">deactivate</a> [unmap] +<p> + value = <a href="#getResource">getResource</a> resource-name [default-value [class]]</a> + <a href="#getResources">getResources</a> resource-list +<p> + <a href="#createMenu">createMenu</a> menu-name parent item-list + <a href="#createMenu">editMenu</a> menu-name parent item-list + <a href="#destroyMenu">destroyMenu</a> menu-name +<p> + <a href="#createBitmap">createBitmap</a> name width height data + <a href="#createCursor">createCursor</a> name source mask fg_color bg_color x_hot y_hot + <a href="#createPixmap">createPixmap</a> name width height depth fg_color bg_color data +<p> + <a href="#print">print</a> arg [arg ...] # debug messages + <a href="#send">send</a> object message +<p> + <a href="#postActivateCallback">postActivateCallback</a> procedure +id = <a href="#postTimedCallback">postTimedCallback</a> procedure msec [client-data] + <a href="#deleteTimedCallback">deleteTimedCallback</a> id + id = <a href="#postWorkCallback">postWorkCallback</a> procedure [client-data] + <a href="#deleteWorkCallback">deleteWorkCallback</a> id +</pre> + +<a name="6.2.1"></a> +<h2>6.2.1 Command Summary</h2> +<p> +<h3><A NAME="serverReset">serverReset</A></h3> +<p> +The "reset-server" command is implemented as a special case in ServerEvaluate. +After doing a true reset ServerEvaluate calls Tcl_Eval to evaluate the full +message which still contains the reset-server command. We want to ignore +this the second time, so we treat the command here as a no-op. +<p> +Usage: +<p> +<pre> + reset-server +</pre> +<p> +Note: for reset-server to be recognized by ServerEvaluate and really reset +things, it must be the first command in a message to the server. +<p> +<h3><A NAME="appInitialize>appInitialize</A></h3> +<p> +TCL command to initialize the server for a new application, setting the +application name and loading the application resources. +<p> +Usage: +<p> +<pre> + appInitialize appname, appclass, resources +</pre> +<p> +<h3><A NAME ="createObjects">createObjects</A></h3> +<p> +TCL command to create the tree of UI objects comprising the user interface. +The object tree is defined by a string valued resource. If no resource is +named the default "objects" resource will be used. +<p> +Usage: +<p> +<pre> + createObjects [resource-name] +</pre> +<h3><A NAME="destroyObject">destroyObject</A></h3> +<p> +Destroy an object and all of its children. +<p> +Usage: +<pre> + destroyObject object-name +</pre> +<p> +<h3><A NAME="activate">activate</A></h3> +Activate the user interface. When called the first time the user interface +is created and activated, thereafter the UI is merely reactivated (e.g. +mapped if unmapped). +<p> +Usage: +<p> +<pre> + activate +</pre> +<p> +<h3><A NAME="deactivate">deactivate</A></h3> +<p> +Deactivate the user interface. Optionally unmaps the UI and calls the Obm +client back to let it know that the UI has been deactivated. +<p> +Usage: +<p> +<pre> + deactivate [unmap] +</pre> +<p> +<h3><A NAME="getResource">getResource</A></h3> +<p> +Get the string value of the specified application resource (window +system parameter). This allows use of the resource mechanism to supply +default values for GUI parameters. +<p> +Usage: +<p> +<pre> + value = getResource resource-name [class [default-value]] +</pre> +<p> +In the simplest case one merely requests a resource by name and the +string value is returned as the function value. If the resource has +an entry in the fallback resources for the application (appInitialize +resource list) then a value is guaranteed to be returned. +<p> +If the Class name for the resource is given then a class default value +will be returned if no entry is found for the name resource instance. This +is useful when there are a number of resources of the same type (same class). +If most or all resources in the same class have the same default value one +need only make one entry for the Class in the application defaults resource +list. It is up to the application developer to define the class name of a +resource - the class name can be any string. Examples are "Font", "Cursor", +etc. By convention the first character of a class name is capitalized, while +instance names begin with a lower case letter. +<p> +If there is an entry for the named resource in the resource list passed to +appInitialize then a value string is guaranteed to be returned. This will be +either the appInitialize default, or a value specified by the system or the +user in an X resources file. If one is not certain a default value is defined +somewhere, a default value should be specified in the getResource call as +shown above. +<p> +See also getResources, used to get multiple resources in one call. +<p> +<h3><A NAME="getResources">getResources</A></h3> +<p> +Get the string values of a list of resources. +<p> +Usage: +<p> +<pre> + getResources resource-list +</pre> +<p> +e.g. +<pre> + getResources { + { resource [variable class [default-value]]] } + { resource [variable class [default-value]]] } + (etc.) + } +</pre> +<p> +<h3><A NAME="createMenu">createMenu, editMenu</A></h3> +<p> +Create or modify a menu. The editMenu function is an alias for createMenu. +<p> +Usage: +<pre> + createMenu menu-name parent item-list +</pre> +<p> +e.g., +<pre> + createMenu menu-name parent { + { label function data [options...] } + { label function data [options...] } + (etc.) + } +</pre> +<p> +where +<p> +<pre> + menu-name is the object name for the menu popup shell + parent is the parent widget of the menu shell + label is a menu item label + function is the function to be performed when the menu + item is selected, e.g., f.exec, f.data, f.space, or f.line. + data is function dependent data + options are option-name option-value pairs, as specified + below. +</pre> +<p> +In the item list the fields label and option-value may be any Tcl expression. +Expressions are evaluated in the server context. The data field is a Tcl +script to be executed when the menu item is selected. +<p> +Options are specified as "option option-value". The menu item options are +as follows. +<p> +<pre> + bitmap A bitmap to be displayed left justified in the label field + (e.g. to indicate a parameter setting). + sensitive Specifies whether the menu item is active (sensitive=true) + or inactive (sensitive=false, item grayed out). + accelerator Specifies an input translation (accelerator, e.g., + keyboard event) which can be used to execute the + menu item. +</pre> +<p> +The option-value field may be any Tcl expression. +<p> +Example: +<p> +<pre> + createMenu fileMenu toplevel { + { "File Menu" f.title} + { Open f.exec openFile} + { Save f.exec saveFile} + { Load f.menu loadMenu} + { no-label f.line } + { Quit f.exec "send client Quit" } + } +</pre> +<p> +The first createMenu is called for a given menu the menu is created, added +to the menu list, and all window system widgets are created for the menu. +Subsequent calls will result in only the changed parts of the menu being +altered provided the changes are not great. Hence this routine can be called +to efficiently modify a menu when minor runtime changes occur, e.g., an +item label or action changes, the item value changes state, and so on, +without need for the GUI code to know how to make the necessary detailed +changes to the widgets used to implement the menu. +<p> +<h3><A NAME="destroyMenu">destroyMenu</A></h3> +<p> +Destroy a menu. This can be used to free up the resources used by a +menu, e.g., if the menu is not expected to be needed again for a while. +<p> +Usage: +<p> +<pre> + destroyMenu menu-name +</pre> +<p> +<h3><A NAME="createBitmap">createBitmap</A></h3> +<p> +Create a named bitmap. This replaces any old bitmap of the same name. The +new bitmap is cached in server memory; when a widget bitmap resource is set, +the bitmap cache will be searched for the named bitmap before asking Xlib +to find the bitmap. +<p> +Usage: +<p> +<pre> + createBitmap name width height data +</pre> +<p> +e.g., +<p> +<pre> + createBitmap foo 16 16 { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +<p> +<h3><A NAME="createCursor">createCursor</A></h3> +<p> +Create a cursor from bitmap data. The cursor is entered into the server's +cursor cache and will override any existing entry of the same name. +<p> +Usage: +<p> +<pre> + createCursor name source mask fg_color bg_color x_hot y_hot +</pre> +<p> +e.g., +<p> +<pre> + createCursor foo bitmap1 bitmap2 black white 8 8 +</pre> +<p> +The named bitmaps must be created first with createBitmap. +<p> +<h3><A NAME="createPixmap">createPixmap</A></h3> +<p> +Create a named pixmap. This replaces any old pixmap of the same name. The +new pixmap is cached in server memory; when a widget pixmap resource is set, +the pixmap cache will be searched for the named pixmap before asking Xlib +to find the pixmap. +<p> +Usage: +<p> +<pre> + createPixmap name width height depth fg_color bg_color data +</pre> +<p> +e.g., +<p> +<pre> + createPixmap foo 16 16 8 black white { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +</pre> +<p> +<h3><A NAME="print">print</A></h3> +<p> +Print a string on the standard output. This is used mainly for debugging +user interfaces. +<p> +Usage: +<p> +<pre> + print arg [arg ...] +</pre> +<p> +<h3><A NAME="send">send</A></h3> +<p> +Send a message to an object. The object interprets the message and returns +a function value as the string result of the TCL command. +<p> +Usage +<p> +<pre> + send <object> <message> +</pre> +<p> +<h3><A NAME="postActivateCallback">postActivateCallback</A></h3> +<p> +Post a callback procedure to be called when the UI is activated. The UI is +activated when it is first downloaded to server, but it may also be +activated (reactivated) after the application has exited and is later +restarted, or when the UI is deactivated and reactivated. Note +that the UI state vis-a-vis the external world (client application) may +no longer be accurate after it has been idle for a time and then reactivated. +<p> +Usage: +<p> +<pre> + postActivateCallback <procedure> +</pre> +<p> +<p> +<h3><A NAME="postTimedCallback">postTimedCallback</A></h3> +<p> +Post a callback to call the named procedure back after a specified delay +in milliseconds. +<p> +Usage: +<p> +<pre> + id = postTimedCallback procedure msec [client-data] +</pre> +<p> +After the specified delay the user callback procedure will be called with +client_data (if given) as the single argument. Only one call will be made; +the client must repost the callback in each call if the procedure is to be +repeatedly executed. +<p> +An ID value is returned which may be passed to deleteTimedCallback to delete +the timer. +<p> +<h3><A NAME="deleteTimedCallback">deleteTimedCallback</A></h3> +<p> +Delete a timer callback procedure. This procedure is typically used to +break a timer loop, where the timer procedure repeatedly reposts itself at +the end of each interval. +<p> +Usage: +<p> +<pre> + deleteTimedCallback id +</pre> +<p> +The ID string is returned by postTimedCallback when a timer is posted. +<p> +<h3><A NAME="postWorkCallback">postWorkCallback</A></h3> +<p> +Post a callback for a procedure to be called when the server is idle. +Work procedures are used to perform computations in the background while +the user interface remains active and able to respond to input events. +This works only if the user work procedure does its job in small increments, +doing only a small amount of processing in each call. The work procedure +will be called repeatedly until it returns a status indicating that it has +finished its task. +<p> +Usage: +<p> +<pre> + id = postWorkCallback procedure [client-data] +</pre> +<p> +When the server has nothing else to do the user work procedure will be +called with client_data (if given) as the single argument. The work procedure +should return the string "done" when all processing is finished, or any other +string if the procedure is to be called again. +<p> +An ID value is returned which may be passed to deleteWorkCallback to delete +the work procedure. +<p> +<h3><A NAME="deleteWorkCallback">deleteWorkCallback</A></h3> +<p> +Delete a work callback procedure. +<p> +Usage: +<p> +<pre> + deleteWorkCallback id +</pre> +<p> +The ID string is returned by postWorkCallback when a work procedure is posted. + +<hr noshade=5> + +<a name="6.3"></a> +<h3>6.3 Gterm</h3> +<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 + <a href="notyet.html">getLogRes</a> width height + <a href="notyet.html">setPhysRes</a> width height + <a href="notyet.html">getPhysRes</a> width height + <a href="notyet.html">setTextRes</a> rows cols + <a href="notyet.html">setDataLevel</a> level + <a href="notyet.html">setLineWidth</a> width + <a href="notyet.html">setLineStyle</a> style + <a href="notyet.html">setColorIndex</a> index + <a href="notyet.html">setFillType</a> filltype +<p> + <a href="#clearScreen">clearScreen</a> + <a href="notyet.html">drawPolyline</a> vector + <a href="notyet.html">drawPolymarker</a> vector + <a href="notyet.html">drawPolygon</a> vector + <a href="notyet.html">drawMarker</a> x y xsize ysize type +<p> + <a href="notyet.html">drawAlphaText</a> x y text + <a href="notyet.html">getAlphaTextSize</a> string width height base + <a href="notyet.html">startDialog</a> + <a href="notyet.html">endDialog</a> + <a href="notyet.html">eraseDialog</a> + <a href="notyet.html">drawDialogText</a> x y text + <a href="notyet.html">getDialogTextSize</a> string width height base +</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 + <a href="notyet.html">createRaster</a> raster type width height depth + <a href="notyet.html">destroyRaster</a> raster + exists = <a href="notyet.html">queryRaster</a> raster type width height depth + raster = <a href="notyet.html">nextRaster</a> [raster] + nrasters = <a href="notyet.html">nRasters</a> [nrasters] +<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 + pixmap = <a href="notyet.html">createPixmap</a> src x y width height + <a href="notyet.html">copyPixmap</a> pixmap dst x y width height +<p> + colormap = <a href="notyet.html">nextColormap</a> [colormap] + <a href="notyet.html">freeColormap</a> colormap + <a href="notyet.html">writeColormap</a> colormap first nelem colors + <a href="notyet.html">readColormap</a> colormap first nelem colors + <a href="#loadColormap">loadColormap</a> colormap offset scale +<p> + <a href="notyet.html">initMappings</a> + mapping = <a href="#nextMapping">nextMapping</a> [mapping] + <a href="notyet.html">freeMapping</a> mapping + <a href="notyet.html">enableMapping</a> mapping + <a href="notyet.html">disableMapping</a> mapping + active = <a href="notyet.html">activeMapping</a> mapping + <a href="notyet.html">refreshMapping</a> mapping +<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 + <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> +<a name="6.3.1"></a> +<h2>6.3.1 GTERM class commands</h2> +<p> +<h3><A NAME="setGterm">setGterm</A></h3> +<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> +<h3><A NAME="activate">activate</A></h3> +<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> +<h3><A NAME="deactivate">deactivate</A></h3> +<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> +<h3><A NAME="reset">reset</A></h3> +<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> +<h3><A NAME="flush">flush</A></h3> +<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> +<h3><A NAME="addCallback">addCallback</A></h3> +<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> +<h3><A NAME="setCursorPos">setCursorPos</A></h3> +<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> +<h3><A NAME="getCursorPos">getCursorPos</A></h3> +<p> +Get the cursor position (raster 0 or screen coordinates). +<p> +Usage: +<p> +<pre> + getCursorPos x y +</pre> +<p> +<h3><A NAME="setCursorType">setCursorType</A></h3> +<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> +<h3><A NAME="bell">bell</A></h3> +<p> +Gterm widget sound output. +<p> +Usage: +<p> +<pre> + bell +</pre> +<p> +<h3><A NAME="setRaster">setRaster</A></h3> +<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> +<h3><A NAME="getRaster">getRaster</A></h3> +<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> +<h3><A NAME="clearScreen">clearScreen</A></h3> +<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> +<h3><A NAME="rasterInit">rasterInit</A></h3> +<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> +<h3><A NAME="writePixels">writePixels</A></h3> +<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> +<h3><A NAME="setPixel">setPixel</A></h3> +<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> +<h3><A NAME="readPixels">readPixels</A></h3> +<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> +<h3><A NAME="getPixel">getPixel</A></h3> +<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> +<h3><A NAME="nextMapping">nextMapping</A></h3> +<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> +<h3><A NAME="getMapping">getMapping</A></h3> +<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> +<h3><A NAME="setMapping">setMapping</A></h3> +<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> +<h3><A NAME="loadColormap">loadColormap</A></h3> +<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> +<h3><A NAME="selectRaster">selectRaster</A></h3> +<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> +<h3><A NAME="unmapPixel">unmapPixel</A></h3> +<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> +<h3><A NAME="flip">flip</A></h3> +<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> +<h3><A NAME="markerInit">markerInit</A></h3> +<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> +<h3><A NAME="createMarker">createMarker</A></h3> +<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 <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. +<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. + +<hr noshade=5> + +<a name="6.4"></a> +<h3>6.4 HTML</h3> + +The HTML (hypertext markup language) widget displays a block of HTML +formatted text, the "document" to be displayed. The text consists of a +mixture of text to be displayed and embedded formatting directives. The +text may also contain "hot links" pointing to other HTML-formatted +documents. + +<pre> + setText text [target [header_text [footer_text]]] + text = getText [format [font]] + retestAnchors + + id = positionToId x y + idToPosition id x y + anchorToPosition name x y + id = anchorToId name + gotoId id + + n = getHRefs list + n = getImageSrcs list + n = getLinks list + + setSelection start end + text = getSelection start end + clearSelection + + searchText pattern start end [direction [search_type]] + + addCallback procedure-name [callback-type] + deleteCallback procedure-name [callback-type] +</pre> + +The possible callback types and their callback arguments are as follows. + +<pre> + anchor widget cbtype event text href element_id + testAnchor widget cbtype href + submitForm widget cbtype event attrs href method enctype encentity + link widget cbtype href role + pointerMotion widget cbtype href +</pre> + +See the comments below for further details on the callback types and their +arguments. + +<p> +<a name="6.4.1"></a> +<h2>6.4.1 Command Summary</h2> +<p> + +<hr noshade=5> + +<a name="6.5"></a> +<h3>6.5 Markers</h3> +<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="#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 <ObmW/Gterm.h> 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 <Btn1Motion> 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() +</pre> +<p> +<a name="6.5.1"></a> +<h2>6.5.1 Command Summary</h2> +<p> +<h3>makeCopy</A></h3> +<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> +<h3><A NAME="addCallback">addCallback</A></h3> +<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> +<h3><A NAME="notify">notify</A></h3> +<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> +<h3><A NAME="destroy">destroy</A></h3> +<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> +<h3><A NAME="markpos">markpos</A></h3> +<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> +<h3><A NAME="redraw">redraw</A></h3> +<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> +<h3><A NAME="raise">raise</A></h3> +<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> +<h3><A NAME="lower">lower</A></h3> +<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> +<h3><A NAME="move">move</A></h3> +<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> +<h3><A NAME="resize">resize</A></h3> +<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> +<h3><A NAME="rotate">rotate</A></h3> +<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> +<h3><A NAME="getAttribute">getAttribute</A></h3> +<p> +Return the value of a marker attribute. +<p> +Usage: +<p> +<pre> + value = getAttribute attribute-name +</pre> +<p> +<h3><A NAME="setAttribute">setAttribute</A></h3> +<p> +Set the value of a marker attribute. +<p> +Usage: +<p> +<pre> + setAttribute attribute-name value +</pre> +<p> +<h3><A NAME="getAttributes">getAttributes</A></h3> +<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> +<h3><A NAME="setAttributes">setAttributes</A></h3> +<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> +<h3><A NAME="getVertices">getVertices</A></h3> +<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> +<h3><A NAME="setVertices">setVertices</A></h3> +<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> +<h3><A NAME="getRegion">getRegion</A></h3> +<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> +<h3><A NAME="getRect">getRect</A></h3> +<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> + +<hr noshade=5> + +<a name="6.6"></a> +<h3>6.6 Widget</h3> +<p> +The Widget class is the generic or base class for the window system +toolkit widgets supported by the object manager. The Widget class +supports a number of different Xt widget classes using a table driven +approach to describe each widget. Any widget may be created, destroyed, +and manipulated in various ways using only the generic Widget class +procedures and Widget-specific resources. The Widget class may be +subclassed to support complex Widgets that require custom class-specific +commands for use by the GUI code. +<p> +Generic Widget-class commands: +<p> +<pre> + <a href="#set">set</a> <resource-name> <value> + <a href="#get">get</a> <resource-name> +<p> + <a href="#addCallback">addCallback</a> <procedure-name> [<callback-name>] + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#setSensitive">setSensitive</a> <sensitive> + <a href="#isSensitive">isSensitive</a> +<p> + <a href="#realize">realize</a> + <a href="#unrealize">unrealize</a> + <a href="#isRealized">isRealizeed</a> + <a href="#map">map</a> + <a href="#unmap">unmap</a> + <a href="#manage">manage</a> child [child ...] + <a href="#unmanage">unmanage</a> child [child ...] + <a href="#popup">popup</a> [grab-kind] + <a href="#popdown">popdown</a> + <a href="#popupSpringLoaded">popupSpringLoaded</a> +<p> + <a href="#move">move</a> <x> <y> + <a href="#resize">resize</a> <width> <height> <border-width> + <a href="#configure">configure</a> <x> <y> <width> <height> <border-width> +</pre> +<p> +The most important Widget commands are set/get resource, and the +callbacks. The widget sensitivity can be set and queried using set/get +resource, but special procedures are provided to make this common operation +more convenient. +<p> +Class specific functions: +<p> +<pre> + <a href="#append">append</a> text # text widget + <a href="#setList">setList</a> list [resize] # list widget + value = <a href="#getItem">getItem</a> itemno + <a href="#highlight">highlight</a> itemno + <a href="#unhighlight">unhighlight</a> +</pre> +<p> +Ideally the widget class should be subclassed for widgets that require +class-specific functions, but in simple cases involving standard widgets +the support is built into the widget class code as a special case. +<p> +Special actions (used in translations): +<p> +<pre> + <a href="#do_userproc">call</a> (proc [,arg, ...]) + <a href="#do_popup">popup</a> (menu-name [xoffset [yoffset]]) + <a href="#do_popdown">popdown</a> (menu-name) +</pre> +<p> +The "call" action is a very general mechanism which allows any GUI procedure +to be registered with any translation using the X translation table +mechanism. The popup and popdown actions are used for popup menus. The +menu will be popped up at the event coordinates plus the optional offsets +if given. +<p> +Event handling: +<p> +<pre> + <a href="#addEventHandler">addEventHandler</a> <procname> <event-mask> [<event-mask>...] +</pre> +<p> +Event callback: +<p> +<pre> + <a href="#userEventHandler">userEventHandler</a> widget event-type time wx wy rx ry other +</pre> +<p> +In most cases translations are preferable to events, but a GUI can capture +raw events if it wishes by adding event handlers. Nearly all of the X +event types are supported. The callback syntax employs a number of +standard arguments, followed by a number of event-specific arguments. +<p> +<h3><A NAME="addCallback">addCallback</A></h3> +<p> +Add a callback procedure to the callback list for +a widget. If no callback name is given, "callback" is assumed. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> [<callback-name>] +</pre> +<p> +Specific widgets only support certain types of callbacks. There is no +checking that the callback type specified is supported by a widget; the +wrong type of callback can be registered, but it will never be called. +<p> +<h3><A NAME="deleteCallback">deleteCallback</A></h3> +<p> +Delete a callback procedure previously registered +for a widget. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<p> +<h3><A NAME="do_userproc">do_userproc (call)</A></h3> +<p> +Translation action procedure used to call general user +action procedures in the interpreter. The name of the user procedure to +be called is given as the first argument in the translation. For example, +the translation "call(foo,a,b,c)" would cause procedure foo to be called +with the arguments (a,b,c). The following arguments are special: +<p> +<pre> + Argument Replaced by +<p> + $name object name of widget + $time event->time + $x event->x + $y event->y + $x_root event->x_root + $y_root event->y_root +</pre> +<p> +The "user procedure" can be any server procedure. +<p> +<h3><A NAME="do_popup">do_popup</A></h3> +<p> +Popup a menu (or other spring loaded popup) at the location +of the event which triggered this action. +<p> +Usage: +<p> +<pre> + popup(menu-name [xoffset [yoffset]]) +</pre> +<p> +<h3><A NAME="do_popdown">do_popdown</A></h3> +<p> +Pop down a menu. +<p> +Usage: +<p> +<pre> + popdown(menu-name) +</pre> +<p> +<h3><A NAME="set">set</A></h3> +<p> +Set a widget resource. +<p> +Usage: +<p> +<pre> + set <resource-name> <value> +</pre> +<p> +<h3><A NAME="get">get</A></h3> +<p> +Get a widget resource value as a string. +<p> +Usage: +<p> +<pre> + get <resource-name> +</pre> +<p> +<h3><A NAME="append">append</A></h3> +<p> +Append data to a text widget. +<p> +Usage: +<p> +<pre> + append <text> +</pre> +<p> +<h3><A NAME="setList">setList</A></h3> +<p> +Set the item list of a list widget. +<p> +Usage: +<p> +<pre> + setList list [resize] +</pre> +<p> +The list is a simple list of strings, passed as a single string argument to +setList (quotes, braces, etc. may be used to quote strings containing +special characters). +<p> +<h3><A NAME="getItem">getItem</A></h3> +<p> +Get an item in a list widget. +<p> +Usage: +<p> +<pre> + value = getItem itemno +</pre> +<p> +If ITEMNO is a number the indicated list item is returned, or the string +"EOF" if the requested item is beyond the end of the list. Otherwise the +currently selected item is returned, and the index of the item is returned +in the output variable ITEMNO. If no item is currently selected ITEMNO +will be set to "none" on output. +<p> +<h3><A NAME="highlight">highlight</A></h3> +<p> +Highlight an item in a list widget. +<p> +Usage: +<p> +<pre> + highlight itemno +</pre> +<p> +The indicated item of the list is highlighted as if the item had been +selected by the user. Any previously highlighted item is unhighlighted. +<p> +<h3><A NAME="unhighlight">unhighlight</A></h3> +<p> +Unhighlight the currently highlighted item in a +list widget. +<p> +Usage: +<p> +<pre> + unhighlight +</pre> +<p> +Any currently highlighted item in the list widget is unhighlighted. +<p> +<h3><A NAME="realize">realize</A></h3> +<p> +Realize a widget. This activates and assigns windows for +a widget and all of its descendants. Realizing a widget does not in itself +cause it to appear on the screen. +<p> +Usage: +<p> +<pre> + realize +</pre> +<p> +<h3><A NAME="unrealize">unrealize</A></h3> +<p> +Unrealize a widget. This destroys the windows assigned +to a widget and all of its descendants. +<p> +Usage: +<p> +<pre> + unrealize +</pre> +<p> +<h3><A NAME="isRealized">isRealized</A></h3> +<p> +Test whether a widget is realized. +<p> +Usage: +<p> +<pre> + isRealized +</pre> +<p> +<h3><A NAME="map">map</A></h3> +<p> +Map a widget. +<p> +Usage: +<p> +<pre> + map +</pre> +<p> +<h3><A NAME="unmap">unmap</A></h3> +<p> +Unmap a widget. +<p> +Usage: +<p> +<pre> + unmap +</pre> +<p> +<h3><A NAME="manage">manage</A></h3> +<p> +Manage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Managing the +children makes them appear in the window, possibly causing the other +children to be rearranged in the window. +<p> +Usage: +<p> +<pre> + manage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h3><A NAME="unmanage">unmanage</A></h3> +<p> +Unmanage a list of child widgets. These should share the +same common parent, a geometry widget of some sort. Unmanaging the +children makes them disappear from the window and be removed from geometry +management, possibly causing the other children to be rearranged in the +window. +<p> +Usage: +<p> +<pre> + unmanage child [child ...] +</pre> +<p> +This message should be sent to the geometry widget which is the parent +of the children. +<p> +<h3><A NAME="popup">popup</A></h3> +<p> +Popup a shell widget. If no grab is indicated the popup +can remain up while other windows accept input. +<p> +Usage: +<p> +<pre> + popup [grab-kind] +</pre> +<p> +<h3><A NAME="popdown">popdown</A></h3> +<p> +Popdown a shell widget. +<p> +Usage: +<p> +<pre> + popdown +</pre> +<p> +<h3><A NAME="popupSpringLoaded">popupSpringLoaded</A></h3> +<p> +Popup a shell widget, e.g., a popup menu. +This implies an exclusive grab. +<p> +Usage: +<p> +<pre> + popupSpringLoaded +</pre> +<p> +<h3><A NAME="move">move</A></h3> +<p> +Move a widget to the given window relative coordinates. +<p> +Usage: +<p> +<pre> + move <x> <y> +</pre> +<p> +<h3><A NAME="resize">resize</A></h3> +<p> +Resize a widget. +<p> +Usage: +<p> +<pre> + resize <width> <height> <border-width> +</pre> +<p> +<h3><A NAME="configure">configure</A></h3> +<p> +Configure a widget, i.e., execute a simultaneous +move and resize. +<p> +Usage: +<p> +<pre> + configure <x> <y> <width> <height> <border-width> +</pre> +<p> +<h3><A NAME="setSensitive">setSensitive</A></h3> +<p> +Set the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + setSensitive <sensitive> +</pre> +<p> +<h3><A NAME="isSensitive">isSensitive</A></h3> +<p> +Test the sensitivity of a widget. +<p> +Usage: +<p> +<pre> + isSensitive +</pre> +<p> +<h3><A NAME="addEventHandler">addEventHandler</A></h3> +<p> +Add a custom event handler to a widget. A list +of event masks is given to define the classes of events the user supplied +event handling procedure is to receive. +<p> +Usage: +<p> +<pre> + addEventHandler <procname> <event-mask> [<event-mask>...] +</pre> +<p> +<h3><A NAME="removeEventHandler">removeEventHandler</A></h3> +<p> +Remove an event handler previously posted +with addEventHandler, above. +<p> +Usage: +<p> +<pre> + removeEventHandler procname +</pre> +<p> +<h3><A NAME="event">event</A></h3> +<p> +Generic event handler called when a widget event handler +posted by addEventHandler is called. +<p> +The user event handler is called as +<p> +<pre> + userEventHandler widget event-type time wx wy rx ry other +</pre> +<p> +where "other" is an event-type specific list of fields describing the +the event. +<hr noshade=5> + +<a name="6.7"></a> +<h3>6.7 Parameter</h3> +<p> +The UI parameter class is used for client-UI communications. The client +does not control the user interface directly, rather the UI defines a set +of abstract UI parameters, and during execution the client application +assigns values to these parameters. These UI parameters should be thought +of as describing the runtime state of the client as viewed by the GUI. +The GUI is free to interpret this state information in any way, including +ignoring it. Many GUIs can be written which use the same client state +as described by the UI parameters. +<p> +Assigning a value to a UI parameter causes the new value to be stored, and +any parameter action procedures registered by the UI to be called. +The action or actions [if any] taken when a parameter value changes are +arbitrary, e.g. the action might be something as simple as changing a +displayed value of a UI widget, or something more complex like displaying +a popup. +<p> +<h2>UI Parameter class commands:</h2> +<p> +<pre> + <a href="#getValue">getValue</a> + <a href="#setValue">setValue</a> <new-value> + <a href="#addCallback">addCallback</a> <procedure-name> + <a href="#deleteCallback">deleteCallback</a> <procedure-name> + <a href="#notify">notify</a> +</pre> +<p> +The most common usage is for the GUI to post one or more callbacks for +each UI parameter. When the UI parameter value is changed [with setValue, +e.g. by the client] the GUI callback procedures are called with the old +and new UI parameter values on the command line. addCallback is used to +add a callback procedure, and deleteCallback to delete one. Multiple +callbacks may be registered for a single UI parameter. notify is used +to simulate a parameter value change, causing any callback procedures to +be invoked. +<p> +The callback procedure is called as follows: +<p> +<pre> + user-procedure param-name {old-value} {new-value} +</pre> +<p> +The important thing to note here is that the old and new value strings +are quoted with braces. This prevents any interpretation of the string +by Tcl when the callback is executed, which is necessary because the +strings can contain arbitrary data. When Tcl calls the callback the +first level of braces will be stripped off, leaving old-value and new-value +each as a single string argument. +<p> +<p> +<h2><A NAME="setValue">setValue</A></h2> +<p> +Set the value of a parameter, and notify all clients +via the posted callback procedures that the parameter value has changed. +<p> +Usage: +<p> +<pre> + setValue <new-value> +</pre> +<p> +<h2><A NAME="getValue">getValue</A></h2> +<p> +Get the value of a parameter. +<p> +Usage: +<p> +<pre> + getValue +</pre> +<p> +<h2><A NAME="notify">notify</A></h2> +<p> +Notify the registered clients of a parameter as if the +value had changed. +<p> +Usage: +<p> +<pre> + notify +</pre> +<p> +<h2><A NAME="addCallback">addCallback</A></h2> +<p> +Add a callback procedure to the callback list for +a parameter. +<p> +Usage: +<p> +<pre> + addCallback <procedure-name> +</pre> +<p> +<h2><A NAME="deleteCallback">deleteCallback</A></h2> +<p> +Delete a callback procedure previously registered +for a parameter. +<p> +Usage: +<p> +<pre> + deleteCallback <procedure-name> +</pre> +<hr noshade=5> + +<hr noshade=5> +</body> +</html> diff --git a/vendor/x11iraf/obm/docs/obm/servercom.html b/vendor/x11iraf/obm/docs/obm/servercom.html new file mode 100644 index 00000000..16c4c24e --- /dev/null +++ b/vendor/x11iraf/obm/docs/obm/servercom.html @@ -0,0 +1,375 @@ +<h1><A NAME="serverReset">serverReset</A></h1> +<p> +The "reset-server" command is implemented as a special case in ServerEvaluate. +After doing a true reset ServerEvaluate calls Tcl_Eval to evaluate the full +message which still contains the reset-server command. We want to ignore +this the second time, so we treat the command here as a no-op. +<p> +Usage: +<p> +<pre> + reset-server +</pre> +<p> +Note: for reset-server to be recognized by ServerEvaluate and really reset +things, it must be the first command in a message to the server. +<p> +<h1><A NAME="appInitialize>appInitialize</A></h1> +<p> +TCL command to initialize the server for a new application, setting the +application name and loading the application resources. +<p> +Usage: +<p> +<pre> + appInitialize appname, appclass, resources +</pre> +<p> +<h1><A NAME ="createObjects">createObjects</A></h1> +<p> +TCL command to create the tree of UI objects comprising the user interface. +The object tree is defined by a string valued resource. If no resource is +named the default "objects" resource will be used. +<p> +Usage: +<p> +<pre> + createObjects [resource-name] +</pre> +<h1><A NAME="destroyObject">destroyObject</A></h1> +<p> +Destroy an object and all of its children. +<p> +Usage: +<pre> + destroyObject object-name +</pre> +<p> +<h1><A NAME="activate">activate</A></h1> +Activate the user interface. When called the first time the user interface +is created and activated, thereafter the UI is merely reactivated (e.g. +mapped if unmapped). +<p> +Usage: +<p> +<pre> + activate +</pre> +<p> +<h1><A NAME="deactivate">deactivate</A></h1> +<p> +Deactivate the user interface. Optionally unmaps the UI and calls the Obm +client back to let it know that the UI has been deactivated. +<p> +Usage: +<p> +<pre> + deactivate [unmap] +</pre> +<p> +<h1><A NAME="getResource">getResource</A></h1> +<p> +Get the string value of the specified application resource (window +system parameter). This allows use of the resource mechanism to supply +default values for GUI parameters. +<p> +Usage: +<p> +<pre> + value = getResource resource-name [class [default-value]] +</pre> +<p> +In the simplest case one merely requests a resource by name and the +string value is returned as the function value. If the resource has +an entry in the fallback resources for the application (appInitialize +resource list) then a value is guaranteed to be returned. +<p> +If the Class name for the resource is given then a class default value +will be returned if no entry is found for the name resource instance. This +is useful when there are a number of resources of the same type (same class). +If most or all resources in the same class have the same default value one +need only make one entry for the Class in the application defaults resource +list. It is up to the application developer to define the class name of a +resource - the class name can be any string. Examples are "Font", "Cursor", +etc. By convention the first character of a class name is capitalized, while +instance names begin with a lower case letter. +<p> +If there is an entry for the named resource in the resource list passed to +appInitialize then a value string is guaranteed to be returned. This will be +either the appInitialize default, or a value specified by the system or the +user in an X resources file. If one is not certain a default value is defined +somewhere, a default value should be specified in the getResource call as +shown above. +<p> +See also getResources, used to get multiple resources in one call. +<p> +<h1><A NAME="getResources">getResources</A></h1> +<p> +Get the string values of a list of resources. +<p> +Usage: +<p> +<pre> + getResources resource-list +</pre> +<p> +e.g. +<pre> + getResources { + { resource [variable class [default-value]]] } + { resource [variable class [default-value]]] } + (etc.) + } +</pre> +<p> +<h1><A NAME="createMenu">createMenu, editMenu</A></h1> +<p> +Create or modify a menu. The editMenu function is an alias for createMenu. +<p> +Usage: +<pre> + createMenu menu-name parent item-list +</pre> +<p> +e.g., +<pre> + createMenu menu-name parent { + { label function data [options...] } + { label function data [options...] } + (etc.) + } +</pre> +<p> +where +<p> +<pre> + menu-name is the object name for the menu popup shell + parent is the parent widget of the menu shell + label is a menu item label + function is the function to be performed when the menu + item is selected, e.g., f.exec, f.data, f.space, or f.line. + data is function dependent data + options are option-name option-value pairs, as specified + below. +</pre> +<p> +In the item list the fields label and option-value may be any Tcl expression. +Expressions are evaluated in the server context. The data field is a Tcl +script to be executed when the menu item is selected. +<p> +Options are specified as "option option-value". The menu item options are +as follows. +<p> +<pre> + bitmap A bitmap to be displayed left justified in the label field + (e.g. to indicate a parameter setting). + sensitive Specifies whether the menu item is active (sensitive=true) + or inactive (sensitive=false, item grayed out). + accelerator Specifies an input translation (accelerator, e.g., + keyboard event) which can be used to execute the + menu item. +</pre> +<p> +The option-value field may be any Tcl expression. +<p> +Example: +<p> +<pre> + createMenu fileMenu toplevel { + { "File Menu" f.title} + { Open f.exec openFile} + { Save f.exec saveFile} + { Load f.menu loadMenu} + { no-label f.line } + { Quit f.exec "send client Quit" } + } +</pre> +<p> +The first createMenu is called for a given menu the menu is created, added +to the menu list, and all window system widgets are created for the menu. +Subsequent calls will result in only the changed parts of the menu being +altered provided the changes are not great. Hence this routine can be called +to efficiently modify a menu when minor runtime changes occur, e.g., an +item label or action changes, the item value changes state, and so on, +without need for the GUI code to know how to make the necessary detailed +changes to the widgets used to implement the menu. +<p> +<h1><A NAME="destroyMenu">destroyMenu</A></h1> +<p> +Destroy a menu. This can be used to free up the resources used by a +menu, e.g., if the menu is not expected to be needed again for a while. +<p> +Usage: +<p> +<pre> + destroyMenu menu-name +</pre> +<p> +<h1><A NAME="createBitmap">createBitmap</A></h1> +<p> +Create a named bitmap. This replaces any old bitmap of the same name. The +new bitmap is cached in server memory; when a widget bitmap resource is set, +the bitmap cache will be searched for the named bitmap before asking Xlib +to find the bitmap. +<p> +Usage: +<p> +<pre> + createBitmap name width height data +</pre> +<p> +e.g., +<p> +<pre> + createBitmap foo 16 16 { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +<p> +<h1><A NAME="createCursor">createCursor</A></h1> +<p> +Create a cursor from bitmap data. The cursor is entered into the server's +cursor cache and will override any existing entry of the same name. +<p> +Usage: +<p> +<pre> + createCursor name source mask fg_color bg_color x_hot y_hot +</pre> +<p> +e.g., +<p> +<pre> + createCursor foo bitmap1 bitmap2 black white 8 8 +</pre> +<p> +The named bitmaps must be created first with createBitmap. +<p> +<h1><A NAME="createPixmap">createPixmap</A></h1> +<p> +Create a named pixmap. This replaces any old pixmap of the same name. The +new pixmap is cached in server memory; when a widget pixmap resource is set, +the pixmap cache will be searched for the named pixmap before asking Xlib +to find the pixmap. +<p> +Usage: +<p> +<pre> + createPixmap name width height depth fg_color bg_color data +</pre> +<p> +e.g., +<p> +<pre> + createPixmap foo 16 16 8 black white { + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc0,0x01, + 0x60,0x03,0x20,0x02,0x60,0x03,0xc0,0x01,0x00,0x00,0x00,0x00, + 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 } +</pre> +<p> +<h1><A NAME="print">print</A></h1> +<p> +Print a string on the standard output. This is used mainly for debugging +user interfaces. +<p> +Usage: +<p> +<pre> + print arg [arg ...] +</pre> +<p> +<h1><A NAME="send">send</A></h1> +<p> +Send a message to an object. The object interprets the message and returns +a function value as the string result of the TCL command. +<p> +Usage +<p> +<pre> + send <object> <message> +</pre> +<p> +<h1><A NAME="postActivateCallback">postActivateCallback</A></h1> +<p> +Post a callback procedure to be called when the UI is activated. The UI is +activated when it is first downloaded to server, but it may also be +activated (reactivated) after the application has exited and is later +restarted, or when the UI is deactivated and reactivated. Note +that the UI state vis-a-vis the external world (client application) may +no longer be accurate after it has been idle for a time and then reactivated. +<p> +Usage: +<p> +<pre> + postActivateCallback <procedure> +</pre> +<p> +<p> +<h1><A NAME="postTimedCallback">postTimedCallback</A></h1> +<p> +Post a callback to call the named procedure back after a specified delay +in milliseconds. +<p> +Usage: +<p> +<pre> + id = postTimedCallback procedure msec [client-data] +</pre> +<p> +After the specified delay the user callback procedure will be called with +client_data (if given) as the single argument. Only one call will be made; +the client must repost the callback in each call if the procedure is to be +repeatedly executed. +<p> +An ID value is returned which may be passed to deleteTimedCallback to delete +the timer. +<p> +<h1><A NAME="deleteTimedCallback">deleteTimedCallback</A></h1> +<p> +Delete a timer callback procedure. This procedure is typically used to +break a timer loop, where the timer procedure repeatedly reposts itself at +the end of each interval. +<p> +Usage: +<p> +<pre> + deleteTimedCallback id +</pre> +<p> +The ID string is returned by postTimedCallback when a timer is posted. +<p> +<h1><A NAME="postWorkCallback">postWorkCallback</A></h1> +<p> +Post a callback for a procedure to be called when the server is idle. +Work procedures are used to perform computations in the background while +the user interface remains active and able to respond to input events. +This works only if the user work procedure does its job in small increments, +doing only a small amount of processing in each call. The work procedure +will be called repeatedly until it returns a status indicating that it has +finished its task. +<p> +Usage: +<p> +<pre> + id = postWorkCallback procedure [client-data] +</pre> +<p> +When the server has nothing else to do the user work procedure will be +called with client_data (if given) as the single argument. The work procedure +should return the string "done" when all processing is finished, or any other +string if the procedure is to be called again. +<p> +An ID value is returned which may be passed to deleteWorkCallback to delete +the work procedure. +<p> +<h1><A NAME="deleteWorkCallback">deleteWorkCallback</A></h1> +<p> +Delete a work callback procedure. +<p> +Usage: +<p> +<pre> + deleteWorkCallback id +</pre> +<p> +The ID string is returned by postWorkCallback when a work procedure is posted. diff --git a/vendor/x11iraf/obm/docs/tody.paper/todyd.html b/vendor/x11iraf/obm/docs/tody.paper/todyd.html new file mode 100644 index 00000000..53705df4 --- /dev/null +++ b/vendor/x11iraf/obm/docs/tody.paper/todyd.html @@ -0,0 +1,522 @@ +<HEAD> +<TITLE> A Portable GUI Development System---The IRAF Widget Server </TITLE> +</HEAD> +<BODY><P> +<h5><hr> Astronomical Data Analysis Software and Systems IV<br>ASP Conference Series, Vol. 77, 1995<br>Book Editors: R. A. Shaw, H. E. Payne, and J. J. E. Hayes<br>Electronic Editor: H. E. Payne <hr> </h5> +<H1><A NAME=SECTION021900000000000000000> A Portable GUI Development System---The IRAF Widget Server</A></H1> +<P> +<P><b>D. Tody</b><br> +National Optical Astronomy Observatories, P.O. Box 26732, +Tucson, AZ 85726<br> +<P> +The National Optical Astronomy Observatories are +operated by the Association of Universities for Research in Astronomy, Inc. +(AURA) under cooperative agreement with the National Science Foundation. +<P> +<P> +<A NAME=1229> </A> +<A NAME=1230> </A> +<A NAME=1231> </A><A NAME=1232> </A> +<A NAME=1233> </A> +<A NAME=1234> </A><A NAME=1235> </A><A NAME=1236> </A><A NAME=1237> </A> +<A NAME=1238> </A> +<A NAME=1239> </A> +<A NAME=todyd> </A><H3>Abstract:</H3> +<EM>We describe a new GUI (Graphics User Interface) development environment +which extends the X window system and the X Toolkit (Xt) with a high-level, +object-oriented, interpreted programming language. +This approach will allow GUIs written +using standard Xt-based widget sets to be constructed without requiring any +window system programming on the part of the programmer. +The architecture of the resulting program completely separates the GUI from +the applications code, allowing the GUI to be developed separately and +replaced at will without modifying the application. +Despite the separation of the GUI from the application the two are tightly +integrated using an asynchronous, event-driven messaging system based on +requests and client events, with the remote client application appearing as +just another class of object within the GUI. +This approach maximizes window system and toolkit independence and is well +suited to distributed applications, allowing the GUI and client application +to be run easily on separate processors or computers. +<P> +</EM><P> +<H1><A NAME=SECTION021910000000000000000> Introduction</A></H1> +<P> +Most window system programming today is done via one of two approaches. The +first approach is to code directly in C or C++ at the window system toolkit +level, usually integrating the user interface code and applications code +within the same program. The second approach, which is really just a +variation on the first, is to use one of the many commercial GUI builders +available. This simplifies the programmer's task by allowing the user +interface to be interactively designed, relying on the GUI builder to +generate the window system code required to implement the user interface +specified by the programmer and requiring the programmer to code only the +application functionality. As with the direct coding approach, the +applications code is often integrated with the GUI in the same program. +<P> +Recently a third approach has been used. This employs a high-level, +interpreted language in which the programmer codes all or part of the +application, with at least the GUI being implemented in the high-level +interpreted language. Tcl/Tk is a recent example of this approach. Other +examples of the high-level interpreted approach from outside the Unix/X +world include Apple's HyperCard/HyperTalk, and the Visual Basic facility of +Microsoft Windows. +<P> +This paper presents a new, high-level, interpreted window system toolkit +which like Tcl/Tk is also based on the Tcl interpreter. Unlike Tcl/Tk, +which is by definition Tk specific, our approach tries to maximize window +system and window system toolkit independence to ease future upgrades to new +window systems or toolkits. The initial implementation, which is for the X +Window System, is based on the X Toolkit (a part of the X Consortium X11 +release) and uses standard Xt-based widgets. Support for an asynchronous, +event-driven messaging system is an integral part of the design, allowing +the GUI to be isolated from the functional part of an application and making +the facility well suited to distributed applications, e.g., where a GUI +executing locally talks to application code executing remotely, with the +application downloading the GUI to be run at startup time. The core +facility is implemented as a simple C-callable library which can be used to +implement new GUI-based programs without having to write any window +system-level code. +<P> +An important aspect of the facility described in this paper is that it +represents a general user interface management system (UIMS) tailored for +astronomical GUIs. The intent is that by providing a high-level facility +tailored for our applications, we can simplify the task of developing GUIs +for astronomical applications while providing a greater degree of +consistency between applications since they will share the same GUI +components. This is particularly important in the area of 2D graphics and +imaging, including presentation and user interaction with such data, since +the standard toolkits do not address this area. +<P> +<H1><A NAME=SECTION021920000000000000000> The Widget Server</A></H1> +<P> +<H2><A NAME=SECTION021921000000000000000> Overview</A></H2> +<P> +``Widgets'' (window objects), are the basic building blocks of graphical user +interfaces. A window system toolkit provides a selection of widgets that +the programmer can use to construct a user interface. Typical widgets +include things like push buttons, scrollbars, pop-down menus, or scrolling +text regions. The <i> widget server</i> serves up widgets to a remote client +process in much the same way that the X display server serves up windows and +other low-level display resources to a remote client application. +<P> +When a client application starts up it connects to the widget server and +downloads its GUI. The GUI is a simple block of text which is interpreted +and executed by the widget server. The GUI text contains a description of +the widgets comprising the user interface, a number of interpreted action +procedures to be called to process user interface or client events during +execution, and any code needed to initialize the GUI. +During execution the client application waits for and executes requests from +the GUI, and sends messages to the GUI to inform it of any ``client events,'' +or changes in the state of the client. The conventional compiled client +application implements all the application-specific functionality, but does +not communicate directly with the user. +<P> +To the client application the GUI is merely a block of text to be passed on +to the widget server; the client code knows nothing about the GUI other than +the name of the GUI file to be sent to the widget server. The client knows +only about the applications functionality which it implements, and the +messages and requests used to communicate with the GUI. The GUI is +completely isolated from the client application. While to the user the GUI +appears to be an integral part of the application, the actual compiled +client application has an interpreted command-line interface and can be +executed stand-alone without any GUI. +<P> +<H2><A NAME=SECTION021922000000000000000> Widget Server Architecture</A></H2> +<P> +<P><A NAME=1250> </A><A NAME=todyfig1> </A><IMG ALIGN=BOTTOM ALT="" SRC="/iraf/web/projects/x11iraf/docs/todyd1.gif"> +<BR><STRONG>Figure:</STRONG> Widget Server Architecture. +<A HREF="http://hoth.stsci.edu/adass-figs/todyd1.eps"> + Original PostScript figure (34 kB) +</A><P> + +<BR> +<P> +<P> +The architecture of an application which uses the widget server is +summarized in Figure <A HREF="todyd.html#todyfig1">1</A>. +The typical widget server-based application consists of two processes, the +process containing the client application, and the widget server process +itself which executes the client's GUI. All user interface functionality +resides in the GUI and all application-specific functionality resides in +the client. During execution these processes communicate via an +asynchronous object-based messaging system. +<P> +<H2><A NAME=SECTION021923000000000000000> Advantages of the Widget Server</A></H2> +<P> +The widget server architecture separates the user interface from the +application-specific code and provides a high-level interpreted language +for developing GUIs. This approach has significant advantages, +including the following: +<P> +<OL><LI> +The high-level, interpreted nature of the widget server makes it much +easier to develop GUIs than is the case with toolkit-level programming or +the conventional, compile-link approach. +<LI> +The use of an interpreted runtime language (Tcl) to compose the GUI is more +powerful than the visual programming approach used in GUI builders, since +the latter only address the appearance of the user interface. +User interface builders can still be used with the widget server to +interactively layout the user interface, although this is less important +than it might be given the interpreted nature of the GUI (i.e., changes can be +made and the GUI redisplayed very quickly). +<LI> +The high-level, integrated nature of the widget server-based GUI development +environment makes it straightforward to customize the environment to support +a particular class of application. This is important for large systems +where GUIs are developed by many people working independently, +to reduce the overall effort and improve consistency. +<LI> +The widget server isolates all window system and toolkit code into a single +executable which can serve any number of applications. This greatly reduces +disk space consumption in a large system that has many application GUIs. +<LI> +Since the widget server is a single executable it is easy to have multiple +versions, e.g., supporting different toolkits or incorporating proprietary +software to optimize performance for a particular class of workstation. +<LI> +Since all the window system code is isolated into a separate process the +client application is completely window system independent, allowing the +same client application to be used with a widget server GUI executing on +any local or remote platform running any operating system. +<LI> +Porting a whole system full of GUIs to a new platform can be done by a +single individual since only the widget server itself need be ported. +<LI> +No window system libraries, and indeed no compilation, is needed +to develop GUIs. All that is needed is the widget server executable. +This makes it much more feasible to use commercial or platform specific +libraries should this be desired. +<LI> +The GUI is completely isolated into a small text file separate from the +application, allowing the GUI and the application to be developed separately, +or several alternate GUIs to be used with a single application. +<LI> +The widget server is well suited to distributed applications since the +widget server can be run on the local workstation while the client +application executes remotely. This allows the entire GUI to execute +interactively on the local workstation, a much more efficient approach than, +for example, running an X application over the network. +</OL> +<P> +Possible disadvantages of the widget server approach are its relative +complexity and the possibility of inefficiency when the application is +distributed over two or more processes. For a small system where only a few +GUI-based applications are needed many of our big-system concerns are +unimportant and it might be simpler to program directly at the toolkit +level, especially if a user interface builder tool is available. Efficiency +can be a problem if the client code is required to respond in real time to +user interface events, however this is rarely a problem in well designed +applications since the more interactive portions of the program can be moved +into the GUI, implemented as interpreted GUI procedures or as calls to the +compiled functions in the widget server itself. The asynchronous nature of +the messaging system ensures that the user interface will always be +responsive even when the client is busy computing. +<P> +<P><A NAME=1259> </A><A NAME=todyfig2> </A><IMG ALIGN=BOTTOM ALT="" SRC="/iraf/web/projects/x11iraf/docs/todyd2.gif"> +<BR><STRONG>Figure 2:</STRONG> A Simple GUI: The ``Hello, world'' Application<BR> +<P><H2><A NAME=SECTION021924000000000000000> Platform Independence</A></H2> +<P> +The widget server automatically provides a high degree of platform and +window system independence since the GUI is isolated from the client +application; in the worst case only the GUI file has to be changed to use a +GUI-based application on a new platform. The current implementation +provides full platform independence for platforms which run the X Window +System since the current widget server implementation is X-based. No +changes to the GUI files are needed for these platforms. +<P> +The current widget server implementation does not, however, provide full +window system toolkit independence for window systems other than X. Ideally +the widget server should define a virtual set of widgets which can be +implemented on a variety of window systems and window system toolkits; not +only X but also Windows, Windows NT, Macintosh, etc. This problem has +partially been solved in that the language used in widget server GUIs +isolates the widget-dependent code into a portion of the GUI which describes +the widget hierarchy, assigning widget classes to named GUI objects. The +runtime part of the GUI, i.e., the interpreted action or callback procedures +called at runtime as the GUI executes, is already almost completely widget- +and toolkit-independent. Defining a fully toolkit-independent virtual +widget set is a future problem which cannot be attempted until we have a +better idea what widgets are needed for our applications. Several +commercial window system toolkits or GUI development environments exist +which have already attempted to address this problem, at least for the +standard toolkits. +<P> +The portion of the widget server which interfaces to the underlying window +system and window system toolkit (widget set) is the <i> Object Manager</i>. +This is discussed in the next section. +<P> +<H1><A NAME=SECTION021930000000000000000> The Object Manager Library</A></H1> +<P> +<H2><A NAME=SECTION021931000000000000000> Overview</A></H2> +<P> +The widget server is actually just a shell around the Object Manager library +(OBM). The widget server extends the Object Manager by providing a way for +external clients to connect to the Object Manager to download and execute a +GUI. All of the real work of creating and executing the GUI is done by the +Object Manager library. The widget server adds a client-server communications +method. +<P> +The Object Manager provides services for creating, deactivating, +reactivating, or destroying a GUI, creating or destroying objects, and +delivering messages and events to objects within the GUI. The OBM provides +the framework within which GUIs execute, including the interpreter, +automatic memory allocation, and a library of runtime services. +The Object Manager defines four main classes of objects: <i> Server</i>, +<i> Client</i>, <i> Parameter</i> (for client events), and <i> Widget</i>, for +the graphical elements of the interface. Within the Widget class are many +subclasses, one for each type of widget. +All Object Manager execution is event driven and asynchronous and is based +on messages (requests), callbacks, and events. For example, defining a new +GUI is done by sending a message to the server object. +<P> +The set of widgets implemented by the Object Manager is not fixed, i.e., new +widgets can be added or existing widgets removed to meet the requirements of +the applications which will be using the widget server. The base Widget +class provides a generic set of methods usable with all widget subclasses. +Complex widgets subclass the base Widget class to add their own methods. +The current Object Manager provides a mixture of Xt-based widgets which +provide a Motif-like appearance but which are publically available and +redistributable. Source for these widgets and for all code used in the +widget server is included in the distribution. The current widget set +includes the base Xt widgets, the 3D Athena widgets, selected FWF (Free +Widget Foundation) widgets, plus a few others such as the Layout widget from +MIT, the HTML hypertext markup language widget from NCSA <i> Mosaic</i>, and +the gterm-image widget from the IRAF project. Additional Xt-based widgets +(including Motif, OLIT, and commercial widgets) can easily be added. +<P> +<H2><A NAME=SECTION021932000000000000000> The OBM Library</A></H2> +<P> +The main entry points of the OBM library are shown in Figure <A HREF="todyd.html#todyfig3">3</A>. +The library is very simple since everything complicated is done by the +interpreted GUI code. The main runtime function of the OBM library, from +the point of view of the application which uses the library, is messaging. +A window system application (such as the widget server) calls +<i> ObmDeliverMsg</i> to deliver a message from the client application to a +GUI object. A callback function is registered with the Object Manager to +intercept client requests and pass them on to the client. +<P> +<P><A NAME=7268> </A><A NAME=todyfig3> </A><IMG ALIGN=BOTTOM ALT="" SRC="/iraf/web/projects/x11iraf/docs/todyd3.gif"> +<BR><STRONG>Figure 3:</STRONG> Principal routines of the Object Manager library, <i> libobm.a</i><BR> +<P><H2><A NAME=SECTION021933000000000000000> Using the OBM Library to Build Standalone Applications</A></H2> +<P> +Our discussion has thus far concentrated on the widget server and +distributed applications, because the widget server provides the best +architecture for adding GUIs to tasks in an existing, large data processing +system. Another important class of applications are window system +applications, where the focus is on the window system functionality +implemented by the application. Most conventional X window system +applications fall into this class. +<P> +An important use of the Object Manager library is to implement such +applications. A stand-alone, single-process window system application can be +built using the OBM library. In this case the ``client'' is not a separate +process, but an application-specific interpreter within the same process as +the OBM library. The program could be written as a conventional window +system program making direct calls to the underlying window system toolkit, +but by using the OBM library virtually all window system specific code is +eliminated and the GUI is isolated to a high-level, interpreted GUI file. +The only compiled code required is that which implements the functionality +of the application itself. The resulting task is almost completely window +system independent. +<P> +A good example of an existing stand-alone window system task built around +the OBM library is <i> ximtool</i>, the IRAF image display server program. +This is a stand-alone X window system application used for image display and +image interaction. <i> Ximtool</i> contains only about one page of C code +which has anything to do with X. All of the remaining C code handles window +system-independent raster image processing and the fifo or socket-based +binary protocol used to communicate with remote clients for image display. +The <i> ximtool</i> GUI is an interpreted GUI text file, identical to what +one might use with a widget server-based task. The widget server itself, +of course, is another example of a stand-alone X application based on the +OBM library. +<P> +<H2><A NAME=SECTION021934000000000000000> The Object Manager Shell</A></H2> +<P> +Another stand-alone host application built around the Object Manager library +is <i> obmsh</i>, the Object Manager shell. This is a Unix shell which executes +OBM windowing scripts. It can be used to execute GUI files from the Unix +command line, or be used in OBM-based scripts to write stand-alone Unix +shell scripts that can be called as commands from the Unix environment. +For example, the ``hello, world'' GUI shown in Figure <A HREF="todyd.html#todyfig2">2</A> could be +converted to a Unix command <i> hello</i> by changing the file name to ``hello'' +and adding something like ``<code>SPM_quot</code>#!/usr/local/bin/obmsh"'' to the file header. +<P> +<H1><A NAME=SECTION021940000000000000000> Messaging</A></H1> +<P> +<H2><A NAME=SECTION021941000000000000000> Messaging Fundamentals</A></H2> +<P> +The key to isolating the GUI from the client code of an application, while +providing a tightly integrated, efficient application, lies with messaging. +The messaging scheme used determines how objects within the application +interact with each other during execution. This includes the interaction +of the client code (client object) with the GUI. Our discussion here will +concentrate on how messaging is used to link the client to the GUI, but it +should be noted that the same messaging scheme is used for all object-to-object +communications within the GUI as well. +<P> +Messaging as defined by the OBM consists of two parts: requests and +client events. Requests are commands send to the client (or any other +object). The recipient is free to modify or ignore the request as it wishes. +Client events are messages sent to the GUI when the client state +changes in any way. The same mechanism is also used to deliver other forms +of client information to the GUI, e.g., in response to requests. The GUI is +free to ignore client events. It is not unusual for a given GUI to be +interested in only a portion of the client events generated by a client. +<P> +A client event is a message sent to an object of the OBM class <i> Parameter</i>. +A parameter object is very simple, consisting of a name and a string value. +The GUI registers callbacks with the user interface (UI) parameters, i.e., +client events, +that it wishes to know about. The string value of a UI parameter can be +anything, for example a number, a structure, a list, or a large block of text. +It is common for multiple callbacks to be registered on a single UI parameter +by independent elements of the GUI. +<P> +Messaging is fully asynchronous. Both requests and client events are queued +and buffered, and periodically flushed to the process on the other end. +Synchronization occurs automatically when the client waits for input from +the server (GUI). The GUI never waits for a request to complete, nor does +it check to see that a request has been honored. Rather, when the client +processes the request it sends client events back to the GUI to inform the +GUI of any actions performed by the client. The same thing happens when +the client performs actions for any other reason, hence the GUI always +reflects the true state of the client. +<P> +Client events are an important abstraction mechanism. Client events and +messages allow the client to provide the GUI with all the information it +needs to function, without the client code having any knowledge of the +nature of the user interface. Yet, since requests and client events are +decoupled, the client will function even if the client events and messages +it sends are discarded, as when running the client code without a GUI or +with radically different GUIs. +<P> +<H2><A NAME=SECTION021942000000000000000> Simple Messaging Example</A></H2> +<P> +Messaging is one of those things which is fundamentally simple, yet +surprisingly hard to explain. As a simple example, consider what happens +when the user selects a frame to be displayed in <i> ximtool</i>: +<P> +<OL><LI> +The user pushes the next frame button. +<LI> +The callback procedure (in the GUI) for the nextFrame button sends the +command ``nextFrame'' to the client. +<LI> +The client receives and processes the request, changing the frame, +sending the new frame number to the UI parameter ``frame''. +<LI> +A GUI callback procedure registered on the ``frame'' parameter is called, +updating the GUI to indicate the new display frame number. +</OL> +<P> +This example simplifies things considerably but is accurate so far as it +goes. In the real program there are a number of different ways the frame +can be changed, e.g., by the next frame or previous frame buttons, by menu +selection, keyboard accelerators, the blink timer, IRAF running in another +process, and so on. All of these end up sending a request to the <i> +ximtool</i> client which directly or indirectly results in a frame change. +When the display frame is changed a number of client events are generated to +inform the GUI not only of the new frame number, but also the new frame +title, zoom, pan, and frame flip values, type of enhancement used for the +frame, and so on. Each of these items represents a separate client event. +Although the action of the program may be arbitrarily complex in real world +examples, the basic messaging mechanism on which this is all based remains +very simple. +<P> +<H1><A NAME=SECTION021950000000000000000> Software Products</A></H1> +<P> +<H2><A NAME=SECTION021951000000000000000> The X11IRAF Package</A></H2> +<P> +All of the software described in this paper is packaged in a single +distribution called <i> x11iraf</i>. This includes <i> xgterm</i>, <i> ximtool</i>, +the Object Manager library, sources for all the third party widgets used in +OBM, and assorted demo applications. Everything needed to build the package +is included, including compatible versions of some publically available +libraries, e.g., Tcl and Xpm. Despite the name the software is +not tied to IRAF in any way, other than that it is a product of the IRAF +project and is used for IRAF GUIs. +<P> +<H2><A NAME=SECTION021952000000000000000> Xgterm</A></H2> +<P> +<i> Xgterm</i> is an upwards compatible version of the popular <i> xterm</i> +with the <i> xterm</i> graphics ripped out and replaced with an +OBM-based GUI which uses the gterm-image widget for graphics. The +graphics supports a number of extensions, including full color support, an +integrated imaging capability, dialog interaction, intelligent unconstrained +resize, and a full crosshair cursor. Although <i> xgterm</i> is often used as +a simple terminal emulator it is also a general widget server since it +contains the full OBM library, and it can be used to execute +arbitrarily complex OBM-based GUIs and manage the communications with the +remote client. The current version of <i> xgterm</i> is based on the X11R6 +version of <i> xterm</i>. +<P> +<H2><A NAME=SECTION021953000000000000000> Ximtool</A></H2> +<P> +<i> Ximtool</i> is an image display server, used by remote client applications +such as IRAF to display and interact with images. Several frames can be +loaded and independently displayed in a full-frame or tiled configuration. +Display frames can be any size. <i> Ximtool</i> is a good example of a +conventional single process windowing application which uses the OBM library +for the GUI and the window system interface. +<P> +<H2><A NAME=SECTION021954000000000000000> The Object Manager Library</A></H2> +<P> +The Object Manager library (OBM) is a high-level, interpreted window system +toolkit that is used to implement arbitrary graphics user interfaces. The OBM +library uses Tcl as the interpreter. The current version of the OBM +library is based on the X toolkit and can be used with any Xt-based +widget or widget set. +<P> +<H2><A NAME=SECTION021955000000000000000> The Gterm-Image Widget</A></H2> +<P> +The gterm-image widget is an X Toolkit-based widget for general +2D graphics and image display. This is a complex widget and a full +description of its capabilities is beyond the scope of this paper. The +Gterm widget provides a general GKS-like vector graphics and text display +capability. An integrated image display capability allows any number and +size of image rasters to be created within the widget or in the X server. +<i> Mappings</i> can be defined to map one raster to another, permitting +general graphics pipelines involving scaling and other geometric transforms +to be set up. Colormap support is included for grayscale and pseudocolor +rendering of raster data. An interactive <i> graphics marker</i> facility is +provided for interaction with the displayed graphic. The Gterm widget is +used for all graphics and imaging in <i> xgterm</i> and <i> ximtool</i>. +<P> +<H1><A NAME=SECTION021960000000000000000> Adding GUIs to IRAF Applications</A></H1> +<P> +A major application of the widget server and the other software described +in this paper is in adding GUIs to IRAF applications. In this case the +IRAF task is the client: when the IRAF task starts up it downloads its GUI +to the widget server, and during execution the IRAF task and the GUI +communicate via the messaging facility described earlier. The changes +required to add a GUI to an IRAF task are minor, ranging from +changing a single line of code to cause the GUI file to be downloaded, to +defining a set of client events and adding <i> gmsg</i> calls to allow more +complete integration of the GUI. Adding a GUI to a task increases the +system size by only the 10 Kb or so required for the GUI file. +<P> +<H1><A NAME=SECTION021970000000000000000> Availability and Further Information</A></H1> +<P> +Further information on the software described in this paper, including +more detailed documentation, full sources, and executables for a variety +of platforms can be found in +<A HREF="/iraf/web/projects/x11iraf">the X11IRAF Web page</A>. +Further information on IRAF itself and other IRAF products can be found in +<A HREF="/iraf/ftp>the IRAF anonymous ftp archives</A>. +Documentation on Tcl, Xt/XLIB and the other standard software products +used in X11IRAF is available from many sources. +<P> + +<P> + +<P> + +<P> +<BR> <HR> +<P><ADDRESS> +adass4_editors@stsci.edu +</ADDRESS> +</BODY> diff --git a/vendor/x11iraf/obm/docs/tody.paper/todyd1.gif b/vendor/x11iraf/obm/docs/tody.paper/todyd1.gif Binary files differnew file mode 100644 index 00000000..ef206249 --- /dev/null +++ b/vendor/x11iraf/obm/docs/tody.paper/todyd1.gif diff --git a/vendor/x11iraf/obm/docs/tody.paper/todyd2.gif b/vendor/x11iraf/obm/docs/tody.paper/todyd2.gif Binary files differnew file mode 100644 index 00000000..b3aea8ba --- /dev/null +++ b/vendor/x11iraf/obm/docs/tody.paper/todyd2.gif diff --git a/vendor/x11iraf/obm/docs/tody.paper/todyd3.gif b/vendor/x11iraf/obm/docs/tody.paper/todyd3.gif Binary files differnew file mode 100644 index 00000000..7038a128 --- /dev/null +++ b/vendor/x11iraf/obm/docs/tody.paper/todyd3.gif |
