;+
; Project     : SOHO - CDS     
;                   
; Name        : QLMGR
;               
; Purpose     : Management of CDS QuickLook data structure variables.
;
; Explanation : In order to manage the windows displaying information
;               concerning a specific CDS QL data structure, all QL data
;               structures (QLDSs) are given an ID with a registration
;               number. The registration number serves as an index to the
;               array QL_DATA, which contains a structure for each registered
;               QLDS.
;
;               This structure contains the widget IDs of each base window
;               that may be generated for a specific QLDS, so that, for
;               instance, the position of any earlier copy of a window that is
;               to be created may be retrieved, and used to position the new
;               window at the same screen offset.
;
;               To avoid confusion when IDL's SAVE/RESTORE ; commands are used
;               to store QLDSs between sessions, the QL_ID variable in common
;               block QLMGR is set to ; the value of SYSTIME(1) upon
;               initialization of QLMGR, ; and every QLDS' QL_ID are set to
;               this value upon ; registration.
;
;               If the QLDS's QL_ID is identical to the one in the QLMGR
;               common block, the QLDS is taken as already registered.
;
;               QLMGR will also check as far as possible whether the supplied
;               parameter is a valid QLDS, and it is recommended that this
;               routine be used in every procedure that needs to be sure of
;               this, by using the optional output parameter VALID
;
;
; Use         : QLMGR, QL_data_struct
;    
; Inputs      : QL_data_struct : 
;                       A CDS QL Data structure, as described in 
;                       "CDS QL data format", version 1.1
;               
; Opt. Inputs : None.
;               
; Outputs     : None.
;               
; Opt. Outputs: VALID:  If supplied, it is set to TRUE (NOT 0) if
;                       the supplied QL_data_struct is a valid
;                       QLDS
;               
; Keywords    : INIT:   When set, the QLMGR is reset, invalidating
;                       any previous registration of QLDSs.
;
; Calls       : DATATYPE()
;
; Common      : QLMGR:
;                       QL_ID:  The identification of the current
;                               QLMGR session. Set to SYSTIME(1)
;                               upon initialization of QLMGR
;                       QL_DATA:An array of structures containing
;                               wiget base ID's of windows with
;                               information concerning a specific
;                               QLDS
;
;               QLSAVE: QLDS : Cache for display routines
;                       SAVED: Set to 1 if current QLDS has been
;                               saved on a storage base.
;
; Restrictions: None.
;               
; Side effects: Alters the QL_ID and QL_NO tags of the supplied
;               QLDS to reflect the current QLMGR's registration.
;               
; Category    : Data_Handling, CDS, QuickLook
;               
; Prev. Hist. : None.
;
; Written     : Stein Vidar Hagfors Haugan, 7 October 1993
;               
; Modified    : SVHH, 8 October 1993 -
;                       Fixed bug: VALID is now set to NOT 0 to
;                       handle 'if NOT valid ...' constructs in
;                       caller program.
;               SVHH, 19 October 1993
;                       Additional tags in the QLINFO structure.
;               SVHH, 20 November 1993
;                       Additional tags.
;               SVHH, Version 2, 4-October-1995
;                       Additional tags + renamed some tags.
;                       Checking of ALL tags dropped.
;               Version 3, SVHH, 22-February-1996
;                       Added tag "HDRTEXT"
;               Version 4, SVHH, 15 August 1996
;                       Compatible with both new and old storage system
;               Version 5, SVHH, 15 July 1997
;                       storagebase => storage_h
;               Version 6, DMZ, 8 June 1999
;                       made VALID a byte variable
;                       
; Version     : 6
;-            

PRO QLMGR,a,init=init,valid
  common QLMGR,QL_ID,QL_DATA
  common QLSAVE,QLDS,SAVED
  
  On_Error,2
  IF N_params() lt 1 THEN message,"Use: QLMGR,QL_DATA [,VALID]"
  
;
; Check for valid structure
;
  
  valid=0b
  
  IF datatype(a) ne 'STC' THEN BEGIN
      IF N_params() eq 2 THEN return
      help,a
      message," is not a valid CDS QL data structure"
  END
  
  dummy = where(Size(a) ne [1,1,8,1],count)
  
  IF count ne 0 THEN BEGIN
      IF n_params() eq 2 THEN return
      help,a
      message," is not a valid CDS QL data structure"
  EndIF
  
  tags = tag_names(a)
  
  deftags = ["QL_ID","QL_NO"]
  
  dummy = where(tags ne deftags,count)
  
  IF count gt 0 THEN BEGIN
      IF n_params() eq 2 THEN return
      help,a,/str
      message," is not a valid CDS QL data structure"
  END
  
  valid = 1b
  
  On_Error,0
  
;
; Valid structure: is QLMGR initialized?
;
  
  IF N_elements(QL_ID) eq 0 or Keyword_SET(init) THEN BEGIN
      QL_ID = systime(1)
      QL_DATA = {QLINFO,          $
                 storage_h:0L,    $ ; ID of the storage handle
                 stored:0,$
                 dsp_menubase:0L,         $
                 xpmenubase:0L,   $
                 examplebase:0L,          $ ; Window template demonstration
                 slitposbase:0L,          $
                 ndspspecbase:0L,         $
                 gdspspecbase:0L,         $
                 dspexpbase:0L,   $
                 dspwavbase:0L,   $
                 infohdrbase:0L,          $
                 infowndbase:0L,          $
                 infoauxbase:0L   $
                }
  END
  
;
; If a.QL_ID is the same as the id for this run of
; QLMGR, we do nothing. If not, register the chunk of
; data..
;
  
  IF a.QL_ID ne QL_ID THEN BEGIN
     a.QL_ID =  QL_ID
     a.QL_NO =  N_elements(QL_DATA)
     QL_DATA =  [QL_DATA, {QLINFO}]
  END
  
END