PRO COLORSET, RETAIN=RETAIN, DECOMPOSED=DECOMPOSED, QUIET=QUIET

;+
; NAME:
;    COLORSET
;
; PURPOSE:
;    Select true color (24 bit) if available, or pseudo color (8 bit) visual
;    consistently on X, Windows, and Macintosh.
;
; CATEGORY:
;    Startup utilities.
;
; CALLING SEQUENCE:
;    COLORSET
;
; INPUTS:
;    None
;
; OPTIONAL INPUTS:
;    None
;	
; KEYWORD PARAMETERS:
;    RETAIN        Specifies the default method used
;                  for backing store when creating new windows.
;                  0 => No backing store
;                  1 => Server or window system performs backing store
;                  2 => Make IDL perform backing store (DEFAULT)
;    DECOMPOSED    Specifies the the way in which graphics
;                  color index values are interpreted when using displays with
;                  decomposed color (TrueColor or DirectColor visuals).
;                  0 = > Color indices given by single 8 bit values (DEFAULT)
;                  1 = > Color indices given by three 8 bit values
;    QUIET         If set, no color information is printed
;                  (default is to print the color table size, and number of colors)
;              
; OUTPUTS:
;    None
;
; OPTIONAL OUTPUTS:
;    None
;
; COMMON BLOCKS:
;    None
;
; SIDE EFFECTS:
;    This routine changes the IDL visual for the rest of the IDL session.
;
; RESTRICTIONS:
;    Only affects X, WIN, and MAC displays.    
;    Only has an effect if run before any windows have been
;    created, and if no DEVICE commands have been executed.
;
; EXAMPLE:
; ;Execute the following command immediately after IDL startup.
; colorset
;
; MODIFICATION HISTORY:
;    Written by: Liam.Gumley@ssec.wisc.edu
;-

rcs_id = "$Id: colorset.pro,v 1.2 1999/04/20 15:04:29 gumley Exp $"

;- Check keyword values

if n_elements( retain ) ne 1 then retain = 2
if n_elements( decomposed ) ne 1 then decomposed = 0

;- Check keyword flags

if not keyword_set( quiet ) then quiet = 0

;- Check if a window has been created previously

if !d.window ge 0 then begin
  message, 'Window already created in this session - COLORSET may have no effect.', /continue
  message, 'To ensure COLORSET works, call it before any windows are created.', /continue
endif

;- Test for supported displays

supported = 0

case 1 of

  ;- Windows case (visual cannot be changed)

  !d.name eq 'WIN' : begin
    device, decomposed=decomposed, retain=retain
    supported = 1
  end
  
  ;- X and Macintosh case (will revert to 8 bit visual if 24 bit fails)

  !d.name eq 'X' or !d.name eq 'MAC' : begin
    device, true_color=24, decomposed=decomposed, retain=retain
    supported = 1
  end
  
  ;- Unsupported display
  
  else : message, 'Not supported on the ' + !d.name + ' device', /continue
  
endcase

;- If display supported, lock in window characteristics, and report what happened
    
if supported then begin

  ;- Create a window to lock in the visual type for this IDL session

  old_window = !d.window
  window, /free, /pixmap
  wdelete, !d.window
  if old_window ge 0 then wset, old_window

  ;- Report what happened

  if not quiet then begin
    print, 'Display device  : ', !d.name
    print, 'Color table size: ', strcompress( !d.table_size, /remove_all )
    print, 'Number of colors: ', strcompress( !d.n_colors, /remove_all )
    print, ''
  endif
  
endif

END