Name
StringRequest -- ask the user to enter a string (V2.0)
Synopsis
s$, ok = StringRequest(title$, body$[, t])
Deprecated syntax
s$, ok = StringRequest(title$, body$[, def$, type, maxchars, password])
Function
This function opens a requester prompting the user to enter a string. You can specify the title for the requester window in title$ and the body text in body$. If you pass an empty string ("") title$, the requester will use the title specified in the @APPTITLE preprocessor command.

StringRequest() will return the string the user has entered if the user acknowledges the requester. If the user cancels this requester, an empty string will be returned. The second return value allows you identify whether or not the user pressed the 'OK' button. This is normally only needed if your application allows an empty string on 'OK'. In that case you need to check the second return value, too.

StringRequest() supports many optional arguments. Before Hollywood 9.0, those had to be passed as optional parameters (see above). Since Hollywood 9.0, however, it is recommended to use the new syntax, which has a single optional table argument that can be used to pass one or more optional arguments to StringRequest().

The following table fields are recognized by this function:

Type:
This table tag can be used to specify which characters the user is allowed to enter. This can currently be #NUMERICAL for numbers only or #ALL for no restriction on characters that can be entered. Defaults to #ALL.

Password:
Set this table tag to True to put the requester in password mode. In that case, the user's input will be hidden. Defaults to False.

MaxLength:
This table tag can be used to specify the number of characters the user will be allowed to enter. This defaults to 0, which means that there is no limit concerning the number of characters the user may enter.

Text:
This table tag can be used to specify the default text for the string requester. The text you specify here will be initially shown in the string requester's text entry widget.

X:
Initial x-position for the string requester on the screen. Not all platforms support this. (V9.0)

Y:
Initial y-position for the string requester on the screen. Not all platforms support this. (V9.0)

Width:
Initial width for the string requester dialog. Not all platforms support this. (V9.0)

Height:
Initial height for the string requester dialog. Not all platforms support this. (V9.0)

Please note that this command requires reqtools.library to be installed on AmigaOS 3, MorphOS, and AROS. Under AmigaOS 4 the StringRequest() function works without reqtools.library.

Inputs
title$
title for the requester window
body$
text for the requester body
t
optional: table containing further arguments (see above) (V9.0)
Results
s$
the string entered by the user or "" if requester was cancelled
ok
True if the user pressed the 'OK' button, False otherwise (V4.5)
Example
a$ = StringRequest("My Program", "Please enter your name!")
Print("Hello,", a$, "!")
Ask the user for his name and print it out.

Show TOC