;+ ; NAME: ; STATUSLINE ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Maintain a one-line status line on a VT100-compatible terminal. (Unix) ; ; MAJOR TOPICS: ; Text Output, Terminal. ; ; CALLING SEQUENCE: ; STATUSLINE, string, column, LENGTH=length, [/CLOSE,] ; [/CLEAR,] [/LEFT,] [/RIGHT,] [/QUIET,] [/ENABLE,] [/DISABLE] ; ; DESCRIPTION: ; ; STATUSLINE maintains the current line of a VT100- or ; ANSI-compatible terminal, usually as a status line. ; ; Programs that run for extended periods of time can inform the user ; of the status of the computation by printing vital information. ; Instead of cluttering the console by using the PRINT procedure, ; which uses a new line with each call, STATUSLINE will re-use the ; same line. This can make a cleaner interface. ; ; STATUSLINE interacts directly with the Unix terminal device, ; sending VT100-compatible cursor commands. As a side effect it ; opens the terminal device /dev/tty and allocates a logical unit ; number. Picky programmers should call STATUSLINE, /CLOSE to close ; the file unit. ; ; Procedures that finish their computation, or wish to make normal ; output to the console should first clear the terminal line with ; STATUSLINE, /CLEAR. This will ensure that the console is ; uncluttered before printing. ; ; By default, STATUSLINE enables output for terminal types vt100, ; vtnnn, xterm, dec, or ansi. *No* output appears on other ; terminals. You can enable it explicitly by calling STATUSLINE, ; /ENABLE, and disable it by calling STATUSLINE, /DISABLE. ; ; INPUTS: ; ; STRING - A string to be placed on the current line. ; ; OPTIONAL INPUTS: ; ; COLUMN - The starting column number, beginning with zero. ; Default: zero. ; ; INPUT KEYWORD PARAMETERS: ; ; LENGTH - the record length, an integer. Strings longer than this ; length will be truncated. ; Default: strlen(STRING) ; ; CLEAR - if set, clear the current line to the end. Control ; returns immediately (i.e., no output is made). ; ; LEFT - if set, then left justify the string within the record. ; If the string is longer than the record length, then the ; leftmost portion of the string is printed. ; The Default (if /RIGHT is not given). ; ; RIGHT - if set, then right jusfity the string within the record. ; If the string is longer than the record length, then the ; rightmost portion of the string is printed. ; ; QUIET - if set, then no output is made (for this call only). ; ; NOCR - if set, no carriage return operation is performed after ; output. This also has the side effect that in subsequent ; calls, column "0" will not cause the cursor to move. ; Default: cursor returns to column 0 after each output. ; ; ENABLE - if set, then permanently enable output by STATUSLINE. ; Normally STATUSLINE automatically enables output only for ; vt100-compatible terminals. By setting /ENABLE, you ; override this automatic test. However, /QUIET will ; still override ENABLE in an individual call. ; ; DISABLE - if set, then permanently disable output by STATUSLINE. ; When disabled, no output is ever produced. Output can ; only be re-enabled again by using the /ENABLE flag. ; ; CLOSE - if set, instruct STATUSLINE to close the terminal device ; logical unit number. Users should perform this operation ; when the computation has finished so that the terminal ; device is not left dangling open. If, at a later time, ; STATUSLINE is called again, the terminal device will be ; re-opened. ; ; OUTPUTS: ; NONE ; ; SEE ALSO: ; PRINT, PRINTF ; PRINTLOG - to maintain transcript of IDL output ; ; MODIFICATION HISTORY: ; Written, CM, 1997-1998 ; Documented, CM, Sep 1999 ; Added NOCR keyword, CM, 28 Oct 1999 ; Doesn't crash if can't write to TTY. Returns silently. CM, 16 ; Nov 1999. ; Added PRINTLOG to "SEE ALSO", CM, 22 Jun 2000 ; Keyword QUIET now causes earlier exit; catch errors in the CLEAR ; case, CM, 12 Oct 2001 ; Allow variations on the "xterm" terminal type, CM, 26 Jun 2007 ; ; $Id: statusline.pro,v 1.5 2007/06/26 16:15:12 craigm Exp $ ; ;- ; Copyright (C) 1998, 1999, 2000, 2001, 2007, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy and distribute unmodified copies for ; non-commercial purposes, and to modify and use for personal or ; internal use, is granted. All other rights are reserved. ;- pro statusline, str, col, length=length, clear=clear, $ left=left, right=right, quiet=quiet, close=close,$ enable=enable, disable=disable, nocr=nocr common statusline_common, statusline_enabled, statusline_unit if n_elements(statusline_enabled) EQ 0 then begin termtype = getenv("TERM") statusline_enabled = 0 if strmid(termtype,0,2) EQ 'vt' OR $ strmid(termtype,0,5) EQ 'xterm' OR $ strmid(termtype,0,3) EQ 'dec' OR termtype EQ 'ansi' then $ statusline_enabled = 1 endif if keyword_set(enable) then begin statusline_enabled = 1 return endif if keyword_set(disable) then begin statusline_enabled = 0 return endif if keyword_set(quiet) OR statusline_enabled EQ 0 then return do_open = 0 if n_elements(statusline_unit) EQ 0 then do_open = 1 if n_elements(statusline_unit) GT 0 then begin if statusline_unit(0) LT 0 then do_open = 1 ;; If the user closes the file behind our back (eg. CLOSE, /ALL) if statusline_unit(0) GE 0 then begin fs = fstat(statusline_unit(0)) if fs.open EQ 0 then do_open = 1 endif endif if do_open then begin statusline_unit = -1L if keyword_set(close) then return openw, unit, '/dev/tty', /get_lun, error=open_error if open_error NE 0 then return statusline_unit = unit endif if keyword_set(close) AND n_elements(statusline_unit) GE 1 then begin if statusline_unit(0) LT 0 then return free_lun, statusline_unit(0) statusline_unit = -1L return endif ;; ASCII carriage return, used for printing the status line cr = string(13b) esc = string(27b) ;; Escape char if keyword_set(clear) then begin outstring = string(' ', cr, format='(A79,A,$)') ;; Prevent errors from stopping the show catch, catcherr if catcherr EQ 0 then writeu, statusline_unit, outstring return endif if NOT keyword_set(right) then left = 1 if n_params() EQ 0 then begin message, 'USAGE: STATUSLINE, str, col, [length=length,]', /info message, ' [/clear,] [/left,] [/right,] [/quiet,] [/close]', /info return endif if n_elements(str) EQ 0 then return if n_elements(length) EQ 0 then length = strlen(str) if n_elements(col) EQ 0 then col = 0L if col LT 0 then col = 0L newstr = str slen = strlen(str) if slen GT length then begin if keyword_set(left) then $ newstr = strmid(newstr, 0, length) $ else $ newstr = strmid(newstr, slen-length, length) endif else begin blanks = ' ' if keyword_set(right) then $ newstr = strmid(blanks, 0, length-slen) + newstr endelse outstring = '' if col GT 0 then $ outstring = outstring + esc + '['+strtrim(col,2) + 'C' outstring = outstring + newstr if NOT keyword_set(nocr) then outstring = outstring + cr ;; Prevent errors from stopping the show catch, catcherr if catcherr EQ 0 then writeu, statusline_unit, outstring return end