workbench/libs/reqtools/rtgetstringa.c

   1 /*
   2     Copyright © 1995-2001, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc:
   6     Lang: English
   7 */
   8
   9 #include <exec/types.h>
  10 #include <proto/exec.h>
  11 #include <proto/reqtools.h>
  12 #include <proto/intuition.h>
  13 #include <exec/libraries.h>
  14 #include <exec/memory.h>
  15 #include <libraries/reqtools.h>
  16 #include <aros/libcall.h>
  17
  18 #include "reqtools_intern.h"
  19 #include "general.h"
  20
  21 /*****************************************************************************
  22
  23     NAME */
  24
  25     AROS_LH5(ULONG, rtGetStringA,
  26
  27 /*  SYNOPSIS */
  28
  29         AROS_LHA(UBYTE *, buffer, A1),
  30         AROS_LHA(ULONG, maxchars, D0),
  31         AROS_LHA(char *, title, A2),
  32         AROS_LHA(struct rtReqInfo *, reqinfo, A3),
  33         AROS_LHA(struct TagItem *, taglist, A0),
  34
  35 /*  LOCATION */
  36
  37         struct ReqToolsBase *, ReqToolsBase, 12, ReqTools)
  38
  39 /*  FUNCTION
  40         Puts up a string requester to get a line of text from the user. The
  41         string present in 'buffer' upon entry will be displayed, ready to
  42         be edited.
  43
  44         'reqinfo' can be used to customize the requester. For greater
  45         control use the tags listed below. The advantage of the rtReqInfo
  46         structure is that it is global, where tags have to be specified
  47         each function call. See libraries/reqtools.[hi] for a description
  48         of the rtReqInfo structure.
  49
  50     INPUTS
  51         buffer - pointer to buffer to hold characters entered.
  52         maxchars - maximum number of characters that fit in buffer
  53             (EX-cluding the 0 to terminate the string !).
  54         title - pointer to null terminated title of requester window.
  55         reqinfo - pointer to a rtReqInfo structure allocated with
  56             rtAllocRequest() or NULL.
  57         taglist - pointer to a TagItem array.
  58
  59     TAGS
  60         RT_Window - see rtEZRequestA()
  61
  62         RT_IDCMPFlags - see rtEZRequestA()
  63
  64         RT_ReqPos - see rtEZRequestA()
  65
  66         RT_LeftOffset - see rtEZRequestA()
  67
  68         RT_TopOffset - see rtEZRequestA()
  69
  70         RT_PubScrName - see rtEZRequestA()
  71
  72         RT_Screen - see rtEZRequestA()
  73
  74         RT_ReqHandler - see rtEZRequestA()
  75
  76         RT_WaitPointer - see rtEZRequestA()
  77
  78         RT_Underscore - [V38] see rtEZRequestA(). Only when you also use
  79             the RTGS_GadFmt tag.
  80
  81         RT_LockWindow - [V38] see rtEZRequestA()
  82
  83         RT_ScreenToFront - [V38] see rtEZRequestA()
  84
  85         RT_ShareIDCMP - [V38] see rtEZRequestA()
  86
  87         RT_Locale - [V38] see rtEZRequestA()
  88
  89         RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  90
  91         RT_TextAttr - [V38] see rtEZRequestA(). Note that under 1.2/1.3 the
  92             string gadget's font will remain the screen font.
  93
  94         RTGS_Width - (ULONG) Width of requester window in pixels. This is
  95             only a suggestion. rtGetStringA() will not go below a certain
  96             width.
  97
  98         RTGS_AllowEmpty - (BOOL) If RTGS_AllowEmpty is TRUE an empty string
  99             will also be accepted and returned. Defaults to FALSE, meaning
 100             that if the user enters an empty string the requester will be
 101             canceled.
 102
 103         RTGS_GadFmt - (char *) [V38] Using this tag you can offer the user
 104             severalresponses. See rtEZRequestA() for more information. Note
 105             that selecting this gadget is considered a positive response so
 106             the string in the gadget is copied to 'buffer'.
 107
 108         RTGS_GadFmtArgs - (APTR) [V38] If you used formatting codes with
 109             RTGS_GadFmt use this tag to pass the arguments.
 110
 111         RTGS_Invisible - (BOOL) [V38] Using this tag you can switch on
 112             invisible typing. Very useful if you need to get something like
 113             a password from the user. It is strongly advised to use an
 114             empty initial string or the user may get very confused!
 115             Default is FALSE.
 116
 117         RTGS_BackFill - (BOOL) [V38] Backfill requester window with
 118             pattern. Default TRUE.
 119
 120         RTGS_TextFmt - (char *) [V38] Print these lines of text above the
 121             gadget in the requester. Very useful to inform the user of what
 122             he should enter. Most of the time you will also want to set the
 123             GSREQF_CENTERTEXT flag. If you set the RTGS_BackFill tag to
 124             FALSE _no_ recessed border will be placed around the text.
 125             Formatting codes may be used in the string (see
 126             RTGS_TextFmtArgs tag).
 127
 128         RTGS_TextFmtArgs - (APTR) [V38] If you used formatting codes with
 129             RTGS_TextFmt use this tag to pass the arguments.
 130
 131         RTGS_Flags - (ULONG) [V38]
 132
 133             GSREQF_CENTERTEXT - centers each line of text above the gadget
 134                 in the requester window. Should be generally set.
 135
 136             GSREQF_HIGHLIGHTTEXT - Highlight text above the gadget. You
 137                 will normally only want to use this if you also turned off
 138                 the window backfilling.
 139
 140     RESULT
 141         ret - TRUE if user entered something, FALSE if not. If one of your
 142             idcmp flags caused the requester to end 'ret' will hold this
 143             flag. If you used the RTGS_GadFmt tag the return code will hold
 144             the value of the response as with rtEZRequestA().
 145
 146     NOTES
 147         The contents of the buffer will NOT change if the requester is
 148         aborted.
 149
 150         Automatically adjusts the requester to the screen font.
 151
 152         rtGetStringA() checks the pr_WindowPtr of your process to find the
 153         screen to put the requester on.
 154
 155         If you use the RTGS_GadFmt tag the return value is not always the
 156         gadget the user selected. If the string gadget is empty and the
 157         user presses the leftmost gadget (normally 'Ok') rtGetString() will
 158         return 0 (FALSE)! If the string gadget is empty and the user
 159         presses one of the other gadgets rtGetString() _will_ return its
 160         value!  Important: 'buffer' will not be changed in either of these
 161         cases.
 162         If you set the RTGS_AllowEmpty tag to TRUE 'buffer' will always be
 163         changed of course, and rtGetString() will always return the value
 164         of the gadget pressed.
 165
 166     EXAMPLE
 167
 168     BUGS
 169         none known
 170
 171     SEE ALSO
 172
 173     INTERNALS
 174
 175     HISTORY
 176
 177 ******************************************************************************/
 178 {
 179     AROS_LIBFUNC_INIT
 180
 181     return GetString(buffer,
 182                      maxchars,
 183                      title,
 184                      0,
 185                      NULL,
 186                      ENTER_STRING,
 187                      reqinfo,
 188                      taglist);
 189
 190     AROS_LIBFUNC_EXIT
 191
 192 } /* rtgetstringa */