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 . 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.