# coyote: TEXTBOX

- coyote/Utilities
- coyote/Widget Programming
- [Source code]

NAME

      TEXTBOX

PURPOSE

      This function allows the user to type some text in a
      pop-up dialog widget and have it returned to the program.
      This is an example of a Pop-Up Dialog Widget.

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com

CATEGORY

      Utility, Widgets

CALLING SEQUENCE

      thetext = TextBox()

INPUTS

      None.

KEYWORD PARAMETERS

      CANCEL: An output parameter. If the user kills the widget or clicks the Cancel
           button this keyword is set to 1. It is set to 0 otherwise. It
           allows you to determine if the user canceled the dialog without
           having to check the validity of the answer.
           theText = TextBox(Title='Provide Phone Number...', Label='Number:', Cancel=cancelled)
           IF cancelled THEN Return
      GROUP_LEADER: The widget ID of the group leader of this pop-up
           dialog. This should be provided if you are calling
           the program from within a widget program:
              thetext = TextBox(Group_Leader=event.top)
           If a group leader is not provided, an unmapped top-level base widget
           will be created as a group leader.
      LABEL: A string the appears to the left of the text box.
      TITLE:  The title of the top-level base. If not specified, the
           string 'Provide Input:' is used by default.
      VALUE: A string variable that is the intial value of the textbox. By default, a null string.
      XSIZE: The size of the text widget in pixel units. By default, 200.

OUTPUTS

      theText: The string of characters the user typed in the
           text widget. No error checking is done.

RESTRICTIONS

      The widget is destroyed if the user clicks on either button or
      if they hit a carriage return (CR) in the text widget. The
      text is recorded if the user hits the ACCEPT button or hits
      a CR in the text widget.

MODIFICATION HISTORY

      Written by: David W. Fanning, December 20, 2001.
      Added VALUE keyword to set the initial value of the text box. 4 Nov 2002. DWF.