; $Id: xbackregister.pro,v 1.3 1993/04/07 00:31:08 ali Exp $

; Copyright (c) 1992-1993, Research Systems, Inc.  All rights reserved.
;	Unauthorized reproduction prohibited.

PRO XBackRegister, NAME, ID, UNREGISTER = UNREGISTER, CHECK = check,  $
	FOUND = found

;+
; NAME: 
;	XBACKREGISTER
;
; PURPOSE:
;
;      ------------------------------------------------------------------
;      | PLEASE NOTE: This routine is OBSOLETE. It's functionality is   |
;      | provided by the TIMER keyword to the WIDGET_CONTROL procedure. |
;      ------------------------------------------------------------------
;
;	Register a background task with a currently-managed widget 
;	application.
;
; CATEGORY:
;	Widgets.
;
; CALLING SEQUENCE:
;	XBACKREGISTER, Name, ID
;
; INPUTS:
;	Name:	A scalar string that contains the name of the background 
;		routine to be registered.
;
;	ID:	The top-level base widget ID of the widget application that 
;		the background routine is associated with.
;
; KEYWORD PARAMETERS:
;   UNREGISTER:	Set this keyword to unregister a widget that is already 
;		registered as a background task.  If this keyword is not
;		specified, the background task is registered.
;   CHECK:	If set, only check if the named task is registered
;		as a background task.  Return 0 in FOUND if not, 1 
;		in FOUND if it is.
;   FOUND: 	Value returned if CHECK is set.
;
; COMMON BLOCKS:
;	MANAGED
;	XBCKREG_OBSOLETE
;
; SIDE EFFECTS:
;	Brings the widget to the front of the desktop if it finds one.
;
; RESTRICTIONS:
;      ------------------------------------------------------------------
;      | This routine is OBSOLETE. It's functionality is                |
;      | provided by the TIMER keyword to the WIDGET_CONTROL procedure. |
;      ------------------------------------------------------------------
;
;	Only one instance of a given background task is allowed for any one 
;	widget ID.;
; PROCEDURE:
;	Insert and delete background events from the XMANAGER's common block.
;
; MODIFICATION HISTORY:
;	Written by Steve Richards, January, 1991
;	Added CHECK keyword, James Tappin, University of Birmingham, Feb, 1993.
;-

COMMON MANAGED, ids, names, $
		nummanaged, inuseflag, $
		backroutines, backids, backnumber, nbacks, validbacks, $
		blocksize, $
		cleanups, $
		outermodal
COMMON MANAGED, xbckreg_obsolete, obsolete

if not KEYWORD_SET(obsolete) then begin
  obsolete = 1
  message,/INFO,"The XBACKREGISTER procedure is obsolete. It is superceeded by the TIMER keyword to the WIDGET_CONTROL procedure."
endif

UC_NAME = strupcase(NAME)
IF(N_PARAMS() NE 2) THEN MESSAGE, "Incorrect number of parameters"
IF(NOT(KEYWORD_SET(inuseflag))) THEN MESSAGE, "XManager not in use"
IF(nbacks EQ 0) THEN begin
  alreadythere = -1
  found = 0
endif ELSE begin
  alreadythere = WHERE((backids EQ ID) and (backroutines eq UC_NAME), found)
endelse

if KEYWORD_SET(check) THEN RETURN

IF(KEYWORD_SET(UNREGISTER)) THEN BEGIN	; Background task is to be removed
  IF(found ne 0) THEN BEGIN
    backroutines(alreadythere) = ''
    backids(alreadythere) = 0L
    nbacks = nbacks - found
  ENDIF ELSE BEGIN
    message,'Background task not registered'
  ENDELSE

ENDIF ELSE BEGIN			;background task is to be added
  IF(found ne 0) THEN MESSAGE, "Routine already registered"
  nbacks = nbacks + 1
  IF(N_ELEMENTS(backids) EQ 0) THEN BEGIN
    backids = LONARR(blocksize)				;build the first block
    backroutines = STRARR(blocksize)			;for background tasks
    freebacks = 0
  ENDIF ELSE BEGIN					;otherwise, just
    freebacks = WHERE(backids EQ 0, found)		;find free spots or
    IF(found EQ 0) THEN BEGIN				;make new ones if full
      backids = [backids, LONARR(blocksize)]
      backroutines = [backroutines, $
			STRARR(blocksize)]
      freebacks = nbacks - 1
    ENDIF
  ENDELSE

  backids(freebacks(0)) = ID
  backroutines(freebacks(0)) = UC_NAME

  WIDGET_CONTROL, ID, /DELAY_DESTROY
  WIDGET_CONTROL, /EVENT_BREAK

ENDELSE

  backnumber = 0			; Start at the beginning of the list
  validbacks = WHERE(backids NE 0)	; Update the valid list

END