diff options
Diffstat (limited to 'vendor/x11iraf/Notes-V1.3.txt')
| -rw-r--r-- | vendor/x11iraf/Notes-V1.3.txt | 1472 |
1 files changed, 1472 insertions, 0 deletions
diff --git a/vendor/x11iraf/Notes-V1.3.txt b/vendor/x11iraf/Notes-V1.3.txt new file mode 100644 index 00000000..bd708235 --- /dev/null +++ b/vendor/x11iraf/Notes-V1.3.txt @@ -0,0 +1,1472 @@ + + X11IRAF V1.3 REVISIONS NOTES + ============================ + +------------------------------------------------------------------------------- + Last Modified: Mon Feb 4 14:29:30 MST 2002 +------------------------------------------------------------------------------- + +Table of Contents: +------------------ + + 1. Installation Changes + + 2. XImtool Revisions + 2.1 Real-Time WCS/pixel Readout + 2.2 "Peak-up" Cursor Centroid Positioning + 2.2.1 Command Summary + 2.2.2 Resource Summary + 2.3 Auto-Registration of Images + 2.3.1 Command Summary + 2.4 Integrated Control Panel + 2.4.1 Load Panel Changes + 2.4.2 Info Panel Changes + 2.4.3 Tile Panel (NEW) + 2.4.4 Coords Panel (NEW) + 2.5 Support for 16 Display Frames + 2.6 Magnifier + 2.7 Freezing Cursor Readout + 2.8 Cut-Graphs + 2.9 Ruler Markers + 2.10 Summary of Cursor Commands + 2.11 Summary of Application Resources + 2.12 Summary of Command-Line Options + + 3. OBM (Widget Server) Revisions + 3.1 New Toolkit Widgets + 3.1.1 Tabs Widget + 3.1.2 ListTree Widget + 3.2 Dynamic Widget Creation + + 4. Client Display Library (CDL) Revisions + 4.1 Display Protocol Changes + 4.2 New Procedures + 4.2.1 C Calling Sequence + 4.2.2 F77 Calling Sequence + 4.2.3 SPP Calling Sequence + 4.3 Demo Task Updates + + 5. Technical Notes + 5.1 IIS Protocol Changes + 5.1.1 IIS Protocol Summary + 5.2 IRAF 'imd' Interface Changes. + 5.2.1 Program Initialization + 5.2.2 WCS Text Changes + 5.2.3 Cursor Reads + 5.3 ISM Communications + 5.3.1 Socket Connection + 5.3.2 Communications Protocol + 5.3.3 GUI Objects + +------------------------------------------------------------------------------- + + + +1. INSTALLATION CHANGES +======================= + + A new script automatically unpacks the distribution and installs +files in the system (or user's directories for a private install), provides +error checking and user interaction to skip parts of the process or change +defaults. The 'install' script is packaged with both source and binary +distribution files. To install for general use in the system directories +the script must be run as root user, it may be run by any user to install +to private directories. + +To install from an unpacked source distribution: + + % xmkmf build the package Makefile + % make World build binaries from sources + % su become the root user + # ./install install the files (interactive) + +Only the last two commands are required to install from an unpacked binary +distribution. + + + +2. XIMTOOL REVISIONS +===================== + + Aside from general bug fixes most of the changes in this release +are all new features for XImtool. Details on individual features are +explained below, but in summary: + + - real-time cursor image WCS and actual pixel readout + - new cursor centroiding function + - ability to "auto-register" frames + - integrated/enhanced control panel + - support for up to 16 display frames + - improved support for image tiling + - a "compass" indicator for the display orientation + - pixel table readout + - image header display (keyword selection, WCS display) + - horizontal/vertical cut-graphs of the display + - ruler markers on the display + - control port for external process communications + + + The most significant change in this version is the ability to +access the displayed image pixels or header data to produce the real-pixel +and WCS readouts. This is done using an external process called an ISM +(Image Support Module) which communicates with ximtool as a "plug-in" +module to enhance the features of the core program. In this case the ISM +is written as an IRAF task (although any application that can send text +over a socket can be used as an ISM regardless of the +language/environment) run at the host level with the ability to access any +supported image format. Any number of such ISM plug-ins can be developed +to provide e.g. catalog overlay, animation, and so on. + + For the WCS/pixel ISM to operate properly changes to the display +protocol were required to pass the needed information. These changes are all +backwards compatible with "older" display servers however for the ISM to +work at all you will need to be running at least IRAF V2.11.4. Updates to +external packages using image display (notably MSCRED) have already been +completed. Details of the changes required are found in the technical notes +at the end of this document. + + Users should feel free to contact IRAF site support (iraf@noao.edu) +with any questions. + + +------------------------------------------------------------------------------ + + + Detailed Revisions Notes + ======================== + + +2.1 Real-Time WCS/pixel Readout +================================ + + XImtool now has the ability to display the actual pixel value of +an image (as well as the scaled value previously shown) and the +cursor position in image WCS values (e.g. RA/DEC, GLAT/GLONG, etc). This +is done using an external task (the 'ism_wcspix.e' binary in the new +distribution) to access the image and pass the coordinate/pixel info- +rmation to the GUI. + + WCS readout is enabled by default but can be toggled or reset +using the 'WCS/Pix' button on the Coords tab in the control panel or the +"ISM" toggle on the alt-gui menubar. When enabled, images currently in +the server or subsequently displayed will be passed to the external +process where they are cached for access. Cursor movements generate an +event that maps the current frame buffer position to a position in the +cached image. The ISM (ISM is Image Support Module) task then reads the +image to determine the pixel value (or a small table of values around the +current position), and computes one or more coordinates from the image +position. The ISM task also has access to the associated BPM images and +can optionally return bad pixel information during the cursor readout. + + By default, the logical and world image coordinates are displayed +to both the Coords panel readout as well as the main display window wcsbox +text marker. Alternate coordinate systems (e.g. transformation of +equatorial to galactic coordinates or some other sky system, physical +coords, amplifier coords, etc) can be selected for display by hitting the +"Options" toggle on the Coords panel. Available coordinate systems are +chosen using the "Type" menu on the panel, the readout format +(sexigesimal, degrees, etc) using the "Format" menu, and the display to +the current panel or main image window using the remaining toggles for +each WCS. Up to four systems may be displayed at one time, the coordinate +panel and wcsbox marker will adjust size automatically depending on the +display. + + By selecting the "BPM Data" toggle from the Coords.Options panel +ximtool is able to flag pixels in images with an associated bad pixel mask. +This bad pixel mask is currently assumed to be named in the image header +"BPM" keyword by convention. If the cursor passes over a bad pixel in the +mask, the Coords bpm display as well as the main window wcsbox will change +to a red background color. Only the Coords display will show the value, +any non-zero value will be flagged with the color change. + + With the ISM enabled the Compass indicator will display a set of +arrows showing North-East if a WCS is available, otherwise just the +current X-Y axes are shown. The pixel table will display actual pixel +values from the image, with the ISM off the pixel table displays the +scaled image values from the frame buffer. + + + +2.2 "Peak-up" Cursor Centroid Positioning +========================================== + + Several new keystroke commands are available to reposition the +cursor to a centroid or min/max pixel value within a bounding box of the +cursor position, allowing you to approximate the position with the mouse +and fine tune it quickly before typing the application keystroke command. +The initial box size is controlled with a 'centerBoxSize' GUI resource +(defaults to 5 pixels) but can be adjusted interactively using the Ctrl-[ +and Ctrl-] commands to descrease/increase the box size respectively. A +marker will flash briefly to indicate the box size. + + The Ctrl-0 (zero) key finds either a centroid or the local maximum +pixel value within this box region, Alt-Ctrl-0 (zero) will find the local +minimum value. In either case the cursor is reposition to the computed +value. The default peak-up action is to find the centroid position in the +box however this can be changed to find the max pixel by selection the +"Centroid Peaks" option from the main Display control panel or by resetting +the "peakCentroid" GUI resource (defaults to True). + + Centroiding is done using only the scaled screen pixel values and +only pixels above the mean value within the box are used. It works best +if the box size is set appropriately, the centroid position may appear to +drift if the box is too large and includes too many background pixels. + + + 2.2.1 Command Summary: + ---------------------- + + Ctrl-0 (zero) Reposition to centroid/max-pixel + Alt-Ctrl-0 (zero) Reposition to min-pixel + Ctrl-[ Decrease centering box size (min of 5) + Ctrl-] Increase centering box size + + 2.2.2 Resource Summary: + ----------------------- + + peakCentroid True Compute the box centroid position, a + 'False' value force the max value to be used + centerBoxSize 5 Size of the centroid box, used as cursor + position +/- this value + + + +2.3 Auto-Registration of Images +================================ + + The auto-register feature allows you specify a registration of +two or more display frames with an offset. When enabled, this registration +is maintained for all frames in the list if any one of them is panned or +zoomed to a new location in the frame buffer. + +For example, to use this feature do the following: + + 1) Enable Auto-Register (either on the Control Panel or the tool- + bar on the alt-gui) and pan/zoom to some star of interest. + 2) Use Mouse-Button-2 to center the star in the frame. + 3) Cycle through the frames and you may see a small shift + of the star. For each frame, position the cursor on the + star and type Ctrl-o to offset it to the center. Repeat + as necessary. Small corrections will be cumulatively added + so you can use the Ctrl-0 peak-up command to centroid each + object in the frame before the Ctrl-o offset. + 4) Pan around the image in one display frame, then switch frames + and the new frame should also be panned to the new image with + the proper offset. + 5) A Ctrl-a command will toggle the feature, offsets are only + allowed when autoreg is enabled. + + Hitting "Register" will zero the offsets, as will toggling the +auto-register function. What you should see is the object centered in +the frame and as you blink through it remains registered but the panner +box marker is moving around. Drag the panner around and all frames +still remain registered with the given offset. The control/info panels +now display what the offset is for each frame. + + The register display list is shared with the blink list and can +be set using the Display control panel. By default all frames are included +in the list. For accessing more than four frames, use the box icon in +the Blink/Register box of the Display control panel to bring up a new window +with access to all 16 available frames. + + + 2.3.1 Command Summary: + ----------------------- + + Ctrl-o set the offset from center + Ctrl-a toggle the Auto-register feature + + + +2.4 Integrated Control Panel +============================= + + The separate windows previous used for Control/Print/Load/Save/etc +have now been integrated into a single window with the appropriate control +panel selectable with a Tab widget. There are also new Tab panels for +setting the frame tile configuration (see below), more detailed information +on the server status, and selecting the WCS readout options (see above). + + All panels were updated as part of the integration, however some +changes of note to each panels include: + + Display + + View box + - supports 16 frames + - Frame offset added to readout + + Blink/Register + - new box icon button brings up independent control panel w/ + access to all 16 frames + + Options + - addition of "Magnifier" and "Centroid Peaks" options + Print + + Postscript Options + - added B5 paper size as option + Load + + Complete redesign of panel (see below) + + New options group (see below) + + Filename filter accepts a comma-delimited list of templates + Save + + EPS added a save format, saves image w/ no annotation + Info + + Complete redesign of panel (see below) + Tile + + New panel allowing configuration of tile frame layout (see below) + Coords + + New panel allowing selection of WCS readout options (see below) + + +2.4.1 Load Panel Changes +------------------------- + + The Load panel was redesigned to make directory navigation easier +as well as to provide new features. The file list box is now larger and +implemented using a more natural directory listing format. The filename +filter box can now accept a comma-delimited list of templates providing +multiple matches to e.g. "*.fits" and "*.imh" images in the same listing. +Directories are always listed in the output. + +A new options group was added to the panel with the following features: + + Auto Load + If enabled, selecting an image name from the list will force it + to the display automatically. Otherwise the Load button at the + bottom of the panel must be used to load the image. Specifying + a filename in the "Load File" text box will load that image either + with a CR or using the panel Load button. + + Auto Grayscale + If enabled, color images (e.g. GIF) are converted to grayscale + automatically, otherwise a private colormap is loaded for the image. + + List Image Headers + If enabled the file list will change to display only the matching + image names along with the pixel size, image size, and optional + title string. Directory navigation is disabled until this option + is turned off. MEF FITS files will be listed with the number + of extensions they contain but cannot be loaded. + + Frame + Select the frame in which to display the image. The special + value "Current" is used to display to whichever is the current + display frame, otherwise any of 16 available frames may be selected. + + Zscale Options + The remaining options can be used to specify the z-scale parameters + used when loading the image. The algorithm works as follows: + + if (zscale enabled) + determine optiminal z1/z2 given 'Nsample' points + else if (zrange enabled) + use image min/max as z1/z2 + else + use panel z1/z2 values + + To load 8-bit data directly the 'zscale' option should be disabled. + + +2.4.2 Info Panel Changes +------------------------- + The Info panel was revised to provide a greater variety of status +information. The type of output is controlled by the toggle buttons on +the bottom of the frame, however all output is kept current as the program +runs. Current info options include: + + Frame - Info about the current display frame + Server - Info about various server options, e.g. colormaps, + memory model, antialias type, etc. + Clients - Show currently connected clients. Lists available + connection channels and active ISM clients. + WCS - List all WCS and mappings for the current frame + ISM - Log of various ISM status messages + Imtoolrc - Show current frame buffer configuration table + + +2.4.3 Tile Panel (NEW) +----------------------- + + With the additional frames, the default tiling scheme proved in- +adequate. A new control panel Tile frame now allows you to select from +a number of tile configurations, the list of frames to be tiled, a "fill +style" (left-to-right or top-to-bottom), as well as optional labels for +each of the tiles (frame number, image title or image name). + +Tile configuration will make use of all frames currently selected in the +"Tile Frame" group in the following manner: + + Disabled Do not tile the display + Manual Tile according to "Manual Configuration" settings + Best Optimize layout for frame buffer aspect + Square Always force a square layout (2x2, 3x3, etc) + Horizontal Preferentially tile horizontally (6 frames ==> 3x2) + Vertical Preferentially tile vertically (6 frames ==> 2x3) + One Row Tile all in one row (Nx1) + One Column Tile all in one column (1xN) + + +2.4.4 Coords Panel (NEW) +------------------------- + + The Coords Panel is meant to provide a full-featured readout as +well as serve as a control panel for the various options. The display +window contains the image name/title and frame buffer info, and a selection +of coordinate and image pixel readouts. The intent is provide more infor- +mation than can fit comfortably on the main image window while still +taking up as little screen space as possible. To this end the "Options" +button is used to hide most of the feature controls when not in use (see +below). Other options on the main panel include: + + WCS/Pix Toggle the real-time WCS/pixel readout capability + (i.e. the ISM used to access the disk image). This + must be enabled for certain other options to work. + + Pix Table Open a panel showing an image pixel table. The panel + shows an array of pixels surrounding the cursor position, + either the actual pixel values if the ISM is enabled, or + scaled display values otherwise. The size of the table + may be selected from the menubar. + + Header Display the current image header in a new panel. Both + the entire image header as well as WCS-specific parts of + the header are available under different tabs. This + option is only active when the ISM is enabled. + + Compass Draw an orientation compass on the display panner. If + the ISM is enabled and a WCS is present in the header, + the compass will indicate N/E according to the WCS, other- + wise the X/Y axes of the image are drawn. + + Options Pop-up/down the option control portion of the panel. When + enabled, the Coords Panel will change size to reveal the + options which can be changed (explained below). + + The "Readout Values" group controls the selection of WCS type, +location and format to be displayed. The "Type" menu always provides a +selection of the image Logical, Physical or World systems, which may be +identical depending on the image header. If a World system is supplied in +the image addition entries for transformations to other sky systems, (e.g. +FK5 to ICRS or galactic/ecliptic) will also be available. The selection +is dependent on whether the ISM is running as well as WCS information +present in the image. The "Format" menu allows the use to select a +sexigeimal display, conversion to degrees or radians, or whichever format +is most natural for the coordinate being display. The two toggle to the +right control whether this WCS is to be displayed on the Panel (i.e. the +Coords Panel window) or the ImgWin (i.e. the text marker on the main +image window). + + Other options below this group control whether or not to display the +WCS labels, the image name/title, and frame buffer information in the main +Coords Panel display. The "BPM Data" option controls whether or not the +ISM will try to map any bad-pixel mask associated with the image. If enabled, +a bad-pixel mask specified by the image header BPM keyword (currently fixed +by convention but this may be selectable later) will be mapped along with the +image. Aside from wcs/pixel readouts at each cursor position, any BPM data +values found will also be displayed. A non-zero value will cause the BPM +field of the Coords Panel readout as well as the main image window marker +to switch to a red background color to flag the value. + + The last box allows the user to specify a different ISM task to be +executed or to reinitialize the current one. In most cases this won't need +to be changed, however a custom ISM could be started when using special +data formats. This command string can also be controlled by the application +"ism_task" resource. + + + +2.5 Support for 16 Display Frames +================================== + + As part of the extensive GUI changes, support for the full 16 +frames allowed by the IIS protocol is now available. IRAF V2.12 or +later client tasks (and CDL library) are required to take advantage of +these frames. All changes are backwards compatible, older versions of IRAF +will continue to work but cannot access more than the original four +frames. The new DISPLAY task will automatically sense whether the display +server being used supports 16 frames or the original 4 and adjust the +'frame' parameter maximum accordingly. The changes are fully backwards +compatible for other servers (e.g. SAOimage, DS9, etc). + + More frames are possible if needed but will require further changes +to the client IRAF code to be effective. Allowing creation of more than +16 frames by the Load panel can be done independently but would also require +numerous code change to XImtool. Please contact site support (iraf@noao.edu) +if there is a need for this, or for workaround suggestions depending on your +application. + + + +2.6 Magnifier +============== + + The magnifier marker appears to be stable and was moved into the +default ximtool GUI and is now enabled by default. The ximtool-mag command +has been removed. + + +2.7 Freezing Cursor Readout +============================ + + Holding down the Alt key will now freeze the cursor display readout +and draw crosshairs on the screen at the last position. This can be used +for example to position the cursor but then allow the cursor to be moved to +another window (to enter text, start a program, whatever) without losing +the position information displayed on the screen. + + +2.8 Cut-Graphs +=============== + + XImtool now has the ability to display horizontal and vertical +cut-graphs of the display, these appear as "flip-out" panels that appear +on the bottom and right side of the main display window and are controlled +by the small "H" and "V" buttons in the lower right corner of the window. +When both panels are enabled the corner area of the display also shows an +options panel for the graphs. Current options are: + + + Better Speed Draw the graphics so they update at the fastest + possible rate. This is done by subsampling pixels + to produce a smoother graph but without sacrificing + too much accuracy. + + Better Accuracy Draw the graphics using all screen pixels to produce + the most accurate display. On fast modern machines + this can be enabled with no apparent loss of speed, + however older machines may wish to use this only + occassionally to limit any lag in the cursor tracking. + + Image Pixels (Not Yet Implemented) + + + Jump Cursor If enabled, large jumps of the cursor do not update + the graphics display, small movements around an object + of interest will update the display continuously. + + Smooth Cursor If enabled, all cursor movements cause the display to + be updated. This is another option that can be set + safely on faster machines but will cause a delay on + slower ones. + + Graphics Cursors If enabled, the graphics cursors in either of the + plots are active and can be used to update the cursor + readout on the main image window and the complementary + cut-graph. This can be used for example to freeze + the cursor in the main display using the Alt key (see + above), then moving to one of the graphics windows + to perform cut graphs in only one axis. + + Graphs are (currently) drawn using only the scaled display values +to avoid complications of accessing multiple images in a mosaic display. Both +plots are labeled using the frame z1/z2 values and contain cursor indicators +which update contuously. + + + +2.9 Ruler Markers +================== + + Holding down the Ctrl key and the Left-Mouse-Button while moving +the mouse will drag out a "ruler marker" measuring the distance from the +initial point to the current mouse position. Releasing the Ctrl key before +lifting the mouse button will leave the marker on the display, otherwise +it will be erased automatically once the mouse button is released. Any +number of ruler markers can be created in the frame. + + Distances are measured by default in image logical pixels however +the Right-Mouse-Button can be used inside the marker to popup a menu of +options: + + Sticky By default rulers are destroyed whenever the display + changes due to a pan, zoom, flip, or frame change. + This option will make the ruler "sticky" so it will + not be erased, subsequent use of the menu to shows + this option to be "UnSticky" to remove this feature. + + Units Sub-menu to select the units of the display. If the + ISM is enabled and a WCS is present in the image and + selected as one of the readout options, distances may + also be read out in units of arcseconds, arcminutes, + or degrees instead of the default logical pixels. All + markers created after the unit change will readout in + the new units as their default. + + Color Select the color of the marker. + + Draw into Frame (Not Yet Implemented) Draw the marker as overlay + graphics in the frame. Doing so will retain the + marker when printing a hardcopy of the display. + + Destroy Destroy the marker. + +The marker can also be destroyed by hitting the Delete or Backspace key +while the cursor is in the marker. There is presently no way to move the +marker to a new position in the frame. + + + +2.10 Summary of Cursor Commands +=============================== + + * - indicates a new/changed command + + Misc Functions + -------------- + Ctrl-b Backward frame + Ctrl-c Center frame + Ctrl-f Forward frame + Ctrl-i Invert + Ctrl-n Normalize +* Ctrl-m Toggle Magnifier +* Ctrl-p Toggle Panner + Ctrl-r Register +* Ctrl-s Match LUTs + Ctrl-t Tile frames toggle + Ctrl-u Unzoom (zoom=1) + Ctrl-x Flip X + Ctrl-y Flip Y + Ctrl-= Print + Ctrl-< Decrease blink rate + Ctrl-> Increase blink rate + Ctrl-+ Zoom in + Ctrl-- Zoom out + + Alt-1 thru Alt-4 Set frame displayed + Ctrl-1 thru Ctrl-9 Set integer zoom factor + + Ctrl-Alt-q Quit + Ctrl-Alt-f Fitframe + + Panels + ------ + Alt-b Blink frames toggle + Alt-c Control panel + Alt-h Help panel + Alt-i Info box panel + Alt-l Load file panel + Alt-p Print panel + Alt-s Save panel + Alt-t Tcl Shell panel + + Auto-Registration + ----------------- +* Ctrl-a Toggle Auto-Reg +* Ctrl-o Set offset + + Cursor Positioning + ------------------ +* Ctrl-h/Left_Arrow move cursor 1 pixel left +* Ctrl-j/Down_Arrow move cursor 1 pixel down +* Ctrl-k/Up_Arrorw move cursor 1 pixel up +* Ctrl-l/Right_Arrow move cursor 1 pixel right + +* Shift-Ctrl-h move cursor 10 pixels left +* Shift-Left move cursor 10 pixels left +* Shift-Ctrl-j move cursor 10 pixels down +* Shift-Down move cursor 10 pixels down +* Shift-Ctrl-k move cursor 10 pixels up +* Shift-Up move cursor 10 pixels up +* Shift-Ctrl-l move cursor 10 pixels right +* Shift-Right move cursor 10 pixels right + + Frame Positioning + ----------------- + Ctrl-Left shift one full frame left + Ctrl-Down shift one full frame down + Ctrl-Up shift one full frame up + Ctrl-Right shift one full frame right + + Ctrl-Alt-Left shift one half frame left + Ctrl-Alt-Down shift one half frame down + Ctrl-Alt-Up shift one half frame up + Ctrl-Alt-Right shift one half frame right + + Peak-Up Centroiding + ------------------- +* Ctrl-[ decrease centering box size +* Ctrl-] inrease centering box size +* Ctrl-0 (zero) centroid/find local max +* Alt-Ctrl-0 (zero) find local min + + Mouse Button Actions + -------------------- + Shift-Btn1Down turn on magnifier + Shift-Btn1Up turn off magnifier + Shift-Btn2Down turn on crosshair cursor + Shift-Btn2Up turn off crosshair cursor + Btn1Down create marker + Btn1Motion resize marker being created + Btn2Down zoom on cursor position + Btn3Down/Motion brightness/contrast scaling + +* Ctrl-Btn1Down create ruler marker +* Ctrl-Btn1Motion resize ruler marker +* Ctrl-Btn1Up destroy ruler marker + +* Alt-Motion freeze cursor readout + + + +2.11 Summary of Application Resources +===================================== + + Following is a summary of the task client and GUI resources, along +with select resources defined for the main image display Gterm widget. All +GUI elements can be controlled to some exten with resource definitions +although not all resources are useful. Feel free to contact site-support +with questions about how to change the appearance of the GUI. Future +versions of XImtool should feature a control panel to allow some of these +more critical resources to be redefined at runtime. + Format for the listing is resource-name, default-value, and type, +with an optional note appended. See the man page or online help for a full +description of all resources. A '*' in the leftmost column indicates a new +resource added with this release, some resource apply only to the alternative +GUI. + + + Client Program Resources + ------------------------ + defConfig 1 Int + defNFrames 0 Int + tileBorderWidth 3 Int + tileBorderColor 9 Int + autoscale False Boolean + antialias False Boolean + antialiasType boxcar String (1) + tileFrames False Boolean + highlightFrames True Boolean + gui default String (2) + imtoolrc /usr/local/lib/imtoolrc String + invert False Boolean + memModel Fast String (3) + basePixel 64 Int + maxColors 216 Int + cmapInitialize False Boolean + cmap1 none String (4) + cmap2 none String (4) + cmapDir1 none String (5) + cmapDir2 /usr/local/lib/imtoolcmap String (5) + input_fifo /dev/imt1i String (6) + output_fifo /dev/imt1o String (6) + unixaddr /tmp/.IMT%d String (7) +* ism_addr /tmp/.ISM%d String (8) +* ism_task "ism_wcspix.e wcspix &" String (9) + + Notes: + 1) Options: nearest, bilinear, area, blkavg, boxcar, lowpass, gaussian + 2) Either the string 'default' or the path to a valid GUI file + 3) Options: fast, small, beNiceToServer + 4) Name of a colormap file in the cmapDir[1|2] directory + 5) Path to directory of valid colormaps + 6) Path to FIFO pipe + 7) Unix socket path, a '%d' is replaced with the uid + 8) Unix socket path, a '%d' is replaced with the uid. This is the + socket used by plug-ins to negotiate a socket, once connected the + actual communications use a different socket. + 9) Command used to start the default WCS/Pixel readout ISM task. + + + GUI Resources + ------------- + autoscale True Boolean + zoomfactors 1 2 4 8 String + displayCoords True Boolean + displayPanner True Boolean + displayMagnifier False Boolean + blinkRate 1.0 Real (1) + pannerArea 150*150 Geometry + pannerGeom -5+5 Geometry +* magnifierArea 100*100 Geometry +* magnifierGeom +5+5 Geometry + wcsboxGeom -5-5 Geometry + maxContrast 5.0 Real +* showToolBar False Boolean +* showPanelBar False Boolean + warnings True Boolean +* centerBoxSize 5 Int +* peakCentroid True Boolean + + Notes: + 1) Value represents blink rate in seconds + + + Main Image Window (Gterm) Resources + ----------------------------------- + cmapName image String (1) + basePixel 64 Int + warpCursor True Boolean + raiseWindow True Boolean + deiconifyWindow True Boolean + ginmodeCursor circle Cursor + ginmodeBlinkInterval 500 Int (2) + color0 Black Pixel + color1 White Pixel + background Black Pixel + foreground White Pixel + width 512 Int + height 512 Int + + Notes: + 1) Any user-defined name is acceptable + 2) Value represents blink rate in milliseconds + + + +2.12 Summary of Command-Line Options +==================================== + + -basePixel <num> Base colormap pixel + -cmap1 <file> User colormap 1 + -cmap2 <file> User colormap 2 + -cmapDir1 <dir> User colormap directory + -cmapDir2 <dir> Default colormap directory + -cmapInitialize <bool> initialize colormap + -cmapName <name> Set Colormap name + -config <num> Set initial config number + -defgui Print default GUI and exit + -displayPanner <bool> Display Panner box + -displayMagnifier <bool> Display Magnifier box + -displayCoords <bool> Display WCS Coords box + -fifo <pipe> Fifo pipe to use for connection + -fifo_only Use fifo only for display + -gui <file> GUI file + -help Print help + -imtoolrc <file> Set frame buffer configuration file + -inet_only | -port_only Use inet only for display + -invert Start with inverted colormap + -ismdev <dev> ISM device (socket) template + -maxColors <num> Max number of image colors to allocate + -memModel <type> Memory model (fast|small|beNiceToServer) + -nframes <num> Number of frames to create at startup + -port <num> Set inet port to use for connection + -printConfig <name> Set printer config file + -tile Start in tile-frames mode + -unix <name> Set unix socket to use for connection + -unix_only Use only unix socket for display + <file> File to load at startup + + + +-------------------------------------------------------------------------------- + +3. OBM (WIDGET SERVER) REVISIONS +================================= + + +3.1 New Widgets +--------------- + + As part of the OBM modifications two new widgets were added to +the toolkit. The widgets were also added to the LISTRES application in +the X11IRAF sources which can be consulted for a complete list of resources. +LISTRES is not normally built with the system but is installed locally on +the NOAO/IRAF development machines. To build it yourself: + + % cd /<path>/x11iraf/obm/listres # go to the source directory + % xmkmf # create the Makefile + % make listres # compile the task + +It may then be used as e.g. "listres <widget>" to print a full list of +resources for the named widget. + + +3.1.1 Tabs Widget +------------------ + + The Tabs widget is a composite widget providing an "index tab" +appearance to it's child widgets. The children will normally be layouts +of more complex panels such as is done for the XImtool Control Panel. +Only the children of the active Tab are visible, the contents of other +Tabs are not displayed until that Tab is raised by selecting it with the +mouse and the left mouse button. + + A new Widget class command was added to allow GUI control of the +active Tab (e.g. to programmatically raise a Tab). This command is of +the form + + send <tab> setTop <name> + +where <tab> is the name of the Tab widget, and <name> is the name of the +child widget to be raised. Only one Tab widget is required to handle +child widgets, the Tabs will be created automatically. + + The widget code was also modified slightly to allow specific +resource values to hide the appearance of the widget from the display, e.g. +to completely change the appearance of a panel's layout by invisibly raising +a different Tab. For instance, assuming we have a Tab widget called +'opPanels' with several child widgets containing layouts of other widgets, +the following resource settings will hide the parent Tabs widget: + + *opPanels.tabLabel: + *opPanels.font: nil2 + *opPanels.height: 0 + *opPanels.width: 0 + *opPanels.borderWidth: 65535 + *opPanels.internalWidth: 32765 + *opPanels.internalHeight: 32765 + +Essentially we set NULL labels and sizes and values for the borderWidth +and internalHeight/Width that have the same bit pattern as a negative value +which internally means the borders are not drawn. The GUI callback code +can then use the setTop Widget method to raise the desired Tab meaning the +entire panel will change layouts automatically. This has advantages over +simply unmapping/mapping the layouts as it doesn't create a window resize +event which may cause the panel to "flash" during the change. + + An example GUI for this widget is in x11iraf$guidemo/tabs.gui + + +3.1.2 ListTree Widget +---------------------- + + The ListTree widget provides a nested list of items, where each +item is either a terminal item in a list, or another list. Lists may be +"open" meaning their contents are displayed, or "closed" meaning they are +shown as an individual item. This widget can best be used to represent +e.g. contents of a directory or sections/subsections of a document. + + A new Widget class command was added to allow GUI control of the +list contents. This command is of the form + + send <listree> setListTree <nested list> + +where <listree> is the name of the widget, and <nested list> is a list of +items to be displayed. This list should be a valid Tcl list, where items +in the list may be lists themselves to produce the nested format. All +ListTree widget are initially presented with the embedded lists "closed". +There is presently no way to append the contents of the list, the entire +list must be redefined with the above command. For example, the command + + send list setListTree {a1 {b1 { {a2 {a3 b3 c3 d3}} { b2 {z1 z2}} } } c1} + +would produce a nested list such as + + a1 + b1 + a2 + a3 + b3 + b2 + c1 + +Specifying the lists is a bit complex, but this widget is a nice way to +handle something like a table of contents in online documentation. + + An example GUI for this widget is in x11iraf$guidemo/ltree.gui + + +3.2 Dynamic Widget Creation (TBD) +--------------------------------- + + In the original implementation of the OBM, the GUI is created or +defined using the 'appInitialize' and 'createObjects' server commands. +appInitialize initializes the X display but the 'resources' argument just +sets the fallback resources for the application. A 'createObjects' call +then queries the fallback resource database (either by a named resource o +the 'objects' resource by default) to get the widget tree and then parses +that as a string to actually create the widgets in the OBM. + + The initial example GUIs all defined an "objects" resource as the +way to define the widgets and all the subsequent GUI tasks followed that form, +however appInitialize requires only a string of resource definitions ('object' +resources or otherwise), and createObjects can take an argument as to which +resource value specifies the widgets to create. For dynamic widget creation +all that's really required is that we have a way to append the fallback +resource database with a new list of widgets. + + The solution then was implement a new 'appExtend' server command +that simply sends a new resource string to the OBM to be merged into the +fallback resource DB. A plug-in would call this to load the widgets, then +call createObjects naming the resource to realize the widgets. The new +widgets are created as though they were specified from the start and can +receive messages, be destroyed, etc. The appExtend server method essentially +works by + + - getting the fallback resource database + - convert resource string arg to a new resource database + - combine the two resource databases + - write the combined database back as the new fallback database + +For example, the plug-in code for a "Hello, World" GUI panel would look +something like + + appExtend { + *test_objects:\ + toplevel TopLevelShell testPanel\ + testPanel Form testForm\ + testForm Label testLabel\ + testForm Command testQuit + + *testLabel.label: Hello, world! + *testQuit.fromHoriz: testLabel + *testQuit.label: Quit + } + createObjects test_objects + send testPanel map + +This code could be uploaded by an ISM plug-in and sourced as Tcl code +in a callback. It's also possible to define objects w/ existing parents +meaning a plug-in can add buttons to menubars or panels when they first +connect (e.g. a plug-in can add a new activation button for it to an +existing menubar on the GUI). + + The ability to dynamically create widgets means that plug-in modules +can create their own GUI components, but it also means that meta-widgets such +as Help panels, Image Display panels, etc can be recycled from a library of +code. To use this effectively, however, some rules need to be established +for an object naming convention, protocols for adding/deleting callbacks and +event handlers, and some method of object orientation is desired in the Tcl +code to make having multiple instances of a meta-widget in a GUI easier to +handle. These details are still largely TBD, the basic functionality now +exists in this version but may change as we take advantage of it and +implement new plug-in tasks or meta-widgets. + + +-------------------------------------------------------------------------------- + +4. CLIENT DISPLAY LIBRARY (CDL) REVISIONS +========================================== + + +4.1 Display Protocol Changes +----------------------------- + + The IIS display protocol used was modified to conform to the XImtool +and IRAF changes implemented for the support of WCS mapping information. +These are detailed in section 5.1 below. + + Unlike the IRAF IMD interface changes though, the WCS version can +be determined when the CDL is first opened so no explicit call to query +this is required by CDL applications. Tasks may still set/retrieve mapping +information and assume this is handled automatically by the interface. +The hi-level routines for displaying FITS or IRAF images will also send the +mapping information automatically, it's only when using the low-level +cdl_displayPix() routine or setting the WCS explicitly where the mappings +need to be set by the application. + + Changes remain completely backwards compatible so client tasks need +to be modified only to support the new XImtool features. + + +4.2 New Procedures +------------------- + + Three new public interface procedures were added in addition to the +internal changes made to support image mappings: + + cdl_setMapping() - Set mapping data to be sent with next cdl_setWCS() call. + Returns a non-zero status if mapping was set. + cdl_getMapping() - Get mapping data returned with last cdl_getWCS() call. + Returns a non-zero status if valid mapping available + cdl_queryMap() - Given a WCS number return the mapping data for that WCS. + Returns a non-zero status if valid mapping available. + + +4.2.1 C Calling Sequence +------------------------- + + valid = cdl_setMapping (cdl, region, sx,sy,snx,sny, dx,dy,dnx,dny, ref) + stat = cdl_getMapping (cdl, region, sx,sy,snx,sny, dx,dy,dnx,dny, ref) +stat = cdl_queryMapping (cdl, wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + +Where the arguments are defined as + + cdl - CDL package pointer returned by cdl_open() + region - user-defined name for the region (e.g. 'image', + 'subras1', 'ccd3', etc). + sx, sy, snx, sny - source rect in the object + dx, dy, dnx, dny - destinaton rect in the display frame buffer + ref - full node!/path/image[sec] image name, same as + was immap'd when the image was displayed. Used + for access after the display + wcs - WCS number for a specified mapping + + + +4.2.2 F77 Calling Sequence +--------------------------- + + cfsetmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cfgetmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cfquerymapping (wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref, ier) + +Where the arguments are defined as above and 'ier' is an error status code. + + +4.2.3 SPP Calling Sequence +--------------------------- + + cdl_setMapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cdl_getMapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cdl_queryMapping (wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref, ier) + +Where the arguments are defined as above and 'ier' is an error status code. + + +4.3 Demo Task Updates +---------------------- + + o The DISPLAY demo task in the 'examples' subdirectory was modified + to show how the cdl_setMappings() call is to be used when displaying + the image using the low-level procedures. + + o The CDLTEST test task in the 'test' subdirectory has a new 'Q' + command to test the cdl_queryMap() procedure. + + + +-------------------------------------------------------------------------------- + +5. TECHNICAL NOTES +================== + +5.1 IIS Protocol Changes +------------------------- + + For backwards compatability none of the existing IIS protocols were +modified completely, however we take advantage of unused registers to flag +the new features in existing functions (like read/write WCS). The WCS mapping +changes required only that the unused 'x' register be set to indicate the new +behavior was desired, e.g. the wcs text containing the extra mapping data. + + We also added two new WCS calls that allow us to query the WCS version, +or query a WCS by a specific number corresponding to a mapping. The WCS +version query will return a string such as "version=10" which can be parsed +by the client to get a version number '10' (corresponding to version 1.0). + + Because of the added mapping text the WCS string length was increased +from 320 to 1024 bytes, the string length used internally depends on whether +the 'x' register has been set. + + Support for the full 16 frames allowed by the bit-flag 'z' register +in the IIS header packet required the masking values be changed at various +places in the code. This was more a limitation of the initial implementation +than a required change to the protocol. + + A complete summary of the XImtool IIS protocol implementation follows. + + +5.1.1 IIS Protocol Summary +--------------------------- + + IIS Header Packet Summary + + TID Subunit Tct X Y Z T Data + +------------------+-------------+-----+---+---+----+---+--------+ +Read Data | IIS_READ|PACKED | MEMORY | -NB | x | y | fr | - | nbytes | +Write Data | IIS_WRITE|PACKED | MEMORY | -NB | x | y | fr | - | nbytes | +Read Cursor | IIS_READ | IMCURSOR | - | - | - | wcs| - | - | +Write Cursor | IIS_WRITE | IMCURSOR | - | x | y | wcs| - | - | +Set Frame | IIS_WRITE | LUT|COMMAND | -1 | - | - | - | - | 2 | +Erase Frame | IIS_WRITE | fb | FEEDBACK | - | - | - | fr | - | - | + | | | | | | | | | +Old Read WCS | IIS_READ | WCS | - | - | - | fr | - | 320 | +Old Write WCS | IIS_WRITE|PACKED | WCS | -N | - | - | fr |fb | 320 | + | | | | | | | | | +WCS Version? | IIS_READ | WCS | - | 1 | 1 | - | - | 320 | +WCS by Num.? | IIS_READ | WCS | - | 1 | - | fr |wcs| 1024 | +New Read WCS | IIS_READ | WCS | - | 1 | - | fr | - | 1024 | +New Write WCS | IIS_WRITE|PACKED | WCS | -N | 1 | - | fr |fb | 1024 | + +------------------+-------------+-----+---+---+----+---+--------+ + + +Where nbytes | NB = number of bytes expected or written + x = x position of operation in frame buffer coords + y = y position of operation in frame buffer coords + fr = frame number (passed as bitflag (i.e. 1, 2 ,4 8, etc) + fb = frame buffer config number (zero indexed) + N = length of WCS string + wcs = WCS number (usually zero) + Data = the number of bytes of data to be read or written + following the header packet. + + IIS_WRITE = 0400000 + IIS_READ = 0100000 + COMMAND = 0100000 + PACKED = 0040000 + IMC_SAMPLE = 0040000 + + MEMORY = 001 + LUT = 002 + FEEDBACK = 005 + IMCURSOR = 020 + WCS = 021 + + + +5.2 IRAF 'imd' Interface Changes. +---------------------------------- + + In order for the XImtool ISM task map exactly the same image that +was passed into the task displaying the image (i.e. the fully qualified +node!path prefix including any image section or kernel args). It was +necessary to modify the IIS SetWCS command to contain extra information +at the end of the normal WCS text. This is passed from XImtool to the ISM +at the time of the display if an ISM is already running, or when the ISM +first connects thereafter. + + To maintain complete backwards compatability it is not possible to +bury this change in the internals of the interface, therefore it will be +necessary for all tasks using the IMD interface to display images to make +revisions to use the new features. Tasks which are not changed will continue +to work, XImtool will simply disable the ISM when the display client connects +without indicating it is able to pass mapping information. Client tasks, +modified or not, will also continue to work when connecting to "mapping +unaware" display servers since the interface only send the extra mapping +information to servers which are expecting it. + + To modify a task to make use these changes, there are just a few +routines you need to be aware of: + + imd_wcsver() - Query the server for new capabilities. Returns a + non-zero version if the server can use the new + mapping functionality. +imd_setmapping() - Set mapping data to be sent with next imd_putwcs() call +imd_getmapping() - Get mapping data returned with last imd_getwcs() call. + returns a non-zero status if valid mapping available + imd_query_map() - Given a WCS number return the mapping data. Returns a + non-zero status if valid mapping available + +where the calling sequence is + + imd_setmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + valid = imd_getmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + status = imd_query_map (wcs, reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + version = imd_wcsver () + +In order to maintain compatability with existing servers as well as take +advantage of the new ximtool features, the idea is that all interfaces will +remain the same and any program wishing to use these features will need a +slight modification to 1) determine whether mappings are supported via a +call to imd_wcsver(), and 2) use the new imd_[sg]etmapping() procedures to +set and retrieve the mapping information. imd_query_map() can be used to +query for the mapping using the wcs number returned from e.g. a cursor read. +Details and examples of these modifications are included below. + + +5.2.1 Program Initialization +---------------------------- + + For a program to use mappings it must first query the server to see +if this is supported, the reply also serves to initialize the imd interface. +This is done using the imd_wcsver() call. For example, in the DISPLAY task +during startup one would do something like + + # Query server to get the WCS version, this also tells us whether + # we can use the all 16 supported frames. + if (imd_wcsver() == 0) + call clputi ("display.frame.p_max", 4) + else + call clputi ("display.frame.p_max", 16) + +The call to imd_wcsver() in this case is used to reset the number of allowed +frames depending on the server. + + This call is REQUIRED before mappings can be used by the interface. +Internally, the interface defaults to a "version" of zero meaning the server +does not support mappings, once the procedure is called the server reply +value is stored in the interface common and returned as the function value. +The return value is always an integer, zero means the server does not support +mappings and a non-zero value is the WCS version number of the display +change (e.g. a value of 10 is version 1.0, 11 is 1.1, etc). + + A 'disable_wcs_maps' boolean environment variable can be set by +the user to force this procedure to always return zero and disable mappings +in case a problem is found after release or the old behavior is desired. + + +5.2.2 WCS Text Changes +---------------------- + + Without getting into the details, if a server is found to be capable +of using mappings in the imd_wcsver() call, the WCS string sent/read will +have two additional lines of information to define the mapping. Specifically, + + name - title\n + a b c d tx ty z1 z2 zt\n + region_name sx sy snx sny dx dy dnx dny\n + object_ref + +where the new parameters are defined as + + region_name - user-defined name for the region (e.g. 'image', + 'subras1', 'ccd3', etc). + sx, sy, snx, sny - source rect in the object + dx, dy, dnx, dny - dest rect in the display frame buffer + object_ref - full node!/path/image[sec] image name, same as + was immap'd when the image was displayed. Used + for access after the display + + Since the interfaces remain the same a separate imd_setmapping() +or imd_getmapping() call is required to set/get the additional mapping data. +For example, + +To set the WCS: + + # Set the mapping info to be written with the WCS. + call imd_setmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + + # Write the WCS and mapping info to the data. + call imd_putwcs (ds, frame, Memc[imname], Memc[title], + a, b, c, d, tx, ty, W_ZS(wdwin), W_ZE(wdwin), W_ZT(wdwin)) + + +To read the frame WCS: + + # Query the server for a wcs. + if (imd_getwcs (frame, server, image, sz_image, title, sz_title, + a,b,c,d, tx,ty) == OK) { + + # If we got that okay, get the mapping information returned. + if (imd_getmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, obj) > 0) { + : + } + } + +In all cases if the imd_wcsver() initialization says the server can't +do mappings these calls will be no-ops. + + For multiple-image displays to a single frame it's important to +remember that the default WCS for the frame will be the *last* WCS set +by the client. For example, a mosaic display can set a wcs and mapping +for each of the subrasters, but a final SetWCS call is required to define +an overall WCS for the frame defining the "detector coords". Note that the +'objref' string should include the MEF extension number so it's mapped +properly by the ISM. + + +5.2.3 Cursor Reads +------------------- + + The imd_query_map() procedure is used to return the mapping for a +particular WCS number, such as that returned by a cursor read. It will do +a new WCS query for this regardless of a previous imd_getwcs() call. Typical +usage would be something like the following in IMEXAMINE: + +procedure t_imexamine () + : +begin + : + wcsver = imd_wcsver() + : + : + while (ie_gcur (ie, curtype, x,y,wcs, key, cmd, SZ_LINE) != EOF) { + + if (imd_query_map (wcs,reg,sx,sy,snx,sny,dx,dy,dnx,dny,imname) > 0) { + .... add image name to list + } + + } + : +end + +[NOTE: in this example the ie_gcur() procedure was modified to return the + wcs from the cursor read.] + +The WCS number returned by a cursor read now corresponds to the object id +used in the server. It still contains the frame number as before, but the +wcs number itself is used to identify the mapping. + + +5.3 ISM Communications +----------------------- + + The ISM (Image Support Module) can be any external task which +connects to XImtool over a socket. Communications are limited to simple +null-terminated text strings. In most cases these strings are just the +standard OBM messages sent to XImtool objects but can also include Tcl +callback code (either ISM-specific callbacks, procedures which can be +added to the callback list for existing XImtool objects, or even new GUI +code to create panels and new objects). + + +5.3.1 Socket Connection +------------------------ + + The ISM first requests a connection to XImtool on a dedicated +socket whose default value is "/tmp/.ISM%d", where the '%d' is replaced +by the userid allowing multiple users on a machine to have independent +sockets. The XImtool 'ism_addr' resource or "-ismdev" command-line option +can be used to change this address, a value of 'none' will disable ISM +communications. The socket may also be set with an ISMDEV environment +variable which will override the resource or command-line options. + + Once a connection request is received, XImtool replies with +a message telling the ISM to reconnect on a different socket, it then +frees the initial connection allowing multiple other ISMs to request +their own connection. The communications between XImtool and the ISM +are carried out entirely over this second negotiated socket. Once connected, +the ISM appears as just another named object which can receive OBM messages. + + +5.3.2 Communications Protocol +------------------------------ + + Messages from the ISM are written to the connection socket and must +be preceeded by one of the following keywords: + + callback Negotiate a connection on another socket + ready Client is ready to begin processing + quit Client is shutting down and disconnecting + send Send a message to another object + + +Messages are of the form: + + connect <name> Request a connection for the <name> ISM + + ready <name> Reconnection request for the <name> ISM on + negotiated socket, ISM is ready to processing. + + send <obj> '{' <msg> '}' Send <msg> to the named <obj>. The message + may be any valid string that will be under- + stood by the recipient. The object may be + any object in the GUI or OBM (see below). + + quit ISM is shutting down. The named is determined + from the communications channel, ISM is + responsible for any cleanup of it's callbacks + before issuing the shutdown. + +All messages must be null-terminated. XImtool will buffer the text until +a complete message is received. Once an ISM client has delivered a QUIT +message no further messages will be sent the that ISM. + + In OBM terminology the ISM is a named Client class object, where +the name is set in the connection request. Messages sent to the ISM should +use this name, messages sent to "client" are still interpreted to mean the +XImtool client. + + The content of messages delivered to the ISM are totally free-form +and may contain any text the ISM is expected to understand. + + +5.3.3 GUI Objects +------------------ + + While the ISM can send a message to any object in the task, there +is a GUI Parameter object called 'ism_msg' designed especially to process +messages from the ISM. The callback in the GUI is expecting a message +beginning with one of the following keywords: + + source Source message text as Tcl code + alert Message contains error text to be displayed in the + GUI 'alert' box + deliver Message text should be passed to a callback routine + specific to that ISM. This processing callback may + have been previously uploaded. The message text + may be any form the processing callback is expected + to understand. + info Message text is status output intended for the + XImtool 'info' panel (connect/disconnect requests, etc) + + +In all cases the message is expected to be of the form + + <cmd> <ism_name> [ <arg1> <arg2> <...> ] + +where <cmd> is one of the above keywords, <ism_name> is the name of the +ISM sending the message. The remainder of the message is passed as an 'argv' +list to the processing callback uploaded for the ISM. The ISM is responsible +for formatting these messages. + + |