Edition 5 now includes some more slight optimizations (particularly in parsing
DRAW options), and changes to the OnMouse command to exit on either a mouse
click OR a key press. (Both the Mouse and Keyboard signals are set to the same
signal, so either will return to your BASIC09 program). This version is
bundled with EOU Version 1.0.0.

NOTE: Edition 4 now includes very slight optimizations, and two more drawingcommands (FCircle, FEllipse) by L. Curtis Boyle 06/18/2018. Also added theundocumented StartX,StartY coords in the DRAW function to this documentation.Original docs from Kevin Darling:This is the Readme file for updated GFX2 partial release, 23Jun90.Here's a new GFX2, uploaded for the use and pleasure of all CoCo-3 L-II users.All files included in this archive should be kept together if re-posted. Thx.This GFX2 has been optimized by Kent D Meyers, and updated by Kevin K Darling.The following new calls are implemented. See "gfx2.man" for the referencemanual (details on calls) and "gfx2.doc" for a quick explanation of use.For far more details and examples, refer to Dale Puckett's "Kissable OS-9"columns in _Rainbow_ Magazine over the last few months.WINDOWS======= Title  - set window title/sizes Menu   - set window menus Item   - set pulldown item WnSet  - set window type WInfo  - return window information GetSel - return menu/button/slider selection UMBar  - update menu bar SBar   - update scroll barsMOUSE===== SetMouse- set mouse params Mouse   - return mouse info OnMouse - set mouse clicked/key pressed signalMUSIC/MISC========== ID      - return process ID Tone    - play a toneDRAWING============FCircle - draw Filled CircleFEllipse - draw Filled EllipseDraw - accepts startx,starty coordinate before draw stringFurther info: gfx2 of 26jul89: Using the new GFX2.WINDOW COMMANDS===============Previously, setting up menued windows, or even getting the mouse packet,involved using the Syscall subroutine and information from the developer'sdocumentation. I believe this has stymied the casual programmers a lot.In an attempt to make things easier, GFX2 now supports the more popularwindowing stat calls. (See "gfx2.man")There are four new calls used to set up a menued window: TITLE, MENU,ITEM and WNSET. They require some program storage for the main windowdescriptor and each of the menus, which is most easily set up by definingstring arrays. The main window descriptor variable must have a dimension ofat least 2; otherwise the dimension should be at least the same count as thenumber of menu bar selections (across the top: like FILES, TANDY, etc),plus 1 more.Each menu bar selection may have items that are in its pulldown menu. Eachpulldown requires an array dimensioned to at least the number of items.SETTING UP MENUS================The new commands are much easier to use than to explain. In addition to theexamples on disk and the Details here, let us set up a small menued windowprogram as a quick example...Let's say that you wanted to write a program called "Tools", that had twomenu selections (in addition to the close box, which is automatically defined).These menus are called "Disk" and "Memory". Under Disk we want "Dir", "Free","PWD", and "Format". Under Memory we want "MFree" and "Procs".First, we must set aside storage for OS-9 and GFX2. Since we have two menubarselections, we define a window descriptor array of size 2+1 = 3.  DIM wd(3):STRING \ (* This is the window descriptor)We also need to define storage for each pulldown menu. Our first selectionhas three items, our second has two. (NOTE: if the number of items mightchange, simple give it more size accordingly).  DIM m1(3):STRING \ (* Disk selection  DIM m2(2):STRING \ (* Memory selectionWe need to assign an ID number to both menu selections. Numbers 1-32 arereserved for the system, so let's use 33 and 34.  DIM MId_Disk,MId_Mem:INTEGER  MId_Disk=33  MId_Mem =34We can also define some numbers that will make reading the program a littleeasier:  DIM Disable,Enable:INTEGER  Disable=0  Enable=1The rest is easy! Simply fill in the blanks for the following commands:Set the title name, minimum window size, number of menu selections:  RUN gfx2("Title",wd,"Tools",34,10,2)Set up each menu selection position,name,ID,width,itemcount,items,enable:  RUN gfx2("Menu",wd,1,"Disk",MId_Disk,8,4,m1,Enable)  RUN gfx2("Item",m1,1,"Dir   ",Enable)  RUN gfx2("Item",m1,2,"Free  ",Enable)  RUN gfx2("Item",m1,3,"PWD   ",Enable)  RUN gfx2("Item",m1,4,"Format",Disable)  RUN gfx2("Menu",wd,2,"Memory",MId_Mem,5,2,m2,Enable)  RUN gfx2("Item",m2,1,"MFree",Enable)  RUN gfx2("Item",m2,2,"Procs",Enable)NOTE: the order isn't important above. It's just easier to read this way.Now that we have defined the window, selections, and pulldowns, we cantell OS9 to set up a framed (type=1) window:  RUN gfx2("WnSet",1,wd)You can disable or change the menus on the fly.USING THE MOUSE===============Now that the menued window is set up, there are several utility calls thatare very helpful. First, we need to turn on the gfx cursor and also theautofollow (since we'd rather not keep telling OS9 where to put the cursor!).  RUN gfx2("SetMouse",3,1,1) \ (* Turn on autofollow  RUN gfx2("GCSet",$CA,1)    \ (* Use standard arrow pointerThe Mouse call will tell us the status of the pointing device:  DIM valid,fire,mx,my,area,sx,sy:INTEGER \ (* Place at program front!  RUN gfx2("Mouse",valid,fire,mx,my,area,sx,sy)We could simple loop around, checking the mouse and the keyboard (INKEY),but quite often a program need only wait for the user to click his firebutton, and only then do we go after the menu selection. This is much morefriendly to other programs running, and aids in multitasking quite a bit:  RUN gfx2("OnMouse",0)  \ (* Sleep until mouse clicked OR a key is pressedThis will return only when this window is the interactive one, and theuser has clicked his mouse button or hit a key. Then we are woken up, and can
figure out what they meant us to do:GETTING MENU SELECTIONS=======================On wakeup, we need to see if the user is really clicking on the menu area.  RUN gfx2("Mouse",valid,fire,mx,my,area,sx,sy)If valid isn't zero, and the right button is down, and the area is themenu area, then we know what the user meant. So we can call the Get Selectionroutine to let the user pulldown a menu or return a bar selection like Close.
(Note that this also includes scroll bar arrows even though they are not
technically on the menu bar.)  DIM menu_id, menu_item:INTEGER \ (* This should be at front of program!  RUN gfx2("GetSel",menu_id,menu_item)The menu_id will be the menubar selection (00 if none), and the menu_itemwill be the specific pulldown item number.The total loop to wait for a click, see if menu, get the selection, is:  LOOP    RUN gfx2("OnMouse",0)    RUN gfx2("Mouse",valid,fire,mx,my,area,sx,sy)    IF valid<>0 AND fire=1 AND area=1 THEN     RUN gfx2("GetSel",menu_id,menu_item)       IF menu_id <> 0 THEN        GOSUB xxx \ (* go do selection number *)       ENDIF    ENDIF  ENDLOOPYou could also wait for the mouse click in a drawing program, for example,and if it wasn't on the menubar area (area=1) then you could start a drawingloop or whatever.-eof-QuickGuide For Forum Upload - 23Jun90 - based on work of 26Jul90Copyright 1989,1990 by Kevin K Darling*************************** CALL DETAILS ************************************CAPITAL LETTERS: passed as INTEGER    lowercase : returned as INTEGER  CAPITAL LETTER$: passed as STRING     lowercase$: returned as STRING=============================================================================TITLE - used to set up main window descriptor RUN gfx2("Title",D_ARRAY$,TITLE$,XMIN,YMIN,MENUCOUNT)  D_ARRAY$........window descriptor array  TITLE$..........title of window  XMIN............minimum column size  YMIN............minimum row size  MENUCOUNT.......number of user-defined menu bar selections=============================================================================MENU  - used to set up a menu bar selection RUN gfx2("Menu", D_ARRAY,NUMBER,MENU$,ID,XSIZ,ITEMCOUNT,M_ARRAY,ENABLE)  D_ARRAY.........window descriptor array  NUMBER..........position on menu bar ( from 1 to MENUCOUNT )  MENU$...........name of menu bar selection  ID..............ID number for GetSel to return as menu_item  XSIZ............size in columns for pulldown  ITEMCOUNT.......number of pulldown items in M_ARRAY  M_ARRAY.........pulldown item array  ENABLE..........selection enable flag (0=disabled, 1=enabled)=============================================================================ITEM  - used to set up a pulldown item RUN gfx2("Item", M_ARRAY,NUMBER,ITEM$,ENABLE)  M_ARRAY.........the menu bar selection array  NUMBER..........position of this item in pulldown ( 1 to ITEMCOUNT)  ITEM$...........name of this item  ENABLE..........item enable flag (0=disabled, 1=enabled)=============================================================================WNSET - used to do the SS.WnSet call that defines a Window type RUN gfx2("WnSet",WTYPE,D_ARRAY)  WTYPE...........window frame type  D_ARRAY.........window descriptor array if needed (type 01 or 02) Window types:  00 - normal window  01 - menu framed window  02 - menu framed with scroll bars  03 - shadowed box  04 - double   box  05 - plain    box=============================================================================GETSEL - called when button is clicked, to return menu selection. RUN gfx2("GetSel",menu_id,menu_item)  menu_id.........the ID number as defined by "Menu". 00 if no selection.  menu_item.......pulldown item number. 00 if "Menu" said there were none.=============================================================================UMBAR - update the menubar. Used to enable changes on menubar menus and/or
        menu items, or for the user to do their own pulldowns. RUN gfx2("UMBar")=============================================================================SBAR  - move scroll bars. RUN gfx2("SBar",horz,vert)  horz............horizontal position (in cols)  vert............vertical position   (in rows)  =============================================================================WINFO - returns information about the window. RUN gfx2("WInfo",sctype,xsiz,ysiz,fore,back,border)  sctype..........screen type (1-8)  xsiz............current working column size  ysiz............current working row size  fore............window foregnd palette number  back............window backgnd  border..........screen border=============================================================================SETMOUSE - set the mouse scan rate, button timeout, autofollow. RUN gfx2("SetMouse",SCANRATE,TIMEOUT,AUTOFLAG)  SCANRATE........1/60 sec ticks between mouse reads (3 works well)
                  A value of 255 leaves the current setting alone  TIMEOUT.........ticks until packet goes into quiet mode (1)
                  A value of 255 leaves the current setting alone  AUTOFLAG........cursor autofollow (0=off, 1=on)=============================================================================MOUSE    - return mouse packet information. RUN gfx2("Mouse",valid,fire,x,y) RUN gfx2("Mouse",valid,fire,x,y,area,sx,sy)  valid...........00 if data invalid (not interactive window)  fire............00 if none, 01=button A, 02=button B, 03=both buttons  x...............window relative, scaled X  y...............window relative, scaled Y  area............window area if WNSET.                     00=inside working area                     01=outside working area (menu region)                     02=off window entirely  sx..............full screen unscaled X  sy..............full screen unscaled Y=============================================================================ONMOUSE  - set up both mouse button & key pressed signals, optionally sleep
 until click / key press. RUN gfx2("OnMouse",SIGNAL)  SIGNAL..........signal on click. If 00, then sleep until button pushed. If
                  you pick a specific signal number, your program must have
                  a signal trap set up (that overrides BASIC09's own).
           NOTE:  We have plans to expand BASIC09 to handle signals through
                  ON ERROR in the future; these will use signal numbers that
                  are not ordinary error codes (ao currently 4-9 or 80-183)=============================================================================ID  - return process ID for use as buffer group, etc. RUN gfx2("ID",id)  id..............process ID number returned=============================================================================TONE - play a tone RUN gfx2("Tone",FREQ,DURATION,VOL)  FREQ............frequency (1-4095)  DURATION........duration in 1/60ths sec  VOL.............volume (1-63)=============================================================================FELLIPSE - Draw a Filled Ellipse in current foreground color RUN gfx2([path,]"FEllipse"[,xcor,ycor],X radius, Y radius) XCOR.............Center point X coordinate YCOR.............Center point Y coordinate X RADIUS.........Radius of width of ellipse Y RADIUS.........Radius of height of ellipse=============================================================================FCIRCLE - Draw a Filled Circle in current foreground color RUN gfx2([path,]"FCircle"[,xcor,ycor],radius) XCOR.............Center point X coordinate YCOR.............Center point Y coordinate RADIUS...........Radius of circle=============================================================================DRAW - Draw a polyine figure RUN gfx2([path,]"Draw"[,startx,starty],option list) (see OS-9 Level II manual for option list commands) STARTX...........Start X coordinate for draw string STARTY...........Start Y coordinate for draw stringNOTE: Although the manual doesn't explicitely state it, you do NOT need
  commas between options (only between X and Y coordinates). So you can
  shorten your Draw strings by removing them:
EXAMPLE:
  Old method: RUN gfx2("draw",260,100,"n15,w10,e60,w10,s15,w40")
  New method: RUN gfx2("draw",260,100,"n15w10e60w10s15w40")=============================================================================