Check for SYS/GL during library init. Reason is that
[AROS.git] / workbench / libs / reqtools / rtezrequesta.c
blob897028b5fd1fd64ef788a88d664113813e210405
1 /*
2 Copyright © 1995-2010, The AROS Development Team. All rights reserved.
3 $Id$
5 Desc:
6 Lang: English
7 */
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>
18 #include "reqtools_intern.h"
19 #include "general.h"
21 /*****************************************************************************
23 NAME */
25 AROS_LH5(ULONG, rtEZRequestA,
27 /* SYNOPSIS */
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 */
35 /* LOCATION */
37 struct ReqToolsBase *, ReqToolsBase, 11, ReqTools)
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).
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.
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'.
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."
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:
69 ...
71 ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
73 rtEZRequest ("String, num: %s, %ld", "Ok", NULL,
74 (struct TagItem *)tags, "six", 6);
76 ...
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.
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.
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.
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'!
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.
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.
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.
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.
131 RT_ReqPos - (ULONG) One of the following:
133 REQPOS_POINTER - requester appears where the mouse pointer is
134 (default).
136 REQPOS_CENTERSCR - requester is centered on the screen.
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.
143 REQPOS_TOPLEFTSCR - requester appears at the top left of the
144 screen.
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).
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.
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.
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).
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).
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.
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).
182 RT_Screen - (struct Screen *) Address of screen to put requester
183 on. You should never use this, use RT_Window or RT_PubScrName.
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.
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.
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.
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.
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.
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.
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.
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.
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:
242 A0 - (struct Hook *) your hook
243 A2 - (struct rtReqInfo *) your requester info
244 A1 - (struct IntuiMessage *) the message
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!
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.
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!
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.
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".
275 RTEZ_Flags - (ULONG) Flags for rtEZRequestA():
277 EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for
278 positive response.
280 EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left
281 Amiga 'V' and 'B', ESC and RETURN.
283 EZREQF_CENTERTEXT - centers each line of body text in the
284 requester window. Useful for about requesters.
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.
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.
297 NOTES
298 Automatically adjusts the requester to the screen font.
300 rtEZRequestA() checks the pr_WindowPtr of your process to find the
301 screen to put the requester on.
303 EXAMPLE
305 BUGS
306 none known
308 SEE ALSO
309 exec.library/RawDoFmt(), rtReqHandlerA()
311 INTERNALS
313 HISTORY
315 ******************************************************************************/
317 AROS_LIBFUNC_INIT
319 return GetString(bodyfmt,
320 (IPTR)argarray,
321 gadfmt,
323 NULL,
324 IS_EZREQUEST,
325 reqinfo,
326 taglist);
328 AROS_LIBFUNC_EXIT
330 } /* rtEZRequestA */