;+
; NAME:
;	CHECKBOX
;
; PURPOSE:
;	Simplifies use of checkboxes that control widget code execution. Utilizes bitwise setting
;	or clearing in a LONG number, and returns bit set/clear information about such numbers.
;
; AUTHOR:
;	Pavel A. Romashkin, Ph. D.
;
; CATEGORY:
;	Utilities.
;
; CALLING SEQUENCE:
;	Result = CHECKBOX(TARGET, BIT_NO, [ACTION=0or1, /GET, /WIDGET, /VARIABLE, NAME='a_string'])
;
; RETURNS:
;	Either a modified variable (if 
;
; INPUTS:
;	TARGET - either a widget ID of a nonexclusive base, or a LONG or INT variable.
;	BIT_NO - number of the bit toset or clear (same as sequential number of the given checkbox).
;
; KEYWORD PARAMETERS:
;	ACTION - uset to toggle the bit ON for that checkbox. 1 is to SET, 0 is to CLEAR.
;	GET - use to make CHECKBOX return the status of the bit: 1 for SET, 0 for CLEAR.
;	RETURN - set to return the properly set value without modifying TARGET.
;		By default, TARGET will be altered to contain new value.
;	WIDGET - set to indicate that TARGET is and ID of a nonexclusive base, which UVALUE contains
;		the variable whos bits are to be controlled.
;	VAR - redundant keyword indicating TARGET to be treated as a variable, not widget ID.
;
; COMMON BLOCKS:
;	None.
;
; SIDE EFFECTS:
;	None.
;
; RESTRICTIONS:
;	None
;
; EXAMPLE:
;	In a widget application, where PLOT_CONTROL_BASE is a nonexclusive base and checkbox number
;	3 controls whether a plot to be appended or replaced:
;	DISPLAY, X, Y, OVER=CHECKBOX(PLOT_CONTROL_BASE, 2, /GET, /WIDGET)
;	
; PROCEDURE:
;	CHECKBOX can be used to easily store the information from switcheable controls in a single variable.
;	This can be convenient and very easy to use. All that a user needs to do is to use CHECKBOX in the event
;	handling procedure to set the bits, and then it can be used anywhere as a flag to check if the bits are
;	set:
;
;	My_pro_event, event
;	. . . .
;	'Overplot_Checkbox' : Temp = CHECKBOX(PLOT_CONTROL_BASE, 1, /WIDGET, ACTION=event.select)
;	. . . .
;	'Display' : DISPLAY, X, Y, OVER=CHECKBOX(PLOT_CONTROL_BASE, 1, /GET, /WIDGET)
;	. . . .
;	END
;
; MODIFICATION HISTORY:
;	Written: P.A.Romashkin, 08-2000
;	Modified: P.A.Romashkin, 10-2000
;	Documented, P.A.Romashkin, 10-2000
;-


function checkbox, TARGET, BIT_NO, ACTION=ACTION, WID=WID, VAR=VAR, RETURN=RETURN, GET=GET

	;Convert bit number to binary bit ID.
BIT = 2L^long(BIT_NO)

	;Get all currently set bits from the appropriate TARGET.
if keyword_set(WID) then widget_control, TARGET, get_uval=Curr_Checked else Curr_Checked=TARGET
if keyword_set(VAR) then Curr_Checked=TARGET
if keyword_set(GET) then return, (Curr_Checked and BIT) ne 0

RESULT=Curr_Checked ; Initialize just in case, if user uses incorrect syntax.

	;If called for toggling bits, change bit setting.
if n_elements(ACTION) ne 0 then begin
	if ACTION then RESULT=(Curr_Checked or BIT) else $
	if (Curr_Checked and BIT) ne 0 then RESULT=(Curr_Checked xor BIT)
endif else return, (Curr_Checked and BIT) ne 0

if keyword_set(RETURN) then return, RESULT else begin
	if keyword_set(WID) then widget_control, TARGET, set_uval=RESULT else TARGET=RESULT
	return, (RESULT and BIT) ne 0
endelse

end