home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff227.lzh / RexxArpLib / docs / rexxarplib.doc < prev    next >
Text File  |  1989-06-25  |  32KB  |  684 lines
  1.  
  2.  
  3.                    RexxArpLib.Library Version 2.3
  4.                    ==============================
  5.  
  6.                       Copyright (C) 1988, 1989
  7.  
  8.                                 by
  9.  
  10.                           W.G.J. Langeveld
  11.  
  12.         Stanford Linear Accelerrator Center
  13.  
  14.  
  15. Version 2.3:
  16. -------------
  17.  
  18.     Minor update. A new option was added to FileList to inhibit expansion of
  19. file names where not wanted. DrawCircle apparently never worked, can't believe
  20. noone noticed: it is fixed now. A small bug in the simple requester code was
  21. found and fixed, as well as a few similar ones in the file requester interface
  22. code. Finally: the 'version' command will now properly display the version
  23. number of rexxarplib and rexxmathlib.
  24.  
  25.     20 May 1989, WGL
  26.  
  27.  
  28. Version 2.2a:
  29. -------------
  30.  
  31.     A small bug fix in IffImage().
  32.  
  33.     5 April 1989, WGL
  34.  
  35.  
  36. Version 2.2:
  37. ------------
  38.  
  39.     New in version 2.2 is an extension to the FileList() function. It can
  40. now expand the file names to include the full path, by supplying another
  41. argument. It will now also return the number of files in the .0 field of the
  42. stem variable, to make it more similar to ExecIO. A bug was fixed...
  43.     Also, version 2.2 now uses ARP's Getenv and Setenv calls, so that with
  44. ARP 1.3 you can use environment variables in the ENV: directory.
  45.     Another addition is a new option for IFFImage() allowing one to load
  46. images without changing the screen's colors.
  47.     Missing from the documentation so far has been that rexxarplib.library
  48. *requires* the presence of screenshare.library and diskfont.library in your
  49. current libs: directory. Several reports about library functions only returning
  50. error 12 have been due to these libraries not being present.
  51.     There was also a mistake in the documentation. The function that used
  52. to be listed as FreeMenu() is really called RemoveMenu().
  53.     The behavior of GetEnv() was changed by popular request. It will no
  54. longer generate an error when the argument is not an existing env variable.
  55. Instead it will return an empty string.
  56.  
  57.     20 February 1989, 8 March 1989, WGL
  58.  
  59. Version 2.1:
  60. ------------
  61.  
  62.     New in version 2.1 are the general function ScreenColor, and the
  63. CreateHost-related functions ReadHost, SetGadget and IFFImage. The allowed
  64. flag for AddItem and AddSubItem is now a specific one (this is an "incompatible"
  65. change). CloseWindow now allows the host to stay around through a second
  66. argument. The window flag DELTAMOVE was added for OpenWindow, and the window
  67. location is now available in reports (%e and %f).
  68.     The function IFFImage needs some explanation. It allows you to display
  69. (a portion of) an IFF image in your CreateHost window. For the time being, this
  70. function makes use of the iff.library written by Christian Weber. However, there
  71. is a suspicion that this library may cause the occasional system crash, and it is
  72. known that DPaint-style brushes are not supported. Only straight IFF picture
  73. files are known to work more or less reliably. At some point I intend to use
  74. something else.
  75.  
  76. Version 2.0:
  77. ------------
  78.  
  79.     Originally, this library was supposed to be an ARexx interface to the
  80. ARP library. However, although it indeed interfaces to some of the ARP
  81. functions, it has become much more of an interface to various Intuition
  82. functions. I have considered renaming the library to something else, but by now
  83. everyone refers to it by this name, so I'll leave it like it is.
  84.     Version 2.0 is pretty much the final version. The library has grown
  85. considerably since the first release, and it is about as big as a library should
  86. ever get. If I find the need for a lot of other functions, they'll have to go
  87. into a different library.
  88.     The library contains over 50 functions now. One is Charlie's famous ARP
  89. file requester, another is a simple combination string/boolean requester that
  90. does auto-everything. All you have to do is specify the strings you want it to
  91. display. Then there are environment variable things, and a simple message window
  92. you can keep hanging around. On popular request, there is now a wildcard
  93. expander (not to be confused with a 'directory' function!) that uses the new Rexx
  94. Variables Interface (RVI).
  95.     The major new things though, are the interface routines to Intuition.
  96. You can now open screens and windows, add boolean and string gadgets to them as
  97. well as menus, draw lines and areas and circles and whatever. You can make your
  98. gadgets, menus, and windows send messages to wherever you like and you can 
  99. format those messages, though they have to ARexx messages, in any way you like,
  100. using any information that's currently available. All this is rather hard to
  101. explain. You'll really have to play with it and look at some examples.
  102.     As usual, this stuff is NOT public domain, but freely distributable.
  103.  
  104.     So have fun!
  105.  
  106.     Willy.
  107.  
  108.  
  109.  
  110. The functions are listed below.
  111. --------------------------------------------------------------------------------
  112.  
  113. GetFile
  114. =======
  115.  
  116.     Calling sequence:
  117.  
  118.     result = GetFile(x, y, pathname, filename, hailstring, publicscreen)
  119.  
  120.     x            = x coordinate of top-left corner of requester.
  121.     y            = y coordinate of top-left corner of requester.
  122.     pathname     = Default path name, first path name to be searched.
  123.         filename     = Default file name.
  124.         hailstring   = User instruction string.
  125.         result       = The selected path/file name
  126.         publicscreen = Name of a public screen (optional).
  127.  
  128.     All arguments are optional, but the order is fixed. Therefore if only
  129. the second or third argument is specified, it needs to be prefixed by
  130. sufficient commas.
  131.     The selected path concatenated with the selected file name are
  132. returned as 'result'. Notice, that the result is not necessarily an existing
  133. file. It is up to the user to ascertain that the result is suitable for his
  134. purposes. If the user hits "CANCEL", the result is an empty string. Notice
  135. that another way the result comes out to be empty is when the user leaves the
  136. requester hitting "OKAY" when both the path and file string gadgets are
  137. empty.
  138.     If 'publicscreen' is specified, the function will try to find the screen
  139. of that name. If it is set up properly, the requester will open on that 
  140. screen. If not, the requester will appear on the Workbench. The mechanism that
  141. is currently used for this is subject to change.
  142.  
  143. Request
  144. =======
  145.  
  146.     Calling sequence:
  147.  
  148.     result = Request(x, y, prompts, string, okaytext, canceltext, publicscreen)
  149.  
  150.     x             = x coordinate of top-left corner of requester.
  151.     y             = y coordinate of top-left corner of requester.
  152.         prompts       = A string which will be displayed above any gadgets.
  153.                         Any embedded '\' characters will be treated as a line
  154.                         break.
  155.         string        = The default string to be displayed in a string gadget.
  156.                         If omitted, no string gadget will be provided.
  157.     okaytext      = The text to be used for an Okay gadget.
  158.                     If omitted, no okay gadget will be provided.
  159.     canceltext    = The text to be used for a Cancel gadget.
  160.                     If omitted, no cancel gadget will be provided.
  161.         publicscreen  = Name of a public screen (optional).
  162.  
  163.     All arguments are optional, but the order is fixed. Therefore if
  164. only the second or third argument is specified, it needs to be prefixed by
  165. sufficient commas.
  166.     If a string gadget is present, but no okay gadget, the string
  167. will be returned after modification by the user in result when the user
  168. hits <return>.
  169.     If both a string gadget and an okay gadget are present, the string
  170. will be returned in result only when the user clicks on the okay gadget.
  171.     If no string gadget is present, clicking of the okay gadget (if 
  172. present) will cause the return in result of the string "OKAY".
  173.     In any case, if the user clicks either the cancel gadget or the
  174. close gadget, an empty string will be returned. Notice that another way the
  175. result comes out to be empty is when the user leaves the requester hitting
  176. "OKAY" when the string gadget is empty.
  177.     If 'publicscreen' is specified, the function will try to find the screen
  178. of that name. If it is set up properly, the requester will open on that 
  179. screen. If not, the requester will appear on the Workbench. The mechanism that
  180. is currently used for this is subject to change.
  181.  
  182. PostMsg
  183. =======
  184.  
  185.     This function sets up a window with text. It returns immediately to
  186. the caller. Subsequent calls will erase lines and fill them with new text.
  187. If a line has zero length, the line will NOT be erased. This has the advantage
  188. that you can change the text in a line without redisplaying text in another
  189. line. It has the disadvantage that in order to erase lines, you have to
  190. specify at least a single space for each line you want to erase.
  191. The window will remain open, until a call is made with too few arguments. 
  192. This is NOT a reentrant function: there is only one window pointer, and
  193. subsequent calls by ANY REXX process will affect the window.
  194.  
  195.     Calling sequence:
  196.  
  197.     result = PostMsg(x, y, strings, publicscreen)
  198.  
  199.     x             = x coordinate of top-left corner of requester.
  200.     y             = y coordinate of top-left corner of requester.
  201.         string        = A string which will be displayed above any gadgets.
  202.                         Any embedded '\' characters will be treated as a line
  203.                         break.
  204.     result        = 1 for success, 0 otherwise.
  205.         publicscreen  = Name of a public screen (optional).
  206.  
  207.     All arguments are optional, but the order is fixed. Therefore if
  208. only the second or third argument is specified, it needs to be prefixed by
  209. sufficient commas.
  210.     Examples:
  211.        Postmsg(50, 50, "This is line 1\This is line 2")
  212. will cause a window to appear with two lines of text. A subsequent call
  213.        Postmsg(50, 50, "\This is a new line 2")
  214. will cause the second line of the window to be replaced by the new text. The
  215. construct:
  216.        PostMsg(50, 50, " \")
  217. will erase the first line but leave the second one alone (notice the space).
  218.     If too few arguments are specified, this function will cause the
  219. window to be closed.
  220.     If 'publicscreen' is specified, the function will try to find the screen
  221. of that name. If it is set up properly, the requester will open on that 
  222. screen. If not, the requester will appear on the Workbench. The mechanism that
  223. is currently used for this is subject to change.
  224.  
  225. Getenv
  226. ======
  227.  
  228.     Calling sequence:
  229.  
  230.     result = Getenv(variable)
  231.  
  232.     variable   = Environment variable.
  233.         result     = The value of the environment variable.
  234.  
  235.     This function gets the value of an environment variable. If the
  236. variable does not exist, an empty string will be returned.
  237.  
  238. Setenv
  239. ======
  240.  
  241.     Calling sequence:
  242.  
  243.     result = Setenv(variable, valuestring)
  244.  
  245.     variable    = Environment variable.
  246.     valuestring = The new value for the environment variable.
  247.         result      = Always 1.
  248.  
  249.     This function (creates and) sets the environment variable to a
  250. a (new) value. If 'valuestring' is missing, the function will remove the
  251. environment variable.
  252.  
  253. ScreenToBack, ScreenToFront
  254. ===========================
  255.  
  256.     These functions depth arrange screens. If no argument is specified,
  257. the screen operated on is the Workbench screen. If the name of a public screen
  258. is specified, it will be affected.
  259.  
  260.     Calling sequence:
  261.  
  262.     result = screentoback(publicscreen)
  263.     result = screentofront(publicscreen)
  264.  
  265.         publicscreen  = Name of a public screen (optional).
  266.  
  267.     The argument is optional. If 'publicscreen' is specified, the function
  268. will try to find the screen of that name. If it is set up properly, the screen
  269. will be moved to the back/front. If not, the function will operate on the
  270. Workbench screen. The mechanism that is currently used for this is subject to
  271. change.
  272.  
  273. ScreenRows, ScreenCols, ScreenLace, ScreenColor
  274. ===============================================
  275.  
  276.     These functions retrieve info about screens. If no argument is
  277. specified, the screen operated on is the Workbench screen. If the name of a
  278. public screen is specified, it will be used.
  279.  
  280.     Calling sequences:
  281.  
  282.     result = ScreenRows(publicscreen)     /* return number of rows */
  283.     result = ScreenCols(publicscreen)     /* return number of columns */
  284.     result = ScreenLace(publicscreen)     /* return interlace */
  285.     result = ScreenColor(publicscreen, n) /* return color n */
  286.  
  287.         publicscreen  = Name of a public screen (optional).
  288.  
  289.     ScreenRows and ScreenCols retrieve the number of rows and columns in
  290. pixels. The function ScreenLace() returns 0 if the screen is not interlaced, and
  291. 1 if it is. The function returns -1 if the information could not be found.
  292. ScreenColor retrieves the RGB values of the selected color in the format:
  293. <red><space><green><space><blue>, e.g:   15 0 0  for an all red screen.
  294.     Except with ScreenColor, the first argument is optional.  If
  295. 'publicscreen' is specified, the function will try to find the screen of that
  296. name. If it is set up properly, information about the screen will be returned.
  297. If not, the function will operate on the Workbench screen. The mechanism that is
  298. currently used for this is subject to change. ScreenColor only operates on
  299. public screens.
  300.  
  301. OpenScreen, CloseScreen
  302. =======================
  303.  
  304.     These functions allow you to open public custom screens.
  305.  
  306.     Calling sequence:
  307.  
  308.     result = OpenScreen(topedge, depth, modes, defaulttitle, publicscreen)
  309.     result = CloseScreen(publicscreen)
  310.  
  311.     topedge       = Y coordinate of top edge of the screen.
  312.     depth         = Number of bitplanes.
  313.     modes         = Viewmodes and type of screen. The currently supported
  314.                         viewmodes are "HIRES", "LACE", and "HAM". The one
  315.                         currently supported type is "SCREENBEHIND".
  316.     defaulttitle  = Default title for the screen title bar.
  317.         publicscreen  = Name of a public screen (optional).
  318.  
  319.     result        = 0 on failure, 1 on success.
  320.  
  321.     The last argument is required, therefore you must supply sufficient
  322. commas and a name for the public screen to be created/closed. With openscreen,
  323. leaving out any of the other arguments will cause defaults to be used. They are
  324. topedge = 0, depth = 2, modes = 0 (meaning LORES, no LACE), and no default
  325. title. This is equivalent to specifying 0 for all arguments (a depth of 0 is
  326. illegal and will be changed to 2). All created screens are CUSTOM screens.
  327.     The mechanism that is currently used for public screens is subject to
  328. change.
  329.     ***NOTE: It is perfectly possible to apply closescreen() to another
  330. application's custom screen (if it is public, using the same conventions as
  331. used here). If you attempt this, a software failure is almost guaranteed. Only
  332. use closescreen() on screens you created using openscreen()!
  333.  
  334. FileList
  335. ========
  336.  
  337.     This function does ARP pattern matching. Given a pattern, it will
  338. return all files and/or directories matching the pattern.
  339.  
  340.     Calling sequence:
  341.  
  342.     number = FileList(pattern, stem, type, expand)
  343.  
  344.     pattern       = a search pattern using ARP wildcards.
  345.         stem          = the NAME of a stem variable to be created.
  346.         type          = D - directories only. F - files only.
  347.         expand        = E - expand full path name. N - remove path name
  348.                     not specified: don't expand, but don't remove either.
  349.  
  350.     number        = the number of files matching the pattern.
  351.  
  352.     When files with names matching the  pattern are found, a stem variable
  353. with the name given by 'stem' is created in the current Rexx context. It has
  354. fields 1, 2, ... , <number> containing the names of the files. The return value
  355. and also the stem variable's field 0 are equal to the number of files. The last
  356. two arguments are optional: with 'type', when an F is specified, only files are
  357. listed. When a D is specified only directories are listed. With 'expand', if an
  358. E is specified, the full path name is expanded. If an N is specified, any
  359. pathname part of the pattern will be removed. Example: a simple directory
  360. program looks like
  361.  
  362.     /* Directory program, list everything, with full path */
  363.     arg pattern
  364.     if pattern = "" then pattern = "*"
  365.     numfils = FileList(pattern, myfilelist, , E)
  366.     do i = 1 to numfils; say myfilelist.i; end
  367.     exit
  368.  
  369. CreateHost
  370. ==========
  371.  
  372.     This function allows you to create a single window with gadgets, menus,
  373. text, graphics, etc. Of course, multiple copies of the function may be started
  374. up to create more windows, but each must have a unique 'controlport'. This
  375. function should be started up asynchronously, using runwsh, and one should wait
  376. for the 'controlport' to appear using e.g. WaitForPort.
  377.  
  378.     Calling sequence:
  379.  
  380.     runwsh 'call CreateHost(controlport, notifyport, publicscreen)'
  381.  
  382.     controlport   = Name of the message port this window should listen to.
  383.     notifyport    = Name of the message port that should be notified when
  384.                         an IDCMP event occurs.
  385.         publicscreen  = Name of a public screen (optional).
  386.  
  387.     When the function is first called, it will open a message port with the
  388. name given by "controlport". The function will then wait for commands coming in
  389. through this port. This may be accomplished using one of many intuition
  390. functions, as explained later. One of the first commands should be to open the
  391. associated window by calling OpenWindow (see later). It will then open a window
  392. as specified in the OpenWindow call. If any message arrives through the IDCMP of
  393. this window, a REXX message will be sent to the port specified as "notifyport"
  394. which either you should set up in your rexx macro for this purpose, or should be
  395. an otherwise existing rexx message port belonging to another process. In the
  396. case you set up your own port, make sure the message is replied to after having
  397. been  retrieved and examined. If the  notifyport does not exist, no message will
  398. be sent. The window can be closed by the rexx macro by calling the function
  399. CloseWindow (see later). On startup, the notify port is the same for all classes
  400. of messages. This can be changed using the SetNotify() function, see later.
  401.     The last argument is optional.  If 'publicscreen' is specified, the
  402. function will try to find the screen of that name. If it is set up properly, the
  403. window will be opened on it. If not, the window will be opened on the Workbench
  404. screen. The mechanism that is currently used for this is subject to change.
  405.  
  406. Supported Intuition (and other) functions with createhost
  407. =========================================================
  408.  
  409.     The following functions are implemented as CreateHost functions. The 
  410. first argument is always the name of the control port of the host that is
  411. supposed to execute the command. A little secret: you can send commands
  412. *directly* to the controlport also by constructs like "Address controlport
  413. commandname". However, this only works for commands without further arguments.
  414. For example, from WShell, "address controlport CloseWindow" is equivalent to
  415. "call CloseWindow(controlport)". This can come in incredibly handy at times.
  416. For example, when you want command hosts to send message to themselves: you
  417. can tell a host to send IDCMP events of class CLOSEWINDOW to itself...
  418. Boggles the mind yet? Read on...
  419.  
  420.    call ActivateGadget(controlport, gadgetid)
  421.         Tries to activate a string gadget with id 'gadgetid'.
  422.  
  423.    call ActivateWindow(controlport)
  424.  
  425.    call AreaCircle(controlport, xcenter, ycenter, radius)
  426.  
  427.    call AreaDraw(controlport, x, y)
  428.         Only 100 vertices are currently allowed before each AreaEnd().
  429.  
  430.    call AreaEllipse(controlport, xcenter, ycenter, radius1, radius2)
  431.  
  432.    call AreaEnd(controlport)
  433.         Only 100 vertices are currently allowed before each AreaEnd().
  434.  
  435.    call AreaMove(controlport, x, y) 
  436.         Only 100 vertices are currently allowed before each AreaEnd().
  437.  
  438.    call AddGadget(controlport, x, y, gadgetid, gadgettext, messagetext, hsize)
  439.         If hsize is specified, this call creates a string gadget of that
  440.         horizontal size and gadgettext is the default string. If hsize is
  441.         not specified, this call creates an autosizing boolean gadget, where
  442.         the text in gadgettext is displayed. In both cases, the string in
  443.         messagetext is sent to controlport (see also under OpenWindow). As
  444.         usual, the gadgettext for boolean gadgets may contain \ characters
  445.         to cause multiple lines of text (See e.g. PostMsg()).
  446.  
  447.    call AddItem(controlport, itemname, message, commandchar, mutualexclude, flag)
  448.         Add a new item with name 'itemname'. Optionally, you may specify a
  449.         command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
  450.         mask. See Intuition manual. A special value of the mutual exclude mask
  451.         is -1: this means that the item will be toggle selectable. If the flag
  452.         argument is "SAMELINE", the item will be on the same line as the previous
  453.         item, otherwise, or if the argument is not present, it will be on the 
  454.         next line.
  455.         See also AddMenu(), AddSubItem(), RemoveMenu(), SetItem().
  456.  
  457.    call AddMenu(controlport, menuname)
  458.         Add a new menu with name 'menuname'. See also AddItem(), AddSubItem(),
  459.         RemoveMenu(), SetItem().
  460.  
  461.    call AddSubItem(controlport,itemname,message,commandchar,mutualexclude,flag)
  462.         Add a new subitem with name 'itemname'. Optionally, you may specify a
  463.         command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
  464.         mask. See Intuition manual. A special value of the mutual exclude mask
  465.         is -1: this means that the item will be toggle selectable. If the flag
  466.         argument is "SAMELINE", the item will be on the same line as the previous
  467.         item, otherwise, or if the argument is not present, it will be on the 
  468.         next line.
  469.         See also AddMenu(), AddItem(), RemoveMenu(), SetItem().
  470.  
  471.    call BackFill(controlport)
  472.         This is not an intuition function. See OpenWindow().
  473.  
  474.    call CloseWindow(controlport, flag)
  475.         This function closes the window and deallocates all resources. The 'flag'
  476.         argument is optional. If present, and if the flag is equal to "CONTINUE",
  477.         the host will remain active. Otherwise, the host will exit.
  478.  
  479.    call Draw(controlport, x, y)
  480.  
  481.    call DrawCircle(controlport, xcenter, ycenter, radius)
  482.  
  483.    call DrawEllipse(controlport, xcenter, ycenter, radius1, radius2)
  484.  
  485.    call Exit(controlport)
  486.         This function closes the window, deallocates all resources and causes
  487.         the host to exit. Exit(), Quit() and Stop() are identical.
  488.  
  489.    call Flood(controlport, mode, x, y)
  490.         If mode is 0, the flood continues until pixels of the outline pen
  491.         color are found. If the mode is 1, the flood continues until pixels
  492.         of a different color than the pixel at x, y are found.
  493.  
  494.    call RemoveMenu(controlport)
  495.         Gets rid of any attached menu.
  496.  
  497.    call IFFImage(controlport, filename, x, y, width, height, flag)
  498.         Displays a chunk of size 'width', 'height' of an IFF ILBM file named
  499.         'filename' at x, y in the window. If x, y, width, and/or height are
  500.         omitted, suitable defaults are chosen. The colormap of the IFF file,
  501.         if any, is NOT used on the Workbench, but IS used on custom screens.
  502.         The 'flag' option can be set to 'NOCOLOR' (N is sufficient) to prevent
  503.         modifying the custom screen's colors.
  504.  
  505.    call ModifyHost(controlport, IDCMPclass, messagestring)
  506.         This function allows you to set the message string that is sent to 
  507.         the notifyport for a particular class of IDCMP events. See OpenWindow.
  508.  
  509.    call Move(controlport, x, y)
  510.  
  511.    call OpenWindow(controlport, leftedge, topedge, width, height,
  512.                                 idcmp, flags, title)
  513.         width and height may be set to 0 to get the maximum size of the window.
  514.         idcmp is a string that specifies the IDCMP for the window. Supported are:
  515.  
  516.            IDCMP message    |  default arg[0]          
  517.         --------------------+-------------------
  518.           "CLOSEWINDOW"     |  "%l"            
  519.           "MOUSEBUTTONS"    |  "%l"            
  520.           "GADGETUP"        |  <its string>   
  521.           "GADGETDOWN"      |  <its string>   
  522.           "MENUPICK"        |  "%l"            
  523.           "NEWSIZE"         |  "%l"            
  524.           "VANILLAKEY"      |  "%l"            
  525.           "RAWKEY"          |  "%l"            
  526.           "NEWPREFS"        |  "%l"            
  527.           "DISKINSERTED"    |  "%l"            
  528.           "DISKREMOVED"     |  "%l"            
  529.           "ACTIVEWINDOW"    |  "%l"            
  530.           "INACTIVEWINDOW"  |  "%l"            
  531.           "REFRESHWINDOW"   |  "%l"            
  532.           "MOUSEMOVE"       |  "%l"            
  533.           "DELTAMOVE"       |  "%l"            
  534.  
  535.         Any number of these may be specified in the OpenWindow call, by conca-
  536.         tenation. When any of these messages arrives at the IDCMP, a REXX
  537.         message is created with a particular string in Arg[0]. This string is
  538.         by default the one given in the table above, after substitution has
  539.         taken place for any two-character sequence starting with '%'.
  540.         The following substitutions will be made:
  541.  
  542.         Sequence: | Typical Use: |     Meaning:
  543.         ----------+--------------+---------------
  544.             %%    |              | A single % sign
  545.             %a    | Vanillakeys  | 'Code' is interpreted as an ASCII character.
  546.             %b    | Buttons      | SELECTDOWN, SELECTUP, MENUDOWN, MENUUP.
  547.             %c    |              | 'Code' is given as an integer.
  548.             %d    | Gadgets      | the gadget id.
  549.             %e    | Window       | the TopEdge of the window
  550.             %f    | Window       | the LeftEdge of the window
  551.             %g    | Gadgets      | the string inside a string gadget goes here.
  552.             %h    | Newsize      | the window height.
  553.             %i    | Menus        | the item number.
  554.             %l    | Any          | the name of the IDCMP class.
  555.             %m    | Menus        | the menu number.
  556.             %q    |              | 'Qualifier' is given as an integer.
  557.             %s    | Menus        | the sub-item number.
  558.             %t    | Time         | the number of seconds since January 1 1980.
  559.             %w    | Newsize      | the window width.
  560.             %x    | Mouse        | the X position of the mouse pointer.
  561.             %y    | Mouse        | the Y position of the mouse pointer.
  562.           %0-%15  |              | which Arg to use.
  563.  
  564.         For example, if the message string of some gadget is
  565.  
  566.             "Mouse is %x, %y%3gadget string is %g"
  567.  
  568.         the following might be sent to the notifyport in Arg[0] when someone
  569.         hits return in that gadget, after typing "This is a test":
  570.  
  571.             Mouse is 320, 200
  572.  
  573.         while Arg[3] of the Rexx message would contain the string:
  574.  
  575.             gadget string is This is a test
  576.  
  577.         The default string for non-gadgets/menus is "%l", which means that they
  578.         only report their name. For example, if one would click in the window,
  579.         one would only receive a message with "MOUSEBUTTONS" in Arg[0]. However,
  580.         all arguments of the message that will be sent to the notifyport may be
  581.         changed using the ModifyHost() call, see there. Any of the escape
  582.         sequences above may be used in any string. Obviously, sometimes
  583.         particular sequences may not be very appropriate for certain uses.
  584.  
  585.         'flags' specifies the various window flags. Currently supported are:
  586.         "WINDOWCLOSE", "WINDOWSIZING" (and "SIZEBRIGHT", "SIZEBBOTTOM"),
  587.         "WINDOWDEPTH", "WINDOWDRAG", "BORDERLESS", "ACTIVATE" and
  588.         "NOCAREREFRESH".   A special flag can be set: "BACKFILL". It implies
  589.         a call to BackFill() after opening the window. It sets the window's
  590.         background to the current requester-style background color.
  591.  
  592.    call Quit(controlport)
  593.         This function closes the window, deallocates all resources and causes
  594.         the host to exit. Exit(), Quit() and Stop() are identical.
  595.  
  596.    call ReadGadget(controlport, gadgetid)
  597.         This function will cause the gadget 'gadgetid' to send its message
  598.         text (after substitutions, of course).
  599.  
  600.    call ReadHost(controlport, notifyport, messagetext)
  601.         This function will cause the message text (after substitutions, of
  602.         course) to be sent to the notifyport.
  603.  
  604.    call RectFill(controlport, xmin, ymin, xmax, ymax) 
  605.  
  606.    call RefreshGadgets(controlport)
  607.  
  608.    call RemoveGadget(controlport, gadgetid)
  609.  
  610.    call SetAPen(controlport, pennumber)
  611.  
  612.    call SetBPen(controlport, pennumber)
  613.  
  614.    call SetDrMd(controlport, mode)
  615.         mode can be any of JAM1, JAM2, INVERSVID or COMPLEMENT.
  616.  
  617.    call SetDrPt(controlport, pattern)
  618.         pattern is interpreted as a long integer of which the bits form the
  619.         pattern.
  620.  
  621.    call SetFont(controlport, FontName, FontSize)
  622.  
  623.    call SetGadget(controlport, gadgetid, action)
  624.         Given a gadget id, perform action on the gadget. Supported are ON and
  625.         OFF, to set or clear the highlighting state of the gadget.
  626.  
  627.    call SetItem(controlport, menunumber, itemnuber, subitemnumber, action)
  628.         Given menu, item (and optionally subitem) numbers, perform action on
  629.         the menu item. Supported are ON and OFF, to set or clear the check mark.
  630.  
  631.    call SetNotify(controlport, IDCMPclass, newnotifyport)
  632.         This function allows you to change the name of the NotifyPort that 
  633.         message strings are sent to for a particular class of IDCMP events.
  634.  
  635.    call SetReqColor(controlport, pentype, colornumber)
  636.         This function allows you to change the color number assigned to
  637.         one of the various pentypes. Currently the pentypes are: BLOCKPEN,
  638.         DETAILPEN, BACKGROUNDPEN, PROMPTPEN, BOXPEN, SHADOWPEN, OKAYPEN,
  639.         and CANCELPEN.
  640.  
  641.    call SetOPen(controlport, pennumber)
  642.  
  643.    call SetRGB4(controlport, pennumber, red, green, blue)
  644.         red, green and blue are values for the RGB content of the color to be
  645.         assigned to the pen. The values are taken mod 16.
  646.  
  647.    call Stop(controlport)
  648.         This function closes the window, deallocates all resources and causes
  649.         the host to exit. Exit(), Quit() and Stop() are identical.
  650.  
  651.    call Text(controlport, string) 
  652.  
  653.    call WindowText(controlport, text)
  654.         The string in text may contain \'s to indicate multiple lines of text.
  655.  
  656.    call WindowToBack(controlport)
  657.  
  658.    call WindowToFront(controlport)
  659.  
  660.    call WritePixel(controlport, x, y)
  661.  
  662.  
  663.  
  664.  
  665. +----------------------------------------------------------------------+
  666. |                                                                      |
  667. |                  D I S C L A I M E R   N O T I C E                   |
  668. |                                                                      |
  669. |  This document and/or  portions of the material and  data furnished  |
  670. |  herewith,  was developed under sponsorship of the U.S. Government.  |
  671. |  Neither the U.S.  nor  the U.S.D.O.E.,  nor  the  Leland  Stanford  |
  672. |  Junior University, nor their employees,  nor their respective con-  |
  673. |  tractors, subcontractors, or their employees, makes  any warranty,  |
  674. |  express or implied, or assumes any liability or responsibility for  |
  675. |  accuracy,  completeness or  usefulness of any information, appara-  |
  676. |  tus, product or process disclosed, or represents that its use will  |
  677. |  not infringe privately-owned rights.  Mention of any product,  its  |
  678. |  manufacturer, or suppliers shall not, nor is it intended to, imply  |
  679. |  approval, disapproval, or fitness for any particular use. The U.S.  |
  680. |  and  the University at all times  retain the right to use and dis-  |
  681. |  seminate same for any purpose whatsoever.                           |
  682. |                                                                      |
  683. +----------------------------------------------------------------------+
  684.