home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 2 / amigaformatcd02.iso / pd / text / alphaspell_suite / varexx / docs / readme next >
Text File  |  1996-05-20  |  32KB  |  934 lines
  1. Document Varexx Readme 5 Feb 1996
  2.  
  3.                         Varexx Documentation
  4.                        ~~~~~~~~~~~~~~~~~~~~~~
  5.                   Release 1.7  (c)1995-1996 Andrew Cook
  6.  
  7.                             5 Feb 1996
  8.                           
  9.  
  10. 1. Introduction - So what is it and what can it do ?
  11. ----------------------------------------------------
  12. Varexx is a program that allows you to control graphical user 
  13. interfaces (GUI's) from Arexx. The program loads the .gui files that 
  14. are saved by Jan van den Baard's Gadtoolsbox program and displays them 
  15. on the screen. Arexx scripts can then send messages to a port and 
  16. control the actions of the Gui. The script can read and set the 
  17. contents of each of the gadgets, resize the window and such like.
  18.  
  19. 2. Legal Bit - What won't I do ?
  20. --------------------------------
  21. Some or all of the files in this package may be may be transmitted by 
  22. any means. Providing words to the effect of
  23.  
  24. Varexx and Arexxport.library are Copyright(c)1995 Andrew Cook.
  25.  
  26. and my email address (amc93el@soton.ac.uk) are included in the 
  27. accompanying documentation. The files are FreeWare, copyright is 
  28. retained by the author (Andrew Cook).
  29.  
  30. These files may be included in any distribution commercial, shareware, 
  31. freeware or other. I would like to be informed of any such packages, 
  32. (drop me an email) but this is not a requirement.
  33.  
  34. ALTHOUGH THE FILES HAVE BEEN CAREFULLY TESTED ANY ERRORS OR ACCIDENTS 
  35. ARISING FROM THEIR USE IS NOT THE RESPONSIBITY OF THE AUTHOR. USE AT 
  36. YOUR OWN PERIL.
  37.  
  38. I take no responsibility for anything Varexx may do to your system. 
  39. But is less likely to crash your Amiga than a certain new operating 
  40. system 95 will. (Unless you've got a bridge board of course.)
  41.  
  42. 3. About the Author - So who are you ?
  43. --------------------------------------
  44. I am a third year electronics undergraduate at the University of 
  45. Southampton, England. I like SF, technology and having a laugh. If you 
  46. like you can't check out my www site as I haven't got one. However do 
  47. drop me a email to
  48.  
  49.     amc93el@soton.ac.uk
  50.  
  51. This will be valid until August 1996 after which I will get a demon 
  52. account. So download this package again and pick my new address out of 
  53. that.
  54.  
  55. 4. Installation - What do I do now ?
  56. ------------------------------------
  57. There are two programs in the Varexx distribution just copy both into 
  58. your path.
  59.  
  60. Varexx GUIPATH
  61.  
  62. This launches the Varexx server. This opens a port called VAREXX and 
  63. waits for scripts to send messages to it. The server detaches itself 
  64. properly so it can be run in the user-startup with the line "Varexx". 
  65. Only one copy of Varexx can (and needs to) be running at one time.
  66.  
  67. The Varexx program requires the Arexxport.library and the 
  68. reqtools.library, both of these are included in the distribution, copy 
  69. them into your libs: assignment.
  70.  
  71. The command can be optionally followed by a path. This will be used as
  72. the default path to load .gui files from.
  73.  
  74. eg Varexx rexx:gui/
  75.  
  76. Varexx will now look in rexx:gui/ path for any .gui files it needs.
  77.  
  78. VXC
  79.  
  80. This closes the Varexx server down. This can only be done if no gui 
  81. files are currently loaded into the server.
  82.  
  83. 10. The Demo Script - What can it do ?
  84. --------------------------------------
  85. To run the demos, click on the DemoSetup Icon. Then open the demos 
  86. drawer and click on the demo or the address book icons.
  87.  
  88. The demo shows off the features of Varexx and source code will reveal 
  89. most of the information needed to write your own scripts for Varexx. 
  90.  
  91. The Address Book is a simple address database written in Arexx. It 
  92. demonstrates the use of two windows at once with Varexx.
  93.  
  94. When address book is started a file requester will appear asking for a 
  95. data file to load. An example containing a few interesting people I 
  96. know is included. (Load the example address.data). 
  97. The main window is now displayed. You can scroll through the names 
  98. using the '<' and '>' buttons. Clicking on the 'List' produces a list 
  99. of names in the book and picking a name jumps to that entry. 
  100. To add an entry click on the 'Clear' button. Fill in the entries and 
  101. click on 'Update' to add the entry to the book.
  102. To change an entry, find it, change it and click on 'Update'.
  103. To delete an entry, click on delete, clicking twice undelete it. None 
  104. of the changes are saved until the address book is closed. A that 
  105. time, the entries are saved and the address book is sorted. 
  106.  
  107. The testgui file, brings up a filerequester asking for the a .gui file. 
  108. It then displays this and echos all messages from Varexx to the output
  109. console.
  110.  
  111. TestGUI2 does the same except, that it hacks about inside the .gui file 
  112. and extracts the name of all the windows in the file and gives you the 
  113. choice of them. This script was written by Nick Ring and contains some 
  114. hairy code so he will be horrified that I've distributed it unchanged. 
  115. I apologise to him for that - but it can be useful. 
  116.  
  117. Fergus Duniho has a script to use his spell checker - AlphaSpell - with 
  118. Varexx. It's on the Aminet as text/util/AspellGUI.lha. (And well worth a 
  119. look.)
  120.  
  121. 5. Programming Varexx - How do they do that ?
  122. ---------------------------------------------
  123. So you want to create your own Arexx gui's. You need will need to 
  124. create a gui file using Gadtoolsbox, see the documentation on using 
  125. that program and the notes below.
  126.  
  127. Having created the gui file you must then write the script to load and 
  128. display the window.
  129.  
  130. Some Notes / Comments and Ideas
  131.  
  132. Okay, having seen a few peoples scripts and written a few of my own. I
  133. feel that some ground rules (ideas anyway) should be written. 
  134.  
  135.  1) Starting, stopping the Varexx server from within a script.
  136. I feel you should only close the Varexx server ('address command VXC'
  137. does it) if you have started it yourself. See the example script below.
  138.  
  139.  2) The location of the .GUI file.
  140. Your script should not hard code this. I feel the best thing to set a
  141. variable near the start of the script containing the .gui file name. 
  142. Allowing the user to change it easily. Secondly I would assume that all 
  143. the .gui files will be stored in a single location, and that the user
  144. will tell varexx where that is. So don't hard code paths into the gui 
  145. file name.
  146.  
  147. But that's just my $0.02 worth.
  148.  
  149. 5.3. Example Script
  150. -------------------
  151. /* Test script for Varexx */
  152.     guifile = 'myguifile.gui'
  153.  
  154.     options results
  155.  
  156.     /* Open libs needed */
  157.     if ~show("L","rexxsupport.library") then
  158.         if ~addlib("rexxsupport.library", 0, -30) then exit
  159.  
  160.     /* Check Varexx is loaded if not load it */
  161.  
  162.     if show( 'p', 'VAREXX' ) ~= 1 then do
  163.         address command 'run Varexx'
  164.         waitforport VAREXX
  165.         RanVarexx = TRUE
  166.     end; else 
  167.         RanVarexx = FALSE
  168.  
  169.     address VAREXX
  170.  
  171.     /* Open the port for gui to talk to */
  172.     call openport("WINDOWPORT")
  173.  
  174.     /* Load the gui file into Varexx */
  175.     'load ' guifile 'WINDOWPORT'
  176.  
  177.     /* Set host to the port for this gui file */
  178.     host = result 
  179.     address value host
  180.  
  181.     /* Display the window */
  182.     show 
  183.  
  184.     /* Wait for the user to close the window */
  185.     do forever
  186.         /* Wait for a message from Varexx */
  187.         call waitpkt( "WINDOWPORT" )
  188.  
  189.         /* Get the message */
  190.         packet = getpkt( "WINDOWPORT" )
  191.  
  192.         /* This is not a null message */
  193.         if packet ~= '00000000'x then do 
  194.  
  195.             /* Get the information about the message */
  196.             class  = getarg(packet)
  197.  
  198.             /* If the message says the user clicked on the closewindow
  199.              * gadget then leave */
  200.             if class = closewindow then leave
  201.  
  202.         end
  203.     end
  204.  
  205.     /* Hide the window and unload the gui file from memory */
  206.     'hide unload'    
  207.  
  208.     /* Close the port */
  209.     call closeport( "WINDOWPORT" )
  210.  
  211.     /* I launched varexx so close it */
  212.     if RanVarexx = TRUE then ADDRESS COMMAND VXC
  213.  
  214.     exit
  215.  
  216. 5.1. The GUI files
  217. ------------------
  218. When using Gadtoolsbox to design .gui file for Varexx the following 
  219. hints may be useful.
  220.  
  221. At the moment, Menus are not supported by Varexx so don't bother to 
  222. set any up. Also Fixed Text and Bevel boxes are not rendered by 
  223. Varexx. Varexx  will ignore any Custom or Public screen settings. This 
  224. may change in the future so it is best to design the Gui to open on 
  225. the default public screen.  This allows the screen to be specified by 
  226. the PS argument to the load command  and will not clash with any 
  227. future behavior of Varexx. The plan is to have Varexx able to open 
  228. custom public / private screens at some time.
  229.  
  230. Of the window flags :
  231.     SIZEGADGET      - Varexx doesn't resize the gadgets in a window. 
  232.                       But this flag may be set.
  233.     DEPTHGADGET     - May be set.
  234.     SIZEBRIGHT      - May be set. See SIZEGADGET.
  235.     SMART_REFRESH   - Ignored by Varexx.
  236.     SUPER_BITMAP    - Ignored by Varexx.
  237.     BACKDROP        - May be set. (Not often useful.)
  238.     GIMMEZEROZERO   - This has no effect on the final appearance. 
  239.                       However less memory is used if it is left off.
  240.     ACTIVATE        - May be set.
  241.     DRAGBAR         - May be set.
  242.     CLOSEGADGET     - May be set.
  243.     SIZEBOTTOM      - May be set. See SIZEGADGET.
  244.     SIMPLE_REFRESH  - Ignored by Varexx.
  245.     OTHER_REFRESH   - Ignored By Varexx.
  246.     REPORT_MOUSE    - Ignored By Varexx.
  247.     BORDERLESS      - May be set. ( But not very useful.)
  248.     RMBTRAP         - Ignored by Varexx.
  249.  
  250. A subset of the IDCMP options are used by Varexx. If these options are
  251. selected then Varexx will send additional messages to the Arexx script.
  252.  
  253.     IDCMP_ACTIVEWINDOW - A activewindow message is sent when the Varexx 
  254.         window becomes active. ie. when the user clicks on it.
  255.     IDCMP_INACTIVEWINDOW - A inactivewindow message is sent when the Varexx
  256.         window ceases to be active. ie. when the user clicks outside it.
  257.     IDCMP_DISKINSERTED - A diskinserted message is sent when when a disk 
  258.         is inserted.
  259.     IDCMP_DISKREMOVED - A diskremoved message is sent if a disk is removed.
  260.     IDCMP_NEWSIZE - A newsize message is sent when the size of the window
  261.         is changed. This includes clicking on the ZIP gadget.
  262.     IDCMP_CHANGEWINDOW - A changewindow message is sent when there is any
  263.         change in the window's size or position.
  264.     IDCMP_VANILLAKEY - When a key is pressed which doesn't affect a gadget 
  265.         then a KEYBOARD message will be sent to the script.
  266.  
  267. Of the tags,
  268.     InnerWidth, InnerHeight,
  269.     AutoAdjust, FallBack    - May be set.
  270.     MouseQueue, RptQueue    - Are all ignored by Varexx.
  271.     WindowTitle is used.
  272.     ScreenTitle is used. Enter a blank title to get the default screen 
  273.     title.
  274.     Prefs Zoom and Pos Zoom will give a window with no size gadget a 
  275. zoom gadget. Both zip the window to it's title bar. Prefs also moves 
  276. the window to the top left corner of the screen.
  277.  
  278. All gadgets are supported. The label for each gadget is the title used
  279. by Varexx to name each gadget.
  280.  
  281. FILE_KIND gadgets rely on the script to supply the filerequester, they 
  282. just act as BUTTON_KIND gadgets. This allows the script rather than
  283. Varexx to determine the information in the requester.
  284.  
  285. Key Strokes ( _Cancel etc ) are supported, providing the box is ticked 
  286. in Gadtoolsbox. Tabbing between gadget also works.
  287.  
  288. Do not compress your GUI files or you will be in deep trouble.
  289. Default options listed for the LISTVIEW kind do not work.
  290.  
  291. 5.2. Arexx Commands
  292. ------------------
  293. When Varexx is active there are three different ports that you have to 
  294. deal with. Two of these are opened by Varexx and you send messages to 
  295. them. The other is opened by you and Varexx sends messages to it when 
  296. the user clicks on a gadget.
  297.  
  298. When the Varexx server it opens a port called 'VAREXX' there are two 
  299. commands that can be sent to this port.
  300.  
  301. 5.2.1. Commands for the VAREXX port.
  302. ---------------------------------
  303. When launched Varexx opens a Arexx port called 'VAREXX'. This port  
  304. accepts two different commands.
  305.  
  306. 5.2.1.1. Load 
  307. ------------
  308. load FILE/A,PORT/A,PS/K
  309.  
  310. Loads the given .gui file into memory. If the file is given an absolute
  311. path ( ie. rexx:gui/myfile.gui ) then that will be loaded. If not then the
  312. default path ( given when Varexx is run ) will be used. If not found 
  313. there then the file on its own will be looked for.
  314. ie. If Varexx is run with the line "Varexx rexx:guifiles/"
  315.  
  316. The commands 
  317.  
  318. load fish/mygui.gui
  319.     will try to load "rexx:guifiles/fish/mygui.gui" and then try 
  320.     "fish/mygui.gui".
  321. load rexx:fish/mygui.gui
  322.     tries to load "rexx:fish/mygui.gui".
  323. load mygui.gui
  324.     tries to load "rexx:guifiles/mygui.gui" and then "mygui.gui".
  325.  
  326. This command doesn't display the window however. PORT is the name of 
  327. the port to which the window will send messages when the user operates
  328. the window's gadgets. This port should be created with the OpenPort( )  
  329. function in the rexxsupport library. 
  330. The windows will open on the default public screen unless the name of  
  331. an alternative screen is given in the PS option.
  332. This command returns the name (in result - so turn 'options results'  
  333. on first) of a Arexx port to which messages about this window may be  
  334. sent. 
  335. eg
  336.         options results
  337.         ...
  338.         
  339.         address VAREXX
  340.  
  341.         call openport("SQUID") 
  342.  
  343.         'load dh1:c_src/Varexx2/gui/test.gui SQUID PS=MYSCREEN'
  344.         host = result
  345.  
  346. This loads the gui file 'test.gui' into memory, setting it to send  
  347. messages to a port called 'SQUID', display it's windows on the  
  348. MYSCREEN and it will receive commands at the port named in the  
  349. variable 'host'. (Use 'address var host' to send commands.)
  350.  
  351. 5.2.1.2. Quit
  352. -------------
  353. quit
  354.  
  355. If there are no .gui file currently loaded by the Varexx server 
  356. this command will close the server down and free the memory used by    
  357. it. This is what the VXC command sends to the VAREXX port.
  358.  
  359. 5.2.1.3. Version
  360. ----------------
  361. version
  362. Returns the version number of currently active copy of Varexx. The 
  363. version number is returned in RESULT. This command first appeared in 
  364. v1.3 so use code like this.
  365.     Options Results
  366.  
  367.     ...
  368.  
  369.     ADDRESS VAREXX
  370.     version
  371.     if rc ~= 0 then say 'Varexx 1.2 or earlier'
  372.         else say 'Varexx 'RESULT
  373.     ...
  374.  
  375. This command may also be sent to the window ports as well.
  376.  
  377. 5.2.2. Commands for window ports
  378. --------------------------------
  379. The following command can be sent to the specific port for a gui file, 
  380. ie. the portname returned by the load command.
  381.  
  382. 5.2.2.1. Show
  383. -------------
  384. show WINDOW
  385.  
  386. This displays the named window. The window name is given to the  
  387. window in Gadtoolsbox not the window title. If no name is given then  
  388. the first window in the file is displayed.
  389.  
  390. 5.2.2.2. Hide
  391. ------------
  392. hide UNLOAD/S
  393.  
  394. If the .gui file has a window open this command will close it. If  
  395. the unload  option is given, the .gui file will be removed from     
  396. memory as well. You cannot read information from the windows gadgets  
  397. after this command has been given. This command can be given with the  
  398. unload option when no window is open to free up memory.
  399.  
  400. 5.2.2.3. Window
  401. ---------------
  402. window ZIP/S,FRONT/S,BACK/S,ACTIVATE/S,X/N/K,Y/N/K
  403.  
  404. This command changes the state of the window.
  405. ZIP - move the window to it's alternate place and size. As if the     
  406. user clicked the zip gadget.
  407. FRONT - Brings the window to front of the screen.
  408. BACK - Puts it to the back (surprised ?).
  409. ACTIVATE - Gives the window the focus for user input.
  410. X - Number specifes the left edge of the window.
  411. Y - Number specifes the top edge of the window.
  412.  
  413. 5.2.2.4. Busy
  414. -------------
  415. busy SET/S
  416.  
  417. The command 'busy set' sets the busy pointer in the Varexx window
  418. and blocks all user input to the window. Just 'busy' on its own clears 
  419. the pointer and unblocks the window again.
  420.  
  421. 5.2.2.5. Set
  422. ------------
  423. set LABEL/M/A,ENABLE/S,DISABLE/S
  424.  
  425. This enables / disables the given gadget(s). A list of gadgets can 
  426. be given and all will be affected.
  427.  
  428. 5.2.2.6. Settext
  429. ----------------
  430. settext LABEL/A,STRING/F
  431.  
  432. Passes the given string to the gadget. Used by STRING_KIND and     
  433. TEXT_KIND  gadgets only. This sets the text in both of those types.
  434.  
  435. 5.2.2.7. Setnum
  436. ---------------
  437. setnum LABEL/A,NUMBER/N
  438.  
  439. Passes the number to the given gadget. Sets the value of NUMBER_KIND 
  440. and  INTEGER_KIND gadgets. Picks the option for MX_KIND and CYCLE_KIND 
  441. (these are  numbered from 0 upwards ). Sets the position of the marker 
  442. in SCROLLER and  SLIDER kind.
  443.  
  444. 5.2.2.8. Setcheck
  445. -----------------
  446. setcheck LABEL/A,CHECK/S
  447.  
  448. Set a gadget of CHECKBOX_KIND to ticked or not.
  449.  
  450. 5.2.2.9. Setbar
  451. ---------------
  452. setbar LABEL/A,MIN=VISIBLE/N/K,MAX=TOTAL/N/K
  453.  
  454. For a SLIDER_KIND this sets the max and min values of the run.
  455. For a SCROLLER_KIND this sets the max values and the number of 
  456. units the knob represents.
  457.  
  458. 5.2.2.10. SetList
  459. ----------------
  460. setlist LABEL/A,CLEAR/S,DEL/S,SELECT/K,STEM/K,ITEMS/M,UPDATE/N/K
  461.  
  462. Controls the listview type of gadgets. Okay, this is were it gets fun. 
  463. CLEAR switch this clears the listview. Before any other action is 
  464. taken. ITEMS is a list of items to be added to the bottom of the list. 
  465. Or if the DEL option is given as well these items will be removed from 
  466. the list instead. 
  467. The SELECT key word is used to specify which item is currently 
  468. selected. Some examples of these :
  469.  
  470. setlist label CLEAR cod haddock place 
  471.  
  472. Clears the current list and replaces it with the items 'cod', 
  473. 'haddock' and 'place'.
  474.  
  475. setlist label DEL cod
  476.  
  477. Removes item 'cod' from the list.
  478.  
  479. setlist label select=place
  480.  
  481. selects the 'place' item.
  482.  
  483. The STEM option. This gives the name of an Arexx variable from which the 
  484. items to be added to the list are taken. The variable 'stem.COUNT' must 
  485. contain the number of items, which are then numbered 'stem.1', 'stem.2' 
  486. etc. This option only allows you to add to the list you cannot use the DEL 
  487. switch in conjunction with this. But the SELECT and CLEAR options do work. 
  488. In addition the variable 'stem.SELECT' may contain the number of item in 
  489. the list to be selected.
  490. To do the same as
  491.  
  492. setlist label CLEAR cod haddock place SELECT cod
  493.  
  494. You can use
  495.  
  496. fish.COUNT = 3
  497. fish.1 = cod
  498. fish.2 = haddock
  499. fish.3 = place
  500. fish.SELECT = 1
  501. setlist label CLEAR STEM fish
  502.  
  503. Note :
  504. Some other rexx utils use stem.0 to hold the number of items rather
  505. than stem.COUNT. A line like stem.0 = 'stem.COUNT' is no real bother.
  506. So Varexx will stick to using stem.COUNT
  507.  
  508. Finally the update option, this will cause the given item number to be 
  509. updated. To the value given on the line.
  510.  
  511. setlist label UPDATE=2 'skate'
  512. Will change item 2 in the earlier example from 'haddock' to 'skate'.
  513.  
  514. If the stem option is given the that item will be read from the variable. 
  515. fish.2 = 'skate'
  516. setlist label STEM fish UPDATE=2
  517.  
  518. If the update and the select option are both given. Then the numbered item 
  519. will be selected in the list. If no stem or text is given then no updating 
  520. will be done. Due the way Varexx parses this command line, a dummy string 
  521. must be given after the select item. 
  522. setlist label SELECT s UPDATE=3
  523. will select 'place' in the above list.
  524.  
  525. setlist label SELECT s UPDATE=3 'skate'
  526. This will change 'place' to 'skate' and then select it.
  527.  
  528. 5.2.2.11. Read
  529. -------------
  530. read LABEL/A,VAR,NUMBER/S
  531.  
  532. Allow Arexx to read the current state of the gadget. The state of the 
  533. gadget is returned in RESULT. If the gadget is a listview and the VAR 
  534. option is given then the complete list is written into the same stem 
  535. variables as the setlist command uses.
  536. The NUMBER option will return the ordinal number of the item in the 
  537. list view in the RESULT variable.
  538.  
  539. If the list contains the items 'cod' 'haddock' 'place' and 'cod' is
  540. selected then
  541.  
  542. read label cake
  543.  
  544. will set these variables.
  545.  
  546. cake.COUNT = 3
  547. cake.1 = cod
  548. cake.2 = haddock
  549. cake.3 = place
  550. cake.SELECT = 1
  551.  
  552. Also the commands
  553.  
  554. options results
  555. read label NUMBER
  556.  
  557. will give RESULT = 1.
  558. If no item is selected in the listview then stem.SELECT = 0.
  559.  
  560. 5.2.2.12. Spawn
  561. ---------------
  562. spawn PORTNAME/A,PS/K
  563. This command allows you to have more than one window open on the screen at
  564. once. It works in the same way as the load command. except that instead of
  565. loading a new .gui file. It merely clones the already loaded one. The 
  566. command returns a new VAREXX.## portname in the RESULT field.
  567.         options results
  568.         ...
  569.         
  570.         address VAREXX
  571.  
  572.         call openport("SQUID") 
  573.  
  574.         'load dh1:c_src/Varexx2/gui/test.gui SQUID PS=MYSCREEN'
  575.         host = result
  576.         address value host
  577.         show window_one
  578.  
  579.         call openport("SQUID.1") 
  580.  
  581.         'spawn SQUID.1 PS=MYSCREEN2'
  582.  
  583.         host2 = result
  584.  
  585.         address value host2
  586.  
  587.         show window_two
  588.  
  589. This opens the 'window_one' on the MYSCREEN public screen and 'window_two' 
  590. on MYSCREEN2.
  591. Each window must be passed a hide unload command to free up the memory
  592. connected with it. However the order in which these are sent doesn't 
  593. matter.
  594.  
  595. 5.2.2.13. Setlabel
  596. ------------------
  597. Setlabel LABEL/A,TEXT/M,CYCLE/S,SCREEN/S,WINDOW/S
  598.  
  599. This command allows you to set the text in the window. It works in a number 
  600. of different ways. For all gadgets except MX_KIND. You can use
  601. 'setlabel GADGET_LABEL TEXT' to set the gadget's title. This only works if 
  602. the window is not open on the screen. Ie the 'show' command hasn't been 
  603. given yet. 
  604.  
  605. For MX_KIND the text for the options. Is given as 
  606. 'setlabel GADGET_LABEL OPTION_1 OPTION_2 etc'
  607. Again the window must not be open for this to work. In all these cases the 
  608. underscore '_' is used to specify the keyboard shortcut.
  609.  
  610. For CYCLE_KIND the options in the gadget may be set by including the CYCLE 
  611. switch. So 'setlabel GADGET_LABEL cycle OPTION_1 OPTION_2 etc' is used. 
  612. This will work regardless of wether the window is open or not.
  613.  
  614. If the SCREEN or WINDOW switch is given. Then the LABEL is assumed to be a 
  615. window name not a gadget name and either the screen title or the window 
  616. title for that window will be set. This will work if the window is open as 
  617. well. 
  618.  
  619. Some examples, (these need the window to be shut.)
  620. setlabel OKAY '_Fin'
  621. Sets the label in the OKAY gadget to Fin.
  622.  
  623. setlabel 'label=CYCLE' '_Choose'  
  624. Sets the cycle gadget label. The 'label=' allows varexx to distinguish 
  625. between the label and the switch option.
  626.  
  627. setlabel MXCHOICE 'One' 'Two' 'Three' 
  628. Sets the options of a MX_KIND gadget.
  629.  
  630. These will work regardless of weather the window is open or not.
  631. setlabel NEXT '"' || 'Window Title' || '"' window
  632.  
  633. Sets the window title of the window called NEXT to 'Window Title' the 
  634. strange syntax is to allow varexx to correctly parse the spaces.
  635.  
  636. setlabel NEXT '"' || 'Varexx by Andrew Cook' || '"' screen
  637. Sets the screen title for when the NEXT window is open.
  638.  
  639. setlabel 'label=cycle' 'cycle' 'Yes' 'No' 'Maybe'
  640. Sets the options in the cycle gadget.
  641.  
  642. 5.2.2.14. Activate
  643. ------------------
  644. Activate LABEL/A
  645.  
  646. This command applies only to STRING_KIND and INTERGER_KIND gadgets only.
  647. It activates the given gadget to allow the user to enter data into it.
  648.  
  649. 5.2.2.15. Readcords
  650. -------------------
  651. Readcords STEM/A
  652.  
  653. This stores the X, Y locations of the currently open window into the
  654. variables STEM.X and STEM.Y.
  655.  
  656. 5.4. Messages from Varexx
  657. -------------------------
  658. Varexx sends messages to the port your script when events occur. Most of
  659. these messages will be as a result of user action. Every time a gadget
  660. is clicked a message is sent consisting the gadgets label and some 
  661. information. The information is dependant on the gadgets type.
  662.  
  663. BUTTON_KIND, FILE_KIND - No information. Just the gadget name is sent.
  664.  
  665. STRING_KIND - The text entered by the user into the gadget.
  666.  
  667. NUMBER_KIND - The number entered into the gadget
  668.  
  669. MX_KIND, CYCLE_KIND - The option number selected.
  670.  
  671. CHECKBOX_KIND - TRUE if the gadget is ticked otherwise FALSE.
  672.  
  673. SLIDER_KIND, SCROLLER_KIND - The slider numeric position.
  674.  
  675. LISTVIEW_KIND - The contents of the selected item.
  676.  
  677. When the user selects the close window gadget a message of 'CLOSEWINDOW' 
  678. is sent.
  679.  
  680. If the correct flags have been set in the IDCMP section of Gadtoolsbox 
  681. then these messages may be received.
  682.  
  683.     ACTIVEWINDOW 
  684.     INACTIVEWINDOW
  685.     DISKINSERTED
  686.     DISKREMOVED
  687.     NEWSIZE
  688.     CHANGEWINDOW
  689.  
  690. It is left as an exercise for the reader to decide what events can cause 
  691. each one ? ( Hint - Look in section 5.1 :-)
  692.  
  693. Some Arexx commands ( WINDOW ) may cause some of these messages to be 
  694. sent so it is possible to get stuck in a loop situation.
  695.  
  696. When windows that have been spawned the CLOSEWINDOW, ACTIVEWINDOW, 
  697. INACTIVEWINDOW, NEWSIZE and CHANGEWINDOW window messages will append the
  698. name of the window they came from (if and only if they come from a 
  699. spawned window.) This allows two windows to share the same port in an 
  700. Arexx script.
  701.  
  702. The KEYBOARD message will be sent if the IDCMP_VANILLAKEY flag has been set.
  703. The message is followed by the value of the key pressed. 
  704. ie
  705.     KEYBOARD a
  706.     KEYBOARD V
  707.     KEYBOARD 4
  708.     KEYBOARD @
  709.  
  710. For other keys the following messages will be sent
  711. ESC TAB 
  712. BS (backspace)
  713. DELETE HELP RETURN 
  714. UP DOWN LEFT RIGHT (Cursor keys.)
  715. F1, F2, F3 etc.
  716.  
  717. ie
  718.     KEYBOARD UP
  719.  
  720. 6. Thanks - Could not be done without ?
  721. ---------------------------------------
  722. And now for something tacky
  723.  
  724. Thanks to
  725.     Jan van den Baard   - For Gadtoolsbox.
  726.     Nico Francois       - For reqtools and many other programs.
  727.     Richard Rauch       - Some early ideas.
  728.     Fergus Duniho       - For AlphaSpell and relighting my interest in
  729.                           this project with his gui's for XES and
  730.                           ideas and help.
  731.     Matt Dillon         - For DICE.
  732.     Peter Miller        - A PC programmer but with a knowledge of
  733.                           68000 assembler and constant source of 
  734.                           (dis)couragement.
  735.     Stephan Sürken      - For Text2Guide.
  736.     Douglas Keller      - The ButClass code. (It on the Aminet in dev/gui).
  737.     Escom               - For this new A1200.
  738.     Commodore           - For this A500.
  739.  
  740.     These people and others have give ideas, bug reports, moans and even
  741.     in some cases actually used Varexx.
  742.  
  743.     Gregg Green, Boris Foldman, Nick Ring, Michael Pounders, Kevin Phair,
  744.     Andy Styles, John Collet, Marcel Offermans, Mattias Linder, 
  745.     Matthew Soar, Jim Hines, Girard Michel, Perry Mowbray.
  746.  
  747.         (Sounds for people being sick offstage.)
  748.  
  749. Cheers
  750.  
  751. Andy Cook
  752.  
  753. Email 'amc93el@soton.ac.uk'
  754.  
  755. Varexx                  Copyright (c)1995-1996 Andrew Cook
  756. Arexxport.library       Copyright (c)1995 Andrew Cook
  757. reqtools.library        Copyright (c)1991-1994 Nico Francois
  758.                                      1995 Magnus Holmgren
  759. rexxreqtools.library    Copyright (c)1992-1994 Rafael D'Halleweyn.
  760. AlphaSpell              Copyright (c)1995 Fergus Duniho.
  761. Text2Guide 03.10        Copyright (c)1994 Stephan Sürken
  762.  
  763. All other copyrights, trademarks etc acknowledged.
  764.  
  765. The button class and file_kind gadgets where created with BOOPSI objects
  766. based on those by Douglas Keller.
  767.  
  768. 7. Arexxport Library - What is that ?
  769. -------------------------------------
  770. This is a shared library I wrote to allow the easy, yet flexible 
  771. implementation of Arexx ports in programs. If you would like the 
  772. (brief) documentation and support files. Drop me a line.
  773.  
  774. 8. Todo - What's left ? 
  775. -----------------------
  776. Features To Add ( possible )
  777.  
  778. - The Gadtoolsbox program allows you to define beveled boxes, and
  779.   fixed text neither of these are rendered by Varexx at the moment.
  780. - Menus.
  781.  
  782. If you want / need one of these (or anything else) email me.
  783.  
  784. 9. History - What was done when ?
  785. ---------------------------------
  786. 9.1. v0.0 To v0.5
  787. -----------------
  788.  v0.2
  789.  02-09-95  - First beta test version.
  790.  
  791.  06-09-95  - Added the Window ZIP/S,FRONT/S,BACK/S,ACTIVATE/S command.
  792.  
  793.  v0.3
  794.  09-09-95  - Added stem/A option to setlist command that adds items to
  795.              list view from rexx variables. Suggested by Fergus.
  796.            - Added a /M option to the set command allows enabling and
  797.              disabling of many gadgets in one line.
  798.  
  799.  10-09-95  - When the close gadget is clicked now returns CLOSEWINDOW
  800.              rather than closewindow. This is more consistent but
  801.              breaks all scripts so far written. :-(
  802.  
  803.  14-09-95  - Some internal clean up.
  804.            - BUGFIX Text_kind gadgets now work properly.
  805.            - Removed the ALL/S option from read command. It didn't do
  806.              anything !
  807.            - read and setlist now can make use of a stem.SELECT 
  808.              variable.
  809.            - Added NUMBER/S option to read command.
  810.  
  811.  v0.4
  812.  17-09-95  - Cleaned up error reporting code.
  813.            - Added code to close the window is the port to which it 
  814.              should send messages is closed. Ie when the script dies.
  815.  
  816.  30-09-95  - BUGFIX Varexx died if the libs weren't installed. Now it 
  817.              doesn't you get a nice error message instead. Unless of 
  818.              course it was the intuition.library that could not be 
  819.              loaded. In which case your Amiga may be sick. Reported by 
  820.              Boris.
  821.            - BUGFIX Fixed string bugs that caused enforcer hits. Again 
  822.              thanks to Boris.
  823.  
  824.  01-10-95  - BUGFIX Located the bug that caused Guru's after exit. Fixed 
  825.  
  826.              but had to removed key short cuts. Boris and enforcer at 
  827.              work again.
  828.            - BUGFIX Can now read properly from unclicked gadgets.
  829.  
  830.  v0.5
  831.  02-10-95  - Added my own key handling functions.
  832.  
  833.  04-10-95  - Wrote a routine to load the .gui files myself. Thus 
  834.              removing the need for GadToolsBox.library.
  835.            - Then replaced the nofrag library with the exec libpooled 
  836.              functions.
  837.  
  838.  05-10-95  - BUGFIX In List view selection. When the current item
  839.              was deleted the selection was not cleared. Reported by 
  840.              Fergus.
  841.  
  842. 9.2. v1.0, v1.1
  843. ---------------
  844.  v1.0        
  845.  05-11-95  - First non-beta release.
  846.  
  847.  07-11-95  - Minor change to window command. Doesn't call 
  848.              WindowToFront() or WindowToBack if not needed.
  849.  
  850.  09-11-95  - Removed the GET command.
  851.  
  852.  20-11-95  - BUGFIX In settext parsing. Reported by Fergus.
  853.  
  854.  v1.1        
  855.  20-11-95  - BUGFIX The layout of gadgets with different fonts works 
  856.              correctly.
  857.  
  858.  21-11-95  - Added support for disk, windowsize, windowactive events.
  859.  
  860.  21-11-95  - BUGFIX Check box gadget now sends the correct messages.
  861.  
  862.  22-11-95  - BUGFIX Large number of selections in cycle gadgets caused
  863.              guru's. Reported by Nick Ring.
  864.            - Add default path for .gui support.
  865.  
  866. 9.3. v1.2, v1.3
  867. ---------------
  868.  v1.2
  869.  22-11-95  - Second public release.
  870.  
  871.  27-11-95  - Can now use set to disable MX_KIND and LISTVIEW_KIND. However
  872.              operation only has an effect on v39+ versions of gadtools. 
  873.  
  874.  28-11-95  - Added spawn command. Allows more than one window to open from
  875.              one GUI at a time.
  876.  
  877.  30-11-95  - BUGFIX Read command now returns 0 in stem.SELECT if not item
  878.              is selected in the list view. Reported by Nick Ring.
  879.  
  880.  04-12-95  - Tidied up the spawn command. 
  881.  
  882.  v1.3
  883.  04-12-95  - Added a version command.
  884.            - Now remembers location of windows when they are closed.
  885.  
  886.  05-12-95  - Now supports GET_FILE gadgets (suggested by Nick Ring) and
  887.              correctly supports shortcuts for buttons.
  888.  
  889.  06-12-95  - Settext with no line, now clears the gadgets.
  890.            - BUGFIX Dealt with enforcer hits reported by Kevin Phair.
  891.  
  892.  07-12-95  - Tided up the distribution
  893.  
  894.  08-12-95  - MX_KIND gadgets now respond to key strokes.  
  895.  
  896.  11-12-95  - BUGFIX Some problems with the setlist command.
  897.  
  898. 9.4. v1.4, v1.5
  899. ---------------
  900.  v1.4
  901.  14-12-95  - Third public release.
  902.  
  903.  03-01-96  - BUGFIX Check box return values inverted. Thanks John Collett.
  904.  
  905.  10-01-96  - BUGFIX Resizing of GUI saved with fonts other than Topaz 8 now
  906.              works. Reported by Michel Girard.
  907.            - Removed case sensitivity from gadget labels.
  908.            - Added the setlabel command.
  909.            - Added X, Y options to window command.
  910.  
  911.  v1.5
  912.  11-01-96  - Added UPDATE option to setlist command. Suggested by Fergus.
  913.  
  914.  25-01-96  - Added activate command. Suggested by Perry Mowbray.
  915.            - Added READCORDS command.
  916.            - Added support for the keyboard.
  917.  
  918. 9.5. v1.6
  919. ---------
  920.  v1.6
  921.  30-01-96  - Fourth public release.
  922.  
  923.  05-02-96  - BUGFIX I had linked v1.6 with a old version of the button BOOPSI 
  924.              gadget.
  925.  12-02-96  - BUGFIX In the readcords command and some fixes to the arexxport
  926.              library. (Arexxport now v36.22).
  927.  
  928. 9.6. v1.7
  929. ---------
  930.  v1.7
  931.     
  932.  12-02-96  - Fifth public release
  933.  
  934.