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