workbench/libs/reqtools/rtgetlonga.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(ULONG, rtGetLongA,
  26
  27 /*  SYNOPSIS */
  28
  29         AROS_LHA(ULONG *, longptr, A1),
  30         AROS_LHA(char *, title, A2),
  31         AROS_LHA(struct rtReqInfo *, reqinfo, A3),
  32         AROS_LHA(struct TagItem *, taglist, A0),
  33
  34 /*  LOCATION */
  35
  36         struct ReqToolsBase *, ReqToolsBase, 13, ReqTools)
  37
  38 /*  FUNCTION
  39         Puts up a requester to get a signed long (32-bit) number from the
  40         user.
  41
  42         'reqinfo' can be used to customize the requester. For greater
  43         control use the tags listed below. The advantage of the rtReqInfo
  44         structure is that it is global, where tags have to be specified
  45         each function call. See libraries/reqtools.[hi] for a description
  46         of the rtReqInfo structure.
  47
  48     INPUTS
  49         &longvar - address of long (32 bit!) variable to hold result.
  50         title - pointer to null terminated title of requester window.
  51         reqinfo - pointer to a rtReqInfo structure allocated with
  52             rtAllocRequest() or NULL.
  53         taglist  - pointer to a TagItem array.
  54
  55     TAGS
  56         RT_Window - see rtEZRequestA()
  57
  58         RT_IDCMPFlags - see rtEZRequestA()
  59
  60         RT_ReqPos - see rtEZRequestA()
  61
  62         RT_LeftOffset - see rtEZRequestA()
  63
  64         RT_TopOffset - see rtEZRequestA()
  65
  66         RT_PubScrName - see rtEZRequestA()
  67
  68         RT_Screen - see rtEZRequestA()
  69
  70         RT_ReqHandler - see rtEZRequestA()
  71
  72         RT_WaitPointer - see rtEZRequestA()
  73
  74         RT_Underscore - [V38] see rtEZRequestA() Only when you also use the
  75             RTGL_GadFmt tag.
  76
  77         RT_LockWindow - [V38] see rtEZRequestA()
  78
  79         RT_ScreenToFront - [V38] see rtEZRequestA()
  80
  81         RT_ShareIDCMP - [V38] see rtEZRequestA()
  82
  83         RT_Locale - [V38] see rtEZRequestA()
  84
  85         RT_IntuiMsgFunc - [V38] see rtEZRequestA()
  86
  87         RT_TextAttr - [V38] see rtEZRequestA(). Note that under 1.2/1.3 the
  88             string gadget's font will remain the screen font.
  89
  90         RTGL_Min - (ULONG) Minimum allowed value. If the user tries to
  91             enter a smaller value the requester will refuse to accept it.
  92
  93         RTGL_Max - (ULONG) Maximum allowed value, higher values are refused.
  94
  95         RTGL_Width - (ULONG) Width of requester window in pixels. This is
  96             only a suggestion. rtGetLongA() will not go below a certain
  97             width.
  98
  99         RTGL_ShowDefault - (BOOL) If this is TRUE (default) the value
 100             already in 'longvar' will be displayed in the requester when it
 101             comes up. If set to FALSE the requester will be empty.
 102
 103         RTGL_GadFmt - (char *) [V38] Using this tag you can offer the user
 104             several responses. See rtEZRequestA() for more information.
 105             Note that selecting this gadget is considered a positive
 106             response so the integer in the gadget is copied to '&longvar'.
 107
 108         RTGL_GadFmtArgs - (APTR) [V38] If you used formatting codes with
 109             RTGL_GadFmt use this tag to pass the arguments.
 110
 111         RTGL_Invisible - (BOOL) [V38] Using this tag you can switch on
 112             invisible typing. Very useful if you need to get something like
 113             a code number from the user. It is strongly advised to use
 114             { RTGL_ShowDefault, FALSE } or the user may get very confused!
 115             Default is FALSE.
 116
 117         RTGL_BackFill - (BOOL) [V38] Backfill requester window with
 118             pattern. Default TRUE.
 119
 120         RTGL_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             GLREQF_CENTERTEXT flag. If you set the RTGL_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             RTGL_TextFmtArgs tag).
 127
 128         RTGL_TextFmtArgs - (APTR) [V38] If you used formatting codes with
 129             RTGL_TextFmt use this tag to pass the arguments.
 130
 131         RTGL_Flags - (ULONG) [V38]
 132
 133             GLREQF_CENTERTEXT - centers each line of text above the gadget
 134                 in the requester window. Should be generally set.
 135
 136             GLREQF_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 a number, 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 RTGL_GadFmt tag the return code will hold
 144             the value of the response as with rtEZRequestA().
 145
 146     NOTES
 147         'longvar' will NOT change if the requester is aborted.
 148
 149         Automatically adjusts the requester to the screen font.
 150
 151         rtGetLongA() checks the pr_WindowPtr of your process to find the
 152         screen to put the requester on.
 153
 154         If you use the RTGL_GadFmt tag the return value is not always the
 155         gadget the user selected. If the integer gadget is empty and the
 156         user presses the leftmost gadget (normally 'Ok') rtGetLong() will
 157         return 0 (FALSE)! If the integer gadget is empty and the user
 158         presses one of the other gadgets rtGetLong() _will_ return its
 159         value!
 160         Important: &longvar will not be changed in either of these cases.
 161
 162     EXAMPLE
 163
 164     BUGS
 165         none known
 166
 167     SEE ALSO
 168
 169     INTERNALS
 170
 171     HISTORY
 172
 173 ******************************************************************************/
 174 {
 175     AROS_LIBFUNC_INIT
 176
 177     return GetString(NULL,
 178                      0,
 179                      title,
 180                      0,
 181                      longptr,
 182                      ENTER_NUMBER,
 183                      reqinfo,
 184                      taglist);
 185
 186     AROS_LIBFUNC_EXIT
 187
 188 } /* rtGetLongA */