;+
; NAME:
;     WSTR
; PURPOSE:
;     Obtain string values from the user via an IDL form.  This is
;     just a convenient interface to the CW_FORM routine.
; CATEGORY:
;     OVRO UTILITY
; CALLING SEQUENCE:
;     out = wstr,title,text=text,label,init,tag,button=button
; INPUTS:
;     title     a string label, which can be used variously as a 
;                 title, heading, or prompt
;     label     a string array of the same length as the INIT and
;                 TAG arrays, giving a text label to be associated
;                 with each integer value the user is to enter
;     init      an array of string initializers, of the same length
;                 as the LABEL and TAG arrays
;     tag       an array of structure tags, of the same length as
;                 the LABEL and INIT arrays, by which the output
;                 structure members can be accessed
; OPTIONAL (KEYWORD) INPUT PARAMETERS:
;     text      an optional string array giving lines of text to
;                 follow the title.  This is intended as further 
;                 descriptive text for clarity.
;     button    an optional array of string labels for buttons.
;                 If omitted, a single OK button is present.  The
;                 button names are also used as structure tags in
;                 the output structure, so they must be single words
;                 without spaces.
; ROUTINES CALLED:
; OUTPUTS:
;     out       a structure containing an entry for each string
;                 plus an entry for each button.  The tag names
;                 for the strings are as given in the TAG array,
;                 while the tag names for each button are the
;                 button labels themselves.  If a button has been
;                 pressed, its value in the structure will be 1,
;                 otherwise 0.
; COMMENTS:
; SIDE EFFECTS:
; RESTRICTIONS:
;     The field widths of the string is currently limited to 10.
;     The string widgets and buttons are oriented in rows, so
;     there is a practical limit to the number allowed.  The button
;     labels are also used as structure tags, so care must be taken
;     to ensure they are suitable (e.g. do not use spaces)
; MODIFICATION HISTORY:
;     Written 09-Apr-1997 by Dale E. Gary
;-
function wstr,title,text=text,label,init,tag,button=button

   ; Check existence of arguments and array sizes

   ; Title must be given

   if (n_elements(title) eq 0) then begin
      print,'Usage: wint,text=text,label,init,tag'
      return,-1
   endif

   ; The text argument is optional

   ntext = n_elements(text)

   ; Verify that the LABEL, INIT, and TAG arrays are present and 
   ; of equal length

   nints = n_elements(label)
   if (nints eq 0) then begin
      print,'No inputs requested (label not given).'
      print,'Usage: wint,text=text,label,init,tag'
      return,-1
   endif
   if (nints ne n_elements(init)) then begin
      print,'Number of labels must equal number of initializers'
      return,-1
   endif
   if (nints ne n_elements(tag)) then begin
      print,'Number of labels must equal number of structure tags'
      return,-1
   endif

   ; Get number of buttons, or if no button, set default OK button

   bbase = 1
   nbuttons = n_elements(button)
   if (nbuttons eq 0) then begin
      nbuttons = 1
      button = 'OK'
   endif

   ; This will hold the descriptions for the IDL form, and must be
   ; of the appropriate size.

   desc = strarr(2+ntext+nints+nbuttons+bbase)

   k = 0          ; Index into desc array

   ; Label descriptor

   desc(k) = '0,LABEL,'+title+',CENTER'

   ; Optional text array descriptor

   if (ntext gt 0) then begin
      for i = 0, ntext-1 do begin
         k = k + 1
         desc(k) = '0,LABEL,'+text(i)+',LEFT'
      endfor
   endif

   ; Base for holding the integer field widgets

   k = k + 1
   desc(k) = '1,BASE,,ROW,FRAME'

   ; Descriptors for all but the last integer (labels to left of fields)

   if (nints gt 1) then begin
      for i = 0, nints-2 do begin
         k = k + 1
         desc(k) = '0, TEXT,'+init(i)+',LABEL_LEFT='$
                   +label(i)+',WIDTH=10,TAG='+tag(i)
      endfor
   endif

   ; Descriptor for the last integer (label to left of field)

   k = k + 1
   i = nints-1
   desc(k) = '2, TEXT,'+init(i)+',LABEL_LEFT='$
             +label(i)+',WIDTH=10,TAG='+tag(i)

   ; Base for holding the buttons

   k = k + 1
   desc(k) = '1,BASE,,ROW,CENTER'

   ; Descriptors for all but the last button

   if (nbuttons gt 1) then begin
      for i = 0, nbuttons-2 do begin
         k = k + 1
         desc(k) = '0,BUTTON,'+button(i)+',QUIT,TAG='+button(i)
      endfor
   endif

   ; Descriptor for the last button

   k = k + 1
   i = nbuttons-1
   desc(k) = '2,BUTTON,'+button(i)+',QUIT,TAG='+button(i)

   ; Now call the IDL form routine, CW_FORM and return the result

   return,CW_FORM(desc,/COLUMN)
end