RequestString version 1.02, December 15th 1992 by Nicolas Dade.

this program and the source are public domain.

this program lets you request a string from the user, similarly to
the many Yes/No/Maybe requesters. It can be used from a CLI or from
ARexx. If it is started from WorkBench it automatically goes into
arexx mode, since the workbench does not supply a standard output
to which to write the string. WB2.04 or higher, of course.

template:

RTITLE=TITLE/K, TEXT=BODY, STRING, OKTEXT=POSITIVE,
CANCELTEXT=NEGATIVE, PUBSCREEN/K, TFONT/K, SFONT/K, BFONT/K,
CENTERX/N/K, CENTERY/N/K, INSTALLAREXX/S

RTITLE or TITLE lets you specify the title of the requester.
TEXT or BODY lets you specify text which appears in the requester. Seperate
	lines with "*n", just like with the Echo command from a shell.
STRING	lets you specify the initial contents of the string (the default
	value, in other words).
OKTEXT or POSITIVE lets you specify the text which appears in the OK
	gadget. the default is "OK".
CANCELTEXT or NEGATIVE lets you specify the text which appears in
	the Cancel gadget. the default is "Cancel".
PUBSCREEN lets you specify the name of the public screen in which the
	requester should appear. the default is the workbench screen.
	This screen MUST exist.
TFONT	lets you specify the font in which the TEXT string should be
	drawn. the format is "name.font/height"---i.e. "Times.font/13"
	If the font cannot be found, the screen's font is used.
SFONT	lets you specify the font in which the string gadget should
	use. same format as for TFONT.
BFONT	lets you specify the font in which the button gadgets should
	use. same format as for TFONT.
CENTERX lets you specify the x coordinate of the center of the requester
CENTERY lets you specify the y coordinate of the center of the requester
	the default position is centered in the whole screen (not the
	visible portion).
or
INSTALLAREXX lets you place RequestString into arexx mode. Commands send
	to the port named REQUESTSTRING will cause a requester to pop up.
	The RC and RESULT variables will contain the return code and the
	string (so be sure to say OPTIONS RESULTS before you do this, or
	you wont be getting the string back). The format of the command
	is identical to to the arguments used when starting RequestString
	from the CLI.
	When this option is given all other options are ignored.

If RequestString is started from workbench it acts as if it had been
started from a CLI with the INSTALLAREXX option, so if you give it
the tooltype DONOTWAIT and put it in your WBStartup drawer it will be
installed each time you boot.
If course you can also put a line like

run >nil: RequestString INSTALLAREXX

in s:User-Startup and achieve exactly the same thing.

To get rid of RequestString in arexx mode, send it a ctrl-c signal.
(Use the Break command from a CLI)



Examples:

entering

RequestString RTITLE="Format blank disk" TEXT="I am going to format
the disk in drive DF0:*n*nplease enter the name of the new disk"
OKTEXT="Format" TFONT=Times.font/13 SFONT=Times.font/11
BFONT=Times.font/13 STRING="Empty" CENTERX=0 CENTERY=0

in a CLI will open a window flushed to the upper left corner of the screen,
looking like

	+-+-----------------------------------------+-+
	| | Format blank disk			    | |
	+-+-----------------------------------------+-+
	|					      |
	| I am going to format the disk in drive DF0: |
	|					      | <- blank line in TEXT
	| please enter the name of the new disk       |
	|					      |
	| [_Empty___________________________________] |
	|					      |
	|  [Format]			    [Cancel]  |
	|					      |
	+---------------------------------------------+

If the user presses return in the string gadget, or presses the OK
button (which has been labeled "Format" in this example),
RequestString outputs the string to its standard output, and exits
normaly.

If the user presses the close-window or the Cancel button
RequestString outputs nothing, and returns with return code WARN
(5).

If some problem occurs which prevents RequestString from running, it
returns with return code FAIL (20).


and if you have already put RequestString in arexx mode, executing
an arexx script like

/* Simple arexx script to get a line from the user via the RequestString program, and to print that line out */
options results /* so that arexx asks RequestString for a result string, which is placed in the variable RESULT */
    /* call RequestString */
address REQUESTSTRING 'text="Please enter some text" string="some text"'
    /* if everything went ok then print out what the user entered */
if rc=0 then say 'You entered "'result'".'
    /* if the user canceled then say so */
if rc=5 then say 'You canceled the requester.'
    /* if RequestString had some problems then say so */
if rc=20 then say 'Something kept RequestString from running.'

will request some text from the user.


If you require any sort of post-request processing of the entered
text (checking that it makes sense, putting double-quotes around it,
etc...) you really ought to be calling RequestString through its
arexx interface instead of driving yourself nuts fighting
limitations of dos scripts. That means you, KH2 :)

 ---------------------------------------------------------------------------

changes from 1.01 to 1.02

1) Bug which showed up when a font was specified has been fixed.
   Sorry KH2 --- there was a d1 that should have been a d0.

2) Width of window is adjusted so that STRING text is always fully
   visible. (well, unless the screen is not wide enough for that)

3) The 3.0 software from C= contains two commands, RequestChoice and
   RequestFile, which are in a similar league with RequestString.
   They use BODY, TITLE, POSITIVE and NEGATIVE in place of my TEXT,
   RTITLE, OKTEXT and CANCELTEXT, so I've changed the template so
   that both my old names and the C= names will work.

4) The TEXT or BODY now allows multiple lines. Just seperate them
   with "*n", just like you do with the Echo command (and, for that
   matter, just like you would with C='s RequestChoice command).