workbench/libs/reqtools/rtezrequesta.c

   1 /*
   2     Copyright © 1995-2010, 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         reqinfo  - pointer to a rtReqInfo structure allocated with
 118             rtAllocRequest() or NULL.
 119         taglist  - pointer to a TagItem array.
 120
 121     TAGS
 122         RT_Window - (struct Window *) Window that will be used to find the
 123             screen to put the requester on. You *MUST* supply this if you
 124             are a task calling this function and not a process! This is
 125             because tasks don't have a pr_WindowPtr.
 126
 127         RT_IDCMPFlags - (ULONG) Extra idcmp flags to return on. If one
 128             these IDCMP flags causes the requester to abort the return code
 129             will equal the flag in question.
 130
 131         RT_ReqPos - (ULONG) One of the following:
 132
 133             REQPOS_POINTER - requester appears where the mouse pointer is
 134                 (default).
 135
 136             REQPOS_CENTERSCR - requester is centered on the screen.
 137
 138             REQPOS_CENTERWIN - requester is centered in the window (only
 139                 works if the pr_WindowPtr of your process is valid or if you
 140                 use RT_Window). If RT_Window is NULL the requester will be
 141                 centered on the screen.
 142
 143             REQPOS_TOPLEFTSCR - requester appears at the top left of the
 144                 screen.
 145
 146             REQPOS_TOPLEFTWIN - requester appears at the top left of the
 147                 window (only works if the pr_WindowPtr of your process is
 148                 valid or if you use RT_Window).
 149
 150             The requester will always remain in the visible part of the
 151             screen, so if you use the Workbench 2.0 ScreenMode preferences
 152             editor to enlarge your Workbench screen and you scroll around,
 153             the requester will always appear in the part you can see.
 154             REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the
 155             visible part of the screen. So if you use one of these the
 156             requester will be appear in the center or the top left off what
 157             you can see of the screen as opposed to the entire screen.
 158
 159             REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to
 160             REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there
 161             is no parent window. So you can safely use these without
 162             worrying about the existence of a window.
 163
 164         RT_LeftOffset - (ULONG) Offset of left edge of requester relative to
 165             position specified with RT_ReqPos (does not offset the
 166             requester when RT_ReqPos is REQPOS_POINTER).
 167
 168         RT_TopOffset - (ULONG) Offset of top edge of requester relative to
 169             position specified with RT_ReqPos (does not offset the
 170             requester when RT_ReqPos is REQPOS_POINTER).
 171
 172         RT_PubScrName - (char *) Name of public screen requester should
 173             appear on. When this tag is used the RT_Window tag will be
 174             ignored. If the public screen is not found the requester will
 175             open on the default public screen.
 176
 177             Only works on Kickstart 2.0! reqtools.library does not check
 178             this, it is up to you *NOT* to use this tag on Kickstart 1.3 or
 179             below! Note that the 1.3 version of reqtools.library also
 180             understands and supports this tag (on 2.0).
 181
 182         RT_Screen - (struct Screen *) Address of screen to put requester
 183             on. You should never use this, use RT_Window or RT_PubScrName.
 184
 185         RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can
 186             start an "asynchronous" requester. ti_TagData of the tag must
 187             hold the address of a pointer variable to a rtHandlerInfo
 188             structure. The requester will initialize this pointer and will
 189             return immediately after its normal initialization. The return
 190             code will not be what you would normally expect. If the return
 191             code is _not_ equal to CALL_HANDLER an error occurred and you
 192             should take appropriate steps.
 193
 194             If the return code was CALL_HANDLER everything went ok and the
 195             requester will still be up! See the explanation for
 196             rtReqHandlerA() below for the following steps you have to take.
 197
 198         RT_WaitPointer - (BOOL) If this is TRUE the window calling the
 199             requester will get a standard wait pointer set while the
 200             requester is up. This will happen if you used the RT_Window tag
 201             or if your process's pr_WindowPtr is valid. Note that after the
 202             requester has finished your window will be ClearPointer()-ed.
 203
 204             If you used a custom pointer in your window you will have to
 205             re-set it, or not use the RT_WaitPointer tag and put up a wait
 206             pointer yourself. If your program requires ReqTools V38 it is
 207             advised you use RT_LockWindow instead. Defaults to FALSE.
 208
 209         RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the
 210             requester will get locked. It will no longer accept any user
 211             input and it will get standard wait pointer set. This will
 212             happen only if you used the RT_Window tag or if your process's
 213             pr_WindowPtr is valid. RT_LockWindow will restore a custom
 214             pointer if you have used one (unlike RT_WaitPointer). So you do
 215             not have to worry about having to restore it yourself. It is
 216             advised you use this tag as much as possible. Defaults to FALSE.
 217
 218             Under Kickstart V39 the original window pointer will not be
 219             restored if it was set using SetWindowPointer(). You will have
 220             to restore the pointer yourself in this case.
 221
 222         RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop
 223             the screen the requester will appear on to the front. Default is
 224             TRUE.
 225
 226         RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share
 227             the IDCMP port of the parent window. Use this tag together with
 228             the RT_Window tag to indicate the window to share IDCMP with.
 229             Sharing the IDCMP port produces less overhead, so it is advised
 230             you use this tag. Defaults to FALSE.
 231
 232         RT_Locale - (struct Locale *) [V38] Locale to determine what
 233             language to use for the requester text. If this tag is not used
 234             or its data is NULL, the system's current default locale will
 235             be used. Default NULL.
 236         RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
 237             this hook for each IDCMP message it gets that doesn't belong to
 238             its window. Only applies if you used the RT_ShareIDCMP tag to
 239             share the IDCMP port with the parent window. Parameters are as
 240             follows:
 241
 242                 A0 - (struct Hook *) your hook
 243                 A2 - (struct rtReqInfo *) your requester info
 244                 A1 - (struct IntuiMessage *) the message
 245
 246             After you have finished examining the message and your hook
 247             returns, ReqTools will reply the message. So do not reply the
 248             message yourself!
 249
 250         RT_Underscore - (char) [V38] Indicates the symbol that precedes the
 251             character in the gadget label to be underscored. This is to
 252             define a keyboard shortcut for this gadget. Example: to define
 253             the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh,
 254             No!" you would use the tag RT_Underscore, '_' and pass as
 255             gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is
 256             used for string formatting. The usual character to use is '_'
 257             like in the example.
 258
 259             IMPORTANT: the shortcuts defined using RT_Underscore take
 260                 precedence of the default shortcuts! It is for example not
 261                 wise to use a 'N' for a positive response! Pick your
 262                 shortcuts carefully!
 263
 264         RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
 265             requester. Default is to use the screen font. Note that the
 266             font must already be opened by you. ReqTools will call
 267             OpenFont() on this TextAttr, _not_ OpenDiskFont()!  If the font
 268             cannot be opened using OpenFont() the default screen font will
 269             be used.
 270
 271         RTEZ_ReqTitle - (char *) Title of requester window, default is
 272             "Request" unless the requester has less than 2 responses, then
 273             the default title is "Information".
 274
 275         RTEZ_Flags - (ULONG) Flags for rtEZRequestA():
 276
 277             EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for
 278                 positive response.
 279
 280             EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left
 281                 Amiga 'V' and 'B', ESC and RETURN.
 282
 283             EZREQF_CENTERTEXT - centers each line of body text in the
 284                 requester window. Useful for about requesters.
 285
 286         RTEZ_DefaultResponse - (ULONG) Response value that will be returned
 287             when the user presses the return key. Will be ignored if the
 288             EZREQF_NORETURNKEY flag is set. The text for this response will
 289             be printed in bold. Default is 1.
 290
 291     RESULT
 292         ret - 1 (TRUE) for leftmost (positive) response, then each
 293             consecutive response will return 1 more, the rightmost (false)
 294             response will return 0 (FALSE), so 1,2,3,...,num-1,0 -- or
 295             idcmp flag.
 296
 297     NOTES
 298         Automatically adjusts the requester to the screen font.
 299
 300         rtEZRequestA() checks the pr_WindowPtr of your process to find the
 301         screen to put the requester on.
 302
 303     EXAMPLE
 304
 305     BUGS
 306         none known
 307
 308     SEE ALSO
 309         exec.library/RawDoFmt(), rtReqHandlerA()
 310
 311     INTERNALS
 312
 313     HISTORY
 314
 315 ******************************************************************************/
 316 {
 317     AROS_LIBFUNC_INIT
 318
 319     return GetString(bodyfmt,
 320                      (IPTR)argarray,
 321                      gadfmt,
 322                      0,
 323                      NULL,
 324                      IS_EZREQUEST,
 325                      reqinfo,
 326                      taglist);
 327
 328     AROS_LIBFUNC_EXIT
 329
 330 } /* rtEZRequestA */