workbench/libs/reqtools/rtezrequesta.c

   1 /*
   2     Copyright © 1995-2018, 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, rtEZRequestA,
  26
  27 /*  SYNOPSIS */
  28
  29         AROS_LHA(char *, bodyfmt, A1),
  30         AROS_LHA(char *, gadfmt, A2),
  31         AROS_LHA(struct rtReqInfo *, reqinfo, A3),
  32         AROS_LHA(APTR, argarray, A4),            /* tagcall: -1 */
  33         AROS_LHA(struct TagItem *, taglist, A0), /* tagcall: -1 +Tags */
  34
  35 /*  LOCATION */
  36
  37         struct ReqToolsBase *, ReqToolsBase, 11, ReqTools)
  38
  39 /*  FUNCTION
  40         This function puts up a requester for you and waits for a response
  41         from the user. If the response is positive, this procedure returns
  42         TRUE. If the response is negative, this procedure returns FALSE.
  43         The function may also return an IDCMP flag or a value corresponding
  44         with one of other possible responses (see below).
  45
  46         'gadfmt' may contain several possible responses. Separate these
  47         responses by a '|'. For example: "Yes|No", or 'Yes|Maybe|No". The
  48         responses should be typed in the same order as they will appear on
  49         screen, from left to right. There is no limit to the number of
  50         responses other than the width of the screen the requester will
  51         appear on.
  52
  53         'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a
  54         new line to be started (surprise, surprise :-).
  55         You may also include printf() style formatting codes. The format
  56         arguments should be pointed to by 'argarray'.
  57         You can use formatting codes in 'gadfmt' as well. The arguments for
  58         this format string should follow the ones for 'bodyfmt'.
  59
  60         NOTE: The formatting is done by exec.library/RawDoFmt(), so be
  61             aware that to display a 32-bit integer argument you must use
  62             "%ld", not "%d", since RawDoFmt() is "word-oriented."
  63
  64         The second and third function use a variable number of arguments.
  65         These functions can be found in 'reqtools[nb].lib'.
  66         The second function has the RawDoFmt() arguments as variable args,
  67         the third the tags. If you need both this is what you can do:
  68
  69         ...
  70         {
  71            ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
  72
  73            rtEZRequest ("String, num: %s, %ld", "Ok", NULL,
  74                                            (struct TagItem *)tags, "six", 6);
  75         }
  76         ...
  77
  78         You can satisfy the requester with the following keyboard shortcuts:
  79             'Y' or Left Amiga 'V' for a positive response,
  80             ESC, 'N', 'R' or Left Amiga 'B' for a negative response.
  81
  82         If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the
  83         RETURN key is also accepted as a shortcut for the positive response
  84         (can be changed using RTEZ_DefaultResponse, see below). The
  85         response that will be selected when you press RETURN will be
  86         printed in bold.
  87
  88         The EZREQF_LAMIGAQUAL flag should be used when you put up a
  89         requester for a destructive action (e.g. to delete something). When
  90         it is set the keyboard shortcuts are limited to Left Amiga 'V' and
  91         'B' so it is harder to accidently select something you will regret.
  92         Note that the RETURN and ESC key remain active!  To disable the
  93         RETURN key use the EZREQF_NORETURNKEY flag. The ESC key cannot be
  94         disabled.
  95
  96         You may pass a NULL for 'gadfmt', but make sure you know what you
  97         are doing. Passing a NULL opens an EZRequester with NO responses,
  98         just a body text. This implies the user has no means of "answering"
  99         this requester. You must therefore use the RT_IDCMPFlags tag to
 100         allow some other events to end the requester (e.g.
 101         IDCMP_MOUSEBUTTONS, IDCMP_INACTIVEWINDOW,...) or you must make use
 102         of the ReqHandler feature. Using a requester handler you can end
 103         the requester by program control. This way you can e.g. put up a
 104         requester before you start loading a file and remove it after the
 105         file has been loaded. Do not pass an empty string as 'gadfmt'!
 106
 107         'reqinfo' can be used to customize the requester. For greater
 108         control use the tags listed below. The advantage of the rtReqInfo
 109         structure is that it is global, where tags have to be specified
 110         each function call. See libraries/reqtools.[hi] for a description
 111         of the rtReqInfo structure.
 112
 113     INPUTS
 114         bodyfmt  - requester body text, can be format string a la RawDoFmt().
 115         gadfmt   - text for gadgets (left to right, separated by '|') or NULL.
 116         argarray - pointer to array of arguments for format string(s).
 117                    nb - : arguments must be handled the same as for RawDoFmt!
 118                    use aros slowstack macros.
 119         reqinfo  - pointer to a rtReqInfo structure allocated with
 120             rtAllocRequest() or NULL.
 121         taglist  - pointer to a TagItem array.
 122
 123     TAGS
 124         RT_Window - (struct Window *) Window that will be used to find the
 125             screen to put the requester on. You *MUST* supply this if you
 126             are a task calling this function and not a process! This is
 127             because tasks don't have a pr_WindowPtr.
 128
 129         RT_IDCMPFlags - (ULONG) Extra idcmp flags to return on. If one
 130             these IDCMP flags causes the requester to abort the return code
 131             will equal the flag in question.
 132
 133         RT_ReqPos - (ULONG) One of the following:
 134
 135             REQPOS_POINTER - requester appears where the mouse pointer is
 136                 (default).
 137
 138             REQPOS_CENTERSCR - requester is centered on the screen.
 139
 140             REQPOS_CENTERWIN - requester is centered in the window (only
 141                 works if the pr_WindowPtr of your process is valid or if you
 142                 use RT_Window). If RT_Window is NULL the requester will be
 143                 centered on the screen.
 144
 145             REQPOS_TOPLEFTSCR - requester appears at the top left of the
 146                 screen.
 147
 148             REQPOS_TOPLEFTWIN - requester appears at the top left of the
 149                 window (only works if the pr_WindowPtr of your process is
 150                 valid or if you use RT_Window).
 151
 152             The requester will always remain in the visible part of the
 153             screen, so if you use the Workbench 2.0 ScreenMode preferences
 154             editor to enlarge your Workbench screen and you scroll around,
 155             the requester will always appear in the part you can see.
 156             REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the
 157             visible part of the screen. So if you use one of these the
 158             requester will be appear in the center or the top left off what
 159             you can see of the screen as opposed to the entire screen.
 160
 161             REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
 162             REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there
 163             is no parent window. So you can safely use these without
 164             worrying about the existence of a window.
 165
 166         RT_LeftOffset - (ULONG) Offset of left edge of requester relative to
 167             position specified with RT_ReqPos (does not offset the
 168             requester when RT_ReqPos is REQPOS_POINTER).
 169
 170         RT_TopOffset - (ULONG) Offset of top edge of requester relative to
 171             position specified with RT_ReqPos (does not offset the
 172             requester when RT_ReqPos is REQPOS_POINTER).
 173
 174         RT_PubScrName - (char *) Name of public screen requester should
 175             appear on. When this tag is used the RT_Window tag will be
 176             ignored. If the public screen is not found the requester will
 177             open on the default public screen.
 178
 179             Only works on Kickstart 2.0! reqtools.library does not check
 180             this, it is up to you *NOT* to use this tag on Kickstart 1.3 or
 181             below! Note that the 1.3 version of reqtools.library also
 182             understands and supports this tag (on 2.0).
 183
 184         RT_Screen - (struct Screen *) Address of screen to put requester
 185             on. You should never use this, use RT_Window or RT_PubScrName.
 186
 187         RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can
 188             start an "asynchronous" requester. ti_TagData of the tag must
 189             hold the address of a pointer variable to a rtHandlerInfo
 190             structure. The requester will initialize this pointer and will
 191             return immediately after its normal initialization. The return
 192             code will not be what you would normally expect. If the return
 193             code is _not_ equal to CALL_HANDLER an error occurred and you
 194             should take appropriate steps.
 195
 196             If the return code was CALL_HANDLER everything went ok and the
 197             requester will still be up! See the explanation for
 198             rtReqHandlerA() below for the following steps you have to take.
 199
 200         RT_WaitPointer - (BOOL) If this is TRUE the window calling the
 201             requester will get a standard wait pointer set while the
 202             requester is up. This will happen if you used the RT_Window tag
 203             or if your process's pr_WindowPtr is valid. Note that after the
 204             requester has finished your window will be ClearPointer()-ed.
 205
 206             If you used a custom pointer in your window you will have to
 207             re-set it, or not use the RT_WaitPointer tag and put up a wait
 208             pointer yourself. If your program requires ReqTools V38 it is
 209             advised you use RT_LockWindow instead. Defaults to FALSE.
 210
 211         RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the
 212             requester will get locked. It will no longer accept any user
 213             input and it will get standard wait pointer set. This will
 214             happen only if you used the RT_Window tag or if your process's
 215             pr_WindowPtr is valid. RT_LockWindow will restore a custom
 216             pointer if you have used one (unlike RT_WaitPointer). So you do
 217             not have to worry about having to restore it yourself. It is
 218             advised you use this tag as much as possible. Defaults to FALSE.
 219
 220             Under Kickstart V39 the original window pointer will not be
 221             restored if it was set using SetWindowPointer(). You will have
 222             to restore the pointer yourself in this case.
 223
 224         RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop
 225             the screen the requester will appear on to the front. Default is
 226             TRUE.
 227
 228         RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share
 229             the IDCMP port of the parent window. Use this tag together with
 230             the RT_Window tag to indicate the window to share IDCMP with.
 231             Sharing the IDCMP port produces less overhead, so it is advised
 232             you use this tag. Defaults to FALSE.
 233
 234         RT_Locale - (struct Locale *) [V38] Locale to determine what
 235             language to use for the requester text. If this tag is not used
 236             or its data is NULL, the system's current default locale will
 237             be used. Default NULL.
 238         RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
 239             this hook for each IDCMP message it gets that doesn't belong to
 240             its window. Only applies if you used the RT_ShareIDCMP tag to
 241             share the IDCMP port with the parent window. Parameters are as
 242             follows:
 243
 244                 A0 - (struct Hook *) your hook
 245                 A2 - (struct rtReqInfo *) your requester info
 246                 A1 - (struct IntuiMessage *) the message
 247
 248             After you have finished examining the message and your hook
 249             returns, ReqTools will reply the message. So do not reply the
 250             message yourself!
 251
 252         RT_Underscore - (char) [V38] Indicates the symbol that precedes the
 253             character in the gadget label to be underscored. This is to
 254             define a keyboard shortcut for this gadget. Example: to define
 255             the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh,
 256             No!" you would use the tag RT_Underscore, '_' and pass as
 257             gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is
 258             used for string formatting. The usual character to use is '_'
 259             like in the example.
 260
 261             IMPORTANT: the shortcuts defined using RT_Underscore take
 262                 precedence of the default shortcuts! It is for example not
 263                 wise to use a 'N' for a positive response! Pick your
 264                 shortcuts carefully!
 265
 266         RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
 267             requester. Default is to use the screen font. Note that the
 268             font must already be opened by you. ReqTools will call
 269             OpenFont() on this TextAttr, _not_ OpenDiskFont()!  If the font
 270             cannot be opened using OpenFont() the default screen font will
 271             be used.
 272
 273         RTEZ_ReqTitle - (char *) Title of requester window, default is
 274             "Request" unless the requester has less than 2 responses, then
 275             the default title is "Information".
 276
 277         RTEZ_Flags - (ULONG) Flags for rtEZRequestA():
 278
 279             EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for
 280                 positive response.
 281
 282             EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left
 283                 Amiga 'V' and 'B', ESC and RETURN.
 284
 285             EZREQF_CENTERTEXT - centers each line of body text in the
 286                 requester window. Useful for about requesters.
 287
 288         RTEZ_DefaultResponse - (ULONG) Response value that will be returned
 289             when the user presses the return key. Will be ignored if the
 290             EZREQF_NORETURNKEY flag is set. The text for this response will
 291             be printed in bold. Default is 1.
 292
 293     RESULT
 294         ret - 1 (TRUE) for leftmost (positive) response, then each
 295             consecutive response will return 1 more, the rightmost (false)
 296             response will return 0 (FALSE), so 1,2,3,...,num-1,0 -- or
 297             idcmp flag.
 298
 299     NOTES
 300         Automatically adjusts the requester to the screen font.
 301
 302         rtEZRequestA() checks the pr_WindowPtr of your process to find the
 303         screen to put the requester on.
 304
 305     EXAMPLE
 306
 307     BUGS
 308         none known
 309
 310     SEE ALSO
 311         exec.library/RawDoFmt(), rtReqHandlerA()
 312
 313     INTERNALS
 314
 315     HISTORY
 316
 317 ******************************************************************************/
 318 {
 319     AROS_LIBFUNC_INIT
 320
 321     return GetString(bodyfmt,
 322              (SIPTR)argarray,
 323              gadfmt,
 324              0,
 325              NULL,
 326              IS_EZREQUEST,
 327              reqinfo,
 328              taglist);
 329
 330     AROS_LIBFUNC_EXIT
 331
 332 } /* rtEZRequestA */