home *** CD-ROM | disk | FTP | other *** search
-
- RexxArpLib.Library documentation
- ================================
-
- Okay, this is the beginning of a REXX interface to the ARP
- library. Only a few functions sofar. One is the famous Heath file requester,
- another is a simple combination string/boolean requester that does
- auto-everything. All you have to do is specify the strings you want it
- to display... Then there are environment variable things, and a simple
- message window you can keep hanging around.
-
- getfile
- =======
-
- Calling sequence:
-
- result = getfile(x, y, pathname, filename, hailstring, publicwin)
-
- x = x coordinate of top-left corner of requester.
- y = y coordinate of top-left corner of requester.
- pathname = Default path name, first path name to be searched.
- filename = Default file name.
- hailstring = User instruction string.
- result = The selected path/file name
- publicwin = Name of a public window (optional).
-
- All arguments are optional, but the order is fixed. Therefore if only
- the second or third argument is specified, it needs to be prefixed by
- sufficient commas.
- The selected path concatenated with the selected file name are
- returned as 'result'. Notice, that the result is not necessarily an existing
- file. It is up to the user to ascertain that the result is suitable for his
- purposes. If the user hits "CANCEL", the result is an empty string. Notice
- that another way the result comes out to be empty is when the user leaves the
- requester hitting "OKAY" when both the path and file string gadgets are
- empty.
- If 'publicwin' is specified, the function will try to find the window
- of that name. If it is set up properly, the requester will open on that window's
- screen. If not, the requester will appear on the Workbench. The mechanism that
- is currently used for this is subject to change.
-
- request
- =======
-
- Calling sequence:
-
- result = request(x, y, prompts, string, okaytext, canceltext, publicwin)
-
- x = x coordinate of top-left corner of requester.
- y = y coordinate of top-left corner of requester.
- prompts = A string which will be displayed above any gadgets.
- Any embedded '\' characters will be treated as a line
- break.
- string = The default string to be displayed in a string gadget.
- If omitted, no string gadget will be provided.
- okaytext = The text to be used for an Okay gadget.
- If omitted, no okay gadget will be provided.
- canceltext = The text to be used for a Cancel gadget.
- If omitted, no cancel gadget will be provided.
- publicwin = Name of a public window (optional).
-
- All arguments are optional, but the order is fixed. Therefore if
- only the second or third argument is specified, it needs to be prefixed by
- sufficient commas.
- If a string gadget is present, but no okay gadget, the string
- will be returned after modification by the user in result when the user
- hits <return>.
- If both a string gadget and an okay gadget are present, the string
- will be returned in result only when the user clicks on the okay gadget.
- If no string gadget is present, clicking of the okay gadget (if
- present) will cause the return in result of the string "OKAY".
- In any case, if the user clicks either the cancel gadget or the
- close gadget, an empty string will be returned. Notice that another way the
- result comes out to be empty is when the user leaves the requester hitting
- "OKAY" when the string gadget is empty.
- If 'publicwin' is specified, the function will try to find the window
- of that name. If it is set up properly, the requester will open on that window's
- screen. If not, the requester will appear on the Workbench. The mechanism that
- is currently used for this is subject to change.
-
- postmsg
- =======
-
- This function sets up a window with text. It returns immediately to
- the caller. Subsequent calls will erase lines and fill them with new text.
- If a line has zero length, the line will NOT be erased. This has the advantage
- that you can change the text in a line without redisplaying text in another
- line. It has the disadvantage that in order to erase lines, you have to
- specify at least a single space for each line you want to erase.
- The window will remain open, until a call is made with too few arguments.
- This is NOT a reentrant function: there is only one window pointer, and
- subsequent calls by ANY REXX process will affect the window.
-
- Calling sequence:
-
- result = postmsg(x, y, strings, publicwin)
-
- x = x coordinate of top-left corner of requester.
- y = y coordinate of top-left corner of requester.
- string = A string which will be displayed above any gadgets.
- Any embedded '\' characters will be treated as a line
- break.
- result = 1 for success, 0 otherwise.
- publicwin = Name of a public window (optional).
-
- All arguments are optional, but the order is fixed. Therefore if
- only the second or third argument is specified, it needs to be prefixed by
- sufficient commas.
- Examples:
- Postmsg(50, 50, "This is line 1\This is line 2")
- will cause a window to appear with two lines of text. A subsequent call
- Postmsg(50, 50, "\This is a new line 2")
- will cause the second line of the window to be replaced by the new text. The
- construct:
- PostMsg(50, 50, " \")
- will erase the first line but leave the second one alone (notice the space).
- If too few arguments are specified, this function will cause the
- window to be closed.
- If 'publicwin' is specified, the function will try to find the window
- of that name. If it is set up properly, the requester will open on that window's
- screen. If not, the requester will appear on the Workbench. The mechanism that
- is currently used for this is subject to change.
-
- getenv
- ======
-
- Calling sequence:
-
- result = getenv(variable)
-
- variable = Environment variable.
- result = The value of the environment variable.
-
- This function gets the value of an environment variable. If the
- variable does not exist, an empty string will be returned.
-
- setenv
- ======
-
- Calling sequence:
-
- result = setenv(variable, valuestring)
-
- variable = Environment variable.
- valuestring = The new value for the environment variable.
- result = Always 1.
-
- This function (creates and) sets the environment variable to a
- a (new) value. If 'valuestring' is missing, the function will remove the
- environment variable.
-
- screentoback, screentofront
- ===========================
-
- These functions depth arrange screens. If no argument is specified,
- the screen operated on is the Workbench screen. If the name of a public window
- is specified, its associated screen will be affected.
-
- Calling sequence:
-
- result = screentoback(publicwin)
- result = screentofront(publicwin)
-
- publicwin = Name of a public window (optional).
-
- The argument is optional. If it is not specified, this function will
- cause the Workbench to be put in back/front of other screens.
- If 'publicwin' is specified, the function will try to find the window
- of that name. If it is set up properly, the window's screen will be moved to
- the back/front. If not, the function will operate on the Workbench screen.
- screen. The mechanism that is currently used for this is subject to change.
-
-
- Willy.
-