Don't change this line:$VER: RexxReqTools_Documentation 37.5 (13.2.93)


			     RexxReqTools 1.0  (37.19)
			    ~~~~~~~~~~~~~~~~~~
					       © 1992, 1993 Rafael D'Halleweyn

Contents
========

1.   Introduction

2.   Using RexxReqTools
2.1. BodyText
2.2. GadgetText
2.3. TagStrings
2.4. Remark about screens

3.   Functions
3.1. rtezrequest()
3.2. rtfilerequest()
3.3. rtfontrequest()
3.4. rtgetlong()
3.5. rtgetstring()
3.6. rtpaletterequest()
3.7. rtscreenmoderequest()

4.   Copyright
4.1. Redistribution

5.   History


1. Introduction
===============

RexxReqTools gives ARexx users easy access to a large family of requesters.
All requesters are easy to use; they require one or no arguments. But the
requesters also have a lot of power through several optional arguments and
through tagstrings (more about those in 2.3).
RexxReqTools itself doesn't implement any of these requesters, it is a link
between ARexx (© William S. Hawes) and ReqTools (© Nico François).

If you have any questions, remarks, suggestions or bug reports about
RexxReqTools please let me know. You can contact me via normal mail (sorry
no e-mail);

	  Rafael D'Halleweyn
	  Perckhoevelaan 17
	  B-2610 Antwerpen

	  BELGIUM


2. Using RexxReqTools
=====================

To use RexxReqTools you first have to install the library rexxreqtools.library
in your LIBS: directory. If you double click the Install_Lib icon, you will be
asked if you want to install the library, if you enter `y' (+<RETURN>) the
library will be installed.

You also have to tell ARexx about this new library. You can do this through
the CLI command

    RxLib rexxreqtools.library 0 -30

If you use RexxReqTools a lot you can insert this line in your startup-sequence
(or user-startup if you have Workbench 2.0 or higher).
Alternatively you can insert the following command in every ARexx script that
uses RexxReqTools

    addlib('rexxreqtools.library',0,-30)

For RexxReqTools to be able to work you'll also need to have the
`rexxsyslib.library' and `reqtools.library' installed in LIBS:.
`rexxsyslib.library' is the heart of ARexx. If you are running Workbench 2.0
or higher you should have this library already installed. If you are running
Workbench 1.3 then you'll have to buy the ARexx packet and install ARexx or
you have to upgrade to Workbench 2.0 (the inclusion of ARexx is reason enough
to upgrade, not to mention the other benefits).
`reqtools.library' is the heart of ReqTools. You should find this library
on the same disk as RexxReqTools (you probably found RexxReqTools in a drawer
of the ReqTools distribution).

2.1. BodyText
-------------
The message, number and string requester take an argument named <bodytext>.
This is the main text that is displayed in the requester.
You can split this text on several lines by using a newline ('0A'x).
If you want to use a `%'-character in bodytext then you'll have to type `%%'.
Also don't use `%s', `%d', or any other C printf-style formatting codes
(The computer won't crash if you do use them, but output will look bad).

EXAMPLES:
    "this is a bodytext"
							     _________________
    "some text split" || '0A'x || "over two lines"  ---->   | some text split |
							    | over two lines  |
							     -----------------
						 ________________________
    "more text, split over" || NL ||,		| more text, split over  |
    "more lines, but easier" || NL ||,	 ---->	| more lines, but easier |
    "to read in the script"			| to read in the script  |
						 ------------------------
NOTE 1: For the third example to work you'll have to add the assignment
	"NL = '0A'x" to the script.
NOTE 2: The comma in the third example is a continuation character for a
	statement that continues on the next line.

2.2. GadgetText
---------------
The message, number and string requester take an argument named <gadgettext>.
This argument describes the gadgets in the requester. It contains the text of
all the gadgets.
Each gadget is seperated from the others by a bar character (`|'). They will
appear in the same order as they were typed. There is no limit to the number of
gadgets other than the width of the screen the requester will appear on.
You can also specify a shortcut for each gadget by placing an underscore (`_')
before the character that identifies the shortcut key.
If you want to use a `%'-character in gadgettext then you'll have to type `%%'.
Also don't use `%s', `%d', or any other C printf-style formatting codes
(The computer won't crash if you do use them, but output will look bad).

EXAMPLES:
    "Continue"

    " _Ok |_Abort|_Cancel"   gives three gadgets: `Ok', `Abort' and `Cancel'
			     with shortcuts `O', `A' and `C'

    "0%%|25%%|50%%|75%%|100%%"	gives five gadgets: `0%',... `100%'

A special case of <gadgettext> is the <oktext> (file and font requester).
It describes the gadget in the down left corner. In this text you can also
use an underscore to indicate a shortcut, but you shouldn't use a bar.

EXAMPLES
    "_Open"

    "Delete"

2.3. tagstrings
---------------
All the requester take an argument called <tagstring>. Tagstrings make it easy
to specify further parameters to the functions. A tagstring is a string made up
of attribute/value pairs, each pair is seperated from the next by one or more
spaces. (The use of spaces as a seperator make it easy to link tagstring
together in ARexx). One attribute/value pair is called a tag item, it contains
the name of the attribute and the value it will take, attribute and value are
seperated by an equal sign.
The attribute can be a number, a constant or a string. If the attribute is a
string it has to be surrounded by quotes (" or '). It the attribute is a
constant then you can use the or sign (`|') to OR several constans together.

EXAMPLES:
      'rt_leftoffset=120'

      'rt_reqpoq=reqpos_centerscr rt_leftoffset=120'

      'rt_pubscrname="PowerPacker"'

NOTE: The last example is equivallent with "rt_pubscrname='PowerPacker'" or
      'rt_pubscrname=''PowerPacker''' or "rt_pubscrname=""PowerPacker"""

All constants are described in chapter 3, except for the IDCMP flags and
`false' and `true'.
The message, number and text requester allow you to specify IDCMP flags
(rt_idcmpflags). RexxReqTools understands most of the IDCMP flags. This
is a list of all supported IDCMP flags:

    idcmp_mousebuttons	requester dissapears when mouse button is pressed
    idcmp_mousemove				  mouse is moved
    idcmp_gadgetdown				  a gadget is depressed
    idcmp_gadgetup				  a gadget is released
    idcmp_rawkey				  any key is pressed
    idcmp_diskinserted				  disk is inserted
    idcmp_diskremoved				  disk is removed
    idcmp_activewindow				  requester window is activated
    idcmp_inactivewindow			  requester window deactivated
    idcmp_vanillakey				  a key is pressed

You can OR several of these together.

EXAMPLE:	"rt_idcmpflags=idcmp_diskinserted|idcmp_vanillakey"

Currently no more then 14 tags are used. If you use more they will be ignored.

2.3. resultname
---------------
All the requesters take an argument called <resultname>. This is the of the
variable where the return value of the requester will be stored. This argument
is optional it defaults to `rtresult'.
Some requesters that have to return a lot of information use compounds of this
variable to store information (filerequester and fontrequester).
For exmaple: the fontrequester returns in the compound <resultname>.height the
height of the selected font.

2.4. Remark about screens
-------------------------
RexxReqTools contains attributes to set the screen on which the requester will
appear (`rt_window', `rt_screen', `rt_pubscrname'). But I would like to
discourage you from using `rt_window' and `rt_screen', because incorrect use
will crash the computer.
RexxReqTools will always try to open the requester on the same screen as the
calling program (TECH INFO: but this may not always be possible because some
programs don't set there pr_WindowPtr).

3. Functions
============

This chapter contains the full documentation for the 6 include functions:

    rtezrequest()	  message requester
    rtfilerequest()	  file requester
    rtfontrequest()	  font requester
    rtgetlong() 	  number requester
    rtgetstring()	  text requester
    rtpaletterequest()	  color requester

All requesters are implemented as functions. This means that you have to use
them in an expression or use the `CALL' instruction.

EXAMPLES:

    filename = rtfilerequest()

    CALL rtezrequest('Hello world')

3.1. rtezrequest()
------------------

    ret = rtezrequest(bodytxt, [gadtxt], [title], [tagstring], [resultname])

  DESCRIPTION
    This function puts up a requester for you and waits for a response from
    the user. If the response is positive, this procedure returns 1.
    If the response is negative, this procedure returns 0.
    The function may also return an IDCMP flag or a value corresponding with
    one of other possible responses (see below).

    You can satisfy the requester with the following keyboard shortcuts:
      'Y' or Left Amiga 'V' for a positive response,
      ESC, 'N', 'R' or Left Amiga 'B' for a negative response.

    If ezreqf_noreturnkey is _not_ set (see rtez_flags below) the RETURN key
    is also accepted as a shortcut for the positive response (can be changed
    using rtez_defaultresponse, see below).  The response that will be
    selected when you press RETURN will be printed in bold.

    The ezreqf_lamigaqual flag should be used when you put up a requester
    for a destructive action (e.g. to delete something).  When it is set
    the keyboard shortcuts are limited to Left Amiga 'V' and 'B' so it is
    harder to accidently select something you will regret.
    Note that the RETURN and ESC key remain active!  To disable the RETURN
    key use the ezreqf_noreturnkey flag.  The ESC key cannot be disabled.

  INPUTS
    bodytxt    - requester body text (required).
    gadtxt     - text for gadgets (optional, default to " OK ").
    title      - title of requester window (optional).
    tagstring  - a tag string to set further attributes (optional).
    resultname - this variable will contain the same value as ret (optional,
		 defaults to "rtresult").

  TAGS
    rt_idcmpflags   - Extra idcmp flags to return on.
    rt_reqpos	    - One of the following:
			reqpos_pointer	  - requester appears where the mouse
					    pointer is (default).
			reqpos_centerscr  - requester is centered on the
					    screen.
			reqpos_centerwin  - requester is centered in the
					    window specified by rt_window.
					    If no 'rt_window' is specified the
					    requester will be centered on
					    the screen.
			reqpos_topleftscr - requester appears at the top left
					    of the screen.
			reqpos_topleftwin - requester appears at the top left
					    of the window specified by
					    'rt_window'.
		      The requester will always remain in the visible part of
		      the screen, so if you use the Workbench 2.0 ScreenMode
		      preferences editor to enlarge your Workbench screen and
		      you scroll around, the requester will always appear in
		      the part you can see.
		      'reqpos_centerscr' and 'reqpos_topleftscr' also apply to
		      the visible part of the screen. So if you use one of
		      these the requester will be appear in the center or the
		      top left off what you can see of the screen as opposed
		      to the entire screen.
		      'reqpos_centerwin' and 'reqpos_topleftwin' fall back to
		      'reqpos_centerscr' or 'reqpos_topleftscr' respectively
		      when there is no parent window.  So you can safely use
		      these without worrying about the existence of a window.
    rt_leftoffset   - Offset of left edge of requester relative to position
		      specified with 'rt_reqpos' (does not offset the requester
		      when rt_reqpos is 'reqpos_pointer').
    rt_topoffset    - Offset of top edge of requester relative to position
		      specified with 'rt_reqpos' (does not offset the requester
		      when 'rt_reqpos' is 'reqpos_pointer').
    rt_pubscrname   - Name of public screen requester should appear on. When
		      this tag is used the 'rt_window' tag will be ignored.
		      If the public screen is not found the requester will
		      open on the default public screen.
		      Only works on Kickstart 2.0!  rexxreqtools.library does
		      not check this, it is up to you *NOT* to use this tag
		      on Kickstart 1.3 or below!
		      Note that the 1.3 version of reqtools.library also
		      understands and supports this tag (on 2.0).
    rt_screen	    - Address of screen to put requester on.  You should
		      never use this, use 'rt_window' or 'rt_pubscrname'.
    rt_window	    - Window that will be used to find the screen to put the
		      requester on.
		      NOTE: You have to be cautious with rt_screen and
			    rt_window: if you specify a wrong value the
			    computer will crash.
    rt_waitpointer  - If this is 'true' the window calling the requester will
		      get a standard wait pointer set while the requester is
		      up.
		      Defaults to 'false'.
    rt_lockwindow   - [ReqTools V38] If this is 'true' the window calling the
		      requester will get locked.  It will no longer accept any
		      user input and it will get standard wait pointer set.
		      Defaults to 'false'.
    rt_screentofront- [ReqTools V38] Boolean indicating whether to pop the
		      screen the requester will appear on to the front.
		      Default is 'true'.
    rtez_flags	    - Flags for rtezrequest():
			ezreqf_noreturnkey - turn off the RETURN key as
					     shortcut for positive response.
			ezreqf_lamigaqual  - keyboard shortcuts are limited
					     to Left Amiga 'V' and 'B', ESC
					     and RETURN.
			ezreqf_centertext  - centers each line of body text
					     in the requester window. Useful
					     for about requesters.
    rtez_defaultresponse -
		      Response value that will be returned when the user
		      presses the return key.  Will be ignored if the
		      'ezreqf_noreturnkey' flag is set.  The text for this
		      response will be printed in bold. Default is 1.

  RESULT
    ret - 1 for leftmost (positive) response, then each consecutive response
	  will return 1 more, the rightmost (false) response will return 0
	  (false), so 1,2,3,...,num-1,0 --.
	  If the functions returns anything else the requester was finished
	  through an IDCMP message.


  EXAMPLES

    call rtezrequest('No block marked')

    call rtezrequest('Do you really want to quit?','Quit|Cancel')

    call rtezrequest('Stop?','_Yes|_Maybe|_No',,'rtez_defaultresponse=2')
    /* makes `Maybe' the default response */


3.2.  rtfilerequest()
---------------------

    newfilename = rtfilerequest ([filename], [directory], [title], [oktext],
				 [tagstring], [resultname] )

  DESCRIPTION
    Get a directory and filename(s), or just a directory from the user.

    If you use multiselect (rtfi_flags freqf_multiselect) you should specify
    a resultname (5th argument). The full paths and names of all selected files
    will be placed in the stems of this variable and <resultname>.count will
    contain the number of selected files (or directories).
    NOTE 1: the first filename is <resultname>.1 !!
    NOTE 2: stemvariables will only have a value when the filerequester was not
    cancled !!

    EXAMPLE:
	rtfilerequest(,,"Pick files",,,"rtfi_flags=freqf_multiselect",files)
	say "You selected" files.count "files"
	do i=1 to files.count
	  say "  file" i||":" files.i
	end

  INPUTS
    filename   - default value for the filename, not including path!! (optional).
    directory  - the directory that shown when the filerequester opens
		 (optional).
    title      - requester window title (optional).
    oktext     - replacement text for "Ok" gadget (optional).
    tagstring  - a tag string to set further attributes (optional).
    resultname - this variable will contain 1 if the user pressed "Ok",
		 or 0 if the user pressed "Cancel". When multiselect is used
		 <resultname>.count will contain the number of files (or
		 directories) selected and <resultname>.1 ... will contain the
		 file (or directory) names (optional: defaults to "rtresult").

  TAGS
    rt_window	       - see rtezrequest()
    rt_reqpos	       - see rtezrequest()
    rt_leftoffset      - see rtezrequest()
    rt_topoffset       - see rtezrequest()
    rt_pubscrname      - see rtezrequest()
    rt_screen	       - see rtezrequest()
    rt_waitPointer     - see rtezrequest()
    rt_lockwindow      - [ReqTools V38] see rtezrequest()
    rt_screentofront   - [ReqTools V38] see rtezrequest()
    rtfi_flags	       - Several flags:
			   freqf_multiselect - allow multiple files to be
					       selected.
			   freqf_selectdirs  - set this flag if you wish to
					       enable the selecting of dirs
					       as well as files.  You *must*
					       also set 'freqf_multiselect'.
			   freqf_save	     - Set this if you are using the
					       requester to save or delete
					       something.  Double-clicking
					       will be disabled so it is
					       harder to make a mistake and
					       select the wrong file.  If the
					       user enters a non-existent
					       directory in the drawer string
					       gadget, a requester will
					       appear asking if the directory
					       should be created.
			   freqf_nofiles     - Set this if you want to use
					       the requester to allow the
					       user to select a directory
					       rather than a file.  Ideal for
					       getting a destination dir. May
					       be used with 'freqf_multiselect'
					       and 'freqf_selectdirs'.
			   freqf_patgad      - When this is set a pattern
					       gadget will be added to the
					       requester.
    rtfi_height        - Suggested height of file requester window.
    rtfi_volumerequest - [ReqTools V38] The presence of this tag turns the file
			 requester into a volume/assign disk requester.  This
			 requester can be used to get a device name ("DF0:",
			 "DH1:",..) or an assign ("C:", "FONTS:",...) from the
			 user.
			 that the user may edit the disk/assign names, or
			 enter a new one.  Note also that the real device
			 name is returned, not the name of the volume in the
			 device.  For example "DH1:", not "Hard1:".
			 The tag data is used to set following flags:
			   vreqf_noassigns - Do not include the assigns in
					     the list, only the real devices.
			   vreqf_nodisks   - Do not include devices, just
					     show the assigns.
			   vreqf_alldisks  - Show _all_ devices.  Default
					     behavior is to show only those
					     devices which have valid disks
					     inserted into them.  So if you
					     have no disk in drive DF0: it
					     will not show up.	Set this flag
					     if you do want these devices
					     included.
			 NOTE: Do *NOT* use 'rtfi_volumerequest 1'!
			       You are then setting the vreqf_noassigns flag!
			       Use 'rtfi_volumerequest 0' for a normal
			       volume requester.

  RESULT
    newfilename - the new filename that was selected or an empty string
		  ("") if the requester was canceled.

  EXAMPLES

    open(file,rtfilerequest(,,'_Open','Pick file to open'))

    volume=rtfilerequest(,,,'Pick volume','rtfi_volumerequest=0')


3.3. rtfontrequest()
--------------------

    fontname = rtfontrequest ([title], [oktext], [tagstring], [resultname])

  DESCRIPTION
    Let the user select a font and a style (optional).

  INPUTS
    title      - requester window title (optional);
    oktext     - replacement text for "Ok" gadget (optional);
    tagstring  - a tag string to set further attributes (optional);
    resultname - this variable will contain 1 if the user pressed "Ok",
		 or 0 if the user pressed "Cancel". In addition, if <resultname>
		 equals 1, <resultname>.name, <resultname>.height,
		 <resultname>.bold, <resultname>.italic and
		 <resultname>.underlined will contain the name, the height and
		 style attributes of the select font (if <resultname>.bold
		 equals 1 then bold was selected). (optional, defaults to
		 "rtresult").

  TAGS
    rt_window	      - see rtezrequest()
    rt_reqpos	      - see rtezrequest()
    rt_leftoffset     - see rtezrequest()
    rt_topoffset      - see rtezrequest()
    rt_pubscrname     - see rtezrequest()
    rt_screen	      - see rtezrequest()
    rt_waitpointer    - see rtezrequest()
    rt_lockwindow     - [ReqTools V38] see rtezrequest()
    rt_screentofront  - [ReqTools V38] see rtezrequest()
    rtfo_flags	      - Several flags:
			  freqf_fixedwidth    - only show fixed-width fonts.
			  freqf_colorfonts    - show color fonts also.
			  freqf_changepalette - change the screen's palette
						to match that of a selected
						color font.
			  freqf_leavepalette  - leave the palette as it is
						when exiting rtfontrequest()
						Useful in combination with
						'freqf_changepalette'.
			  freqf_scale	      - allow fonts to be scaled
						when they don't exist in the
						requested size.
						(works on Kickstart 2.0 only,
						 has no effect on 1.2/1.3).
			  freqf_style	      - include gadgets so the user
						may select the font's style.
    rtfo_height       - Suggested height of font requester window.
    rtfo_sampleheight - Height of font sample display in pixels (default 24).
    rtfo_minheight    - Minimum font size displayed.
    rtfo_maxheight    - Maximum font size displayed.

  RESULT
    fontname - name of the font

  EXAMPLES

    call rtfontrequest('Pick font',,'rtfo_flags=freqf_style',font)
    say "You picked" font.name "size" font.height
    if font.bold then say "You selected bold"

3.4.  rtgetlong()
-----------------

    newnumber = rtgetlong ([number], [bodytxt], [title], [gadtxt], [tagstring],
			   [resultname])

  DESCRIPTION
    Puts up a requester to get a signed number from the user.

  INPUTS
    number     - default value (optional);
    bodytxt    - requester body text (optional);
    title      - title of requester window (optional);
    gadtxt     - text for gadgets (optional, defaults to " _Ok |_Cancel");
    tagstring  - a tag string to set further attributes (optional);
    resultname - this variable will contain 1 if the user pressed "Ok",
		 or 0 if the user pressed "Cancel". if rt_idcmpflags or <gadtxt>
		 are used this variable will contain the same value as
		 rtezrequest() would return (optional: defaults to "rtresult").

  TAGS
    rt_window	     - see rtezrequest()
    rt_idcmpflags    - see rtezrequest()
    rt_reqpos	     - see rtezrequest()
    rt_leftoffset    - see rtezrequest()
    rt_topoffset     - see rtezrequest()
    rt_pubscrname    - see rtezrequest()
    rt_screen	     - see rtezrequest()
    rt_waitpointer   - see rtezrequest()
    rt_lockwindow    - [ReqTools V38] see rtezrequest()
    rt_screentofront - [ReqTools V38] see rtezrequest()
    rtgl_min	     - Minimum allowed value. If the user tries to enter a
		       smaller value the requester will refuse to accept it.
    rtgl_max	     - Maximum allowed value, higher values are refused.
    rtgl_width	     - Width of requester window in pixels.  This is only a
		       suggestion. rtgetlong() will not go below a
		       certain width.
    rtgl_invisible   - [ReqTools V38] Using this tag you can switch on invisible
		       typing.
		       Very useful if you need to get something like a
		       code number from the user. Default is 'false'.
    rtgl_backfill    - Backfill requester window with pattern.	Default 'true'.
    rtgl_flags	     - [ReqTools V38]
			 glreqf_centertext    - centers each line of text
						above the gadget in the
						requester window. Should
						be generally set.
			 glreqf_highlighttext - Highlight text above the
						gadget. You will normally
						only want to use this if you
						also turned off the window
						backfilling.

  RESULT
    newnumber - the number that was entered or empty string ("") if the
		requester was canceled.

  EXAMPLES

    age=rtgetlong(,"Enter your age",,,"rtgl_min=0 rtgl_max=120")

3.5. rtgetstring()
------------------

    newstring = rtgetstring ([string], [bodytxt], [title], [gadtxt],
			     [tagstring], [resultname])

  DESCRIPTION
    Puts up a string requester to get a line of text from the user.
    The text present in 'string' upon entry will be displayed, ready to
    be edited.

  INPUTS
    string     - default value (optional);
    bodytxt    - requester body text (optional);
    title      - title of requester window (optional);
    gadtxt     - text for gadgets (optional, defaults to " _Ok |_Cancel");
    tagstring  - a tag string to set further attributes (optional);
    resultname - this variable will contain 1 if the user pressed "Ok",
		 or 0 if the user pressed "Cancel". if rt_idcmpflags or <gadtxt>
		 are used this variable will contain the same value as
		 rtezrequest() would return (optional: defaults to "rtresult").

  TAGS
    rt_window	     - see rtezrequest()
    rt_idcmpflags    - see rtezrequest()
    rt_reqpos	     - see rtezrequest()
    rt_leftoffset    - see rtezrequest()
    rt_topoffset     - see rtezrequest()
    rt_pubscrname    - see rtezrequest()
    rt_screen	     - see rtezrequest()
    rt_waitpointer   - see rtezrequest()
    rt_lockwindow    - [ReqTools V38] see rtezrequest()
    rt_screentofront - [ReqTools V38] see rtezrequest()
    rtgs_width	     - Width of requester window in pixels.  This is only a
		       suggestion. rtgetstring() will not go below a certain
		       width.
    rtgs_invisible   - [ReqTools V38] Using this tag you can switch on invisible
		       typing.
		       Very useful if you need to get something like a
		       password from the user.	It is strongly advised to use
		       an empty initial string or the user may get very
		       confused!  Default is 'false'.
    rtgs_backfill    - [ReqTools V38] Backfill requester window with pattern.
		       Default 'true'.
    rtgs_flags	     - [ReqTools V38]
			 gsreqf_centertext    - centers each line of text
						above the gadget in the
						requester window. Should
						be generally set.
			 gsreqf_highlighttext - Highlight text above the
						gadget. You will normally
						only want to use this if you
						also turned off the window
						backfilling.

  RESULT
    newstring - the string that was entered or empty string ("") if the
		requester was canceled.

  EXAMPLES

    name=rtgetstring(,"Enter your name")

    password=retgetstring(,"Enter your password",,,"rtgs_invisible=true")


3.6. rtpaletterequest()
-----------------------

    newcolor = rtpaletterequest ([color], [title], [tagstring], [resultname])

  DESCRIPTION
    Put up a palette requester so the user can change the screen's colors.

    The colors are changed in the viewport of the screen the requester will
    appear on, so that is where you will find them after the palette
    requester returns.

    The selected color is returned, so you can also use this requester to let
    the user select a color.

  INPUTS
    color      - initially selected color of palette (optional, defaults to 1);
    title      - requester window title (optional);
    tagstring  - a tag string to set further attributes (optional);
    resultname - this variable will contain 1 if the user pressed "Ok",
		 or 0 if the user pressed "Cancel" (optional: defaults to
		 "rtresult").

  TAGS
    rt_window	     - see rtezrequest()
    rt_reqpos	     - see rtezrequest()
    rt_leftoffset    - see rtezrequest()
    rt_topoffset     - see rtezrequest()
    rt_pubscrname    - see rtezrequest()
    rt_screen	     - see rtezrequest()
    rt_waitpointer   - see rtezrequest()
    rt_lockwindow    - [ReqTools V38] see rtezrequest()
    rt_screentofront - [ReqTools V38] see rtezrequest()

  RESULT
    newcolor - the color number of the selected color or an empty string ("")
	       if the request was canceled.

  EXAMPLES

    color=rtpaletterequest(,"Pick color")

3.7. rtscreenmoderequest() [ReqTools V38] (NOT IMPLEMENTED)
--------------------------

    screenmode = rtscreenmoderequest ( ??? )

  DESCRIPTION

    Get a screen mode from the user.

    The user will be able to pick a screen mode by name, enter the size and
    the number of colors (bitplane depth).

  NOTE: If you have any suggestions for this requester, please send them to
	me, and then maybe I will implement this requester in a future
	version.

4. Copyright
============

The programs and files in this distribution are freely distributable, but are
also Copyright © Rafael D'Halleweyn. They may be freely distributed as long as
no more than a nominal fee is charged to cover time and copying costs.
No commercial usage is allowed, except for W.S. Hawes who has the explicit
permision to include RexxReqTools with ARexx.

4.1. Redistribution
-------------------
You are allowed to redistribute this package. However the minimal distribution
should contain

    rexxreqtools.doc
    rexxreqtools.library
    reqtools.library


5. History
==========

Release 1.0 [library version 37.19]

    First release

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

RexxReqTools was written by Rafael D'Halleweyn. Thanks go to Nico François,
who wrote ReqTools, who was great support and from whom I stole a large part
of this manual. Also thanks to William Hawes for ARexx.

(C) 1992-1993 Rafael D'Halleweyn