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