^button_box^
        Adds a button that the user can click on to a dialog box. The box
        should be created using the init_box function. 
        
^SYNTAX :^
 
        int box;
        int item;
        int x,y;
        int state;
        char *str;
        item = text_box(box,x,y,str,state);
        
        
^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 button 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 left of the dialog box.
         
        - ^str^  
                This parameter represents the string that is displayed in
                the button.
                It should be a character pointer or an array of characters
                or a string of characters between quotes.
                 
        - ^state^
                This parameter indicates the sort of button that you
                want to have. The different states that a button may have
                are as follows: 
                        - selectable            (1)
                          i.e. the user may click on this button. 
                          
                        - default               (2)
                          When a button is of type default, then this
                          button is selected when the user presses the
                          Return key. There should only be one button
                          of this type in a given box. This is almost
                          always an exit button, so the user can use
                          return to exit the dialog box without having to
                          use the mouse.
                          
                        - exit                   (4)
                          When this button is selected the dialog box is
                          finished. Normally the dialog box is closed
                          and removed from the screen and control returns
                          to the calling program.
                          
                        - radio button           (16)
                          Radio buttons appear in groups of two or more.
                          Ony one of these buttons may be selected at a
                          given time. When the user selects one of these
                          buttons, the others are automatically de-selected.
        
                The numbers in brackets indicate the value to add to
                the state parameter to give the corresponding attribute
                to this button. A button may be of more than one type,
                just add the values together. In pratice, buttons are
                always selectable; otherwise you can do nothing with them;
                they just look pretty.
                There are three main sorts of buttons:
                  
                        - simple exit.
                          The user can select the button with the mouse
                          and the form is exitted.
                          type = selectable + exit.
                          The state parameter has the value 5 in this
                          case.
                        - default exit.
                          The user can select the button with the mouse or
                          by pressing Return. The dialog box is then finished.
                          type = selectable + default + exit.
                          The value of the state parameter is 7. (1 + 2 + 4)
                        - radio buttons.
                          The user must choose between several options, but
                          only one may be selected at once. For example,
                          in the dialog box for the Find command the buttons
                          for the direction of the search are radio buttons.
                          type = selectable + radio button.
                          The value of the state parameter is 17. (1 + 16)
                          
^RETURN VALUE^        
        
        This is the number of the object within the dialog box; if you need
        to distinguish between different buttons you will need to store this.
        For example, has the user clicked on OK or Cancel?
        
^EXAMPLE^
        
        The following program creates a dialog box with two exit buttons.
        One, "OK", can be selected with the return key. The other button
        can only be selected by clicking on it.
 
        ^ int ok,cancel;                                          ^
        ^ int box;                                                ^
        ^ int ret;                                                ^
        ^ main()                                                  ^
        ^ {                                                       ^
        ^       box = init_box(20,5,2);                           ^
        ^       ok = button_box(box,1,2,"OK",7);                  ^
        ^       cancel = button_box(box,1,2,"Cancel" ,5);         ^
        ^       ret = draw_box(box);                              ^
        ^       if (ret == cancel)                                ^
        ^               printf("You have selected Cancel");       ^
        ^       if (ret == ok)                                    ^
        ^               printf("You have selected OK");           ^
        ^ }                                                       ^
        
        Note : draw_box draws the box and waits for the user to finish
        the dialog.
        
