^edit_box^
 
        Adds a field to a dialog box so that the user can enter a string
        using the keyboard. The box should be created using the init_box
        function.
        
^SYNTAX :^
 
        int box;
        int item;
        int x, y;
        int border;
        char *str, *template, *valid;
        item = text_box(box,x,y,str,template,valid,border);
        
        
^PARAMETERS :^
 
        Function parameters :
        
        - ^box^
                This parameter is the integer that was returned when this
                dialog box was created. This indicates to which dialog
                box the string is to be added. 
                See the function init_box for a description of this value.
                
        - ^x^ and ^y^
                These two parameters give the position of the field within
                the dialog box.
                They are expressed in numbers of characters from the top
                left of the dialog box.
                For example, if you specify 0 for both values then the
                string will be placed at the top right of the dialog box.
                
        - ^str^
                This parameter represents the string that is displayed in
                the editable field. The user can modify this string.
                It should be a character pointer or an array of characters
                or a string of characters between quotes.
                 
        - ^template^
                This parameter is a string indicating the format of the
                editable field. A "_" character indicates that the user
                can enter a character in this position. The other
                characters are displayed as shown. See the example below.
                
        - ^valid^
                This string indicates which characters can be typed by the
                user:
                        9 - the digits 0 - 9
                        A - the upper case letters A - Z and space
                        a - upper and lower case letters A - Z and space
                        N - digits 0 - 9, upper case letters A - Z,
                            and space
                        n - digits  0 - 9, upper and lower case A-Z letters
                            and space
                        F - filename characters and ? * :
                        P - path name characters plus \ : * ? 
                        p - path name characters plus \ : 
                        X - any character
                        
        - ^border^
                The string may be surounded by a border. This parameter
                lets you set the width of the border. This may be between
                1 and 3; 3 giving the largest border.
                If the value of border is not between 1 and 3 the string
                is not given a border.
                
^RETURN VALUE^        
        
        This is the number of the object within the dialog box; you will
        need this to read the string that the user has entered, via the
        readstr_box function.
        
^EXAMPLE^
        
        In the following example, the user must enter today's date
        using the keyboard and then click on the OK button.
 
  ^  int box;                                                                ^
  ^  int edit;                                                               ^
  ^  char *date;                                                             ^
  ^  main()                                                                  ^
  ^  {                                                                       ^
  ^      box = init_box(30, 5, 2);                                           ^
  ^      button_box(box, 12, 4, " OK ", 7);                                  ^
  ^      edit = edit_box(box, 10, 2, "010101", "__/__/__", "999999", 3);     ^
  ^      draw_box(box);                 /* draw the box */                   ^
  ^      date = readstr_box(box, edit); /* read the date */                  ^
  ^      puts(date);                    /* display the date on the screen */ ^
  ^  }                                                                       ^
        
^NOTE^
 
        To read the string that the user has entered with the keyboard,
        you should use thre readstr_box function which returns a pointer
        to this string. See the description of that function.
        
        The function color_box lets you change the colour of editable
        text. For example, you can have a green string on a black
        background with a red border.
