The current Array (Developer Reference) The current Array (Developer Reference)Alongside the ds9 array, DS9's Tcl library keeps a second, much smaller global array, current, that tracks which frame/channel/mode is presently selected. This is the array behind the $::current(frame) handle used throughout Frame Commands and the Command Line Options examples, e.g.:
global current
if {$current(frame) != {}} {
puts "current frame is $current(frame), zoom is $current(zoom)"
}This page documents every element of current, derived from its initialization in CurrentDef (ds9/library/util.tcl) and its use across the rest of the library.
A note on pcurrent: six of the elements below (display, mode, zoom, rotate, orient, align) have a same-named counterpart in a separate global array, pcurrent — the persisted preference written to ~/.ds9.ini (the Preferences dialog's radiobuttons for "default display mode," "default pointer mode," and default zoom/rotate/orientation/align settings write directly into pcurrent). current(...) itself is always the live value — the actual state of the currently-selected frame or the UI right now — not the saved default; use pcurrent(...) only if you specifically want to read or change the persisted startup preference. This mirrors the ds9/pds9 relationship described on the ds9 array page.
The selected frame and its widgets
- current(frame)
- Frame command name (e.g. Frame1) or {} if no frame exists. The canvas-item command of the currently-selected frame — the handle used for every frame command, e.g. $::current(frame) get zoom. Set whenever the user selects a different frame (click, Tab, Frame menu, -frame/XPA frame commands, etc.); read-only in the sense that a script should change frames through those normal mechanisms rather than by assigning this variable directly, since a raw assignment would desynchronize it from the menus, panner, and info panel. Safe and common to read.
- current(colorbar)
- Canvas-item command name or {}. The colorbar item associated with the current frame: normally ${current(frame)}cb (a per-frame colorbar) or the single shared item named colorbar, depending on the colorbar-display preference; {} when there is no current frame. Kept in sync with current(frame) automatically. Safe to read; not meant to be set directly.
- current(ext)
- String, usually {}. Caches the FITS extension name last used to look up a colormap level for a mosaic frame under local scaling, so repeated lookups at the same pointer position can skip redundant work. Internal; not useful to a script.
- current(cursor)
- String, a Tk cursor name, or {}. Caches the cursor most recently applied to the main canvas, so the library can skip a redundant configure -cursor call when the cursor hasn't actually changed. Internal; not useful to a script.
Composite-frame channel selection
These select which channel of a multi-channel composite frame subsequent single-channel operations (e.g. colormap edits) apply to; each is mirrored from the frame itself and used to drive the RGB/HSV/HLS menu's radiobuttons.
- current(rgb)
- String, one of red | green | blue; default red. The active channel of an RGB composite frame. See the frame rgb command.
- current(hsv)
- String, one of hue | saturation | value; default hue. The active channel of an HSV composite frame. See the frame hsv command.
- current(hls)
- String, one of hue | lightness | saturation; default hue. The active channel of an HLS composite frame. See the frame hls command.
Display and pointer mode
- current(display)
- String, one of single | tile | blink | reveal | fade; default single. The frame display/layout mode, mirrored into ds9(display) (see the ds9 array) and bound directly to the View/Frame menu's display-mode radiobuttons via -command DisplayMode. Because the menu entries invoke DisplayMode as a side effect of setting this variable, a script should call the same mechanism (or the equivalent -tile/-single/... command line option or XPA point) rather than assigning current(display) directly, which would only change the cached value without actually re-laying-out the frames.
- current(mode)
- String, one of none (default, the plain pointer) | region | crosshair | colorbar | pan | zoom | rotate | crop | catalog | footprint | examine | 3d | illustrate (also transiently iexam while the interactive-examine dialog is driving it). The active Edit-menu pointer mode, i.e. what a mouse click/drag on the canvas currently does. Like current(display), this is bound to the Edit menu's radiobuttons via -command ChangeMode; change it through the menu, the -mode command line option, or the equivalent XPA point rather than by assigning the variable directly.
- current(mode,illustrate)
- Boolean (0/1), default 0. A sub-flag of Illustrate mode: 1 while an illustrate drawing gesture is actively in progress on the canvas, toggled back to 0 when it finishes. Internal; not useful to set from a script.
Current frame's view settings
These four mirror the currently-selected frame's actual zoom/rotation/orientation/WCS-alignment, refreshed whenever the frame selection changes or the corresponding menu/dialog action runs (see UpdateZoomMenu in ds9/library/mzoom.tcl). They exist to back the Zoom/Pan menu's checkmarks and the Pan/Zoom/Rotate dialog's fields. A script that changes a frame's zoom/rotate/orient/align by calling the frame command directly (bypassing the menu/dialog code) should not assume these mirrors have been refreshed — query [$current(frame) get zoom] etc. directly for a value guaranteed to be current.
- current(zoom)
- Two numbers {<x> <y>}, default {1 1}. Mirrors the current frame's zoom factor; see the frame zoom command.
- current(rotate)
- Number of degrees, default 0. Mirrors the current frame's rotation angle; see the frame rotate command.
- current(orient)
- String, one of none (default) | x | y | xy. Mirrors the current frame's flip orientation; see the frame orient command.
- current(align)
- Boolean (0/1), default 0. Mirrors whether the current frame's WCS is aligned to the other frames; see the frame wcs command's align forms.