home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 432b.lha / EzLib / doc / getstring.doc < prev    next >
Encoding:
Text File  |  1990-11-11  |  2.4 KB  |  66 lines
  1. FUNCTION  getstring()  -  Get a string from the user, using a window
  2.  
  3.   char *getstring(screen, title, def_string)
  4.       struct Screen *screen;
  5.       char *title;
  6.       char *def_string;
  7.  
  8.     This function will pop open a window to prompt the user for a string.
  9. The window has o.k. and cancel gadgets, and in addition, a Close gadget.
  10. The string you wish to get should be less than 256 characters (the default
  11. buffer size).
  12.  
  13.     The screen argument is a pointer to a screen on which to open the
  14. new window.  The screen argument can be NULL in which case the window will
  15. simply appear on the Workbench screen.    The title argument will be the
  16. title of the new window.   The def_string argument is a pointer to the
  17. default string that will appear in the string gadget.
  18.  
  19.     This function will return NULL if the user clicks the Close Gadget or
  20. clicks the cancel gadget.  If they click the "OK" gadget or press return in
  21. the string gadget, you will get a pointer to a string back.  The string is
  22. dynamically allocated and you must free it when you are done with a call to
  23. FreeMem() (see below).
  24.  
  25.      Here is an example that gets back the users name and prints it in the
  26.      CLI window.  In this example, the window will appear on workbench,
  27.      have a window title "Please enter your name", and there will be no
  28.      default string.
  29.  
  30.      char *string;
  31.  
  32.      string = getstring(NULL, "Please enter your name", NULL);
  33.  
  34.      if (string == NULL)
  35.        printf("User does not have a name.\n");
  36.      else {
  37.        printf("Your name is %s.\n", string);
  38.  
  39.        /* for this example we are done with the string, so we will free
  40.     * it now.
  41.     *        !!!!!! **  NOTICE  ** !!!!!!
  42.     *   You should be very careful to make sure that you free the
  43.     * proper amount of memory using the following style call.
  44.     * The size you MUST free is the length of the string + 1.
  45.     * This is VERY IMPORTANT as otherwise you mess up memory.
  46.     */
  47.        FreeMem(string, strlen(string)+1);
  48.      }                /*  ^^^^ The +1 is _very_ important! */
  49.  
  50.  
  51.     Again, if you want this window to appear on a custom screen (opened by
  52. a call to makescreen() or similar) you should pass it the screen pointer
  53. instead of NULL as the first argument.
  54.  
  55.     You should also check to make sure you didn't get back an empty string.
  56.  
  57.  
  58.  
  59. TODO : Probably should (again) make this into a higher level routine with
  60.        lower level support routines.  For now this works however.
  61.  
  62. BUGS : None to the best of my knowledge.
  63.  
  64. SEE ALSO : getyn(); makewindow()
  65.  
  66.