Build Screen Usage Guide Table of Contents: Introduction 1 Running tbuildscreen 1 Program Format 1 Statements 2 Comments and Line Continuation 2 Symbol substituion 2 Substitution and arithmettic 3 Undefined symbols 3 String Array 3 Handles 3 Symbol format checking 3 Defining variables 4 Errors 4 Program issues 4 Cleanup 4 Communication and gadget/menu processing 4 Statement ordering and nesting 5 Detailed description of Statements 7 Graphic Statements 7 Arithmetic and Control Statements 19 Communication packet format 23 Statement summary 25 Index 1 Introduction Build-Screen is a window/screen server. When invoked (its file name is tbuildscreen), it runs as an independent program that will display screens and/or windows with menus and/or gadgets and communicate the results of user interaction by intertask communication;. Both an aRexx ;and a Pipe;: interface are supported. With a pipe, all communication goes from tbuildscreen to the external program via the pipe. With an arexx interface, communication can go both ways. Tbuildscreen is started with the name of a file that contains a text description of screens, windows, menus, etc. and optionally the name of a pipe: to use for communication. The text file can be thought of as a small program for building screens which is directly interpreted at run time by Build-Screen (there is no compile step). Some simple capabilities for looping and variables are implemented as well as a macro substitution capability. The majority of this document is a description of this language. An arexx program can issue each of these through the arexx port ;(except for the loop and end loop statements). Running tbuildscreen Usage;: tbuildscreen [program-file] [output-stream] Tbuildscreen is the file name of the Build-Screen program. It retreives the command line ;arguments and calls on its interpreter to process the text file given as the first argument. If a second argument is given, it is used as the name of the output stream;. There are defaults for both. If program-file is not given, then screen.dat is assumed. If output-stream is not given it is assumed to be "*" which translates to the current console output window. Note that output-stream may be specified as NIL: which is especially useful if one is using the arexx interface. If the output-stream is to be used by a program for communications, then it should be given as pipe:xxx where xxx is the name of the pipe. To use the pipe device meaningfully, the reading program must do unbuffered single character reads until it reaches the newline character whereupon it can process an entire line. See the Amiga-Dos 1.3 description for use of the pipe device. Output-stream can also be a file but there can then not be any direct response until the user picks the close box, at which time the file will be closed and can then be read by a program. The output-stream may also be used for debugging by running the program at the CLI and noting what menu/gadget outputs occur. Program Format A program ;is a set of statements one per line. However, there is a facility (hyphen) for continuing a statement to the next line. For example: CreateScreen sname 640 400 - 3 "scr1" 6 4 CreateWindow wname sname 0 0 640 400 - "closewindow" "borderless" "title" setfont Helvetica.font 24 textat wname 365 startline2 "hello" 1 2 jam1 !comments like this delay 100 CloseScreen sname This will create a hi res screen named scr1 depth 3 with front/back pens of 6 and 4. Then it will open a window, write hello using the Helvetica font size 24, wait 2 seconds and then close the screen (and windows) and exit. .c2.Statements Statements ;are 1 or more words separated by spaces. There are 2 word types: "strings" symbols For example, in the create screen statement above, "scr1" is a string and all the rest are symbols (whether text or numbers, if not quoted they are symbols). The first symbol on a line is the command symbol;i.Case ;does not matter here. Other symbols may be case sensitive or not. As a rule, internal symbols are NOT case sensitve, user defined symbols ARE. .c2.Comments and Line Continuation line continuation The first ! and characters up to the end of a line are automatically stripped before anything else occurs. However, you may force a ! into the statement by preceding it with a \ escape. For example: textat wname 365 startline2 "hello\!" 1 2 jam1 !comments like this A line may be continued if the LAST symbol on a line (after removing comments) is a "-" by itself. This means it must NOT be attached to the preceding symbol or string. Thus place 1 or more spaces before it. It may be followed immediately by a comment;. Blank lines ;or comment only lines are ok. .c2.Symbol substituion;; There are two symbol substitution mechanisms: symbol and stream. Symbols are complete words that are not imbedded in other text and are not enclosed in quotes. If a symbol is defined as for example: setstr "myname" "This is my name" Then any later symbol occurance of myname without quotes is replaced by the string This is my name.. Note that a symbol is only substituted once; if the result is another symbol, it is not replaced. A symbol substitution cannot replace multiple symbols. When defining a symbol, you should place it in quotes as in : setstr "aname" myname since this would insure that aname is not substituted for in the event that it had been previously defined. It is permissible to leave off the quotes if the symbol has not been previously defined. Stream substitution refers to a mechanism which provides for substition anywhere in a statement; including in quotes and embedded in other text. The mechanism requires that a defined symbol or variable be enclosed in a pair of $ (dollar sign) characters. For example, setstr "eric" "123" add 5$eric$0 x would result in the value 51230 being added to the variable x. These symbols must be defined or an error stop will occur. The procedure for substitution is a two step process. After a complete line is assembled it is copied character by character left to right replacing each $sym$ occurance with the value of sym. Note that sym may be either a variable (1 char a..z either case) or a symbol (2 or more characters). After the new line is built, it is then parsed into entities separated by spaces but keeping quoted strings as a single entity. Then each of the entities that was not quoted is checked to see if it is a symbol that has been defined by the setstr statement. If true, it is replaced by its value from the setstr statement. .c2.Substitution and arithmettic There is a very simple numerical substition ;capability here. A single character e X will be intrepreted to be one of 26 variables ;(a..z case is not important here). To specify a string of X do it a "X". The "set", "add", etc. statements manipulate numerical variables;. For example, here are some numerical and symbol substitions;: set x 5 ! numeric, variable x must be only 1 char set y 10 setstr penA 5 ! symbol definition, penA must be 2 or more chars setstr penB 6 setstr mode "jam1" textat window1 x y "hello text at x,y" penA penB mode .c2.Undefined symbols undefined symbols ;If a symbol is greater than 1 character in length and is not defined, then it is treated as a literal string as though it had been quoted. In the above example, penA is defined to a 5 in this manner. Note that 5 is a string in the above. When a number is required, the 5 is scanned and since it is a string comprised of all digits, it is a valid number.This technical detail is more complicated to describe than to use. Quotes are important in two cases. In a setstr statement, the symbol to be defined must be quoted if it is already defined. If it is not defined, then the quotes are not necessary. The other case is where there is a string that needs to include blanks - such as a list of attributes such as window flags. .c2.String Array String array;There is one and only one string array built by the strings statement. The members of this array of strings are referenced by a symbol that is a * followed by either a number or a single letter. For example: *5 means the 5'th string in the string array. *x means the x'th string in the string arrayc2.Handles Handles;. When creating a window or a screen, you provide a symbolic name that will be used later. For example, when you create a screen, you later can create a window on that screen by providing a connection between them which is a symbol to name the screen. These symbols are refered to as handles since internally each symbol is placed into a symbol table with the corresponding intuition pointer (handle) for the particular entity created. For example, the screen handle is a pointer to an intuition screen structure. Each handle is one of 5 types (Menu, Image, window, screen, or Gadget) and the type is checked when the handle is used. .c2.Symbol format checking There is some bit of symbol checking ;for each statment. For example, a numerical parameter must be either a constant or a numerical variable or a symbol that is defined to be a number. In addition, some numbers must not be negative and others must be 0. Data parameter format ;summary: ".." string '..' string xxxxxx string or variable (if defined then a string variable) I if I is a..z or A..Z then a numeric variable 9 or 9999 a number constant (may be negative) *9 the 9'th string setup via the Strings statement *I the I'th string Summary of substitution algorithm When a parameter is accessed, it is checked to see if it is a string constant. If not, then it is looked up in a table if it is at least 2 chars in length. If it is 1 char in length, then it is checked to see if it is an a. If it begins with a * then the next chars are checked for either an integer constant or a single alphabetic character - in which case its assumed to be an index into the strings set by the strings statement. .c2.Defining variables Defining variables;: set n value this sets n to be a numeric variable setstr vvv "string" makes vvv a string macro; vvv must be 2 or more chars. strings "aaa" "bbb".. defines string array that can be referenced by *i or *9 .c2.Errors Errors All errors invoke a standard error module which displays a system request with the line number in the file that caused the problem and possibly the symbol that is in error. There are 2 options. The left option is "debug" and will cause a trap instruction. This is useful only if you have source and the benchmark source debugger in place. It causes a trap instruction that loads the debugger. The right option "continue" causes a return from the error module where a cleanup operation occurs followed by a halt. This is the proper choice for all but the program author or his test crew. Note that considerable effort is given to cleanup - windows and screens etc. are completely tracked (including which windows go with which screens) and they are closed down in the proper order. All memory allocated is also returned to the system. I don't know what happens if you select the debug option and the debugger is not available. Program issues .c2.Cleanup cleanup The program tries to clean up after itself where ever possible. If any error occurs it attempts to close all windows and screens created thus far. This is not easy so it may not always work. .c2.Communication and gadget/menu processing;. There is the capability for the program to write to a pipe: with information when there is a menu or gadget invocation. Thus an external program could use buildscreen as a window server. There is a run statement which can specify a window to monitor for gadget and menu selections. It will interpret the action and write a text string into the pipe. Any program that reads this pipe, MUST read 1 char at a time. Buffered i/o will not work because you will not get a completion or eof from the pipe device. So you must read unbuffered 1 char until you see a newline. An arexx port capability is also provided. Details to follow. .c2.Statement ordering and nesting There are a number of statements that must be specified in a particular order. Gadgets: The gadget statement group must be ordered as follows and must precede the statement that creates a window which uses the gadget lists. BeginGadgetList AddGadget statements -- 1 or more of these GadgetOpt -- optionally follow an AddGadget statement to modify default actions EndGadgetList mygadgets -- note the name parameter, it is the handle wherein these gadgets can be referenced later when creating a window to use these gadgets Some gadgets ;make use of images. These images must be specified prior to their use in some add gadget statements. Menus: Menu's ;can be built at any time but cannot be used until a window has been created whereupon there is a statement that attaches a menu to an open window. The ordering is: CreateWindow wname statement BeginMenuStrip addmenu addmenuitem or addmenuitems BeginSubMenu addmenuitem or addmenuitems addmenuitem or addmenuitems addmenuitem or addmenuitems endsubmenu BeginSubMenu addmenuitem or addmenuitems addmenuitem or addmenuitems addmenuitem or addmenuitems endsubmenu addmenu EndMenuStrip mstrip wname -- note the wname handle The EndMenuStrip command attaches the menu built up in the prior statements to the window via the connection handle wname. There are 2 ways to add menuitems; one lets you specify lots of parameters such as color etc. The other, lets you specify lots of menuitems in one statement, but uses the current settings for each item. Currently, buildscreen only supports interaction with a single window that has menu's and gadgets. However, multiple windows can be built with windows and gadgets; its just that you will not really be able to do much with them. Future enhancements are planned to deal with this situation. Gadget ID's ;These are specified in 2 ways, either a value such as 10, or -1 which means set this gadget id to 1 more than the last one entered. Detailed description of Statements;: The statement descriptions that follow have the following format: Statement Parameters Description An example in this font Statement may be entered in any case the that is convenient, including mixed case. Italics is used to distinguish the parameter name (as used in this manual) from other cases where a word of the same spelling is used. .c2.Graphic Statements;: ? commands:addMenu; text Adds a menu to the menu strip. This starts a new column of menu items. The parameter text is the name of the menu. Example: addMenu "project" ? commands:addGadgetImageButton ; left top imname id Adds an image button type gadget to the current gadget list. The image is specified by the imname parameter. The gadget is placed in the window according to the left and top parameters. The gadget is given an id as specified unless id is -1. When -1, the gadget id becomes 1 more than the last gadget created. Example: image image1 "pics:image1.iff" ! read image1 into memory addgadgetimagebutton 10 20 image1 5 ! build a gadget based on image1 ? commands:addGadgetImageButton2; left top imname1 imname2 id Same as addGadgetImageButton except uses 2 images for selected and not selected. Example: image image1 "pics:image1.iff" ! read image1 into memory image image2 "pics:image2.iff" ! read image2 into memory addgadgetimagebutton 10 20 image1 image2 50 ? commands:addGadgetInteger; left top chars bufsize str name id Example: AddGadgetinteger 10 180 - ! x,y 20 100 - ! screen, buff sizes 0 0 - ! init value 200 ! gadget id Builds a gadget that inputs a numerical string. Position at left and top with chars characters showing in the gadget, and bufsize characters maximum string size (lets you scroll this much) str is the default starting setting. name is not implemented. id is the gadget id as described in the description of addGadgetImageButton. ? commands:addGadgetProp ; left top wid height hon von hpot vpot hbody vbody id proportional gadget described by left top wid height with hon and von 0/1 for horizontal and vertical enabled, hpot and vpot are the pots and hbody and vbody are the body values. id is the gadget id. Example: AddGadgetProp 180 15 20 130 - ! left,top,wid,height 0 1 - ! horz,vert enables 0 0 - ! pot values 32768 32768 - ! body values -1 ! gadget id ? commands:addGadgetString ; left top chars bufsize str name id This is the same as addGadgetInteger except for the string entered being allowed to be non-numerical. Example: AddGadgetString 10 150 - ! x,y 20 100 - ! size on screen, size of buffer "Enter a string here" "spare" - ! initial string, spare arg -1 ! use prior value + 1 ? commands:addGadgetTextButton ; left top name id This creates a simple text button using name for the text to insert in the button. Left and Top position the gadget and it is given and id as specified. Example: AddGadgetTextButton b 70 "button 2" -1 ? commands:addMenuItem; text Adds a menu item using text. Example: AddMenuItem "menu item" See also menuItemOpt for changing some of the options for a menuitem. SetFont will be used to determine the font for a menuitem if the command menuitemtextattr is used as well. ? commands:addMenuItems ; text1 mut1 text2 mut2 This adds multiple menu items. Each text is paired with a mutual exclusion parameter. Note that mutual exclusion numbers beginning with a 0 are treated as binary values. The example below shows how to set up the first item using menuitemOpt to set the current values. Also note the mutual exclude item in the menuitemOpt statement. The 2..n'th items all will have the same attributes as the first, only the mutual exclude needs to be different. Also note that in binary, its the 0 that changes position. I its in the rightmost position for the first item, second item its in the second position etc. There needs to be enough 1's to account for all the possible items. The below example assumes certain symbols have been setup elsewhere (frontpen etc Example: BeginSubMenu 120 0 addmenuitem "Blue" menuitemOpt = - ! = means set the flags to the next arg "itemtext itemenabled checkit highcomp " - !flags 110 - ! mutex 0xxx = binary, xxx = decimal "" - ! the char (requires commseq flag) frontpen backpen jamtype addmenuitems "Red " 101 - "Green" 011 endsubmenu ? commands:beginGadgetList This begins a gadget list. It just gets things set up for the list to follow. ? commands:beginSubMenu; left top This begins the description of a sub menu. The left and top parameters denote the postion relative to the menuitem for the location of the submenu items. See the example above under add menu items. ? commands:beginMenuStrip This begins a menu list. It just gets things set up for the list to follow. ? commands:blit ; wfrom x1 y1 wto x2 y2 sizex sizey minterm This command will blit a rectangular section from window wfrom (x1,y1) to window wto (may be the same as wfrom) at coordinates (x2,y2). Sizex and sizey specify the size of the rectangle. This function uses the blitter ;and takes a minterm argument. ? commands:checkmark ; image width hflag Specify a user defined checkmark to be used in menus. Image is an image handle, width is either 0 to use the width specified in the image or a user defined value to determine the space set aside for checkmarks. Hflag is either 0 or 1 to specify that MenuitemHeight should be automatically set to the height found in the image specified. ? commands:createScreen ; name wid height depth title image-color-map detail block Create a screen. name is the handle to reference this screen. image- color-map is a handle for a prior image loaded. It uses that images color map. detail and block are pen colors. Height, depth, and title are self-explanitory. Example: Image colormap "gov:brushes/button.col" CreateScreen sname 704 - ! width 420 - ! height 3 - ! depth "scr1" colormap - ! This is the title and the color map to use 6 4 ! detail block pens Note: A predefined screen handle WB is defined when you want to open a window on the WorkBench window. (No checking is done to determine if a workbench screen exists however!) ? commands:closeScreen ; name Closes screen and all windows on the screen specified by name. ? commands:createWindow; wname sname x y wid height idcmp flags gadgets title Creates a window 'wname' on the screen sname. x y wid height determine its location and the idcmp' and flag strings are each a list of keywords (case-insensitive) that are "added" together to determine the attributes of the window. gadgets is a handle from a gadget list. The window's title is given by the last parameter. The screen may be "WB" to open on the workbench screen. Example: CreateWindow - wname - ! window name sname - ! screen name This may be "WB" for workbench 0 - ! origin is 0,100 3 - 704 - ! the width 408 - ! the height "closewindow menupick gadgetup" - ! idcmp flags "WINDOWCLOSE activate" - ! window flags mygadgets - ! gadgets "" ! window title ? commands:closeWindow; name This just closes a window give a window handle. ? commands:delay; ticks This causes a delay; normally used for debugging purposes. Ticks are in 50'th of a second intervals. ? commands:draw; wname x y This draws a line in window wname from the current pen position to x,y. See also Move. ? commands:drawImage; wname image x y This will take an image image and draw it into window wname at location x,y. ? commands:drawLine; wname x1 y1 x2 y2 PenA PenB Mode This draws a complete line from position (x1,y1) to (x2,y2) using the specified pens and drawing mode. The line is drawn into window wname. ? commands:ellipse; wname centerX centerY HorizontalRadius VerticalRadius PenA This draws and ellipse with the given (x,y) center position using the 2 specified radii. If the radii are equal, then a circle is drawn. The color used is PenA but this may be specified as -1 to use the current A pen value. Drawing occurs into window wname. ? commands:endGadgetList ; name This closes the construction of a gadget list and creates the handle name that can be used to place this gadget list in a window. Note, that the gadget list should be created before the openWindow call since gadgets are attached to windows only via openWindow. For example: Image b1 b1.iff ! read in images, b1-b4 Image b2 b2.iff Image b3 b3.iff Image b4 b4.iff BeginGadgetList set x 20 set y 20 setstr separation 25 loop 15 AddGadgetImageButton2 x y b2 b1 100 ! b2,b1 are 2 images GadgetOpt . "" - ! gadget flags + "TOGGLESELECT" - ! activation flags 0 ! mutual exclude add separation y ! create 15 buttons, 25 pixels apart end loop EndGadgetList mygadgets CreateWindow - wname - ! window name sname - ! screen name 0 100 - ! origin is 0,100 704 - ! the width 408 - ! the height "closewindow menupick gadgetup" - ! idcmp flags "WINDOWCLOSE activate" - ! window flags mygadgets - ! gadgets "" ! window title ? commands:endSubMenu This closes a submenu. It affects the use of addMenuIem; following calls to addMenuItem will define the parent menu. ? commands:endMenuStrip; msname wname This is used after a menu strip is completely defined. It provides a name for the menu, msname, and a window, wname, to which the menu will be attached. The msname parameter is used only for the purposes of later removing the menu and reclaiming any resources (memory). The wname parameter is used to denote which window will have a menustrip attached. This means that it only makes sense to open a window prior to building the menustrip. However, it is possible to build all of the menuitems and then open a window just prior to calling endMenuStrip. CreateWindow - wname - ! window name WB - ! screen name 50 - ! origin 50 - 300 - ! the width 200 - ! the height "closewindow menupick gadgetup" - ! idcmp flags "WINDOWCLOSE activate windowdrag windowsizing" - ! window flags mygadgets - ! gadgets "" ! window title BeginMenuStrip addmenu " First menu " addmenuitem "menu item one" addmenuitem "menu item two" EndMenuStrip mstrip wname ? commands:fillBox; wname x y wid hgt penA penO This will draw a filled box into the wname window at location x and y in pixels. The box will have a width and height described by the wid and hgt parameters. The penA parameter describes the color to be used for the box and the penO paramter is the outline color. The outline is a 1 pixel outline and to make a one color box it is necessary to supply both penA and penO to be the same color. For Example: fillbox wname 50 20 105 45 - 2 3 ! pen color and outline color ? commands:fillBoxs; sname x y wid hgt penA penO This will draw a filled box into the sname screen at location x and y in pixels. The box will have a width and height described by the wid and hgt parameters. The penA parameter describes the color to be used for the box and the penO paramter is the outline color. The outline is a 1 pixel outline and to make a one color box it is necessary to supply both penA and penO to be the same color. For Example: fillboxs sname 50 20 105 45 - 2 3 ! pen color and outline color ? commands:flood; wname mode Cx Cy PenA PenO This will flood a region in window wname given the mode, coordinates and pen parameters. This call corresponds directly to the graphics library call of the same name. ? commands:gadgetOpt ; "+-=." flags "+-=." activate mutualex This permits a finer control over the options of a gadget. It must immediately follow some add gadget statement. Both the flags and activate argument take a set of strings in quotes. These strings are keyword flags that are added together to form a flag value which is then, added to, subtracted from, or used instead of the default value. The preceding string is a single character which may be "+", "-", "=", or " It does not need to be placed in quotes. A "+" causes the flags to be added to the default, a "-" means subtract, "=" means replace, and "." means leave it as is. If "." is specified, then the flags or activate will be ignored, but must still be present. A pair of "" may be used to hold the position without actually supplying a value. The final parameter is the mutual exclusion value for this gadget. The flags are the same as those found in the intuition manual except that case does not matter here. The permitted gadget flags ;are: gadghcomp;, gadghbox;, gadghimage;, gadghnoen;, gadgimage;, grelbottom;, grelright;, grelwidth;, grelheight;, selected;, gadgdisabled;. The permitted activation flags ;are: toggleselect;, gadgimmediate;, relverify;, endgadget;, followmouse;, rightborder;, leftborder;, topborder;, bottomborder;, stringcenter;, and stringright;. For example: AddGadgetImageButton2 420 25 mickey2 mickey GadgetOpt . "" - ! gadget flags + "TOGGLESELECT" - ! activation flags 0 ! mutual exclude ? commands:globalGadgetOpt not implemented yet ? commands:image ; imname file This reads into memory the specified picture file (or brush) and labels it imname for use in later gadget statements. It can also be referenced in a createScreen statement to specify the color pallette. image myimage ram:brush.pic ? commands:menuItemOpt ; "+-=." flags mutualex char frontpen backpen mode This provides finer control over menu options. The first argument determines how the flags argument is used. See the discussion on gadgetOpt flags for more information. The flags argument is the set of flags which may be set for menus: checkit;, checked;, itemtext;, commseq;, itemenabled;, highflags;, highcomp;, highbox;, highimage, and highnone;. These flags are defined in the Intuition manual and have the same spelling as the standard intuition flags; however, buildscreen does not care about the case of the characters. Multiple flags are entered by quoting the group with each separated by 1 or more spaces. The char parameter is the character that when combined with the right amiga key will invoke the menu selection. The flag commseq must be set for the char parameter to be meaningful. Frontpen, backpen and mode describe the text in the menu item. The 2 pen values should be 0..N-1 where N is the number of colors in the screen where this menu will appear. The mode may be one of: Jam1;, Jam2;, compliment;, or inversvid;. For example: BeginSubMenu 120 0 addmenuitem "Blue" menuitemOpt = - ! = means set the flags to the next arg "itemtext itemenabled checkit highcomp " - !flags 0110 - ! mutual exclude 0xxx = binary, xxx = decimal "" - ! the char (requires commseq flag) 2 4 jam1 ! the front, back pens and the pen mode addmenuitems "Red " 0101 - "Green" 0011 endsubmenu ? commands:menuItemHeight; value This specifies the height for each menuitem to be used to computer where the next menuitem is placed. The value is in pixels. ? commands:menuItemLastRow ; value Normally, items are placed in the menu downward until they reach a limit whereupon a second column is created. This value permits an override which is normally used to force the next column earlier than usual. The value is in pixels. ? commands:menuItemSize ; value Normally, a highlighted item is boxed or inversed according to the value of menuItemHeight. That is, if the height is 10, say, then the box would also be 10. However, if the font is small, then the box encompases much blank area below the text. This value permits an override; its used when you want a lot of spacing around each menu item, but don't want the selection box area to look off centered vertically. The value is in pixels. ? commands:menuItemTextAttr ; This is a toggle. It is initially set to off. When it is set on, it specifies that a setFont, which preceeds this statement, is to specify the font that is used for following menu items. ? commands:move; wname x y This moves the current pen position in window wname to (x,y). ? commands:nextItemColumnOffset ; value This value controls the number of pixels to skip between vertical columns of menu items. ? commands:palette; wname x y sizex sizey This produces a horizontal palette, mostly for debugging purposes, in window wname starting at location (x,y) with each palette box of sizex pixels wide and sizey pixels high. The number of colors is dependent upon the screen depth. ? commands:refreshGadgets ; wname This causes a refresh of the gadgets in window wname. It is quite useful when you want to draw into a window and then redraw the gadgets that might have been obscured. ? commands:screen sname function This command operates on a screen sname according to the function given. The values permitted for function are: back;, and front;. Back and front specify the depth control ;of the screen. ? commands:setDrawMode ; wname mode This sets the drawing mode to be used by following draw statements when building up objects using draw and move. setdrawMode wname Jam1 draw wname 10 10 draw wname 20 20 ? commands:setFont ; name size This sets the font to be used by following textAt statements. If menuItemTextAttr is on, then the menu items will also use this font setting. setFont times.font 18 textAt 10 20 "here is some text" 1 2 jam1 ? commands:setPens ; wname PenA PenB PenO This sets the current value for the 3 pens. Currently, the draw command is the only statement that does not have any pen values in its statement and thus must have its pens setup in this way. The Ellipse statement permits the pen value to be -1 to indicate use the current value of PenA. This statement also permits one to leave 1 or more of the pens set with their current value; specify a -1 for any pen value that you do not wish to change. For example: setPens 1 3 -1 setPens -1 -1 valueofpenO ? commands:strings ; "xxx" This defines a set of strings ;that can be referred to by using a numeric variable. The purpose of this statement is allow the definition of text that can be referenced inside a loop. set x 10 ! init x to 10 set t 1 ! init t to 1 strings "one" "two" "three" "four" "five" ! define 5 strings loop 5 ! 5 times thru the loop textAt window x 20 *t 1 2 jam1 ! place t'th string at position (x,20) add 10 x ! add 10 to x add 1 t ! increment t end loop ? commands:textat; wname x y text penA penB mode This places text in the window wname at position x ,y using penA and PenB in drawing mode mode. See above for an example. If text is null, only the current colors and x and y position will be set. This is normally used when the next statement will be textStrings. If x and/or y is -1, then the x and/or y position will be left unchanged (but the color and mode is changed). ? commands:textStrings ; xinc yinc text1 text2 textN This places multiple text strings using the pen setup and window of the previous textAt statement. Each text string is written (if not null) and then its starting position is incremented in x and y by xinc and yinc for the placement of the next string. It makes sense to have the first string be null otherwise one may overwrite the previously placed text string. Note the initial start position is the same as the last x and y in a textAt statement, not the end of where that text was placed. Alternatively, one may specify a null string in a textAt statement simply to position the current starting postion and set the current colors. See also the description of textAt which permits setting of the x and y positions and color without drawing any text. textat wname 55 startline "" 1 2 jam1 !start coords no text to print textstrings 0 movedown "Red Units" "Blue Units" textat wname -1 -1 "" 4 2 jam1 !change color only textstrings 0 movedown "" "Local Standard Routes" "Global Standard Routes" ? commands:wBenchToBack ? commands:window wname function This command operates on a window wname according to the function given. The values permitted for function are: back;, front;, and wake;. Back and front specify the depth control ;of the window and wake will activate a window;. This moves the workbench screen to the back postion. .c2.Arithmetic and Control Statements ? commands:setstr ; var val This sets a symbol var to be equal to some string. The string, val, may be any printable text characters. It may also be another symbol. setstr x-start-position 20 setstr y-start-position x-start-position setstr increment "20" setstr title "this is a title with spaces" ? commands:set ; var val This sets a variable var to a value. Val may be an integer number, or another variable or a symbol that has been defined to be a variable or constant. set x 5 ? commands:say ; string val This is a debugging statement. It will write to the output console window a string and a value. say "this is x " x ? commands:add; val var This adds a value val to a variable var. add 3 x setstr width 20 add width x ? commands:add3 ; val1 val2 var This adds val1 to val2 and places the result in var. add3 x 3 y !y = x + 3 ? commands:sub ; val var This subtracts value val from variable var. sub 3 y !y = y - 3 ? commands:mul; val var This multiplies value val by variable var. The result goes to var. mul 3 y !y = y * 3 ? commands:div ; val var This divides value val into variable var. The result goes to var. div 3 y !y = y / 3 ? commands:loop; num This begins a loop. The num parameter determines the number of times the loop is run. There is no way to break out of the loop once begun and the loop must run at least one time. ? commands:endloop ; This denotes the end of a loop. ? commands:if ; var1 relational var2 This denotes the beginning of an if-block. There must be exactly 3 parameters here with var1 and var2 being numerical arguments and relational ;is one of 4 relations: > greater < less than = equal # not equal There may be nested if blocks and there may also be an else statement. If blocks are terminated by and endif statement. For example: set x 5 set y 6 if x = y setstr thefont topaz.font else setstr thefont courier.font endif if x = 5 say "x = " x endif ? commands:endif ; This denotes the end of an if block. ? commands:else ; This may be used inside an if block. ? commands:run ; wname This instructs buildscreen to loop until the window given as wname has its close button depressed (if the window has one - if not, there is NO way to exit except to reboot!!!). Each menu selection ;and/or gadget pick ;will cause a text string to be written to the output stream ;(setup by the initial call to tbuildscreen). See the section on communication for the format of these text strings. ? commands:rexx ; wname rexxport This instructs buildscreen redirect input to the arexx port rexxport. Further commands will then come in thru this port rather than the input file. Two special commands that can only be executed when they come thru the arexx port ar e RWAIT and REXIT. The RWAIT command is used to wait for some user action in the given window wname which will be returned to the arexx port as a result string. The REXIT command is used to terminate the rexx command. The rexx command is also terminated when the user selects the close box in the window wname. To use the rexx command with an arexx program, the arexx program normally invokes tbuildscreen with the name of a file that contains window and/or gadget commands followed by a rexx command to start communication. The arexx program waits for the port to arrive followed by a loop which issues the RWAIT command. When the RWAIT command finishes, there will be a result in the RESULT arexx variable that contains a text string describing the action taken by the user at the window. The arexx program can then decide how to use this string and may issue a command that directs build-screen to write text, draw a box etc. or just RWAIT for another user input. See the section on communication for the format of these text strings. Here is an example arexx program;: /* */ options results address command 'stack 20000'||'0a'x|| 'c:run >nil: c:tbuildscreen screen3.dat nil:' address command 'waitforport foobarport'||'0a'x|| 'waitforport bscrport' do forever address 'bscrport' RWAIT a = RESULT parse var a action p2 p3 p4 p5 p6 . say 'here is the result "'|| a ||'"' say action say p2 say p3 say p4 if action = "" then do /* check for what action occured */ say 'menu null' n = 50 /* lets write a 50 into the window */ address 'bsccrport' 'textat wname 190 140 "' || n || '" 2 3 jam2' end if action = "C" then do /* if C, then the user hit the close box */ say 'window closed' leave end if action = "G" then do /* if G, then a gadget was hit */ say 'gadget ID ' p3 ' type is ' p2 end if action = "M" then do /* if M, then a menu item was selected */ say 'Menu checked=' p2 ' menu# ' p3 ' item ' p4 ' sub item ' p5 end end This program turns on results (options results) and then spawns the program tbuildscreen with an input of screen3.dat which contains a program that tbuildscreen interprets thereby creating a window and/or screen with menus and/or gadgets. In this program is a statment rexx wname bscrport which cause tbuildscreen to begin receiving messages from the arexx program. When the arexx program sends the command RWAIT, tbuildscreen waits until the user selects some menu or gadget. The arexx program then parses the result and based on the first word determines what action had taken place. When the action is a "C", then this is a signal that the user hit the close box and so the arexx program leaves the loop it is in and exits. Note that there is a coupling between the arexx program and the file screen3.dat in the symbol used to denote the window. Wname is the symbolic name given in a createwindow statement contained within the file screen3.dat. It is possible for an arexx program to send in any command that is permitted in the input file except for a rexx command itself. The input file should not contain any RWAIT or REXIT commands. ? commands:rexit This command may only be sent from an arexx program and causes termination of a prior rexx command. It causes a close of the arexx port and a result of OK is sent back. ? commands:rwait This command may only be sent from an arexx program and causes a wait until a user window or gadget selection occurs after which a result string is sent back to the arexx program containing information about the user selection. See the section below on packet formats for more information. Communication packet format When either the run or runrexx commands are issued, buildscreen will report menu and/or gadget selections to an arexx port ;and and output stream;. The format of these messages ;are nearly identical. The only difference is that arexx port messages do not have a newline following the text whereas the text written to the output-stream does. In all other respects, the two streams are the same. The format is as follows: type word1 word2 wordN where type is one of: C for closewindow G for gadget selection M for menu selection P for pointer selection K for keyboard selection For the C, closewindow message, there are no following words. For the G, gadget selection type, the format of the words depends on a sub-type (that is, what type of gadget). The first and second words are always the sub-type and gadget-ID as shown below: G sub-type gadget-ID {sub-type-dependent-data follows here} The word1 is the gadget sub-type which can be P, B, I, or S. These 4 sub-types look as follows: G P gadget-ID HorizPot VertPot !Proportion gadgets G B gadget-ID selected !Boolean gadgets G I gadget-ID value !Integer gadgets G S gadget-ID =stringtext !String gadgets Note that for the string gadget;, there is really no strict word format, rather, the string is the text following the = up to the end of the message (or line if a stream). This was done to make parsing easier; just find the first occurance of the = and everything following is the result. For the other three, only numbers can occur and these are given in word format (i spaces separating individual words). For example: G P 45 65535 32222 ! proportional gadget, id=45, hpot=65535, vpot=32222 G B 22 0 ! a boolean gadget, id=22, value=0 (not selected) G I 55 100 ! integer gadget id=55, value =100 G S 222 =This is the text ! string gadget id=222 with text 'This is the text' For the M, menu selection types, there is one format, but there may be repetitions if the user uses the extended menu selection option. Theformat of a menu selection report ;is: M {checked menu-num item-num sub-num} Checked is either 0 or 1. If this item is not a toggle select, then checked will always be 0. The next three numbers are the menu number, item number, and possibly the sub-item number. If there is no sub-item, it will be specified as a -1. All numbers are the position in the menu and begin at 0. The portion in {}'s may be repeated N times. An extended selection is one where the user keeps the right mouse button depressed while selected multiple options (by dragging or pressing). For example: M 1 0 0 0 ! checked, menu 0, item 0, sub 0 M 0 0 0 1 0 0 0 2 0 0 0 3 ! 3 menu items all in menu 0, item, 0 sub1..3 M 1 1 3 -1 ! checked, menu 1 item 3, no sub item For both the P and K types, the same information is returned. The current mouse x and y location are given along with a qualifier and a code. The qualifier is the input device value that denotes which of the shift-like keys were depressed at the time the event occured. The code is the value that determines which key or button was the cause of the event. For P, the values denote which mouse button was selected and for K the value denotes which key was depressed (or let up). These are raw keycodes. The formats are: P x y Qual Code K x y Qual Code where x and y are decimal and Qual and Code are given in Hex. For example: P 100 50 8000 e8 K 125 300 40 69 Statement summary;: add val var add3 val1 val2 var addGadgetImageButton left top imname id addGadgetImageButton2 left top imname1 imname2 id addGadgetInteger left top chars bufsize str name id addGadgetProp top width height hon von hpot vpot hbody vbody id addGadgetString left top chars bufsize str name id addGadgetTextButton left top name id addMenu text addMenuItem text addMenuItems text1 mut1 text2 mut2 beginGadgetList beginMenuStrip beginSubMenu left top blit wfrom x1 y1 wto x2 y2 sizex sizey minterm checkmark image width hflag closeScreen name closeWindow name createScreen name wid height depth title col-map detail block createWindow wname sname x y wid height idcmp flags gadgets title drawImage wname image x y delay ticks div val var draw wname x y drawLine wname x1 y1 x2 y2 PenA PenB Mode ellipse wname centerX centerY H-radius V-radius PenA else endGadgetList name endif endloop endMenuStrip msname wname endSubMenu fillBox wname x y wid height penA penO fillBoxs sname x y wid height penA penO flood wname mode Cx Cy PenA PenO gadgetOpt "+-=." flags "+-=." activate mutualex globalGadgetOpt IF var1 relation var2 image imname file loop num menuItemHeight value menuItemLastRow value menuItemOpt "+-=." flags mutex char fntPen bckPen mode menuItemSize value menuItemTextAttr move wname x y mul val var nextItemColumnOffset value palette wname x y sizex sizey refreshGadgets wname rexit rexx window rexxport run window rwait say string val screen sname function set var val setDrawMode wname mode setFont name size setPens wname penA penB penO setstr var val strings "xxx" sub val var textat wname x y text penA penB mode textStrings xinc yinc text1 text2 textN wBenchToBack window wname function Index activate a window 18 activation flags 14 aRexx 1 arexx port 1, 23 back 16, 18 Blank lines 2 blitter 10 Boolean gadgets 23 bottomborder 14 Case 2 checked 15 checkit 15 cleanup 4 closewindow 23 command line 1 command symbol 2 commands add 19 add3 19 addGadgetImageButton 7 addGadgetImageButton2 7 addGadgetInteger 8 addGadgetProp 8 addGadgetString 8 addGadgetTextButton 9 addMenu 7 addMenuItem 9 addMenuItems 9 beginGadgetList 10 beginMenuStrip 10 beginSubMenu 10 blit 10 checkmark 10 closeScreen 11 closeWindow 11 createScreen 10 createWindow 11 delay 11 div 20 draw 12 drawImage 12 drawLine 12 ellipse 12 else 21 endGadgetList 12 endif 21 endloop 20 endMenuStrip 13 endSubMenu 13 fillBox 13 fillBoxs 13 flood 14 gadgetOpt 14 globalGadgetOpt 14 if 20 image 14 loop 20 menuItemHeight 15 menuItemLastRow 15 menuItemOpt 15 menuItemSize 15 menuItemTextAttr 16 move 16 mul 20 nextItemColumnOffset 16 palette 16 refreshGadgets 16 rexit 22 rexx 21 run 21 rwait 23 say 19 screen sname function 16 set 19 setDrawMode 16 setFont 16 setPens 17 setstr 19 strings 17 sub 19 textat 17 textStrings 17 wBenchToBack 18 window wname function 18 comment 2 commseq 15 compliment 15 Defining variables 4 depth control 16, 18 endgadget 14 Errors 4 example arexx program 21 followmouse 14 front 16, 18 gadgdisabled 14 gadget flags 14 Gadget ID's 6 gadget pick 21 gadget selection 23 gadgets 5 gadghbox 14 gadghcomp 14 gadghimage 14 gadghnoen 14 gadgimage 14 gadgimmediate 14 grelbottom 14 grelheight 14 grelright 14 grelwidth 14 Handles 3 highbox 15 highcomp 15 highflags 15 highnone 15 Integer gadgets 23 intertask communication 1 inversvid 15 itemenabled 15 itemtext 15 Jam1 15 Jam2 15 keyboard selection 23 leftborder 14 line continuation 2 menu selection 21, 23 menu selection report 23 Menu's 5 messages 23 numerical substition 3 numerical variables 3 output stream 1, 21, 23 parameter format 4 Pipe 1 pointer selection 23 program 1 Proportion gadgets 23 relational 20 relverify 14 rightborder 14 selected 14 Statements 2 String array 3 string gadget 23 String gadgets 23 stringcenter 14 stringright 14 strings 17 substitution algorithm 4 symbol checking 3 symbol substitions 3 toggleselect 14 topborder 14 undefined symbols 3 Usage 1 variables 3 wake 18