@DATABASE @INDEX INDEX @NODE MAIN *** Gui4Cli *** An interpretive GUI programming language (c) 1995-1999 by D.C.Keletsekis @{" Introduction. " link "introduction"} @{" ToolTypes & Options " link "options" } @{" Program Operation " link "operation" } @{" Visual Editing " link "guiedit"} @{" Programming GUIs " link "programming" } @{" The GUI loader " link "c_Gui"} @{" Advantages/Features " link "advantages" } @{" Author/Bugs/Licence " link "licence"} @{" Important Background Information " link "Important_Topics"} * G u i 4 C l i C o m m a n d s : @{" Parser commands " LINK "c_parser"} NewFile, TextFile @{" Global commands " LINK "c_global"} WinBig, Wintype, ResInfo, ShareMenu... @{" Events " LINK "c_events"} Gadgets, Listviews, xOnLoad, xTimer.. @{" Graphics " LINK "c_graphics"} xTextBox, Line, Gauge.. @{" Event modifiers " LINK "c_gadmod"} GadID, Attr, GadTitle... E v e n t c o m m a n d s : @{" Controling Gadgets " LINK "c_gadcontrol"} SetGad, Update, Redraw.. @{" Control Statements " LINK "c_control"} if/endif, ifexists, Gosub, stop ..the ones below can also be sent as arexx commands.. @{" DOS commands " LINK "c_dos"} Run/Launch, SendRexx, Wait, Action.. @{" Handling guis " LINK "c_handle"} GuiLoad, GuiOpen, Info... @{" Handling variables " LINK "c_vars"} SetVar, ParseVar, Extract, RepVar.. @{" Listview commands " LINK "LV_Commands"} LVUse, LVDel, LVAdd, LVClip... @{" Multimedia " LINK "c_multimedia"} Images, Sounds, Speach, Palette... @{" Various commands " LINK "c_various"} ReqFile, EZReq, MakeScreen, BreakTask.. @{" Index of all the commands " link "all_the_commands"} ------------------------------------------------------------------- Click on the Demo.gc icon to begin. * **** Gui4Cli WWW Page - http://users.hol.gr/~dck/gcmain.htm **** ** EMail me at dck@hol.gr to join the Gui4Cli EMail List ** * @ENDNODE @NODE Action ACTION Source =================================================================== This is a command which will recursively scan the directory tree and perform the given to the Source. @{" LVAction " link lvaction } will do the same things, but to all the selected files/dirs of a given dir listview. The ESCAPE key - hit while a Gui4Cli window is active - will abort any operation taking place. The "Source" can be a File or a Directory - *not* a device. The Actions that can be performed, are : COPY Will copy the file or dir to the destination. ex : ACTION COPY dh0:MyDirectory ram: Action COPY (also @{" COPY " LINK "Copy"} and @{" LVACTION COPY " LINK "LVAction"}) will check if the destination file exists and is more recent than the source. If yes, it will warn you (as is done by Dir-Opus, Windows etc) and ask you if it should proceed (with Yes, Yes to all, No etc..) COPYNEW Same as copy but will only copy files created at a later date than the destination files (if they exist). MOVE Will move the Source to the destination (or just rename them if they are on the same device). DELETE Will delete the source file or dir. You *must* give a destination. This can be anything or "NOREQ". If you state "NOREQ" you will suppress a "Delete Files ?" kind of requester that will otherwise appear. ex : Action delete Ram:t/MyDir NOREQ - Will delete dir Ram:t/MyDir, without asking you first. SIZE Here, must be the name of a variable where the total size of the File or Directory (or all dirs/files for lvaction) will be stored. ex : Action SIZE ram:t/MyDir MyVariable The sizes will be shown in the listview next to the dirs. PROTECT Protect requires that the argument be a MASK denoting the protection bits you want to set the file to. This MASK, is a 7-digit number, where each number can be a 1 or a 0, showing that you want the given bit set. Each digit represents : 1st Delete -> 1 means file can NOT be deleted, 0 it can. 2nd Execute -> Used by shell commands - set to 0 (I think) 3rd Write -> 1 = File is writable 4th Read -> 1 = File is readable 5th Archive -> 1 = File has not changed 6th Pure -> 1 = File is program that can be made resident 7th Script -> 1 = File is a script ex : Action Protect DH0:MyDir 1000000 - Protect all files in dh0:MyDir from deletion. CLI This is new with V3.0 and it allows you to execute a command recursively through a directory and all it's subdirectories, for all files found therein. There is a special internal variable called $$FILE which will be valid whenever Gui4Cli is recursing through the files of a directory. Using it you can do this (for example) : ACTION CLI MyDirectory 'search $$FILE string' and all the files within the directory and it's subdirs, will be searched. This command is very important, because it can take simple CLI commands and make them recursive - saves on a lot of code repetition.. @ENDNODE @NODE Advantages @{B}THE ADVANTAGES OF Gui4Cli@{UB} Gui4Cli is a new way of programming. It's event driven, logical, easy and interpreted (i.e. made from plain ascii files and not compiled) @{B}This gives it many advantages, such as :@{UB} 1.- The GUI is separate from the program, which means that : (a) You can have many GUIs loaded, without the programs they are meant to control being also loaded. This means less memory is used. (b) A programmer can write a program without bothering about the Wait() loops, intuition messages, resizable, font sensitive windows, workbench start-up code and all the other stuff he is supposed to do to make a GUI for his program. Just grab the command line arguments and run ! (like the good old days :) (c) The program thus written will not only be smaller, but will also be more flexible since the user can use it as he sees fit. 2.- The user can change the GUI to fit his preferences. With the new Visual Editing facility, the gui becomes completely plastic and changeable by the user at will, while it's running! This is very important because many programs fail on the functionality of their GUIs, not being as intuitive as the user would want them. A GUI is, just a way to communicate with the user, so let the user decide how he wants to be told what to do.. 3.- The user can incorporate the GUI, with other GUIs. There are many wonderful small utilities for the Amiga, which can be combined into common GUIs, as functions would in a program. 4.- With the (simple but sufficient) ARexx capability that Gui4Cli has, the user can make many different GUIs to take advantage of a program's ARexx interface (look at the CygnusEd demo). 5.- The user gets standard keyboard shortcuts and a standard working environment with every GUI. Much easier to remember. Apart from the above, Gui4Cli is also simple and stand alone. This means that anyone can use it, without programming knowledge compilers, libraries and/or patience. @{B}Some of the other Features it has, are :@{UB} - Can open unlimited resizable, windows of various types. - Can handle all Gadtools Gadgets & Menus, easily. - Visual Editing makes it *very* easy to construct guis. - Keyboard shortcuts for gadgets & menus - Can use icons as Buttons, Window background or in Menus - ARexx interface (for sending and receiving ARexx commands) - C interface (for adding new commands) - Can use different fonts for gadgets, menus and graphics. - Has Graphics commands for lines, boxes, circles etc. - Standard keyboard shortcuts which apply to all windows. - Much more.. - Give me a break.. isn't the above enough ? Apart from the above, Gui4Cli programs, being 7 bit ASCII files, can be sent through the Internet. - So what ? I hear you say. - Well.. ok, I just thought I'd mention it.. @ENDNODE @NODE All_the_Commands @{" L T W H " link "ltwh" } Values you can use. Parser Commands : @{" NewFile " link "newfile" } NewFileName @{" TextFile " link "textfile" } FileName --------------------------- GLOBAL COMMANDS ------------------------ @{" WinBig " link "winbig" } L T W H Title @{" WinSmall " link "winsmall" } L T W H @{" WinType " link "wintype" } MASK (Close|Drag|Zoom|Depth|Borderless|Backdrop|RIGHT|BOTTOM) @{" WinOut " link "winout" } ConsoleSpecification @{" WinOnWin " link "winonwin" } GuiName LeftOffset TopOffset @{" WinOnMouse " link "winonmouse" } LeftOffset TopOffset @{" Screen " link "screen" } PublicScreenName @{" WinFont " link "winfont" } FontName Size UL|BD|IT(Mask) @{" WinBackground" link "winbackground" } SOLID|PATTERN|ICON|IMAGE APen|Name BPen @{" UseTopaz " link "usetopaz" } @{" NoFontSense " link "fonts" } @{" VarPath " link "varpath" } VariableSearchPath @{" ResInfo " link "resinfo" } FontHeight ScreenWidth ScreenHeight @{" ShareMenu " link "ShareMenu" } GuiFile ------------------------------ EVENTS ------------------------------ @{" xButton " link "xButton" } L T W H Title @{" xCheckBox " link "xCheckBox" } L T W H Title Variable OnText OffText ON|OFF @{" xVSlider " link "xSlider" } L T W H Title Variable Min Max Current ShowStr @{" xHSlider " link "xSlider" } L T W H Title Variable Min Max Current ShowStr @{" xTextIn " link "xTextIn" } L T W H Title Variable StartingText Bufflength @{" xCycler " link "xCycler" } L T W H Title Variable @{" xRadio " link "xRadio" } L T W H Variable Spacing @{" xArea " link "xArea" } L T W H COMP|BOX|NONE @{" xPalette " link "xPalette" } L T W H @{" xListview " link "Listview" } L T W H Title Variable File|Dir Offset NUM|TXT|MULTI|DIR @{" LV Hooks " link "xLVHook" } LVDirHook HookID, LVHook HookID @{" xMemu " link "xMenu" } Menu Item SubItem Shortcut @{" xIcon " link "xIcon" } L T IconName (no .info) @{" xAppMenu " link "xAppMenu" } AppMenuName Variable ONOFF @{" xAppIcon " link "xAppIcon" } L T IconName Title Variable ON|OFF @{" xAppWindow " link "xAppWindow" } Variable @{" xPipe " link "xPipe" } PipeFileName ON|OFF @{" xTimer " link "xTimer" } TIME|SINGLE|REPEAT Time|Interval ON|OFF @{" xNotify " link "xNotify" } File|Dir ON|OFF @{" xHotKey " link "xHotKey" } KeyCombination ON|OFF @{" xRoutine " link "xRoutine" } RoutineName @{" xOnKey " link "xOnKey" } Letter|#KeyValue @{" xOnReturn " link "xonreturn" } LaunchID @{" xOnJump " link "xonjump" } Variable @{" System Events" link "xOnLoad_etc" } xOnLoad, xOnOpen, xOnClose, xOnQuit @{" Other Events " link "xOn_Various" } xOnActive, xOnFail, xOnDiskIn etc.. -------------------------- GRAPHIC Events ------------------------- @{" Graphics " link "graphics" } The following commands : BOX L T W H IN|OUT BUTTON|RIDGE|ICONDROP CTEXT L T Text FontName size FGpen BGpen UL|BD|IT|EMBOSS|SIZE(mask) LINE L T L T ColorNo SQUARE L T W H ColorNo FILL|NOFILL CIRCLE centerL centerT xradius yradius ColorNo FILL|NOFILL ICON L T IconName (no info) @{" Text " link "text" } L T W H Text Length BOX|NOBOX @{" Gauge " link "gauge" } L T W H IN|OUT BUTTON|RIDGE|ICONDROP APEN BPEN PERCENT @{" xTextBox " link "xTextbox" } L T W H Title Text --------------------- ATTRIBUTES & Event MODIFIERS ------------------ Gadget Modifiers : @{" GadID " link "gadid" } IDNumber @{" GadHelp " link "gadHelp" } HelpText @{" GadFont " link "gadfont" } FontName FontSize MASK(Underline|Bold|Italics) @{" GadTitle " link "gadtitle" } ABOVE|BELOW|LEFT|RIGHT @{" GadKey " link "gadkey" } Letter (or #ASCII value) @{" GadTxt " link "gadtxt" } LEFT|CENTER|RIGHT @{" LVDirHook " link "lvhook" } HookID @{" Local " link "local" } Variables/var/var... @{" Attr " link "Attr" } AttributeName Value (IMPORTANT) --------------------------- EVENT COMMANDS --------------------------- Controlling Gadgets : @{" SetGad " link "setgad" } GuiFile GadIDs ON|OFF|SHOW|HIDE (Arexx capable) @{" Update " link "update" } GuiFile GadID Value (Arexx capable) @{" ChangeArg " link "changearg" } GuiFile GadID ArgNumber NewValue @{" ChangeGad " link "changegad" } GuiFile GadID L T W H Title @{" ReDraw " link "redraw" } GuiFile @{" PartReDraw " link "Partredraw" } GuiFile L T W H @{" GadReDraw " link "Gadredraw" } GuiFile LeftGad Top Right Bottom Offset @{" ChangeIcon " link "changeicon" } GuiFile GadID L T NewIconName @{" SetAttr " link "Attr" } GuiFile/GadID AttributeName Value @{" SetGadValues " link "setgadvalues" } GuiFile Control Statements : @{" If/ElseIf/Else/Endif/And.." link "if" } Argument @{"Operator" link "operator"} Argument @{" IfExists/Else/EndIf.. " link "ifexists" } @{" SYSTEM " link "system"} Name|~Name @{" While/EndWhile/And/Or " link "while" } Argument @{"Operator" link "operator"} Argument @{" Mark/Goto " link "mark" } MarkName @{" Gosub/Return " link "gosub" } GuiName RoutineName (ARexx capable) @{" DoCase/Case/Break/EndCase " link "docase" } (DoCase) Argument - Case @{"Operator" link "operator"} Argument @{" Stop " link "stop" } --- All Commands below this line are ARexx capable ---- @{" Quit " link "quit" } DOS Commands : @{" Run, CLI " link "run" } CommandLine @{" SendRexx " link "sendrexx" } PortName CommandLine @{" Wait " link "wait" } @{" SYSTEM " link "system"} Name|~Name TimeOut @{" MakeDir " link "makedir" } DirName @{" Assign " link "assign" } Device: Path|REMOVE @{" Rename " link "rename" } OldFile NewFile @{" Launch " link "launch" } LaunchID CommandLine @{" FailAt " link "failat" } ErrorNumber Recursive commands : @{" Copy " link "copy" } FileName (with wild characters) Destination @{" Delete " link "delete" } FileName (with wild characters) @{" Action " link "action" } COPY|COPYNEW|MOVE|DELETE|SIZE|PROTECT|CLI File/Dir Destination @{" LVAction " link "lvaction" } COPY|COPYNEW|MOVE|DELETE|SIZE|PROTECT|CLI Destination Note : DOS and Recursive Commands always set the @{" $$RetCode " link "iv_retcode"} Handling GUIs : @{" Load/Open... " link "guiload" } GuiLoad GuiFullPathName - GuiOpen/GuiClose/GuiQuit GuiName @{" GuiRename " link "guirename"} OldGuiName NewGuiName @{" Status " link "status" } @{" Info " link "info" } GUI|GADGET|PALETTE|IMAGE Guiname|Guiname/GadID|ImageAlias Handling Variables : @{" SetVar " link "setvar" } Variable String (or var = string) @{" DelVar " link "delvar" } Variable @{" AppVar " link "appvar" } Variable Text @{" CutVar " link "cutvar" } SourceVar CUT|COPY CHAR|WORD|LINE Amount DestinationVar @{" Counter " link "counter" } Variable INC|DEC Amount @{" Append " link "append" } File String @{" JoinFile " link "joinfile" } Path File Variable @{" ParseVar " link "parsevar" } Variable @{" CalcVar " link "calcvar" } ResultVar Argument operator Argument @{" ReadVar " link "readvar" } FileName Start Length Variable @{" SearchVar " link "searchvar" } Variable String CI|CS FIRST|NEXT @{" RepVar " link "repvar" } Variable OldString NewString CI|CS @{" Extract " link "extract" } FromVar ITEM ToVar @{" ListView Commands " link LV_Commands } : @{" LVUse " link "LVuse" } GuiFile GadID @{" LVDel " link "LVdel" } LineNumber @{" LVPut " link "LVput" } NewText @{" LVChange " link "LVchange" } NewFromFile @{" LVSort " link "LVsort" } ASC|DSC|%FieldName @{" LVFind " link "LVfind" } String @{" LVAdd " link "LVadd" } String @{" LVInsert " link "LVinsert" } (Before)LineNumber String @{" LVClear " link "LVclear" } @{" LVSave " link "LVsave" } FileName @{" LVMove " link "LVmove" } +-Offset|#LineNumber @{" LVGo " link "LVgo" } first|next|prev|last|#LineNumber @{" LVSearch " link "LVsearch" } string CI|CS First|Next @{" LVRep " link "LVrep" } OldString NewString CI|CS @{" LVMode " link "LVmode" } NUM|TXT|MULTI|DIR @{" LVClip " link "LVclip" } CUT|COPY lines|-1 ADD|PASTE|INSERT Gui ID @{" LVSwitch " link "LVswitch" } Gui ID @{" LVMulti " link "lvmulti"} First|Next|On|Off|All|None|Show @{" LVDir " link lvdir} Parent|Root|Disks|All|None|Refresh|NoRefresh|#DirName @{" DataBase ListView Commands " link DBase_LVs } : @{" DBSum " link DBSum } ALL|SELECTED|UNSELECTED %FieldName ResultVar @{" RecSort " link RecSort } %FieldName Multimedia commands : @{" SetColor " link "setcolor" } GuiFile ColorNumber R G B @{" Palette " LINK "Palette"} LOAD|SAVE|SET|GET|REMAP Src Dest @{" Speak " link "speak"} Text @{" Images " link "images" } LOADIMAGE ImageFile Alias ScreenName|NoRemap FREEIMAGE Alias IMAGE Left Top Alias CHANGEIMAGE GuiFile GadID Left Top Alias @{" Sound Effects " link "sound" } LOADSOUND FileName Alias FREESOUND Alias PLAYSOUND Alias SETSOUND Alias VOLUME/SPEED value Various Commands : @{" SetScreen " link "setscreen"} GuiFile ScreenName @{" GuiScreen " link "guiscreen"} GuiFile FRONT|BACK @{" GuiWindow " link "guiwindow"} GuiFile ON|BIG|SMALL|FRONT|BACK|WAIT|RESUME @{" SetWinTitle " link "setwintitle" } GuiFile NewTitle @{"SetScreenTitle" link "setscreentitle" } GuiFile NewTitle @{" ReqFile " link "reqfile" } L T W H Title SAVE|LOAD|MULTI|DIR Variable DirName @{" CD " link "cd" } NewDirectoryName @{" Delay " link "delay" } Ticks @{" EZReq " link "ezreq" } Text Choices Variable @{" Say " link "say" } Text @{" Set " link "set" } [parameter] [value] @{" SetStack " link "setstack" } StackSize @{" MakeScreen " link "makescreen" } ScreenName Depth|(W/H/D/Mode) Title @{" KillScreen " link "killscreen" } ScreenName @{" TTGet " link "ttget" } FullPath/IconName (without ".info") @{" BreakTask " link "BreakTask"} TaskName CDEF(signals) @{" Flash " LINK "Flash"} @{" MoveScreen " LINK "movescreen"} GuiName/#ScreenName X Y @{" Workbench " LINK "Workbench"} Open/Close @{" SetPointer " LINK "SetPointer"} GuiName #Image/DEFAULT/HIDE @ENDNODE @NODE Append APPEND File String This command attaches the specified String to the end of the File. File - A File name String - Any character, sentence, or whatever. Example : .MyVar = "This is a " <-- Note the space Append Env:.MyVar "Test" Now .MyVar should contain "This is a Test" You can use this command to append a String to any file. @ENDNODE @NODE AppVar AppVar Variable Text This command will append the Text you provide to the Variable. If the variable does not exist it will be created. Note that you can not have a variable larger than the size of Gui4Cli's buffer (which, by default, is about 1000 characters). You can increase the buffer size if you want with the "BUFFERS" Tool Types option. OR - use an env: variable and the APPEND command. ------------------------------------------------------------------- @{b}See also :@{b} @{" Options " link Options } @{" Variables " link Variables } @ENDNODE @NODE ARexx ARexx & Gui4Cli Gui4Cli tries to be as ARexx friendly as possible. Communication between them is achieved in two ways : - Sending messages to ARexx : This is done with the @{" SendRexx " link sendrexx} command. - Sending ARexx messages to Gui4Cli : Most of the event commands of Gui4Cli are "ARexx capable" i.e. they can be sent to Gui4Cli as arexx messages and be executed as if they existed in a gui. The @{" detailed list " LINK "All_the_Commands"} of commands will show you which are ARexx capable and which are not. When sending arexx commands to Gui4Cli from an arexx program, there is a @{" global variable " LINK "Variables_Normal"} named *REXXVAR which has special meaning. You use it as you would any global variable from within Gui4Cli, but if the arexx program sending the command has declared OPTIONS RESULTS then the contents of this variable will be returned to arexx and will be available from within arexx as variable RESULT. So... SetVar "*REXXVAR" "'$mygui.gc/myvar'" ..would put whatever is in $mygui.gc/myvar into RESULT. Note the use of the quotes: one set for arexx, another for Gui4Cli (since $mygui.gc/myvar could be a string of words). Also, if you set OPTIONS RESULTS you will cause the Gui4Cli command you have sent from an ARexx program to be executed synchronously. This has the advantage of returning a result. Without OPTIONS RESULTS the execution is asynchronous. @ENDNODE @NODE Assign ASSIGN Device Path|REMOVE This is a simple command that will assign a path to a device. ex: Assign GUIs: dh0:Mydir/Gui4Cli If, instead of a Path you give the keyword "REMOVE", the assign will be removed. Multiple assigns are not implemented yet. @ENDNODE @NODE Attr ATTRIBUTES =================================================================== Attributes are a way of telling Gui4Cli various details about how you want your gadgets to look and behave. There are 2 ways in which attributes can be set : - ATTR gad modifier - used as a gadget modifier - SETATTR command - used as a normal command (like SetGad etc) The templates are as follows : - ATTR AtributeName Value - SETATTR GuiName/GadID AttributeName Value These are the attributes that can be changed (click for details) GADGET Attributes (applicable to all gadgets) - @{" RESIZE " LINK "at_resize"} (mask)LTWH - @{" TITLE " LINK "at_title"} apen/bpen/drawmode/justify/title - @{" FRAME " LINK "at_frame"} (mask)Type|Recess @{" LISTVIEW Attributes " LINK "at_lvs"} : - LVSTYLE StyleMask - DIRSTYLE StyleMask - FIELDSTYLE %FieldName/StyleMask - LVLINEDIST Pixels - LVFILTER Pattern @{" TEXTIN Attributes " LINK "at_textin"} : - TITYPE INT/FLOAT/HEX/DATE/UPPER/LOWER/STRING - TIPOS Position - TITRANS ON|OFF @{" xTEXTBOX Attributes " LINK "xTextBox"} - TBSTYLE apen/bpen/drawmode/justify - TBOX apen/bpen/bgpen/drawmode/border/recess/justify/position @{" SOUND Attributes " LINK "Sound"} - SOUND SampleAlias =================================================================== NOTE that with SETATTRIBUTE, you will probably have to redraw the gui or gadget, in order to make the change visible. This allows you to issue many SetAttribute commands and redraw once. @ENDNODE @NODE at_frame FRAME (mask)Type|Recessed This will draw a border around the given gadget. The mask is a series of 2 numbers: 1st number is type: 1=Button, 2=Ridge, 3=IconDrop 2nd number is : 0=Out(normal), 1=Recessed. @ENDNODE @NODE at_lvs Attributes for LISTVIEWs =================================================================== LVSTYLE StyleMask Will set the style for the whole listview. The StyleMask is defined as a 3 or 4 digit number, each digit meaning : 1st digit - ForeGround color (the pen number) 2nd digit - Background color (normal lines) 3rd digit - Selected Background color (selected lines) 4th digit - (optional) Color of "shadow" which will be used to give the text a 3D effect. ex : ATTR LVStyle 2031 ; set white on black 3D text DIRSTYLE StyleMask Will set the style for DIRs, VOL, ASN etc in Dir LVs FIELDSTYLE %FieldName/StyleMask Sets the style for each field. ex: SETATTR MyGui.gc 1 FieldStyle %field/2031 LVLINEDIST Pixels Will set the distance between lines in a listview. By default this distance is 0. LVFILTER Pattern Will filter the files in a dir listview according to the pattern you give - examp - make a LV hide all the icons: > SetAttr MyGui.gc/1 LVFILTER "~(#?.info)" Must for the change to actually take place. Example : @{" Run Gui " system "gui guis:docs/tutorials/FileFilter.gc"} @{" Source " link "guis:docs/tutorials/FileFilter.gc/Main"} @ENDNODE @NODE at_resize RESIZE (mask)LTWH This is an ultra cool attribute which lets you define exactly how you want a gadget to resize and reposition itself when you resize its window. The argument is a series of 4 numbers which act on the Left, Top, Width and Height of the gadget respectively and which can be a number from 0 to 3, meaning: 0 = no resize, 1 = Proportional resize (this is the Normal resize) 2 = Delta resize (add the full length change) 3 = Max resize (the sum of both (1) and (2) above) Example: xBUTTON 10 10 100 15 "My button" Attr RESIZE 0022 The above button will not move and will resize to the full increase of the window size in both width & height. @{FG shine}Example@{FG text} : @{" Run Gui " system "gui guis:docs/tutorials/Resize.gc"} @{" Source " link "guis:docs/tutorials/Resize.gc/Main"} @ENDNODE @NODE at_textin TEXTIN Attributes : These are attributes for xTEXTIN types gadgets: - TITYPE INT/FLOAT/HEX/DATE/UPPER/LOWER/STRING Will let you define what kind of data can be entered in the gadget. for example will only let you enter numbers and '.' into it. DATE will allow numbers and /.- STRING allows anything. (*** still needs work on formating ***) Example : @{" Run Gui " system "gui guis:docs/tutorials/TextIn.gc"} @{" Source " link "guis:docs/tutorials/TextIn.gc/Main"} - TITRANS ON|OFF The text in the textin gadget will, by default, be translated as soon as you've finished entering data. Set this attribute to OFF to stop translation. - TIPOS Position Will set the position of the cursor inside the textin gadget. @ENDNODE @NODE at_title TITLE apen/bpen/drawmode/XJustify/YJustify/Title With this you can add a fancy title to almost any type of gadget. It does not replace the title you may have given through the gadget's specification and which is rendered by GadTools. This title is separate and is rendered by Gui4Cli. It has many options: apen, bpen : are the color numbers of the pens that will be used to render the text. "bpen" is the shadow color. drawmode : can be : PLAIN, SHADOW or OUTLINE XJustify : can be : LEFT, CENTER, RIGHT, LSIDE or RSIDE. This determines the horizontal position of the title. LSIDE and RSIDE mean the left/right sides of the gadget, YJustify : can be : ABOVE, TOP, MIDDLE, BOTTOM, or BELOW This determines the vertical position of the title. If its TOP, and if XJustify is Left, Right or Center the title will be drawn on the gadget line. Title : is the text of the title. The left/right margins and the text position can be further refined with the @{" SET " LINK "Set"} MARGINS command. example: > xListView 10 10 100 200 '' var file 0 DIR GadID 3 Attr TITLE "2/1/SHADOW/CENTER/ABOVE/This is my title" The title can be changed by using the SETATTR command: > SetAttr MyGui.gc/3 TITLE "2/1/OUTLINE/LEFT/BELOW/I changed it!" > Redraw #this ; Must redraw to make the change visible.. @ENDNODE @NODE BreakTask BreakTask TaskName CDEF(signals) This command is usefull for stopping any programs you may have run/cli/launched. It does the same as the c:BREAK and c:STATUS commands combined. Most programs will respond to one or more CONTROL signals. There are 4 possible control signals C, D, E and F. The most common is CONTROL-C - which will stop a program executing. example : if you have started a program with : -> run 'c:search dh0:MyBankAccount OneBillionDollars' you can stop it (if the taxman walks by), by issuing : -> BreakTask c:search C You can also send multiple signals like : -> BreakTask c:search CF which would send both Control-C and Control-F signals **** IMPORTANT **** You *MUST* give the *exact* name that the program was launched under, otherwise it will not be found. i.e. : "c:search" is *not* the same as "dh0:c/search" or "search" ------------------------------------------------------------------- @{b}See also :@{b} @{" Run " link Run } @ENDNODE @NODE CalcVar CALCVAR ResultVar Argument operator Argument ******* THIS COMMAND IS OBSOLETE ********* You can use instead the @{" $(expression) " link Maths } method to do complex math calculations using flaoting point numbers etc. However, the command still works for compatibility, but it does not handle floating point numbers - it converts them to whole numbers - which may sometimes prove useful.. ****************************************** This command is a feeble attempt at giving Gui4Cli some mathematical abilities. Gui4Cli is not meant to be a programming language in the usual sense, so maths is usually not needed, still... CalcVar Result 2 + 3 - will place the number 5 into variable Result. You can also (like in the SetVar command) use : Result == 2 + 3 - which is easier to the eye. All calculations are *Integer* only! Operators are : + - * / also % (modulus) and ^ (to the power of) @ENDNODE @NODE Call CALL PortName Command Arg1 Arg2... Arg6 Gui4Cli has a special message type (something like an arexx message) which can be used by programs to help gain access to Gui4Cli's internal structure and manipulate or read them. The CALL command is used to send commands to such programs. PortName - is the name of the Public Message port of the program you want to call. Note : You must have run the program first.. Note2: PortNames are *case sensitive* Command - this would usually be one word - a command recognisable to the outside program. For convenience, this is always converted to upper case by Gui4Cli before sending the message. Arguments - up to 6 arguments can also be passed. You need to know the template of each command. When you send such a message, there may be some return value. If there is it will be in @{" internal variable " LINK "Variables_Int"} $$CALL.RET It may be a number, a word, or a sentence.. ex : run 'guis:ext/lvform' ; load the program lvuse mygui.gc 1 ; make an lv "current" call LVFORM indent "\t" ; send the lvform program the command ; to indent the current lv by a tab. say 'Ret: $$call.ret\n" ; it won't return anything.. @ENDNODE @NODE CD CD NewDirectoryName This command will change the current directory of the program. This is useful when launching programs : When you run a program, and unless specified otherwise by this command, the default directory of the program you launch will be the directory Gui (the gui launcher) resides in, i.e. c: With this command you can change the default directory before you launch the program. @ENDNODE @NODE ChangeArg CHANGEARG @{" GuiFile " LINK "GuiNames"} GadID ArgumentNumber NewValue This command enables you to dynamically change a GUI, by changing the values of a gadget, while the program is running. If you just want to change the size position or title, use CHANGEGAD instead. The gadget you want to change is specified with : GuiFile - which is the GUI program file the gadget resides in. GadID - which is the ID you have given to the gadget. If you give a GadID of "0", it means the window itself. All gadgets (and the window itself ie the WinBig command) have a number of arguments, which are counted from left to right, starting from 0. A xBUTTON, for example, has the following arguments : - xBUTTON Left Top Width Height Title Argument - Number 0 1 2 3 4 So, if you wanted to change the width of a button : > ChangeArg MyGui.gc 5 2 100 This would set the width of a button which has an ID of 5 and resides in file "MyGui.gc", to 100 pixels wide. This command has no immediate effect, unless and until the @{" ReDraw " link "redraw" } command is used. Then the window will be redrawn with this (and any other gadgets you may have changed) redrawn to their new dimensions and/or values. Example : @{" Run Gui " system "gui guis:docs/tutorials/ChangeArg.gc"} @{" Source " link "guis:docs/tutorials/ChangeArg.gc/Main"} ***** IMPORTANT **** - Be very careful with changing string arguments, such as the Title. Gui4Cli (for reasons best left untold), will only store a string which is less than or equal to the length of the existing string. So if you want to replace the title "My Button" with "My Other Button" declare the title as "My Button ", so the new title fits. NOTE that if you want changing titles you should use the @{" TITLE " LINK "at_title"} Attribute which fits all gadgets and has no such restrictions. - Fonts & Font sizes can not be changed (yet) - Menus can NOT be changed. - Icons must be changed with the @{" ChangeIcon " link "changeicon" } command. - If the GuiFile or the GadID are not found, NOTHING will happen and the user will NOT be told (unless in DEBUG mode). @ENDNODE @NODE ChangeGad CHANGEGAD GuiFile GadID Left Top Width Height Title Similar to the CHANGEARG command, but this is easier and, if you want to change more than one of the gadgets arguments, faster. Read the CHANGEARG command for more details. All the restrictions specified there, apply here as well. This command has no immediate effect, unless and until the @{" ReDraw " link "redraw" } command is used. Then the window will be redrawn with this (and any other gadgets you may have changed) redrawn to their new dimensions and/or values. You can change the size of the WINDOW also, by giving 0 as the GadID. If you give -1 for either of the Left or Top arguments, these will remain unchanged. Negative values for width & height have the same meaning as the WinBig command. Currently the Title argument is disregarded. Example : ChangeGad MyFile 2 10 20 100 20 "New Title" - will set the size of the gadget bearing a gad-ID of 2, to 100 pixels wide by 20 pixels high, position it at 10,20 and give it the "New Title" - This will all happen after you have given the REDRAW command. ChangeGad MyFile 0 -1 -1 100 200 "" - Will resize MyFile's window to 100x200 (+ any resizing you may have done) and not change it's position. @ENDNODE @NODE ChangeIcon CHANGEICON GuiFile GadID Left Top NewIcon (no .info extension) This command will change the Icon of Gadget "GadID" in file "GuiFile" to the "NewIcon" and place it at Left, Top. The effect will be immediate. You can ONLY use this command on xICON or ICON gadgets. It will have no effect on others. Icons in menus can NOT be changed. NOTHING, will happen, if the Icon is not found. You can also state "" as the icon name, to make the icon disappear. You can pass a negative value (-1) for either the Left or Top. In this case, these will remain unchanged. ------------------------------------------------------------------- @{b}See also :@{b} @{" xIcon " link xIcon } @ENDNODE @NODE Clipboard ClipBoard support @{" Listviews " LINK "ListView"} now have Clipboard support for text clips. The amiga ClipBoard is a device somewhere in ram to which you can read or write text blocks, temporarily. It's the place where text that you CUT or COPY from various editors etc is stored until it can be PASTEd somewhere by the same or some other program. (Note that some editors do not use the clipboard and so no-one else but them has access to their cut/copy/paste text blocks). As far as I know, the clipboard can have 256 such "units" numbered 0 to 255. By default the clipboard unit is No. 0 and most programs will only use this unit. This is how the clipboard is accessed from Gui4Cli : Reading the clipboard : ----------------------- If you try to load a file into the listview (either on startup or via @{" LVCHANGE " LINK "LVChange"}) then this file will be checked first and : o If the path starts with "CLIPS:" and has a clipboard unit number (0-255), Gui4Cli will read into the listview whatever happens to be in the clipboard unit specified. ex : LVCHANGE Clips:1 - will load into the lv the contents of clipboard unit 1 o Otherwise, if the file is a standard IFF FTXT clip file it will be loaded as such - i.e. only the text Writing to the clipboard : -------------------------- Again, if you try to save the contents of a listview with @{" LVSAVE " LINK "LVSave"} and if the filename path is something like CLIPS:0 then the lv contents will be written to the given clipboard unit. ex : LVSAVE Clips:3 - will save the lv contents into clipboard unit No 3 Note that if you give LVSAVE Ram:clipboards/1 (or Clips:myfile) the file will be saved normally - not as iff - and you'll confuse the hell out of everybody.. Here is a ClipBoard viewer gui : @{" Run gui " SYSTEM "gui GUIs:Docs/Tutorials/ClipView.gc"} - @{" See source " LINK "GUIs:Docs/Tutorials/ClipView.gc/MAIN"} @ENDNODE @NODE Command_Lines CONSTRUCTING COMMAND LINES ====================================================================== You can express many weird combinations of characters in Gui4Cli allowing you to form just about any string, with or without variables, non-printable characters etc.. These combinations are usefull in forming other variables or CLI command lines.. NOTE: All special characters below, should be preceded by ONE BackSlash char. Some versions of AmigaGuide will not show you the backslash unless it's preceded by another backslash, so if you're seeing double backslashes remember they should be single ones.. Special Characters : -------------------- You can use the following special characters inside command lines : \\n = (BackSlash + n) NewLine \\r = Carriage return \\t = Tab \\# = starts a character expressed as a decimal value ex : Say '\\#7' will cause the screen to flash (7 is the decimal value of the "beep" or "bell" character). Another example : ex : Say "\\#155\\1;33;40;>0mText is now color 3" will print "Text is now color 3" in your console in color 3. All text will now be in color 3, until reset. The Amiga console device has *many* such commands, with which you can output to and control a shell as you need. Any other character which is preceded by a \\ will be written literally. So, you can write : \\\\ = the BackSlash character itself \\" = the " character \\' = the ' character \\$ = the $ character \\A = character A ..... etc With the above you can do many usefull tricks such as having @{" Variables within variables " LINK "Var_in_var"} Joining variables: ------------------------ The slash "\\" character will also end a variable name. So if you wanted for example to append ".info" to a filename which you have stored in a variable, you can do this : > filename = MyFile > say "$filename\.info" will print "MyFile.info" It can also be done with the @{" AppVar " LINK "AppVar"} command.. Joining filenames: ------------------------ This can best be done with the @{" JoinFile " LINK "JoinFile"} command which will also take care of quotes, slashes etc.. Weird Stuff : ------------------------ For some reason the console device will replace $$ with nothing. So if you want to, say, send a rexx command to Gui4Cli with GRX, containing an internal variable, you must do this: > grx Gui4Cli say \\$\\$G4C.dir This will print out Gui4Cli's current dir. @ENDNODE @NODE Copy COPY File/Dir(with wildcards) DestinationFile/Dir This is a recursive command which will copy files or directories to the destination. ex: Copy dh0:myfile#? ram: or: Copy dh0:myfile ram:MyNewFile If a directory is given as destination then the file(s) will be copied into that dir. Copy (also @{" LVACTION COPY " LINK "LVAction"} and @{" ACTION COPY " LINK "Action"}) will check if the destination file exists and is more recent than the source. If yes, it will warn you (as is done by Dir-Opus, Windows etc) and ask you if it should proceed (with Yes/Yes to all/No etc..) NOTE: Since v3.8, after a HD crash I had which invalidated the damn thing, I made the COPY command (and ACTION etc) safer. Copy will now read from the source file, open the destination, seek to the end, write the buffer (about 64K), and *close* the file every time, so that the disk bitmap is written if the amiga crashes by the time the buffer is ready for the next write. @ENDNODE @NODE Counter COUNTER Variable INC|DEC Amount ++/--Variable This is a command which (INC)reases or (DEC)reases Variable by a given Amount. Example : MyVar = 20 COUNTER MyVar INC 10 The variable MyVar will now contain "30" This command is perfect for using in "DoWhile" loops, as a counter. It also has a simpler and easier form, like the C notation: ++MyVar - will increase whatever number MyVar contains by 1, or --MyVar - which will decrease it by 1. MyVar = 10 ++MyVar ; now it's 11 --MyVar ; now it's 10 MyVar must be a number for this to work. @ENDNODE @NODE CutVar CutVar SourceVar CUT|COPY CHAR|WORD|LINE Amount DestinationVar This command allows you a little control over what your variables contain. It allows you to CUT or COPY a specific AMOUNT of CHARacters, WORDs or LINEs from SourceVar and put it into DestinationVar. SourceVar - The source variable. CUT|COPY - CUT will cut the CHARacters, WORDs or LINEs from SourceVar whereas COPY will just copy them into DestinationVar, without changing the SourceVar contents. CHAR|WORD|LINE - Keywords denoting whether you want an Amount of CHARacters, WORDs or LINEs cut or copied. Amount - How many CHARacters, WORDs or LINEs to cut or copy. A Positive amount means CUT or COPY from the beginning of the variable, whereas a negative amount means from the end. DestinationVar - The destination variable to put the stuff cut or copied. example : MyVar = "This is a variable" CutVar MyVar CUT CHAR -2 MyOtherVar After these 2 lines have executed, MyVar should contain "This is a variab" and MyOtherVar should contain "le" Example gui : @{" Run Gui " system "gui guis:docs/tutorials/CutVar.gc"} @{" Source " link "guis:docs/tutorials/CutVar.gc/Main"} @ENDNODE @NODE c_control Control Statements : These control the flow of execution of your program @{" If/ElseIf/Else/Endif/And.." link "if" } Argument @{"Operator" link "operator"} Argument @{" IfExists/Else/EndIf.. " link "ifexists" } @{" SYSTEM " link "system"} Name|~Name @{" While/EndWhile/And/Or " link "while" } Argument @{"Operator" link "operator"} Argument @{" Mark/Goto " link "mark" } MarkName @{" DoCase/Case/Break/EndCase " link "docase" } (DoCase) Argument - Case @{"Operator" link "operator"} Argument @{" Stop " link "stop" } ARexx capable control statements : @{" Gosub/Return " link "gosub" } GuiName RoutineName (ARexx capable) @{" Quit " link "quit" } @ENDNODE @NODE c_dos DOS and Recursive Commands : These do the actual work - launch programs, copy files, send rexx commands and more: @{" Run, CLI " link "run" } CommandLine @{" SendRexx " link "sendrexx" } PortName CommandLine @{" Wait " link "wait" } @{" SYSTEM " link "system"} Name|~Name TimeOut @{" MakeDir " link "makedir" } DirName @{" Assign " link "assign" } Device: Path|REMOVE @{" Rename " link "rename" } OldFile NewFile @{" Launch " link "launch" } LaunchID CommandLine @{" FailAt " link "failat" } ErrorNumber Recursive commands : @{" Copy " link "copy" } FileName (with wild characters) Destination @{" Delete " link "delete" } FileName (with wild characters) @{" Action " link "action" } COPY|COPYNEW|MOVE|DELETE|SIZE|PROTECT|CLI File/Dir Destination @{" LVAction " link "lvaction" } COPY|COPYNEW|MOVE|DELETE|SIZE|PROTECT|CLI GuiFile GadID Destination Note : DOS and Recursive Commands always set the @{" $$RetCode " link "iv_retcode"} @ENDNODE @NODE c_events Events : These are what drives Gui4Cli - they are gadgets, user actions etc, which, when triggered, will start the execution of commands. @{" xButton " link "xButton" } L T W H Title @{" xCheckBox " link "xCheckBox" } L T W H Title Variable OnText OffText ON|OFF @{" xVSlider " link "xSlider" } L T W H Title Variable Min Max Current ShowStr @{" xHSlider " link "xSlider" } L T W H Title Variable Min Max Current ShowStr @{" xTextIn " link "xTextIn" } L T W H Title Variable StartingText Bufflength @{" xCycler " link "xCycler" } L T W H Title Variable @{" xRadio " link "xRadio" } L T W H Variable Spacing @{" xArea " link "xArea" } L T W H COMP|BOX|NONE @{" xPalette " link "xPalette" } L T W H @{" xListview " link "Listview" } L T W H Title Variable File|Dir Offset NUM|TXT|MULTI|DIR @{" LV Hooks " link "xLVHook" } LVDirHook HookID, LVHook HookID @{" xMemu " link "xMenu" } Menu Item SubItem Shortcut @{" xIcon " link "xIcon" } L T IconName (no .info) @{" xAppMenu " link "xAppMenu" } AppMenuName Variable ONOFF @{" xAppIcon " link "xAppIcon" } L T IconName Title Variable ON|OFF @{" xAppWindow " link "xAppWindow" } Variable @{" xPipe " link "xPipe" } PipeFileName ON|OFF @{" xTimer " link "xTimer" } TIME|SINGLE|REPEAT Time|Interval ON|OFF @{" xNotify " link "xNotify" } File|Dir ON|OFF @{" xHotKey " link "xHotKey" } KeyCombination ON|OFF @{" xRoutine " link "xRoutine" } RoutineName @{" xOnKey " link "xOnKey" } Letter|#KeyValue @{" xOnReturn " link "xonreturn" } LaunchID @{" xOnJump " link "xonjump" } Variable @{" System Events" link "xOnLoad_etc" } xOnLoad, xOnOpen, xOnClose, xOnQuit @{" Other Events " link "xOn_Various" } xOnActive, xOnFail, xOnDiskIn etc.. @ENDNODE @NODE c_gadcontrol Controlling Gadgets : These event commands can be used to control the behaviour of gadgets and guis. @{" SetGad " link "setgad" } GuiFile GadIDs ON|OFF|SHOW|HIDE (Arexx capable) @{" Update " link "update" } GuiFile GadID Value (Arexx capable) @{" ChangeArg " link "changearg" } GuiFile GadID ArgNumber NewValue @{" ChangeGad " link "changegad" } GuiFile GadID L T W H Title @{" ReDraw " link "redraw" } GuiFile @{" PartReDraw " link "Partredraw" } GuiFile L T W H @{" GadReDraw " link "Gadredraw" } GuiFile LeftGad Top Right Bottom Offset @{" ChangeIcon " link "changeicon" } GuiFile GadID L T NewIconName @{" SetAttr " link "Attr" } GuiFile/GadID AttributeName Value @{" SetGadValues " link "setgadvalues" } GuiFile @ENDNODE @NODE c_gadmod Gadget Modifiers : ======================================================================= Gadget modifiers are statements that modify the appearance or behaviour of various gadgets in some way. They can appear anywhere in the body of an event's block of statements, although it is best to put them right under the event definition, for clarity. One of the most important of these is ATTR through which many things can be set. @{" Attr " link "Attr" } AttributeName Value @{" GadID " link "gadid" } IDNumber (Important!) @{" GadHelp " link "gadHelp" } HelpText @{" GadFont " link "gadfont" } FontName FontSize MASK(Underline|Bold|Italics) @{" GadTitle " link "gadtitle" } ABOVE|BELOW|LEFT|RIGHT @{" GadKey " link "gadkey" } Letter (or #ASCII value) @{" GadTxt " link "gadtxt" } LEFT|CENTER|RIGHT @{" LVDirHook " link "lvhook" } HookID @{" Local " link "local" } Variables/var/var... @ENDNODE @NODE c_global GLOBAL COMMANDS These are usually be declared at the start of the file. They describe the general appearance and behaviour of the window: @{" WinBig " link "winbig" } L T W H Title @{" WinSmall " link "winsmall" } L T W H @{" WinType " link "wintype" } MASK (Close|Drag|Zoom|Depth|Borderless|Backdrop|RIGHT|BOTTOM) @{" WinOut " link "winout" } ConsoleSpecification @{" WinOnWin " link "winonwin" } GuiName LeftOffset TopOffset @{" WinOnMouse " link "winonmouse" } LeftOffset TopOffset @{" Screen " link "screen" } PublicScreenName @{" WinFont " link "winfont" } FontName Size UL|BD|IT(Mask) @{" WinBackground" link "winbackground" } SOLID|PATTERN|ICON|IMAGE APen|Name BPen @{" UseTopaz " link "usetopaz" } @{" NoFontSense " link "fonts" } @{" VarPath " link "varpath" } VariableSearchPath @{" ResInfo " link "resinfo" } FontHeight ScreenWidth ScreenHeight @{" ShareMenu " link "ShareMenu" } GuiFile @ENDNODE @NODE c_graphics GRAPHICS : Graphics are treated like events, with the only difference that no commands can be attached to them, since graphics can not be selected (like gadgets) so they never happen and so the commands would never be executed. However, graphics can be given a @{" GadID " LINK "GadID"} and you can @{" SETGAD " LINK "SetGad"} them (SHOW/HIDE only). Some can also be @{" Updated " LINK "Update"} Graphics that can be updated : @{" Text " link "text" } L T W H Text Length BOX|NOBOX @{" Gauge " link "gauge" } L T W H IN|OUT BUTTON|RIDGE|ICONDROP APEN BPEN PERCENT @{" xTextBox " link "xTextbox" } L T W H Title Text @{" Image " link "images" } L T Alias (update with ChangeImage) Simple graphics : @{" Graphics " link "graphics" } BOX L T W H IN|OUT CTEXT L T Text FontName size FGpen BGpen UL|BD|IT|EMBOSS|SIZE(mask) LINE L T L T ColorNo SQUARE L T W H ColorNo FILL|NOFILL CIRCLE centerL centerT xradius yradius ColorNo FILL|NOFILL ICON L T IconName (no info) @ENDNODE @NODE c_Gui ******* c:Gui *** NOTE : NEW VERSION WITH G4C 3.6 *** Gui is a "LOADER" for Gui4Cli. *ALWAYS* use it to load your GUIs or to start up Gui4Cli, as it will make sure that Gui4Cli knows your default paths, even if started from the workbench. (The code to achieve this was written by Ralph Babel and can be found in Guis:Docs/WBPath). You pass it the same options as you would pass to Gui4Cli, i.e. PORT, DEBUG, OUTPUT, BUFFERS etc - (see @{" ToolType&Options " link options } ) It will then look if Gui4Cli is already running, and if it is, it will pass it the gui's filename to load, with the options specified. Otherwise, it will start-up Gui4Cli with the filename & options given. Gui4Cli will also do the same (i.e. look for itself) but this program is much smaller and faster. GUI will look for Gui4Cli in the default path of your system and if not found there, it will look for it under GUIs:Gui4Cli. This program is now pure and can be made resident (for faster loading) by putting this command in your user-startup file : > Resident c:gui pure add It is Workbench capable, so you can put it as the default tool in your Gui4Cli program icons. If a gui script is started by clicking on it's icon, then the icon of the gui script will be read by GUI and any tool types found therein will be passed to Gui4Cli. Most of the tooltypes will not do anything if Gui4Cli is already running, but some like the PORT=NewPortName tooltype *will*, i.e. Gui4Cli will be started again under a new port name. @ENDNODE @NODE c_handle Handling GUIs : These enable you to open/close guis, get info etc. @{" Load/Open... " link "guiload" } GuiLoad GuiFullPathName - GuiOpen/GuiClose/GuiQuit GuiName @{" GuiRename " link "guirename"} OldGuiName NewGuiName @{" Status " link "status" } @{" Info " link "info" } GUI|GADGET|PALETTE|IMAGE Guiname|Guiname/GadID|ImageAlias @ENDNODE @NODE c_multimedia Multimedia : These commands deal with Sound, Images, Speach etc, hence the "Multimedia" bit.. @{" Palette " LINK "Palette"} LOAD|SAVE|SET|GET|REMAP Src Dest @{" SetColor " link "setcolor" } GuiFile ColorNumber R G B @{" Speak " link "speak"} Text @{" Images " link "images" } LOADIMAGE ImageFile Alias ScreenName|NoRemap FREEIMAGE Alias IMAGE Left Top Alias CHANGEIMAGE GuiFile GadID Left Top Alias @{" Sound Effects " link "sound" } LOADSOUND FileName Alias FREESOUND Alias PLAYSOUND Alias SETSOUND Alias VOLUME/SPEED value * GCView and GCSound ------------------- A *LOT* more can be done with the use of 2 "sister" programs to Gui4Cli, "GCView" and "GCSound", both of which can be found, together with their docs in the GUIs:ext directory. These can easily be called from Gui4Cli with the @{" Call " LINK "Call"} command. @ENDNODE @NODE c_parser Parser Commands : These are executed while the file is being loaded. @{" NewFile " link "newfile" } NewFileName @{" TextFile " link "textfile" } FileName @ENDNODE @NODE c_programs C Programmers Interface : If you can program in C, there is a special type of message that Gui4Cli understands that will enable you to interface with Gui4Cli and in effect provide extensions to Gui4Cli's command set, as follows : - From outside programs -to-> Gui4Cli a) Send message and LOCK Gui4Cli, look at it's internal structures, manipulate variables, listviews etc, and then unlock it again, and let it continue, or b) Send command lines for it to execute (like rexx msgs) - From Gui4Cli -to-> outside programs Use the new command : > @{" CALL " link "Call"} PortName Command Arg1 Arg2... Arg6 to send special Gui4Cli messages containing commands to outside programs, who should then process the commands using, if they want, any of Gui4Cli's internal structures, and give control back to Gui4Cli (maybe returning something) The place to start if you are interested is the guis:ext directory, which contains : - the @{" Gui4Cli.h " LINK "GUIs:Ext/Include/Gui4Cli.h/MAIN"} include file, showing all the internal Gui4Cli structures that you can access and - Many examples showing you all possible ways you can interface, as well as how to manipulate listviews and other internal structures. They are kept as simple as possible and are well commented. If you write any such extension binaries, I want them! @ENDNODE @NODE c_various Various Commands : These are various usefull commands : @{" SetScreen " link "setscreen"} GuiFile ScreenName @{" GuiScreen " link "guiscreen"} GuiFile FRONT|BACK @{" GuiWindow " link "guiwindow"} GuiFile ON|BIG|SMALL|FRONT|BACK|WAIT|RESUME @{" SetWinTitle " link "setwintitle" } GuiFile NewTitle @{"SetScreenTitle" link "setscreentitle" } GuiFile NewTitle @{" ReqFile " link "reqfile" } L T W H Title SAVE|LOAD|MULTI|DIR Variable DirName @{" CD " link "cd" } NewDirectoryName @{" Delay " link "delay" } Ticks @{" EZReq " link "ezreq" } Text Choices Variable @{" Say " link "say" } Text @{" Set " link "set" } [parameter] [value] @{" SetStack " link "setstack" } StackSize @{" MakeScreen " link "makescreen" } ScreenName Depth|(W/H/D/Mode) Title @{" KillScreen " link "killscreen" } ScreenName @{" TTGet " link "ttget" } FullPath/IconName (without ".info") @{" BreakTask " link "BreakTask"} TaskName CDEF(signals) @{" Flash " LINK "Flash"} @{" MoveScreen " LINK "movescreen"} GuiName/#ScreenName X Y @{" Workbench " LINK "Workbench"} Open/Close @{" SetPointer " LINK "SetPointer"} GuiName #Image/DEFAULT/HIDE @ENDNODE @NODE c_vars Handling Variables : With these commands you can manipulate variables, numbers and strings in various ways. @{" SetVar " link "setvar" } Variable String (or var = string) @{" DelVar " link "delvar" } Variable @{" AppVar " link "appvar" } Variable Text @{" CutVar " link "cutvar" } SourceVar CUT|COPY CHAR|WORD|LINE Amount DestinationVar @{" Counter " link "counter" } Variable INC|DEC Amount @{" Append " link "append" } File String @{" JoinFile " link "joinfile" } Path File Variable @{" ParseVar " link "parsevar" } Variable @{" CalcVar " link "calcvar" } ResultVar Argument operator Argument @{" ReadVar " link "readvar" } FileName Start Length Variable @{" SearchVar " link "searchvar" } Variable String CI|CS FIRST|NEXT @{" RepVar " link "repvar" } Variable OldString NewString CI|CS @{" Extract " link "extract" } FromVar ITEM ToVar @ENDNODE @NODE DBase_LVs DATABASE LISTVIEWS: --------------------- A DataBase listview is not declared through a keyword such as NUM or MULTI etc. - It is declared by loading a special type of file. Example : @{" Run Gui " system "gui guis:docs/tutorials/Dbase.gc"} @{" Source " link "guis:docs/tutorials/Dbase.gc/Main"} The file structure is simple : - It must start with the header "GCDB" - The next line must state the number of records in the file - The next line is the number of Fields - Then come the Field definitions (Name Size Type) - Then come the data - i.e. the records - which are all the same size. Their size will be equal to the length of all the fields added together. Records are separated with NewLine characters (Enter) ---------- Example file : GCDB 1 3 %number 10 N %item 30 S %price 10 N 35 This is a dummy item 15000 ---------- end of file The above file, when loaded into a listview, will be understood as a DataBase file, and the listview will become a DataBase LV. It will have 3 fields (or columns), %number, %item and %price and 1 record (the last line shown). If you thereafter load another (normal) text file, the LV will become a normal LV again. And so on.. The LV's other atributes will remain the same - i.e. if it's a MULTI or a TXT etc listview, it will remain so.. FIELDS : --------------- Each line of a Database (or Dbase) LV is called a "record" and must be the same length as all the other lines. Each record has fields which are just consecutive pieces of each record. You can think of them as columns. They are declared in the header. In the above example file, there will be 3 fields : Name Length Type Start ------- -------- ----------- ------ %number 10 N (number) 0 %item 30 S (string) 10 %price 10 N (number) 40 ------------------------------- Record is 50 characters long The 2nd field (%item), for example, starts at the 10th character (i.e. where the previous field ends) and is 30 characters long. The next field starts where this one ends. - As you see field names *MUST* start with the % character. Unlike normal variables though, they are not case-sensitive. - The "Type" definition is : N means a number S means a string - i.e. any word, words, numbers.. D date (currently treated as if it were a string) When their LV is CURRENT, fields can be used like variables : lvuse gui 1 ; use the above lv lvgo #0 ; goto the 1st record %number = 15 ; set the "%number" field to 15 %price == $%number * 3 ; do a pointless calculation.. %item = "Another item" ; change the %item field say '$%price = $%item\n' ; print out.. should print out : 15 = Another item. Each field has the value of whatever the CURRENT record of it's listview contains. So, if you added a lot of records to the above lv, you could, for example, do this : lvuse gui 1 lvgo first ; use the lv & goto top while $$lv.line > '' ; do for all records total == $%number * $%price ; calculate CURRENT record say '$%item costs $total\n' ; print info lvgo next ; get next record endwhile It is important to understand that the %fields exist ONLY when the listview in which they are defined is CURRENT. If you LVUse another listview, then they will disappear and the other listview's records (if any) will appear. COMMANDS and DBASE LVs ----------------------- There are some commands which behave differently if they are given a dbase listview to deal with. @{" LVADD " link LVAdd } string - the line added will be of "record" length i.e. as long as all the lengths of all the fields added together. @{" LVINSERT " link LVInsert } string - again, a record length line will be added. @{" LVPUT " link LVPut } string - will Overwrite the current record, without changing it's length. @{" LVSORT " link LVSort } %Field - will sort the listview according to the given field. Nice eh? In general, Gui4Cli will help you in making sure that the record lengths are kept the same. You can, however, circumvent that and trash a database listview if you handle it carelessly, so BEWARE!! - keep record lengths the same. DATABASE COMMANDS : --------------------- There are a few new commands which are specifically for DBase LVs : - @{" DBSUM " link DBSum } ALL|SELECTED|UNSELECTED %FieldName ResultVar will add the values of a certain field for all or the selected/ unselected records and put them into a variable. - @{" RECSORT " link RecSort } %FieldName will sort the current record into the current listview according to the %field given. ... that's it for now... @ENDNODE @NODE DBSum DBSUM ALL|SELECTED|UNSELECTED %FieldName ResVar This command is for DataBase listviews. It will add the fields of ALL or the SELECTED or the UNSELECTED records of the listview and place the result into ResVar. ex: ; use a listview and go to the 1st record lvuse mygui 1 lvgo first ; hide the listview for speed.. setgad mygui 1 HIDE ; unselect all records that may have been selected lvmulti NONE ; go through all records, selecting all for which the field "%amount" ; is over 1000 while $$lv.line > '' if $%amount > 1000 lvmulti ON endif lvgo next endwhile ; sum all selected records dbsum SELECTED %amount result ; print the result say 'The total of all amounts over 1000 is : $result\n' ; set the listview back on setgad mygui 1 SHOW @ENDNODE @NODE Delay DELAY ticks This command will delay all activity performed by Gui4Cli for the number of ticks you gave. One tick = 1/50th of a second. Therefore... eg : DELAY 100 will give a delay period of 2 seconds. @ENDNODE @NODE Delete DELETE FileName/Dir This deletes the file "FileName". Now delete is recursive and will also delete directories. This argument can have wildcards in it : Delete #?.bak for example, will delete all files(or directories) ending with ".bak", in the current directory. The Amiga is notorious at getting invalidated hard disks, if something goes wrong during writing or deleting a file. So be careful when deleting stuff. The FileName is translated, before being parsed for wild characters. @ENDNODE @NODE DelVar DelVar Variable Delete a variable or variables. Can use wildcards for deleting Gui4Cli variables ex : DelVar MyVar - Delete MyVar or: DelVar MyVar#? - Delete all variables starting with MyVar. You can use this command for deleting both NORMAL or ENVIRONMENT variables (env: variables have a . (full stop) as the first character) If you want to use wildcards in deleting env: variables, use the DELETE command. Nothing drastic happens if the variable does not exist. Also, nothing happens if at end of the program you do not delete all the ENV: variables that you have declared. They just remain in the ENV: directory of your ram: wasting space. The NORMAL variables will be automatically be deleted when Gui4Cli quits. @ENDNODE @NODE DirList DIRECTORY LISTVIEWS ================================================================= Example: > xListView 10 10 200 100 Title MyVar dh0:MyDir 10 DIR A Directory ListView is a listing of the files devices etc on your computer. See below for how to make it have images. A Directory Listview will not "Happen" unless double clicked upon. This is how it works : Clicking on a file or directory (single click) : ------------------------------------------------- A DIR type Listview will not "happen" when the user just clicks an item once - only when he double clicks on it. If you need to be notified everytime the user single-clicks an item you have to declare a @{" xLVHook " link xlvhook} event. Double clicking on a directory : --------------------------------- In this case, the directory will be entered into and displayed automatically. If an @{" xLVDirHook " link xlvhook} event has been declared for this gadget, it will be executed. This enables you to refresh the current LV directory name in some other part of your GUI. Double clicking on a file : --------------------------- In this case, the full path of the file will be stored into the Variable (quoted if needed), and the event commands attached to this particular ListView, executed. Reading the MultiSelected files : --------------------------------- The files which you may have multiselected can be read with the @{" LVMulti " link lvmulti} command, at any time. Images in Dir listviews : ------------------------- You can set default images to be used to precede each DEV, VOL, ASN, DIR or FILE item in Dir LVs. You just give the name of an image (which you must already have loaded with LoadImage) with > @{" SET " LINK "Set"} ImDEV/ImVOL/ImASN/ImDIR/ImFILE ImageName This can be done also from the Gui4Cli.gc gui. Note also that you can show images anywhere in listviews by stating: > this is a ESC\MyImage\ test.. (where ESC is the escape char) General : --------- In controlling DirLVs, you can also use : The @{" LVDir " link lvdir} command. The @{" LV Internal Variables " LINK "iv_listview"} @ENDNODE @NODE DoCase DOCASE, CASE, BREAK, ENDCASE ================================================================ This command structure is like a multiple IF. It lets you choose easily between more than 1 choices. The format is as follows: DOCASE Argument CASE Operator Argument (commands....) BREAK CASE Operator Argument <- you may have many case statements CASE Operator Argument (commands....) BREAK ENDCASE Example : TestVar = "TEST" DoCase $TestVar Case = "Wrong choice" Case = "Another wrong choice" Say "This is never happen\n" BREAK Case = "TEST" Say "Yes, this is the one!\n" BREAK EndCase The above should print the word "Yes, this is the one!" You can have as many case statements as you want. These are @{" OPERATOR " link "Operator"} you can use (same as IF and WHILE). You can have DoCase within DoCase etc... When docase finds a case which is true, it will start executing until it encounters an ENDCASE or a BREAK. - like in a C program This means that you can have multiple case arguments in a row (as is done above in the first 2 cases), and the code following will be executed if any one of them is true. @ENDNODE @NODE Extract EXTRACT Variable ITEM ToVariable This is a very usefull command. It will extract the given ITEM from "Variable" and place it into "ToVariable". Note that "Variable" and "ToVariable" can be the same variable. * Extractions related to files : ------------------------------ Some of the ITEMs you can extract relate to files. "Variable" must be a file (although Gui4Cli does not check if it actually exists, so you could also give a dir or a non existant file). Example: "Work:MyDir/MyPic.iff" - will extract: ROOT => Work: PATH => Work:MyDir FILE => MyFile EXT => .iff (the file extension with the dot) FULLPATH This requires that you give a file name and it will try to locate the given file in your path and return the full path and file name. If the file does not exist in your path, "ToVariable" will contain nothing (""). Example: > MyProg = "DPaint" > Extract MyProg FullPath MyProg Now $MyProg should be the full path of DPaint or "". * Extractions related to text strings : ------------------------------------- These are various things that can be extracted from text strings. Say you have a string: "This is my string " CLEAN => This is my string (will also delete the trailing spaces) UNQUOTE => This is my string (will not delete the trailing spaces) UPPER => "THIS IS MY STRING" LOWER => "this is my string" * Other ITEMs that can be extracted : ----------------------------------- GUIPATH must be given a GUI name as "Variable", and it will place the full path (without the filename) of the GUI given, into "ToVariable". This is useful for finding out in which dir your gui is in, so you can load other guis, icons etc.. See also @{" Paths " link "paths" } HEX Must be given a number in Variable and will convert it to HEXadecimal notation. OCT Same as above, but in OCTal notation. @ENDNODE @NODE EZReq - EZReq Text Choices Variable This command will put up a system requester, in the same screen as the GUI that called it, and wait for the user to click on a choice. If the window that called them is not yet open, the EZReq will open on the frontmost screen, or, if the font screen is not public, on the workbench. Text - This is the text that will appear in the requester Choices - These are the choices which will appear as buttons in the requester. The format for specifying them is to separate the choices with | characters i.e.: "Quit|Cancel" will supply you with 2 choices: "Quit" and "Cancel" Variable - Will contain the number of the requester button chosen: The Right most button (which will usually be CANCEL) will put a 0 into Variable. The other choices will put the number of the button, reading from left to right. Example: EZReq "Quit?" "Abort|Quit|Exit|Cancel" MyVar - will make a requester with 4 buttons, which will place the following values into Variable, if they are clicked : Abort = 1, Quit = 2, Exit = 3, Cancel = 0. @ENDNODE @NODE FailAt FAILAT ErrorNumber When you use CLI (without run) and other commands, you get a "return code" ($$RETCODE) when whatever you did with this command finishes executing. This return code is stored in the internal variable $$RETCODE. If this return code is equal or more than the ErrorNumber you have set with the FAILAT command, then Gui4Cli will stop execution immediately, and return to the waiting for something to happen. The default value for ErrorNumber is 10, which most programs return if a pretty serious (but not fatal) error occurs. You can set this to 20 for example, if you do not want anything but a very serious error interrupting your CLI commands. (or 1000 for kamikaze pilots) You can also declare an event type xONFAIL (see "Other Events"), whose commands will be executed if such an error occurs. This command eliminates the need for constantly checking $$RETCODE to see if an error occurred, before proceeding to other commands. $$RETCODE is reset to 0, after such an error. @ENDNODE @NODE Flash FLASH Will flash the screen, indicating an error. Don't flash all over the place, it can get tiring.. @ENDNODE @NODE Fonts FONT COMMANDS : In the Font Commands below, there are two very important keywords you can use, instead of actual font names : #MONO - specifies the user's preferred MONOSPACE font #SCREEN - specifies the user's prefferre SCREEN font which will usually be PROPORTIONAL. Use these instead of actual font names where ever possible, since they will change as per the user's preferences. There are various FONT commands you can use : Globals : --------------------- WINFONT - will set a default font for all the gadgets which have no GADFONT declared. - it is the default window font. USETOPAZ - This command will force Gui4Cli to disregard all fonts declared and use topaz 8 instead. Event specific : --------------------- GADFONT - This, attached to a Gadget will define the font for that gadget. If none of the above commands are declared, then the SCREEN font will be used. Gui4Cli comes also with a Graphic font, courtesy of G.Maddox. It has arrows, disk images, smileys etc.. and you can easily use it as text in buttons. Also see @{" Font Sensitivity " link Font_Sensing } @ENDNODE @NODE Font_Sensing FONT SENSITIVITY : Gui4Cli is Font Sensitive! Well, ok.. not so much font-sensitive as font-aware.. (font-respectful ?.. font-give-a-damn ?..) You can turn this feature off with the NOFONTSENSE global command. What it does, is the following : - On opening the GUIs window, it will check to see if the text, using the default window font, will fit into the respective gadget, and if not, it will enlarge the window and resize the gadgets, so that the text does fit. The following restrictions apply (for now) : - Only xBUTTON, xCYCLER, TEXT and xTEXTIN gadgets will be checked and even then, only when no GADFONT command has been declared for them. Other gadgets, such as sliders etc do not have text in them, and others, such as listviews, are self-adjusting, so no action is taken on their behalf. This means that if you do not have any of these gadgets in your GUI, the GUI will not adjust itself. - Resizing is done only to increase the GUI's size. - Currently, width is not checked - (tried it and didn't like it..) The width is resized proportionally to the height. NOTES ON DESIGNING GUIs : The Left & Top sizes you declare will be offsets INSIDE the window. Do not account for the window border, it will be added automatically. If you want to make a GUI which other people might use, it is best to make it so it looks good using TOPAZ 8 font, on a High-Res, Non-Interlaced screen. Then Gui4Cli can resize the window for a bigger font, if needed. Use the #MONO and #SCREEN keywords instead of actual font names whereever possible, since they denote the users preferred monospace and screen (proportional) font. Buttons, Text and Cycler type gadget heights will be resized to the font-height + 2 pixels, whereas xTEXTIN type gadgets will be resized to font-height + 5 pixels. - So make the xTEXTIN gads a little taller. @ENDNODE @NODE GadFont GADFONT FontName FontSize MASK(Underline|Bold|Italics) Gadget text is drawn in the default font, or the font declared by the WinFont command. You can, however, have a different font for every gadget. This is the command that does it. The MASK is a 3 number string (see the WinType command) 1st Number : Underline ? - 1=Yes, 0=NO 2nd Number : Bold 3rd Number : Italic e.g. GadFont times.font 11 010 This defines Bold 11 point times font For a font name, it is always best to use the #MONO or #SCREEN keywords. You can find more on them @{" Here " link fonts} With Dir Listviews specially, you want to use the #MONO font, since you want the filename etc lined up and a proportional font would look ugly.. @ENDNODE @NODE GadHelp GADHELP HelpText This gadget provides on line help. > xButton 10 10 60 12 MyButton GadHelp "This is some help text" Now, if the on-line help system is on, whenever the mouse pointer hovers over this button (could have been any gadget) the text declared will be shown in the TitleBar of the Screen the gui is open on. To set HELP on/off you can either: - Press the HELP key, or - Use the command SET HELP ON|OFF See also the @{" xONHELP " LINK "xOnHelp"} event, with which you get much greater control over where, how and when you want show the help text. @ENDNODE @NODE GadID GADID IDNumber This command assigns IDNumber to the gadget you attach it to. > XButton 10 10 100 10 "Example" > GadID 10 The IDNumber is used by other commands to reference the gadget. You need not give a GadID to a gadget if you are not going to change it. Other commands will usually reference the Gadget as follows : > Update GuiName GadID Value In the above example, GuiName is the name of the file that the gadget resides in and the GadID is the ID you have given it. In this way, you can SetGad, Update etc any gadget, in any GUI. Note that you can give the same GadID to many gadgets. This is useful if you want to, say, setgad lots of gadgets on/off all together. --------------------------------------------------------------- @{b}See also :@{b} @{" LVHook " link LVHook } @{" LVUse " link LVUse } @{" SetGad " link SetGad } @ENDNODE @NODE GadKey GADKEY Letter This is to assign a short cut to a gadget. The effect of the short cut varies with different gadgets. If you can not express the letter, you can assign it with its decimal ASCII value by putting a "#" character in front of it. GadKey #13 for example is ENTER IMPORTANT : Note that you may also assign a short cut to a gadget by specifying it in it's Title. All you do is put an _ (underscore) character before the letter in the Title that you want as a short cut. The letter will be underscored when the gadget is drawn. example : xBUTTON 10 15 80 15 "Hit _Me" <- here the M is underscored and becomes the button's keyboard shortcut. To avoid confusion, the underscore method takes precedence over the GadKey command, if both are used on the same gadget. Example : @{" Run Gui " system "gui guis:docs/tutorials/GadMods.gc"} @{" Source " link "guis:docs/tutorials/GadMods.gc/Main"} @ENDNODE @NODE GadRedraw GADREDRAW GuiName LeftGad TopGad RightGad BottomGad OFFSET This provides the most accurate redrawing. It works like @{" PartRedraw " LINK "PartRedraw"} but instead of actual positions for Left, Top, Width, Height, you give the GadIDs of the gadgets whose borders will be used to calculate the area to erase. This provides better precision. > GadRedraw mygui.gc 10 11 12 13 1 If "10" is, for example, the GadID of a button, the position of the button's Left edge will be used as the left edge of the rectangle to be erased. OFFSET is a number that these sizes will be shifted by. So, in the above example, where OFFSET=1, the erase rectangle will fall one pixel inside of the left edge of the button's border, and accordingly for all other gadgets too. and OFFSET of -1 will Erase from 1 pixel outside the borders. @ENDNODE @NODE GadTitle GADTITLE ABOVE|BELOW|LEFT|RIGHT Usually the titles of the gadgets are placed to their left. With this command you can change this : GadTitle ABOVE ..for example will put the title above the gadget. Example : @{" Run Gui " system "gui guis:docs/tutorials/GadMods.gc"} @{" Source " link "guis:docs/tutorials/GadMods.gc/Main"} @ENDNODE @NODE GadTxt GadTXT LEFT|CENTER|RIGHT This command will only work on a TEXT type gadget. It will justify the text of the gadget on the LEFT, CENTER or the RIGHT side of the gadget box. Example : @{" Run Gui " system "gui guis:docs/tutorials/GadMods.gc"} @{" Source " link "guis:docs/tutorials/GadMods.gc/Main"} @ENDNODE @NODE Gauge GAUGE L T W H IN|OUT BUTTON|RIDGE|ICONDROP APEN BPEN PERCENT It's one of those pretty little thingies which show you how far you have progressed in some action. A Gauge is not actually an event, since it can not be selected with your mouse, so it will never "happen". If you attach commands to it, they will never be executed. You can however, give it a GADID and UPDATE it at any time. The arguments are the same as for a BOX except for APEN = the number of the foreground color, BPEN = background color PERCENT = the starting percentage. Example : @{" Run Gui " system "gui guis:docs/tutorials/Gauge.gc"} @{" Source " link "guis:docs/tutorials/Gauge.gc/Main"} @ENDNODE @NODE GoSub GOSUB GuiName Routine RETURN ================================================================ A Routine is an Event declared with @{" xROUTINE " link xroutine} and is a bunch of commands that can be called and executed from another event. GOSUB is the command that does this. You can GOSUB to routines of your or any other GUI files. GuiName : Is the name of the GUI in which the xROUTINE exists. Note that if the GUI is not loaded, the routine will NOT be executed, and the User will NOT be told. Routine : The name of the routine to execute GOSUB can also take up to 6 @{" Arguments " link Passing_args} and pass them to the routine it calls, as internal variables $$ARG.0 to 5 RETURN is used in xRoutines and it stops execution and returns to the GOSUB statement that called the routine and continues execution with the command following the GOSUB. RETURN can also be used in xONLOAD etc type events and can *also* take up to 6 arguments, which it returns to the calling GoSub, Guiload etc. as internal variables $$RET.0 to 5 Example : @{" Run Gui " system "gui guis:docs/tutorials/GoSub.gc"} @{" Source " link "guis:docs/tutorials/GoSub.gc/Main"} @ENDNODE @NODE Graphics GRAPHICS =========================================================================== These are the graphics commands that you can use to tart-up your GUI. They are treated in every way as if they were normal events, like buttons etc, but since they can not be selected, they never "happen" so no commands can be attached to them. Example : @{" Run Gui " system "gui guis:docs/tutorials/Graphics.gc"} @{" Source " link "guis:docs/tutorials/Graphics.gc/Main"} You can, however, give them a GadID, like normal Events, and SetGad or ChangeGad them, redrawing them to new positions. BOX L T W H IN|OUT BUTTON|RIDGE|ICONDROP Draw a beveled box of size L T W H. IN means that the box will be recessed, OUT means the opposite. You can have 3 types of boxes : BUTTON, RIDGE or ICONDROP. These have different border types - try them out. CTEXT L T Text FontName size FGpen BGpen UL|BD|IT|EMBOSS|SIZE(Mask) Draw colored text, starting at (L)eft, (T)op. (New with V3.2 is that you can add a "Shading" or 3D effect) Text = The text to be drawn FontName = the font to use (ex: topaz.font or #MONO or #SCREEN) Size = The size of the font FGpen = Foreground pen number BGpen = Background pen number (-1 means leave the background alone) Mask = This is a mask (see the WinType command for explanation) Digit 1 = Undelined (1=yes, 0=no) Digit 2 = Bold Digit 3 = Italic Digit 4 = The color number you want to use for "shading" Digit 5 = The offset of the shade (defaults to 1) Example : CTEXT 10 30 "Test text" times.font 11 2 -1 01032 LINE X Y x y ColorNo Draw a line from X,Y to x,y, of ColorNo color. SQUARE X Y x y ColorNo FILL|NOFILL Draw a square from X,Y to x,y, of color ColorNo. FILL means filled - NOFILL means that only an outline is drawn. CIRCLE centerL centerT xradius yradius ColorNo FILL|NOFILL Draw a circle at centreL, centerT, with the respective radii. FILL it or NOFILL it with ColorNo color. ICON Left Top IconName Display icon as image at Left, Top. The only difference from the xIcon event, is that this is not clickable. @ENDNODE @NODE GuiEdit VISUAL EDITING =============================================================== Gui4Cli GUIs can be edited while they are running. This is done by using the CONTROL key together with the mouse : Moving Gadgets : Press CONTROL-MouseClick on a Gadget or Graphic to Select it. You will see that an outline of the gadget is drawn. You can now let go of the CONTROL button and move the gadget outline around in your window. When you are satisfied with the new position, just click the mouse and the gadget/graphic will be redrawn to this new position. You can also use CONTROL-H instead of CONTROL-MouseClick to select a gadget, and CONTROL-H again to place it where you want. This comes in handy if : (a) you are running programs like CycleToMenu etc which may interfere with your mouse clicks, or (b) you are trying to paste some gadget over another gadget in which case GadTools may eat-up the mouse clicks. There is also a GRID available, which makes lining up the gadgets much easier. By default the grid size is 1 which means "no grid". You can set the grid size to any size you want, with "SET GRID 5" (5 is a good size..) - or through the Prefs gui. Resizing Gadgets : You can resize a gadget by clicking on it's bottom right corner. Note that some gadgets (such as ICONs, Images, xICONs and CTEXT) can not be resized. Also note that to resize a listview you have to click on the listview's bottom right corner - *not* on the arrow buttons (unless you use control-h). Since LVs adjust their size automatically to show as many lines as possible, they may be a little difficult to select correctly for resizing.. Resizing the window : You can enlarge or reduce the window size by resizing the window while holding down the CONTROL key. In this case, the window is resized, while the gadget sizes/positions remain the same. Cloning gadgets : After selecting a gadget you can "clone" it (i.e. make a copy) by using the CONTROL-J shortcut. In this case a copy of the gadget will be created and drawn where the mouse is at. Note that *only* the gadget information is copied. The gadgets modifiers and it's commands are *not* copied. Inter-GUI Cloning : After selecting a gadget you can also place it in another Gui4Cli window. In this case a copy of the gadget will be created and drawn into the window where you clicked. This enables you to make new guis by copying gadgets from other guis - in effect, a gui editor. Here also, *only* the gadget information is copied. Deleting gadgets : You can delete a gadget or graphic by selecting it and pressing the DELETE key. Saving your GUIs : Once you have made the GUI of your dreams, you can save it by pressing CONTROL-G. A simple requester will ask you if you want to save the gui. IMPORTANT notes on saving : - NEVER - load a gui, then change it's file by manually editing it and then edit & save the gui. To keep all your file notes etc in tact, Gui4Cli remembers the line numbers of the gadgets when the file is loaded, and then, when saving, it goes and changes only these lines, leaving everything else untouched. So if you have meanwhile changed the gui manually the gadget line numbers will have changed and ... well you're looking for trouble, that's what! Same will happen if you visually edited the file before and added 1 or more xCYCLER or xRADIO type gadgets. Since these need extra lines to describe the fields they'll have, it throws the whole numbering scheme off if you try to save the gui again without having reloaded it first. Hitting CONTROL-R to reload the gui (if you have changed it manually or have added cycler/radio gads) *before* starting to visually edit it, will reload and thereby refresh the correct line numbers etc. Gui4Cli will check and tell you if it doesn't find the edited gadget where it should be in the file. - BE VERY CAREFUL when saving multi-gui files, if you are trying to edit more than one of the file's guis at the same time. Reloading the gui will *not* refresh the gadget line numbers of the other guis, since only the active gui is reloaded.. If you must edit many guis of a multi-gui file at the same time, then reload *all* the file's guis everytime you save any one of them. - If you have deleted existing gadgets, then the lines of the original GUI describing the gadget and all it's attached commands will be commented (i.e. a ; will be added in front) This will be done for all the lines following the gadget, until the next gadget is declared, or the end of file is reached. - If you have created new gadgets, these will be added at the bottom of the GUI file. If it's a multi-gui file, then at the end of the given gui within the file. - Any RESIZE_BIG/RESIZE_SMALL commands that the gui file may contain will be commented out and the gui will be saved at it's current size. Quirks : - Circles are selected by clicking on their lower right quarter. - Boxes (even filled ones) are selected by clicking on their border. You have to click *exactly* on a pixel on their border. - TextIn gads (and maybe some others) will give you a little trouble if you try to paste them over themselves (i.e. move them a tiny bit. Try to pick them up from their edges.. Final word : Visual editing is very helpful for creating and setting up a gui just the way you want it. However, a gui will do nothing unless you tell it what to do - this can only be achieved by actually programming them. So Press CONTROL-E and get on with it.. Example : @{" Run Gui " system "gui guis:docs/tutorials/VisEd.gc"} @{" Source " link "guis:docs/tutorials/VisEd.gc/Main"} @ENDNODE @NODE GuiLoad GuiLoad GuiFullPathName GuiOpen @{" GuiName " LINK "GuiNames"} GuiClose GuiName GuiQuit GuiName These commands load,open,close and unload(quit) GUIs. When loading a GUI, you have to give the GUIs full path, i.e. : GuiLoad GUIs:MyGUIS/ThisGui.gc Thereafter, the GUIs are referred to by the file name only, i.e. : GuiOpen ThisGui.gc (or GuiOpen #This) When opening/closing etc the GUIs, the respective events : @{" xOnLoad, xOnOpen, xOnClose and xOnQuit " link xOnLoad_etc } are executed, if defined. Starting with V3.2, these commands can also take @{" Arguments " link Passing_Args } This ability makes them very powerfull, allowing for function-type guis which can be called at will. (see guis:tools/rtn) ***** IMPORTANT note about GuiQuit : When an GuiQuit is encountered, the file which has been instructed to quit is marked as such and the execution of the commands continues uninterrupted. When all the commands have executed, then Gui4Cli looks around to see if there are any files marked for deletion, and deletes (unloads) them. So, if you want a gui to quit immediately, you have to issue a STOP command after the GuiQuit command : Guiquit mygui.gc Stop ; more commands here.. otherwise the commands following GuiQuit *will* be executed, and the file will be unloaded afterwards.. @ENDNODE @NODE GuiNames @{U}Using Gui names :@{UU} You will only ever need to give a gui's full path when you first load it with : > GuiLoad dh0:mypath/mygui.gc Note that if the gui is in the same directory as the gui from where you issue the GuiLoad command, you can : > GuiLoad :mygui.gc and the path will be automatically substituted for the ':' Thereafter you can refer to the gui with only it's name: > GuiOpen mygui.gc If the command you issue exists in the same file as the gui it wants to act upon, the you can use the "#This" keyword: > GuiOpen #This meaning - open the gui in which this command is located. This indirection is very usefull in many cases, such as when you want to change the gui name and do not want to change the GuiName in all the commands in the file. It gives you more independent code, which is always good. If you want to load the same gui many times, you can also play around with the @{" GuiRename " LINK "GuiRename"} command. @ENDNODE @NODE GuiRename GUIRENAME OldGuiName NewGuiName This renames a GUI. It is useful in many instances, for example if you want to load many copies of a certain GUI, or reloading a GUI in the middle of a command sequence, like so : GuiRename MyGui MyGui2 ; Reload a GUI GuiLoad MyGui GuiQuit MyGui2 Be careful though.. A renamed GUI has no file, so you can't edit it, or save the resize BIG|SMALL commands into it. @{FG shine}Example :@{FG text} @{" Run Gui " system "gui guis:docs/tutorials/GuiRename.gc"} @{" Source " link "guis:docs/tutorials/GuiRename.gc/Main"} @ENDNODE @NODE GuiScreen GUISCREEN GuiFile FRONT|BACK This will bring the screen that the GuiFile is open on, to the FRONT or move it to the BACK. No action will be taken if the GUI is not open. You can also give the ScreenName directly, by putting a # char in front : GuiScreen #Workbench Front will bring the workbench to the front. Note that screen names are case-sensitive. @ENDNODE @NODE GuiWindow GUIWINDOW GuiFile ON|BIG|SMALL|FRONT|BACK|WAIT|RESUME With this command you can do various things to a GUI. ON - will activate the GUI BIG - will zoom the GUI to its WinBig size (if it was small) SMALL - will zoom the GUI to its small size FRONT - bring the GUI to the front (also done by double-clicking on the window) BACK - Move GUI to the back of other windows. WAIT - Will change the pointer to the default wait pointer and disable any user input into the GUI. RESUME - will break the WAIT above. WAIT and RESUME are usefull for when you launch a command, or do something which will take some time. You can set the gui to wait so that you don't have to worry about the user clicking buttons while he's waiting. @ENDNODE @NODE If IF Argument @{" OPERATOR " link "operator"} Argument ELSEIF, ELSE, ENDIF AND, OR ================================================================ This is the standard If/Else/EndIf stuff, common in any computer language. The way to use it, is to think logically. var = 1 IF $var = 2 OR $var = 3 say 'var = 2 or 3\n' ELSEIF $var = 5 AND $var = 1 say 'var = 1 and 5\n' ELSEIF $var = 1 say 'var = 1 - correct\n' ELSE say 'don't know..\n' ENDIF The above should print out 'var = 1 - correct' Rules of the game : - In any if construct, you MUST start with IF and end with ENDIF. - In between you may use only one ELSE - You can have as many ELSEIF's as you want - only the commands attached to the 1st ELSEIF which satisfies the criteria will be executed. - You can have many AND or OR statements - these MUST follow exactly after an IF or ELSEIF or ELSE. - You can have if within if within if constructs, up to 126 levels. If you don't understand how it works, run gui4cli in debug mode. (Press control-D) This will show you what it's doing. The Arguments can be strings, or numbers or variables. Note that if you want to compare a variable you MUST place a $ character in front of it (to indicate that you mean the *contents* of the variable). See the OPERATOR explanation to see what operators you can use. IF (as well as WHILE etc) is smart enough to understand the comparison of Numbers. So if you compare : IF 2 > 10 ...the answer will be FALSE, since 2 is less than 10, although if they were compared strictly as strings 2 would be more that 10. IF can also be replaced by the @{" IFEXISTS " LINK "IfExists"} command. This has different arguments (see its explanation), but otherwise replaces IF in every way. IMPORTANT : The most common mistake I make when writing GUIs is this : If variable = 10 <- This compares 10 to the name of the variable instead of : If $variable = 10 <- Correct. Compares 10 to the contents of "variable" Example : @{" Run Gui " system "gui guis:docs/tutorials/IfTest.gc"} @{" Source " link "guis:docs/tutorials/IfTest.gc/Main"} @ENDNODE @NODE IfExists IFEXISTS @{" SYSTEM " link "system"} NAME|~NAME ElseIfExists, Else, EndIf AndIfExists, OrIfExists This command works exactly the same as the "IF" command, but with different arguments. Look at the if command to understand it. It lets you see if various things such as PORT, FILE, DEVICE etc.. exist in your system, or not. Example : TestVar = "MyWindow" IfExists WINDOW $TestVar Say "My Window is open." Else Say "My Window is closed" EndIf You can also use a negative form to check if something does *not* exist, by puting a ~ character in front of the item you're looking for : IfExists PORT ~AREXX ; Port AREXX doesn't exist run 'RexxMast' endif @ENDNODE @NODE Images IMAGES (pictures, brushes, JPGs etc) Images can be used, via the datatypes.library (OS V39+ only) They are handled differently from icons, so that memory is saved. You first load an image and give it a "Alias" (i.e. any name you want, to which you can thereafter refer). Then you can use it in many guis, as a background or as an Image, without having to load another copy of it. When you're done, you unload it.. Image Commands : -------------------- o LoadImage ImageFile Alias ScreenName|NoRemap will load the ImageFile, call it the Alias you gave and if you give a screen name, the image will be remapped to that screen's colors. If "NoRemap" is given, the image will not be remapped. o FreeImage Alias will unload a previously loaded image. If you don't unload your images they will be automatically freed when Gui4Cli quits. o ChangeImage GuiFile GadID Left Top Alias will change the specified picture, to the "Alias" named picture which must have already been loaded. L T of -1 means position unchanged. The IMAGE Event : --------------------- o IMAGE Left Top Alias will place the (already loaded) picture at the position specified. L T of -1 means center in window. Note that no commands can be attached to this event, since it is not selectable and does not "happen". You can, however, give it an ID and use "ChangeImage" on it to show an other image. You can also SHOW or HIDE it with the @{" SETGAD " link SetGad } and @{" REDRAW " link Redraw } commands. If you want to be able to select an image, or any part of it (if you need an image map for example), you can use the @{" xAREA " link xArea } Event and overlay invisible gadgets on the image where ever you want it to be clickable. - You can get some information on images via it's @{" internal vars " LINK "iv_image"}. - You can change palettes etc, with the @{" Palette " LINK "Palette"} command @{FG shine}Example :@{FG text} @{" Run Gui " system "gui guis:docs/tutorials/ShowPic.gc"} @{" Source " link "guis:docs/tutorials/ShowPic.gc/Main"} How to use images --------------------- Apart from displaying an image somewhere with the IMAGE event you can also use them as follows : o Embed them in @{" listviews " LINK "ListView"} by stating the image Alias in the text as follows : ESC\\Image\\ (ie Escape-BackSlash-ImageName-Backslash) o A special case of the above is the images used in Directory Listviews, which you can set with the @{" Set " LINK "Set"} command. o As pointers, with the @{" SetPointer " LINK "SetPointer"} command o As background for windows, with the @{" WinBackGround " LINK "WinBackGround"}Command. Example : G4C WinBig -1 -1 200 100 "Test.gc" ; declare the Alias of the image you want as a background WinBackground IMAGE MyPicure "" xOnLoad ; here, load the image, so that when the window opens and ; tries to use the image for it's background, it will find ; it already loaded and ready. LoadImage Ram:MyImage.iff MyPicture Workbench ; now open the window.. GuiOpen Test.gc xOnQuit ; on quiting, unload the image (unless you need it elsewhere) FreeImage MyPicture @ENDNODE @NODE Important_Topics @{B}* T h i n g s y o u s h o u l d k n o w :@{UB} @{" Variables " link "variables"} Must read. @{" Internal Variables List " link Variables_IntList} Must read. @{" Keyboard Shortcuts " link "winshortcuts"} Very usefull shortcuts. @{" Passing Arguments " link "Passing_Args"} Pass args to routines & guis @{" Translation " link "translation"} Interpretation of arguments @{" Making Commands Lines " link "Command_Lines"} Tricks & tips of forming commands @{" C Programs interface " link "c_programs"} Talk to Gui4Cli & add new commands @{" DataBase Listviews " link "DBase_LVs"} Columns, Fields etc @{" Mathematical Calculations " link Maths } Floats & functions @{" Using the Clipboard " link "Clipboard"} How to Load/Save clips. @{" ARexx " link "arexx"} How to talk to ARexx @{" Finding Paths " link "paths"} Make GUIs run from anywhere. @{" Resizable Windows " link "resize"} How to make Guis resizable. @{" Gui Names " link "guinames"} Using #This @{" Fonts " link "fonts" } Fonts & Font commands. @{" Font Sensitivity " link Font_Sensing } Font Sensing @{" Thigs you can wait for " link System } @{" Operators " link Operator } + - * / and others.. @{" The SET command " link set } Some important commands you @{" Attributes " link attr } might miss... @{" Extract " link extract } ------------------------------------------------------------ @{B}@{U}Writing Programs:@{UU}@{UB} In Gui4Cli, commands can not span lines. A line can be 1000 characters long (you can increase this with the SET BUFFERS command) A ";" character ends the line (unless it is inside a quoted string), and you may place comments or anything else after it. A "parser" is computer-jargon for that part of the program that reads your program file and tries to make sense out of it. The parser, in this case, is pretty simple-minded. It's designed to be as fast as possible - not as intuitive as possible. Do not try to confuse it because you probably will. When you write commands, separate each argument with a space or a comma. IF $Variable= 10 <- is NOT correct. IF $Variable=10 <- is NOT correct. IF $Variable = 10 <- IS correct. @{B}@{U}Use of Quotes:@{UU}@{UB} A string which starts with " ends with a " and if it starts with a ' it ends with another ' If you load files and put them in a variable, and if these files contain a space they will be quoted e.g. "Ram Disk:MyFile" So, if your arguments are likely to contain such quoted strings, it is vital that you use single quotes ' to surround each argument. @{B}@{U}Debugging :@{UU}@{UB} When writing a GUI, apart from the DEBUG mode (which you can activate with Control-D), there are 2 other useful keys: Control E - will run "c:ed" loading the GUI for editing. (can be changed to any name with the @{" SET " LINK "Set"} command) Control R - will Re-Load the active GUI. These will make editing much easier, especially for seeing the positions of the gadgets and graphics. @ENDNODE @NODE Info INFO ITEM ARGUMENT This command will cause the given ITEM to become the CURRENT one. This is used with @{" internal variables " link Variables_IntList } which will reflect the values of CURRENT gadgets or other items. Gadgets will automatically become CURRENT when clicked upon. With this command however, you can make any other gadget the current one, if you need the internal variables to reflect its values. All other items will become current only if specifically chosen with this command. The ITEMs you can use INFO on, and their ARGUMENTs are : @{" GUI " LINK "iv_window"} GuiName Will select another gui. The WIN & @{" SCREEN " LINK "iv_screen"} int vars Will show you that gui's values. @{" GADGET " LINK "iv_gadget"} GuiName/GadID Will select another gadget and make it "current" Example: Info Gadget MyGui.gc/2 Note - For Listview specific variables, like @{" $$LV.LINE " LINK "iv_listview"} etc, you must use the @{" LVUse " LINK "LVUse"} command - not INFO - Info will only change the $$GAD.soandso variables. @{" PALETTE " LINK "iv_palette"} GuiName/GadID Select another palette gadget Example: Info Palette MyGui.gc/2 Note - Again, this is for the palette specific internal variables only, such as $$PAL.colors @{" IMAGE " LINK "iv_image"} Alias Will select another image (for the image specific intvars). @{" FILE " LINK "iv_file"} FileName Will select a file (give full path), so you can get info on it, such as size etc.. @{" VARIABLE" LINK "iv_var"} VariableName Select a given variable, so you can get its length.. @ENDNODE @NODE Introduction INTRODUCTION & BASICS ------------------------- A Graphical User Interface (GUI), is the Buttons, Cyclers, Sliders, Menus and all the other gadgets you play with when using a program. Gui4Cli is a program which enables anyone to write such a GUI and from it, issue CLI or ARexx commands to other programs. What you do, is write a script in the Gui4Cli programming language, (which is very easy) and just run it! How it works : -------------- Gui4Cli is and Event-Driven language. This means that it reacts to various events, such as the clicking of a gadget by the user, or a command to close the window etc. Events can be Gadgets, Menus, AppMenuItems, User Actions etc. A GUI program is a series of such events, defined by the programmer, and attached to these events are commands that are executed each time the event "happens" Gui4Cli relies heavily on the use of Variables. Variables are temporary storage places where you can place any sentence or sentences (strings). You can think of them as little files. These Variables are referenced as follows : MyVar - is the name of a variable called MyVar (case sensitive) $MyVar - is the contents of a variable called MyVar Example : > MyVar = "DPaint" ; This stores "DPaint" into variable MyVar > Say $MyVar Gui4Cli will actually execute : > Say DPaint We will call this process @{" Translation " link "translation"} (because I don't know what else to call it) This translation is done on ALL the arguments of ALL the Event Commands, making Gui4Cli very flexible. Using this Translation method, Gui4Cli is able to provide a GUI that will form any CLI or ARexx command and run it. For example, a Cycler (that's the gadget which looks like a button with a bent arrow at one end and when you click on it it changes the text displayed on the button), is declared in the following way: xCYCLER 100 12 100 15 "This is a cycler" CyclerFile CSTR "DPaint" "DH0:Dpaint/Dpaint" CSTR "PlaySound" "DH0:Music/Playsound" CSTR "LightWave" "DH0:MyDir/MyOtherDir/LightWave" This declares a CYCLER type gadget (or EVENT), with it's top left corner at position 100,12 (pixels) of your window, 100 pixels long, and 15 pixels high. The title next to the CYCLER will be "This is a cycler", and the name of the Variable that it will put it's value in will be "CyclerFile". This CYCLER will have 3 choices : Dpaint, PlaySound and LightWave. Every time you click on the CYCLER, the text shown above next to each of the choices will be placed in the Variable "CycleFile". So, if you click on the CYCLER several times and at the end the choice displayed is "PlaySound", then the Variable CyclerFile will contain the words "DH0:Music/Playsound". Now, say you declare a BUTTON gadget as follows : xBUTTON 10 30 100 15 "RUN" CLI 'Run >NIL: $CyclerFile' This declares a BUTTON at position 10,30, 100 pixels wide and 15 pixels high, with the text on it. Attached to this Gadget, is the Gui4Cli command "CLI", which means run whatever is declared after it as if it were typed at a shell. If you hit this button, the command that will actually be performed will be : Run >NIL: DH0:Music/Playsound Using other gadgets, you can declare other variables, such as the File name you want loaded (with file requesters), the program's Cli options (with checkboxes or cyclers), the volume/rate etc (with sliders), and have a command line like : Run >NIL: DH0:Music/Playsound MyFile Volume=64 Option1 Option2 etc... This, in effect, provides a GUI for Cli based programs. This, is the simplest way in which Gui4Cli can be used. There are many other uses it can be put to, as you will see in the Demos. In the above example for the BUTTON gadget, we "attached" the command to the BUTTON gadget or EVENT. There are many such commands which can be attached to all types of Events, forming small programs which are executed every time the the user makes the Event happen (i.e. clicks on the gadget, chooses the menu, closes the window, deactivates the window... etc). These are called "EVENT COMMANDS" and provide control of what you want to achieve (with commands such as if/endif, gosub/return, while/endwhile etc), the ability to perform Cli commands, send ARexx messages, tell other Gui4Cli windows to open or close and more. Apart from the EVENTS and their EVENT COMMANDS there are also GLOBAL COMMANDS, which control the size of your window, which screen it opens on etc. and GRAPHICS COMMANDS which allow you to draw lines, boxes, circles, color text etc, in order to give your GUI a nicer appearance. Simple Example : @{" Run Gui " system "gui guis:docs/tutorials/Buttons.gc"} @{" Source " link "guis:docs/tutorials/Buttons.gc/Main"} The best way to learn how to make a GUI yourself, is to look at the @{" tutorials " system "gui guis:docs/tutorials.gc"} (which are plain ASCII files with Gui4Cli commands in them) and which are commented. Feel free to change them and try them out to see what happens. If you make a mistake, Gui4Cli will tell you what line and what type the mistake was. There is also a DEBUG option that can be used, which shows you what commands Gui4Cli performs every time you click on a Gadget or choose a Menu, making it easier to work out the logic of your program. @ENDNODE @NODE iv_file FILE variables ============================================================= To get these variables to show you valid information, you must first choose a file with the @{" Info " LINK "Info"} command : > Info FILE DH0:Mydir/MyFile $$FILE.LENGTH - file length $$FILE.BLOCKS - The number of blocks it occupies $$FILE.DATE - date it was last changed $$FILE.DAY - day last changed $$FILE.TIME - time last changed $$FILE.TYPE - either DIR or FILE $$FILE.COMMENT - file comment (if any) @ENDNODE @NODE iv_g4c These are the system internal variables, which are valid all the time. G4C.PORT Gui4Cli's port name (normally Gui4Cli) G4C.VERSION Gui4Cli version number => version 3.0 = 30 G4C.BUFFERS The buffer size - (see the @{" Set " LINK "Set"} command) G4C.LOADED No of guis loaded G4C.OPEN number of guis whose window is currently open G4C.DIR current directory G4C.FAIL current failat level G4C.DEFSCREEN The screen name which all guis get (default = '*') G4C.OUTPUT The default console output spec G4C.FILEPATTERN The default ASL requester file pattern G4C.EDITOR The default editor name (c:Ed) G4C.GUIPATTERN The dafault gui extension (#?.gc - for the requester) G4C.GUILOADDIR The dir that the G4C load requester will open at G4C.TAB The current tab setting (default=8) G4C.GRID The current grid size G4C.LVFILL 1=Draw the listview fill-in box at bottom, 0=don't G4C.NOVOL 1=Do not show volumes in device list, 0=Show them G4C.MARGINS Returns 3 numbers "SideMargin TopMargin OffSet" G4C.TBMARGINS Returns 2 numbers (xTextBox margins) "Horz Vert" G4C.LVSORT 0=Normal, 1=Date, 2=Ssize, 3=Extension @ENDNODE @NODE iv_gadget GADGETS ================================================================ Made current upon being clicked upon or by being chosen with the @{" INFO " LINK "Info"} command. These vars are valid for all types of gadgets. GAD.L gadget left edge (from the outer edge of the window) GAD.T gadget top edge '' GAD.IL gadget left edge (from the inner edge of the window) GAD.IT gadget top edge '' GAD.W gadget width GAD.H gadget height GAD.GUI gui file name gadget resides in GAD.TYPE type of gadget (i.e. XBUTTON, XLISTVIEW etc) GAD.ID gadget's ID GAD.VAR the name of the variable the gadget will store it's value in. GAD.VALUE gadget's value (varies - same value as you would give with the update command) @ENDNODE @NODE iv_gadkey --------------------------- KEY CODES --------------------------- These are the codes & qualifiers of the last key pressed. You can learn what code each key has, by setting DEBUG ON (in the new debug mode) and pressing any key. RAWKEY.CODE code of last raw key (arrow, help F1-F10) pressed RAWKEY.QUAL it's qualifier (i.e. if key was shifted, alt etc) VANKEY.CODE code of last vanilla key pressed (except control-key) VANKEY.QUAL it's qualifier VANKEY.LETTER the letter of the key pressed @ENDNODE @NODE iv_image ---------------------------- IMAGES ----------------------------- Images can not "happen" so they become current *only* by being chosen with the info command. These are their internal variables : IMAGE.W current image's width IMAGE.H height IMAGE.DEPTH depth in bitplanes IMAGE.COLORS number of colors (as per bitplanes) @ENDNODE @NODE iv_listview ---------------------------- LISTVIEWS ----------------------------- Listviews are special. They are made current upon being clicked on, or upon being specifically chosen with the LVUSE command. All types of Listviews have lines. The vars $$LV.LINE, $$LV.TYPE and $$LV.REC, refer to the CURRENT LINE, which is the line that was last clicked on or the line that was last acted upon with something like an LVMULTI, LVSEARCH, LVFIND or LVGO command. Each Listview keeps track of it's own current line, so you can have many listviews and use the LVUSE command to switch between them. The current line of each listview will be remembered when you get back to it (with an LvMulti-next command, for example). LV.LINE Current line No (or "" for no current line) LV.REC The text of the current line LV.TYPE Type of current line (DEV,VOL,ASN,DIR,FILE,NONE) LV.SEL = 1 if line is selected, 0 if not LV.MODE What the mode of the lv is (NUM,TXT,MULTI,DIR) LV.DIR (for directory LVs) The current directory LV.TOTAL The total number of lines the lv has LV.GUI the LV's gui name LV.ID the LV's ID (or 0 for no ID declared) LV.VAR the (full path of) the name of the listview variable. eg: mygui.gc/myvar Note that in Gui4Cli the number 0 is a valid number (like in C) The first line of a listview is line number 0. So if there is no current line you will get a "" i.e. nothing (not 0) example : lvuse mygui 1 ; make LV No 1 in mygui, "current" lvgo first ; go to the first record (no 0) say 'Line = $$LV.LINE\n' ; will print : Line = 0 while $$LV.LINE > "" ; while line is more than nothing.. say '$$LV.REC\n' ; print the text of the current line lvgo next ; go to the next line endwhile The above will print out all the lines in a listview. @ENDNODE @NODE iv_mem MEMORY information These variables show you the current memory information. $$MEM.CHIP - the remaining chip memory $$MEM.FAST - the remaining fast memory $$MEM.ALL - all the remaining memory $$MEM.CLARGE - largest chip memory block $$MEM.FLARGE - largest fast mem block The last 2 are a little slow to get the info. @ENDNODE @NODE iv_mouse ---------------------------- MOUSE --------------------------- These values show you the mouse data when the mouse was last clicked on (while any Gui4Cli window was active). MOUSE.X mouse x position in screen MOUSE.Y mouse y position MOUSE.WX x position inside currently active window MOUSE.WY y position inside currently active window MOUSE.COLOR Color number of pixel at mouse position @ENDNODE @NODE iv_obsolete OBSOLETE VARIABLES These are the old variables names which you shouldn't use anymore, although they still work, for compatibility. They have their new equivalents. LOADED_GUIS OPEN_GUIS LASTLV CURRENT_DIR @ENDNODE @NODE iv_palette ---------------------------- PALETTES ----------------------------- A palette is made current by being clicked on or chosen with info. COLOR.R Palette's chosen color - red value COLOR.G green COLOR.B blue COLOR.NUMBER chosen color number COLOR.TOTAL total number of colors @ENDNODE @NODE iv_parsevar ---------------------------- PARSEVAR --------------------------- These variables become valid after calling the ParseVar command. They will remain valid throughout the life of G4C, until an other parsevar command is issued. PARSE.n ex: $$PARSE.0, $$PARSE.1 etc, are words No 0, 1, etc respectively. Note the first word is No 0. PARSE.TOTAL The total number of words parsed. (Maximum is 30) @ENDNODE @NODE iv_rand Random number generator $$RAND.xxx Will supply you a random number from 0 to "xxx". ex: > $$Rand.100 - will give you a random number from 0 to 100. Note that if you wanted a range of 1-100, you would have to do > x = $($$rand.99 + 1) You can also use a variable as the last part. This must be a simple variable - i.e. no variable paths, vars within vars etc. Ex: > var = 100 > number = $$RAND.$var The function used to generate the number is SAS's drand48() which generates the number using a linear congruential algorithm and 48bit arithmetic... I don't know what it means, but it sure sounds good :) @ENDNODE @NODE iv_retcode $$RetCode There are certain commands which set the $$RETCODE. This tells you the "return code" of the command, i.e. whether the command succeeded or failed. Usually a 0 means success. RetCode will be valid for recursive Gui4Cli commands such as copy etc, as well as ARexx commands given with SendRexx. Also, if you issue a CLI command you can afterwards check the $$RETCODE, to see if the command was successful. Example : CLI 'c:copy Myfile to ram:myfile' if $$RETCODE = 0 say "File copied" else say "Error during copy" endif The $$retcode will only make sence in CLI commands which are not "run >nil:" because otherwise it will tell you if the "run" commmand succeeded and not the command itself.. See also @{" $$RexxRet " LINK "iv_rexxret"} @ENDNODE @NODE iv_rexxret $$RexxRet If you send ARexx commands with SendRexx or otherwise, there may be a value returned by the program to which you sent the command. If so, then an internal variable named $$REXXRET will contain this value (RESULT_2) Usually programs don't return anything though.. See also @{" $$RetCode " LINK "iv_retcode"} @ENDNODE @NODE iv_screen ---------------------------- SCREENS ----------------------------- These values show you the data of the screen that the current gui is (or will) open on. While the current gui is usually the active one this can be changed with the info command. So, you can see any public screen's data by say, making a dummy gui and setscreening it to the screen you want (don't open it), and then choosing it with the info command. SCREEN.W screen width SCREEN.H screen height SCREEN.BAR screen's title bar height SCREEN.NAME screen's name SCREEN.DEPTH number of bitplanes of screen's bitmap SCREEN.COLORS number of colors screen can show @ENDNODE @NODE iv_search --------------------------- SEARCHVAR --------------------------- These variables show the results from the @{" SearchVar " LINK "SearchVar"} or @{" LVSearch " LINK "LVSearch"} commands : SEARCH.POS contains the number of the character where the string found begins (the 1st character is 0) or "" if nothing was found. SEARCH.LENGTH is the total length of the variable. @ENDNODE @NODE iv_system SYS internal variables These try to tell you some things about the amiga system: @{B}========= >>> Time & date@{UB} $$SYS.TIME - the current time (ex: 10:30:25 - hh:mm:ss) $$SYS.TS - the seconds part of the above time (i.e. 25) $$SYS.TM - the minutes part (i.e. 30) $$SYS.TH - the Hours part (i.e. 10) $$SYS.DATE - the date (see below for formats) - following available *only* for dd-mm-yy (CDN) format: $$SYS.DD - the Day part of the above date $$SYS.DM - the month part $$SYS.DY - the year part $$SYS.DAY - the day of the week (i.e. Monday) By default the date format is DD-MM-YY (15-07-98) You can change this with the SET command : > SET DATEFORMAT number - where number can be: 0 = DOS format -> dd-mmm-yy (15-Apr-98) 1 = INT format -> yy-mm-dd 2 = USA format -> mm-dd-yy 3 = CDN format -> dd-mm-yy (default) NOTE : the $$SYS.DD/DM/DY vars expect that the day is 1st, the month 2nd etc. If you use the USA mode for example, the $$SYS.DD will contain the month. With DOS format all hell breaks loose.. @{B}========= >>> Screens & windows@{UB} $$SYS.AW - will give you the title of the Active Window. Any window.. not just a Gui4Cli window $$SYS.AS - will give the active screen title $$SYS.ASN - Active Screen Name (if it's a public screen) $$SYS.FS - Frontmost Screen Title $$SYS.FSN - Frontmost Screen Name (if it's public) - Screens : Note that, if you need other data for a screen (width etc) you can do this : .temp = "G4C\nScreen MyScreenName\n" ; create a temp gui GuiLoad env:.temp ; load it info gui .temp ; make it "current" ; now all the $$SCR.xx vars will show you this screen's info delete env:.temp ; be tidy :) @ENDNODE @NODE iv_textin xTextIn Internal variables : These vars give you information on the latest xTEXTIN gadget to have been made current. $$TI.POS - the cursor position in the current textin gadget $$TI.LENGTH - total length of string in the gadget $$TI.REC - the string in the gadget $$TI.ID - the ID of the gadget $$TI.GUI - the name of the gui it's in @ENDNODE @NODE iv_var VARIABLEs A variable can be chosen with the INFO command: > Info Variable myvar The only available internal var at present, is: $$VAR.LENGTH - length of variable (in characters) @ENDNODE @NODE iv_window ---------------------------- WINDOWS ----------------------------- These are the values of the currently active window, or of the window you have specifically chosen with the @{" INFO " link info} command WIN.L current window's left edge in screen WIN.T top edge WIN.W external width (i.e. full window) WIN.H external height WIN.IW internal width (i.e. inside window) WIN.IH internal height WIN.SCREEN name of window's screen WIN.NAME name of gui file WIN.PATH the path of the gui file @ENDNODE @NODE JoinFile JOINFILE Path File Variable Will join the path to the file and place it into Variable. It's there to make life easier when dealing with paths or filename which contain spaces in them. Path and File are STRINGS not Variables. ex: path = "Ram Disk:" JoinFile $path MyFile Var Say '$Var\n' will print out "Ram Disk:MyFile" @ENDNODE @NODE KillScreen KILLSCREEN ScreenName This command will delete the screen "ScreenName". ScreenName IS case-sensitive. IMPORTANT : 1.- All windows must be closed before the screen can close. If they are not, you will be notified with an EasyRequester. 2.- Gui4Cli will try to close the Public Screen you tell it. It will NOT check if this screen has been opened by Gui4Cli. Becarefull, therefore, not to close a screen of another program !! You can check if the screen closed, with the IFEXISTS command. @ENDNODE @NODE Launch LAUNCH LaunchID CommandLine This is a command that allows multitasking to take place within Gui4Cli itself. Thanks to Michael Van Elst for the help. Some programs (like c:search for example) take a long time to finish their work. You need however to know when they are finished, so that you can display their results, or go on to another command. In this case you can not use RUN, because Gui4Cli would run the program and return to whatever it was doing and you wouldn't know when the program you ran had finished it's work. If you use the CLI command, then Gui4Cli would start the command and sit around waiting for it to finish, thereby blocking all other operations. In these cases, you can use LAUNCH. LAUNCH will create a new process which will run the command, thereby freeing Gui4Cli to do something else.. When the command finishes executing, it will return to a @{" xONRETURN " link xonreturn} event with the same LaunchID and do the commands declared there. (unless the ESCAPE key has meanwhile been pressed by the user) example : xButton 10 10 100 15 "Click Me!" Launch 1 'c:search dh0:PlanetEarth IntelligentLife' ; now Gui4Cli is free to continue with other commands etc xOnReturn 1 Say 'The Search has finished\nNo Intelligent Life found..' ; just kidding... @ENDNODE @NODE Licence BUGS : ------------------ Many mosquitoes, some cockroaches, but hopefully no tarantulas. Gui4Cli is (in my experience) a stable program and it is difficult to crash it (I earnestly hope). As of version 3.6 I have caught all enforcer hits I could find (about 10 of them) and various bugs that came up when I recompiled it with SAS 6.58. So it should be quite clean. However, since I mostly program the binary instead of making GUIs for it, there are and will forever continue to be minor errors, unless and until someone tells me about them. If something doesn't seem to work correctly, use the DEBUG option to see what the program is doing and if you see a fault, please tell me. Also if you see enforcer hits... you know.. Licence to use Gui4Cli : -------------------------- The program Gui4Cli, the concept, the language and the logic it uses as well as any and all other aspects of Gui4Cli are the copyright (c) of Dimitris C. Keletsekis. All rights are reserved. Commercial usage is forbidden, without the prior written consent of the Author. Use of the program is at your own risk. No warranty is made or implied. Permission to use this program in Magazine cover disks, Aminet CDs or Fish Cds, is hereby granted. A small charge for copying the program, is allowed. @{B}For personal use, this program FREEWARE.@{UB} There are no rules for the GUIs you make and may want to distribute. Do with them as you like. You may include Gui4Cli in your distribution, but make sure that you also include c:gui and you state clearly in your documentation where the latest version of Gui4Cli can be found. Latest versions of this package can always be found : - on AmiNet, under Dev/Gui/Gui4Cli.lha, or - at my web page, http://users.hol.gr/~dck/gcmain.htm Contacting the Author ---------------------- Gui4Cli is my first attempt at writing a computer language. I hope it doesn't show too much. Writing the manual was absolutely the worst part and I hope it shows. In general, Gui4Cli is just a matter of reading in arguments given by you, the user, and passing them to the Amiga OS, which has all these commands and many more, built into it's amazing ROM. The windows, gadgets, menus and all the other stuff, the Amiga does itself, as it has been doing since before mud was invented, so get down on your knees and thank the Lord for the fact that such a computer, made for people who love and not just use computers, still exists. You can contact me by mail or Email at the following address : AUTHOR : D. Keletsekis 14 King George Str. Athens 10674 Greece. EMail : dck@hol.gr <- Preferred. @{B}Additional Code by :@{UB} - Michael Van Elst, who wrote the code for the window backfill routines, the Launch command and who generally helped me understand the Amiga better. @{B}Thanks to:@{UB} - Graham Maddox for lots of great GUIs, a beautiful new graphic font and many bug reports. - John Collett, for writing the tutorials, various guis, and for the bug reports and encouragement. @ENDNODE @NODE ListView LISTVIEWS ============================================================== Listviews are very powerfull gadgets. They can take many forms and have many @{" dedicated commands " link LV_Commands }. This is their template : > xLISTVIEW L T W H Title Variable File|Dir Offset Mode where : Title : is a string that will be placed to the left (by default) of the listview. Usually you'll give a "" i.e. no title. Variable : is the variable where the lv's value will be stored. This "value" varies according to the type of listview: DIR type LVs will store the file name you clicked on. NUM type LVs will store the number of the line. All other types will store the text of the line. File|Dir : This argument is the name of the file that the LV should load. When Gui4Cli loads your gui, it will look for this file, and if it finds it, it will load it. Listviews will display any kind of file, text or binary. There is one special kind of text file though that will be interpreted as a @{" DataBase " link DBase_LVs } file. This allows you the use of %fields and other neat stuff. You can create a file on the fly if you want, with the TextFile command. The file can be changed any time with the LVChange command. For DIR type LVs this argument is the name of the directory the LV should open on. You can therafter change this with the @{" LVDir " link LVDir } command. Offset : LVs can be shifted right/left by clicking on the left or right quarter of the gadget. This "Offset" argument specifies the number of characters it should shift. You can set a 0 value, to disable this feature. Also, Gui4Cli will automatically move the CURRENT LV if you use the arrow keys: - Up/Down/Left/Right arrows - normal movement - Control key + arrows - Fast movement - Shift + arrows - go to top,bottom,left,right of document. Mode : The mode can be NUM, TXT, SHOW, MULTI, or DIR. This argument defines the LV's type. Listviews come in 3 basic types, according to the last keyword you use : Normal : (NUM or TXT or SHOW) ------------------------------- The normal listview is a single-select simple listing of a file. Example : @{" Run Gui " system "gui guis:docs/tutorials/ListViews.gc"} @{" Source " link "guis:docs/tutorials/ListViews.gc/Main"} > xListView 10 10 200 100 ListView Var dh0:MyFile 10 TXT This is a listview which will show the file "dh0:myfile" and when clicked upon, the Text (TXT or SHOW) of the line you clicked on will be placed into the "Var" variable. If you had given the NUM keyword (instead of TXT or SHOW) then the line number of the line would have been stored into the variable. The difference between TXT and SHOW, is that SHOW will show you the selected item i.e. the line clicked on will remain highlighted, until an other line line is clicked. Multi-Listviews : (MULTI) ------------------------- Example : @{" Run Gui " system "gui guis:docs/tutorials/ListViews2.gc"} @{" Source " link "guis:docs/tutorials/ListViews2.gc/Main"} This is how a multi-select listview is defined : > xListView 10 10 200 100 ListView Var dh0:MyFile 10 MULTI (i.e. change the last keyword) - This kind allows you to make multiple selections and read them afterwards. This listView will only "Happen" if the user double-clicks on an item - then this will be stored into the variable. You can "read" the selected items at any time. See the Directory ListView explanation - they both work in the same way. Directory Listviews : (DIR) --------------------------- Example : @{" Run Gui " system "gui guis:docs/tutorials/ListViews3.gc"} @{" Source " link "guis:docs/tutorials/ListViews3.gc/Main"} These are File/Dir listers and this is how to get them : > xListView 10 10 200 100 ListView Var dh0:MyDirectory 10 DIR These types have more dedicated commands and need more @{" explanation " link DirList }. DataBase Listviews: ------------------- NUM,TXT,SHOW and MULTI listviews can also load a special type of file which will make them into @{" DataBase Listviews " link DBase_LVs }. Database listviews allow you the use of Fields and other goodies. Understanding ListViews & their Commands : ------------------------------------------ Listviews have the following @{" dedicated commands " link LV_Commands} Listviews are governed by the notion of CURRENT LISTVIEW and CURRENT LINE (of the current listview). The CURRENT LISTVIEW is the one on which all listview commands will act on. A ListView becomes current when the user clicks on it. All listview commands executed thereafter will refer to that Listview. The Current ListView can be changed with : > LVUSE GuiFile GadID Now, all commands will use the specified listview. Each listview is made up of a number of lines (or "records"). Commands that act on individual lines (like LVPUT) will act on the CURRENT LINE of the listview. The current line is the line that the user last clicked upon, but that can also be changed to any line you want with the LVGO command. More over, commands like LVSEARCH, LVADD etc will change the CURRENT LINE to the line they return or add etc. The @{" internal variables " LINK "iv_listview"} $$LV.LINE, $$LV.REC and $$LV.TYPE will always show you what the CURRENT LINE of the CURRENT LISTVIEW is. Each listview will keep track of it's own CURRENT LINE, and remember it throughout it's life. COLORED TEXT IN LISTIVIEWS : ---------------------------- Starting with V3.2, listviews will interpret ANSI sequences such as "\#27[32mText is now white", and render text in colors or bold italics etc. Example : @{" Run Gui " system "gui guis:docs/tutorials/LVStyles.gc"} @{" Source " link "guis:docs/tutorials/LVStyles.gc/Main"} And it was a real bitch to get it right, too... IMAGES IN LISTVIEWS : --------------------- You can show images anywhere in a listview by stating in the text, at the place you want the image to appear: > this is a ESC\\MyImage\\ test.. (ie Escape-BackSlash-ImageName-Backslash) (where ESC is the escape char and MyImage is the image's alias) ie you embed the image name with ESC\ on one side and \ again at the end. Note that the image must already be loaded with the @{" LoadImage " LINK "Images"} command. Note also that an image can be the height of the line - no more. If its heigher it will be clipped. You can increase the line height with the LVLINEDIST attribute. LISTVIEW @{" ATTRIBUTES " LINK "Attr"} : ----------------------- You can change various things about a listview, using @{" Attributes " LINK "at_lvs"}. RESIZING Listviews : -------------------- xLISTVIEW gadgets do not resize properly, because gadtools insists on limiting their height to a multiple of the font height. I have added a drawing routine which will fill in the remmaining space at the bottom with a beveled box. This can be disabled globally with: @{" SET " LINK "Set"} LVFILL OFF @ENDNODE @NODE Local LOCAL var1/var2/var3... This command allows the use of @{" LOCAL " link Variables_Normal } variables, i.e. variables which are visible only inside a given event. This is usefull for small throw-away variables. You declare them within the body of an event, separating them by slashes, and they will not be visible or accessible to any other event. Example : xButton 10 10 60 12 'test' Local a/b ; declare 2 local variables a = 3 ; use them normally, together with other vars.. b == $a * $var ; they will not be visible outside this event You can hit CONTROL-V for a full listing of all variables used at any time. @ENDNODE @NODE LTWH L T W H -> (L)eftEdge, (T)opEdge, (W)idth, (H)eight These 4 values are the sizes you declare for windows, gadgets & ASL requesters. Apart from normal numbers, you can also use the following numbers, which have special meaning : L = LeftEdge - if L is a negative value : - If used with a window or requester, then these will be centered horizontally on the screen. - If used with a gadget, then the gadget will be centered horizontally in it's window. T = TopEdge - if T is a negative value : - If used with a window or requester, then these will be centered vertically on the screen. - If used with a gadget, then the gadget will be centered vertically in it's window. NOTE : The Left & Top sizes you declare will be offsets INSIDE the window. Do not account for the window border, it will be added automatically. W = Width - if W is less than or equal to 0, then : - If used with a window or requester, their width will be the SCREEN WIDTH minus this number i.e. -1 will make a window 1 pixel smaller than the screen size, and if 0 it will be screen sized. - If used with a gadget, the width of the gadget will be the width of it's window minus this number. H = Height - if H is less than or equal to 0, then : - If used with a window or requester, their height will be the SCREEN Height minus this number - If used with a gadget, the height of the gadget will be the height of it's window minus this number. The only case where the above does not apply, is to the WinSmall command - look at it to see the meanings. @ENDNODE @NODE LVAction LVACTION This command is practically the same as the @{" ACTION " link action } command. See it for more information. The difference is that ALL SELECTED Files and/or Directories of the CURRENT listview will be operated on. The "CURRENT" listview is the one you choose with the @{" LVUse " LINK "LVUse"} command. All needed updating of the listview will be done automatically. With the SIZE action, the dir sizes will be displayed next to their names as they are being processed. Makes life a lot easier in dealing with dir listviews.. @ENDNODE @NODE LVAdd LVADD String Add a new line (or record) to the current listview. The current record will become the line added. If the listview is a @{" DataBase " link DBase_LVs }, then the line added will be as long as all the other records, whatever length the string may be. @ENDNODE @NODE LVChange LVCHANGE NewFromFile Load another file into the CURRENT ListView. The current record will be reset to 0 - i.e. the top line. @ENDNODE @NODE LVClear LVCLEAR Clear the listview. All records will be deleted and the current line will be "" i.e. nothing. @ENDNODE @NODE LVClip Duch Changed - LVClip CUT|COPY lines|-1 ADD|PASTE|INSERT gui ID Will CUT or COPY the amount of lines specified starting at the current record from the current LV () and ADD or PASTE or INSERT them into the destination LV given . It will do the same for all lines, starting at the currentline till the end of the LV, if -1is given : example : lvuse MyGui.gc 1 ; make an lv "current" lvgo #10 ; goto the 10th line lvclip CUT 5 ADD MyGui.gc 2 ; cut lines 10-14 from lv No.1 and ; add them to lv No.2 If we used INSERT, the lines would be inserted after the current record of lv No.2 - which you must have previously gone to. If the destination lv is not found, or if you give "" as the dest gui, LVClip will go ahead and execute the first part, i.e. CUT|COPY lines from the source lv - this is a easy way of deleting many records from a lv : lvclip cut 10 add "" 0 ; will delete 10 lines from the current lv. lvgo #12 lvclip cut -1 add "" 0 ; will delete lines 12 till end of lv. @ENDNODE @NODE LVColors LVCOLORS GuiFile GadID ForeGround BackGround Selected Dirs This is a gadget modifier and will set the colors of the listview to which it is attached : ForeGround is the color the normal text is drawn in Background is the background Selected is the background color of the selected items Dirs is the color of the directories in DirListViews The defaults are : LVColors MyGui GadID 1 0 3 2 This command has been superceeded by the @{" Attr " link Attr } modifier, although it still works. @ENDNODE @NODE LVDel LVDEL LineNumber (or -1 for current line) Will delete the line with the line number given, or, if -1 is given, the current line the LV is at. IMPORTANT : if the current line is deleted then the previous line becomes the current one, unless it's the first line in the listview, whereby the new top line becomes the current line. @ENDNODE @NODE LVDir LVDir Parent|Root|Disks|All|None|Refresh|NoRefresh#DirName This will do one of the following things to the CURRENT Dir Listview: Parent Will change the directory to the parent directory Root Will change to the Root dir. Disks Will change to the Device List All Will select all the files or dirs None Will clear all selections NoRefresh - This takes some explanation : The DirListView, loads the files it finds on your computer, and then places them as strings in the listview. Thereafter it acts like a normal multiselect listview. Now, if you were to e.g. delete some files and not refresh the listview accordingly, the files shown would be wrong, so any further actions on them would result in errors... Gui4Cli will automatically check and if there is any change in the directory, it will ABORT all commands, and instead re-read the current directory. (Don't I think of everything...) If though you have correctly deleted all entries in the listview according to the files you actually deleted, then you can give this command, so as to stop this automatic refreshing. Refresh Will reload the current directory. #DirName Give this, to change to a specific directory. ex : LVDir #DF0:MyDir @ENDNODE @NODE LVFind LVFIND String This command is a little weird.. It's for sorted LVs and it will find the line containing the String and visually move the ListView to it. If the line is not found, it will stop at the closest alphabetic match to the line. The @{" internal variables " link Variables_Int } $$lv.line, $$lv.rec etc will tell you the line found. @ENDNODE @NODE LVGo LVGO first|next|prev|last|#LineNumber This command will change the current record of the LV *without* visually moving it. The arguments you can use are : First go to the top record (Number 0) Last go to the last record Prev go to the previous record Next go to the next record #Number go to given record number (top = 0) For example - the following code will print out the LV's contents: LVUse MyGui 1 ; use LV No1 in MyGui LVGo first ; goto the 1st record while $$lv.line > '' ; while there are records (or lines) say '$$lv.rec\n' ; print the line LVGo next ; go to next record endwhile ; end of while loop say 'Boy.. that was easy!\n' ; superfluous comment :) @ENDNODE @NODE LVHook LVDIRHOOK HookID - only for directory & multi listviews ---- YOU NO LONGER HAVE TO DECLARE THIS MODIFIER. --- If you do not declare it, the HookID will be the same as the GadID if this gadget. The HookID is a number of a @{" XLVDirHook " link xlvhook} event which will be executed every time you change directories, or in an xLVHOOK The Directory ListView will show you the file list, but it will not show you what directory you are in.. You have to do this yourself, using this modifier and the event it points to. @ENDNODE @NODE LVInsert LVINSERT RecordNumber String Insert a new line (or record) to the current listview, *before* RecordNumber (-1 means before current record) The line added will become the new "current" record. ex: LVInsert 0 "New Top Line" - will insert a new first line. If the ListView is a @{" DataBase " link DBase_LVs }, then the line added will be the same length as the other lines - which may be less than the string you give. The rest of the space will be filled with blanks. @ENDNODE @NODE LVMode LVMODE NUM|TXT|MULTI|DIR This command will change the mode of the LV on the fly, to the mode you give. Be careful with this command as it can get confusing.. @ENDNODE @NODE LVMove LVMOVE +-Offset|0|#RecordNumber This command will visually move a listview, *without* changing the current record. You can move : + or - Offset : Move the display left or right. Ex - LVMove +5 LVMove 0 : This will have the effect of refreshing a listview's display. It allows you to HIDE an LV with @{" SETGAD " link SetGad } and thereby speed up all the actions you take immensly. When you're done, you SETGAD it on again, and refresh it with LVMove 0. #RecordNumber : will move the LV to the record given. @ENDNODE @NODE LVMulti LVMulti First|Next|On|Off|All|None|Show This allows you to read the selections made on multiple and directory listviews. It will act on the CURRENT LISTVIEW. The First & Next keywords are the ones that do this. You MUST start with : - LVMULTI FIRST This will store into the given ListView's variable, the text of the first selection in the list. (or "" i.e. nothing, if there is none). Thereafter you read selections in some kind of loop, usually using the WHILE/ENDWHILE commands : - LVMULTI NEXT This will store the next selection into the listview's variable. You will call this many times, until it stores a "" (i.e. nothing) into the variable, whereby you know that the selections have finished. Example : (Filename = MyGui) ------------------------------------------------------- G4C WinBig -1 -1 320 100 "My Directory" xListView 10 10 200 100 "" LVar dh0:MyDir 10 DIR GadID 1 xButton 210 10 100 15 "List Selections" LVUse MyGui 1 ; use the above LV LVMulti First ; goto the 1st selected record while $$lv.line > "" ; while there are records Say '$LVar\n' ; print it LVMulti Next ; goto next selected record EndWhile ; close while loop ------------------------------------------------------- The rest of the keywords have the following meanings : ON : set current line ON (select it) OFF : set current line OFF ALL : select *all* the lines of the LV NONE : un-select all lines SHOW : redraw the LV. This is important in speeding up lv processing. It is *much* faster to HIDE an lv (with SetGad) and act on it (with lvadd, lvput etc) and then SHOW it again, than to have the LV updated continuously while actions are going on. When you show it again, you must "nudge" it into redrawing itself with LVMulti SHOW (can also be done with LVMOVE 0) ------------------------------------------------------- *** Not Implemented yet *** Many programs can take myltiple files as arguments, so there is no need to feed each file one by one to them. By using these two, the DirListView's Variable will be filled with all selections made (i.e. the file names you've selected, listed one after the other), until the first xxx bytes (ex: First_910) of your "buffer" are full. By default, the "Buffer" in Gui4Cli is 1024 bytes. This means your variables can not have more than 1024 characters (spaces inclusive). The buffer size can be changed with the "ToolTypes and Options". So when executing a command line you would give a command : CLI 'MyProgram $MyFiles $Option1 $Option2 etc etc' Here, you must calculate approximately the size that the program name and all the other options will take up in the command line, and ask for First_xxx Next_xxx number of bytes in the $MyFiles variable to be filled, so that the complete resulting command line fits into the 1024 bytes (or whatever) buffer available. You got all that ? @ENDNODE @NODE LVPut LVPUT string will change the text of the current record the LV is at, to what ever you give in "String". ex: lvuse gui 1 lvgo #5 lvput "This line has new text" If the ListView is a @{" DataBase " link DBase_LVs }, the old line will not be deleted and replaced with the new (like normal listviews) but will be copied over with the string given. The rest of the buffer, will be filled with blanks. It's better to use %Fields that LVPut when dealing with DataBases. @ENDNODE @NODE LVRep LVREP OldString NewString CI|CS Replace all occurances of "OldString" with "NewString" in all the records of the current listview. BECAREFULL if the listview is a DataBase listview, because it may trash your records if the string you are replacing is longer or shorter than the new string. Again, CS means "Case-Sensitive" and CI, not. @ENDNODE @NODE LVSave LVSAVE SaveFileName Save the listview as "SaveFileName" If it's a DataBase listview it will be automatically saved with the correct header. @ENDNODE @NODE LVSearch LVSEARCH String CS|CI First|Next Search the LV for "String" CS|CI means = Case Sensitive (CS) or Case Insensitive (CI) First|next are for control : LVSearch "MyString" cs first - will return with the first line containing "MyString". You can get the line number, text etc of the line found, via the @{" Listview internal variables " LINK "iv_listview"} You can get the position of the string within the line via the @{" Search internal variables " LINK "iv_search"} You can thereafter call : LVSearch "MyString" CS next - again and again, to get the rest of the lines or strings. If there are 2 or more occurences of the same string in the same line, LVSearch will stop as many times as there are strings for. (This has been added in version 3.6+) When there are no more more lines containing the given text, then the $$lv.line internal variable will contain "" (nothing) and that's how you know you're finished. Note : "" is *not* the same as 0 in Gui4Cli. "" means Nothing - 0 means the top line. @ENDNODE @NODE LVSort LVSORT ASC|DSC|%FieldName This command will sort the Current listview alphabetically, in ascending order. You can give the following arguments : ASC or DSC - meaning Ascending or Descending. Currently however, only ASC works.. or.. %FieldName - If the file loaded is a @{" DataBase " link DBase_LVs }, then you can give a fieldname and the LV will be sorted according to the Field name. The current record will be reset to 0. Example : @{" Run Gui " system "gui guis:docs/tutorials/LVHandler.gc"} @{" Source " link "guis:docs/tutorials/LVHandler.gc/Main"} @ENDNODE @NODE LVSwitch LVSwitch Gui ID Will switch the data of the current listview with the one specified. Everything else (IDs, gadget attributes, lvmode etc) will remain the same. ex: lvuse gui 1 ; use lv No.1 lvswitch gui 2 ; switch all the data with lv No.2 This is helpfull when you use LVs as databases, or want to have one visible lv gadget and many lists. @ENDNODE @NODE LVUse LVUSE GuiFile GadID Select another listview and make it the CURRENT LISTVIEW. A ListView becomes CURRENT when the user clicks on a line. You can thereafter change the Current listview with this command : LVUse MyGui.gc 1 This is an important command, because most of the other ListView commands will act on the CURRENT LV, and this is the command that can set or change it. @ENDNODE @NODE LV_Commands LISTVIEW COMMANDS ---------------------------- Listviews have the following dedicated Event Commands. All the commands (except LVUse) will act on the CURRENT listview, or the CURRENT RECORD of the current listview. @{" LVUSE " link LVUse } GuiFile GadID - Loading saving files : @{" LVCHANGE " link LVChange } NewFromFile @{" LVSAVE " link LVSave } SaveFileName @{" LVCLEAR " link LVClear } - Handling listviews : @{" LVGO " link LVGo } first|next|prev|last|#LineNumber @{" LVMOVE " link LVMove } +-offset (do also #rec) @{" LVFIND " link LVFind } String @{" LVSORT " link LVSort } ASC|DSC|%FieldName @{" LVSEARCH " link LVSearch } string cs|ci first|next @{" LVREP " link LVRep } OldString NewString CI|CS @{" LVSWITCH " link LVSwitch } Gui ID - Acting on records : @{" LVADD " link LVAdd } String @{" LVINSERT " link LVInsert } RecordNumber String @{" LVPUT " link LVPut } string @{" LVDEL " link LVDel } LineNumber (or -1 for current line) @{" LVCLIP " link LVClip } CUT|COPY lines|-1 ADD|PASTE|INSERT gui ID - MultiSelect listviews : @{" LVMULTI " link LVMulti } First|Next|ON|OFF - Commands for DIRECTORY LISTVIEWS : @{" LVDIR " link LVDir } All|None|Parent|Root|Disks|#dirname(string) @{" LVACTION " link LVAction } COPY|COPYNEW|MOVE|DELETE|SIZE|PROTECT|CLI Dest|REQ|NOREQ|Var|Mask - Various : @{" LVMODE " link LVMode } NUM|TXT|MULTI|DIR - Gadget modifier : @{" LVCOLORS " link LVColors } GuiFile GadID ForeGround BackGround Selected Dirs (it is better to use @{" attributes " link Attr } for colors etc) - DataBase listview commands : @{" DBSUM " link DBSum } ALL|SELECTED|UNSELECTED %FieldName ResultVar @{" RECSORT " link RecSort } %FieldName -------------------------------------------------------------------- An example gui : @{" Run Gui " system "gui guis:docs/tutorials/LVHandler.gc"} @{" Source " link "guis:docs/tutorials/LVHandler.gc/Main"} *** IMPORTANT: A note about acting on listviews *** It is *much* faster to @{" HIDE " link SetGad } an lv and act on it (with commands like lvadd, lvput etc) and then SHOW it again, than to have the LV updated continuously while actions are going on. When you show it again, you must "nudge" it into redrawing itself - with LVMULTI SHOW or LVMOVE 0 @ENDNODE @NODE MakeDir MAKEDIR NewDirName Create a new directory, named NewDirName. That's all really... @ENDNODE @NODE MakeScreen MAKESCREEN ScreenName Depth|(Width/Height/Depth/Mode) Title This command will make a public screen, on which you can open windows. ScreenName The name of the screen you want to make. The name is case sensitive, so when referring to it, you have to have the same case letters. Depth A number, signifying the bitplanes of the screen. It can be from 1-8. If it isn't, the depth will be set to 2. -OR- Width/Height/Depth/ViewMode You can also give the full size of the screen, if you want, instead of just the depth. The viewmode is optional. ex> MakeScreen MyScreen 640/512/4/0x21004 'my screen' Title A string which will be the default title of the screen. Ex : MakeScreen MyScreen 4 "Hey! - This is my Screen!" If you only give the depth (instead of full size string), the new screen will be the same size, resolution etc as the Workbench screen, and at a TEXT sized overscan. Example : @{" Run Gui " system "gui guis:docs/tutorials/MakeScreen.gc"} @{" Source " link "guis:docs/tutorials/MakeScreen.gc/Main"} You can check if the screen opened with the IFEXISTS command. IMPORTANT : The Screen will NOT be automatically closed when Gui4Cli quits. You MUST (if you want) specifically close it, after closing all the windows that you have opened on it. If you do not close it, it will just stay there. @ENDNODE @NODE Mark MARK MarkName GOTO MarkName =============================================================== This is a simple way to jump around inside an Event's commands. You don't really need this command, since it may be confusing. When you declare MARK, you are just marking a point in the program. No action is taken when the command is encountered. GOTO goes to the MARK which bears the same MarkName as itself. You can not jump to a Mark of a different Event. Also you may confuse Gui4Cli if you jump in and out of while loops of other such constructs.. @ENDNODE @NODE Maths Mathematical Calculations & Expression Evaluation: -------------------------------------------------- Gui4Cli will evaluate a mathematical expression, if enclosed in brackets with a $ (dollar sign) in front. x = $(4*2) ; will set x to 8 This can be used anywhere, just as if it were a variable : Say 'The result is $(45/(2*4.56))\n' Gui4Cli will read brackets as if they were quotes - i.e. you can have spaces inside the brackets without having to quote the whole thing : x = $( 4 * 2 ) You can also have variables in the brackets, but.. BECAREFULL : Gui4Cli allows almost any character to be a part of a variable name. (This is done because file names - which can have almost any character in them - can also be variables (env:) or part of the specification of variables (GuiName/VarName)) So Gui4Cli will also consider things such as +, *, -, / etc to be included in the variable name if there is no space between the end of the name and the operator : x = $($var*3) ; <- wrong is wrong, because Gui4Cli will try to find variable "var*3" Gui4Cli will understand the end of a variable name if it is followed by a space, or a bracket or a '\', so x = $($var *3) ; is correct x = $(3*$var) ; is correct x = $($var\*3) ; is correct The available operators are : + - * / as you know.. ^ means to the power of = 4^2 = 16 Note that to get a square root you can do : x = $(25^(1/2)) ; 25 to the half = 5 Inside the brackets, you can also use the following math functions : abs(x) absolute value of x sin(x) sin of x cos(x) cosine of x tan(x) tagent of x log(x) logarithm of x ln(x) natural log of x exp(x) exp of x pi = 3.141592654 example : x = $($MyVariable * pi + tan(0.85)-(4*sin(45))) I used to know all this stuff, now I can't remember a thing.. The parser which does the actual calculation was written by Kittiphan Techakittiroj, who put it in the public domain where from I appropriated it with his blessings and put it to good use. Here's a calculator : @{" Run Gui " system "gui guis:Tools/Calc.gc"} @{" Source " link "guis:Tools/Calc.gc/Main"} @ENDNODE @NODE MoveScreen MOVESCREEN GuiName/#ScreenName X Y Will move the screen that GuiName is (or will be) open on to position X, Y. You can also give the ScreenName directly, by putting # in front. example: (move the Workbench screen down in a dramatic way..) c = 10 while $c < 150 movescreen #Workbench 0 $c c == $c + 10 endwhile @ENDNODE @NODE NewFile NEWFILE NewFileName This is a "parser" command, i.e. it is executed while G4C is reading your file. It enables you to have many GUIs in one file. When G4C encounters this command in a file, it marks the beginning of a new GUI. No new "G4C" marker is needed !! example : ----------------- File named test1.gc G4C WinBig -1 -1 400 100 "test 1" NEWFILE test2.gc WinBig 10 10 300 150 "test 2" ----------------- end of file This file, when loaded, will result in 2 GUIs, one named test1.gc and another named test2.gc. Example : @{" Run Gui " system "gui guis:docs/tutorials/Window.gc"} @{" Source " link "guis:docs/tutorials/Window.gc/Main"} IMPORTANT : Such multiple GUI files have the following limitations : - Only the xOnload commands of the 1st file will be executed. xOnLoad events of other files, if present, will be ignored. - On Ctrl-R (reload), all GUIs contained in the file will be reloaded but only the GUI you asked to reload, will have quit first, so you will get reports that the other files exist - This is normal. - On Ctrl-E (edit), the "mother" file will be loaded for editing. - RESIZE_BIG & RESIZE_SMALL commands now have filename. But the old versions will also work. @ENDNODE @NODE Operation @{B}* P r o g r a m O p e r a t i o n *@{UB} @{B}Starting up :@{UB} There are 2 main binaries - c:GUI and GUI4CLI (which can be in c: or in Guis:, depending on the installation). You should *always* start Gui4Cli by runing c:GUI. It will look for Gui4Cli in both places and load it. It will also make sure that Gui4Cli inherits your cli paths. > run gui -or- > run gui SomeGuiName.gc One of the best ways to start-up Gui4Cli is to have "GUI" as the default tool of the icon of a gui. Double clicking the icon will automatically start-up Gui4Cli and run the gui. @{B}Where it lives :@{UB} When Gui4Cli starts up, it may or may not be given a gui (script file) or guis to execute. In any case, it will load itself and install an APPMENU Item, by the name of "Gui4Cli...". This will appear in the Tools menu of the Workbench. This is your anchor to the world. When you choose this menu item, an easy-requester will appear, allowing you to Quit, Load, Open, Unload Guis, or run the Prefs gui (Gui4Cli.gc) @{B}The requester :@{UB} If you choose Quit, all windows will be closed, all GUIs unloaded and the program will quit. Load will take you to the default directory where your GUIs are, so you can choose one and load it. - If no directory has as yet been given, you will be asked for Volume GUIs: (you *should* make this assign - believe me..) Open and Unload will take you to a directory called ENV:Gui4Cli, where the names of the loaded GUIs are listed, and you can choose one. If you choose "Prefs" Gui4Cli will run the gui Guis:Gui4Cli.gc (if it exists). This is a normal gui which provides an easy way to set various things (tabs/grid sizes etc). You can, if you want, change this gui. The settings can be saved. @{B}The preferences file :@{UB} There is a special file called GUIs:Gui4Cli.prefs which is a normal gui file, generated by the Gui4Cli.gc gui (when you save the preferences) - or you can also create it yourself, manually. When Gui4Cli starts up, it will look for this file and if found, it will run it. It is a good place to keep all the startup settings you want, such as TAB/Grid sizes, sound effects etc.. @{B}Method of Operation :@{UB} A GUI can be loaded into memory and be or not be open. You can have as many GUIs as you want loaded into memory, and as many of these as you want, open at the same time. Thereafter, every time you run GUI (or even Gui4Cli itself), it will look for a running instance of Gui4Cli and if it finds one, it will send it a message to load the program you have specified, or clicked on. This means that you will only have one running Gui4Cli, with many GUIs loaded and some or all of them open. If you need another instance of Gui4Cli, you have to specify another PORT name in the tool types, or as a CLI option. In this case, another APPMENU item will be created with the name of the PORT you have specified and through this other GUIs can be run separately. In effect, you can have unlimited, easily constructed GUIs running on your Workbench or on other Public screens. Gui4Cli >--o---> A Gui --------->o--> Event 1 -->o--> Command 1 | | O--> Command 2 | | O--> Command n.. | | | | | O--> Event 2 -->o--> Command 1 O---> another | O--> Command n.. | gui | | | | | | O--> Event n.. | . | . O---> unlimited . guis.. . This is what it looks like in concept. @ENDNODE @NODE Operator OPERATORS ================================================================ The following are the operators you can use with IF, WHILE and DOCASE commands (all comparison are case-sensitive unless stated otherwise) : EQUAL (Insensitive) == (Comparison is CASE-INSENSITIVE) EQUAL (Sensitive) = (Comparison is CASE-SENSITIVE) NOT EQUAL (Insensitive) !! (Comparison is CASE-INSENSITIVE) NOT EQUAL (Sensitive) != (Comparison is CASE-SENSITIVE) MORE > (Left side more than right side) MORE than or EQUAL to >= LESS < (Left side less than right side) LESS than or EQUAL to <= FILE HEADER COMPARE H= This operator MUST have a file name on the left of it and a comparison string on the right : IF df0:MyFile H= "FORM????ILBM" the comparison string contains the starting bytes of the file type you are looking for. - Question marks are wild (-see below-) STRING COMPARISON S= This MUST have a string on either side of it and will compare them. it is case-insensitive and wild characters can be used (see below). ex : IF "This" S= "THIS" This is meant to be used along with the ReadVar command and provides a faster method of checking file headers than the above H= operator. DEVICE COMPARISON D= FILE/DIR COMPARISON F= Both of these need a file, dir or device on either side. D= will yield TRUE if the files/dirs are on the same device, and F= will be TRUE if they are the same file or directory. Wild Characters that can be used with H= and S= ? Means any character # Means any Printable character % Means any UnPrintable character Operators MUST have a space to each side of them : if This= That <- is not correct if This=That <- is not correct if This = That <- is correct @ENDNODE @NODE Options TOOLTYPES & OPTIONS The CLI or TOOLTYPE options are identical. The only difference is that the TOOLTYPES are in the icons. PORT=PortName Usually the Public message port name is Gui4Cli. This way all GUIs are run from the same one program. You can, if you want, though, launch as many Gui4Cli's as you want, by specifying different PORT names for them. This keyword is the way to do it. DEBUG If this word appears in the commandline, then Gui4Cli is started in the "debug" mode, which means that it will print out in the default shell all commands that it executes, in the order it executes them. Use this command to see what the program is doing, if it behaves illogically. The STACK statements that are printed out, you can forget. DEBUG (in a simplified form) can also be started/stopped at any time, with the SET DEBUG ON|OFF command, or by just pressing CONTROL-D while a G4C window is active. BUFFERS=Bytes When Gui4Cli starts up it grabs 12 buffers (pieces of memory), in which it does all the translating and other command processing. These are 1024 bytes long, by default. This means, for example, that your translated command line in a CLI or SENDREXX command, can not be longer than 1024 characters. It also means that your variables can not be bigger than this size. You may, if you want, change this with this option. You can also change it whith the @{" SET BUFFERS " LINK "Set"} command. OUTPUT=Console By default, the console specification for any output from CLI commands, or Gui4Cli error reports etc, is : - If started from a shell -> the shell itself - If started from WB -> "con:0/12/450/80/Gui4Cli Output/AUTO/CLOSE/WAIT" This is the console that is passed to all CLI commands. You may want to change this (to KCon:, or NIL: for example) so this is the way to do it. (Also with SET) Note also that you may specify a different console for each GUI (with the WinOut command), but this is wasteful, as each new console you specify uses memory. EDITOR=Editor When you press CONTROL-E, the default editor will be (NOT CLI) started up, in order to edit the current GUI. The default editor is c:ed. With this option you can change the name of the editor to whatever you want (ex : EDITOR=C:CygnusEd) NOREQUEST If you specify NOREQUEST as an option, you will disable the file requester which appears at startup. If no filename is given - allows you to put a GUI with an icon into the WBStartup drawer without getting a requester at startup time. The OUTPUT and EDITOR can also be changed with the SET command. @ENDNODE @NODE Palette PALETTE LOAD|SAVE|SET|GET|REMAP Source Destination This command will allow you to do just about anything involving palettes. The keywords you can use take different arguments, as follows : LOAD DiskFile ImageAlias(create if non-existant) Load a palette from a file, into an image's palette. If the image does not exist, an empty one will be created having a depth of however many colors the palette has. SAVE ImageAlias DiskFile Will save an image's palette into a given file, in standard IFF format. SET ImageAlias ScreenName Will change the palette for the given screen to the images's. GET ScreenName ImageAlias(create if non-existant) Will copy the given screen's palette, into the image's. Again, if the image does not exist, it will be created. REMAP FromImageAlias ToImageAlias Will remap the "FromImageAlias" to match the palette that "ToImageAlias" has. @{FG shine}Example :@{FG text} @{" Run Gui " system "gui guis:tools/Palette.gc"} @{" Source " link "guis:tools/Palette.gc/Main"} @ENDNODE @NODE ParseVar PARSEVAR VariableName This command will take a variable and split it up into arguments (words or quoted strings), returning them as internal variables. The internal variables are : $$PARSE.0, $$PARSE.1, $$PARSE.2 etc - up to PARSE.29 which will hold the various arguments (30 maximum) or words resulting from the splitting of the variable The 1st word will be in $$PARSE.0 $$PARSE.TOTAL will contain the number of arguments that have been parsed. Note - the ; character ends the line being parsed (like in G4C) The values of the PARSE internal variables will remain unchanged until another ParseVar command is issued. Example : @{" Run Gui " system "gui guis:docs/tutorials/ParseVar.gc"} @{" Source " link "guis:docs/tutorials/ParseVar.gc/Main"} @ENDNODE @NODE PartRedraw PARTREDRAW GuiName L T W H This command was added to make redrawing of windows easier to the eye. It will redraw only part of the window, thereby reducing the flashing. Use this if you're just changing some gadgets in one area of the window and do not want a full redraw. L T W H denote the area which you want redrawn. It's exactly the same as the @{" Redraw " link redraw} command, only that a part of the window is erased instead of all the window as is done in the Redraw command. Otherwise, the gadgets, graphics etc are drawn from scratch, same as with Redraw. @ENDNODE @NODE Passing_Args PASSING ARGUMENTS : =================================================================== Arguments can be passed by the following commands : GUILOAD to xONLOAD or xONRELOAD GUIOPEN to xONOPEN GUICLOSE to xONCLOSE GUIQUIT to xONQUIT GOSUB to xROUTINE The way this is done is by declaring the arguments in the command's command line, like so > GUILOAD guis:MyGui Arg0 Arg1... Arg5 - or - > GOSUB MyGui MyRoutine My_Arg My_Other_Arg Up to 6 arguments may be passed. Inside the event they call, these arguments can be accessed in either of two ways : 1. As normal Variables (if defined in the Event's definition). If declared in the event's definition, they'll be automatically converted to variables. For example : > xONLOAD Var1 Var2 If you were to call this event with : > GUILOAD MyGui.gc SomeText "Some more text" then when MyGui.gc loads, there would be 2 variables created : - "Var1" which would contain the word "SomeText" and - "Var2" which would contain "Some more text" You can also pass variables: > gui/myvar = "Some text" > GOSUB MyGui.gc RoutineName $gui/myvar If you pass variables you should use the variable's *full* path (as is done above) to avoid confusion. 2. As internal variables $$ARG.0 to $$ARG.5 Note that even if you define variables in the event's definition as above, they'll still be available as $$ARG.xx also. Another internal variable: $$ARG.TOT will (always) contain the actual number of arguments passed. The RETURN command ------------------------- The above events (xONLOAD, xROUTINE etc) can also RETURN arguments via the RETURN command. > RETURN Arg0 Arg1... Arg5 The arguments can be accessed (when they return to the routine that called the event) as internal variables $$RET.0 to $$RET.5. $$RET.TOT will contain the actual number of arguments returned. - Example : xBUTTON 10 10 60 12 Test var = "This is a test" GoSub MyGui routine1 $var ; We only pass "var" as an argument here. We could have had up to 6 args. ; the routine will return one argument to us (also could have been 6) ; which we just print.. say 'Return returned $$RET.0\n' xROUTINE routine1 MyVar ; here variable "MyVar" will contain $var (i.e. "This is a test") ; Note that $$ARG.0 will also contain the same thing. say '$MyVar is the same as $$ARG.0\n" ; now we return something... Return "Thank you.." -------------------------------------------------------------------- ** WARNING : - If you want to pass a variable you should give the variable's full path (i.e. RETURN MyGui/MyVariable), since it may be in another gui which may not have you in it's varpath. ** WARNING 2: - You can not pass an $$ARG.0 type of internal variable you receive as an argument to an other routine/xonload etc. : > GOSUB mygui myroutine $$ARG.0 <-* is WRONG! That's because when Gui4Cli attempts to translate the variable when it gets to the routine, it will find variable $$ARG.0 containing $$ARG.0 and it will go into a wild loop trying to translate it.. This loop will time out after 100 rounds (i.e. the default depth of variables within variables that you can have) and the error will be reported. There are no such problems if you use the definition in the event's command line, so use that instead. @ENDNODE @NODE Paths FINDING your way in other people's systems =============================================================== 1. Locating your own gui ------------------------------ Whenever you make a GUI which other people might also use, you will need to know various paths where you can load any helper GUIs or icons that your GUI needs, since you don't know how other people's systems are set up. There are 2 ways of doing this : 1st is to use the @{" Extract " link "extract" } command, as follows : > Extract MyGui.gc GuiPath MyPath Now variable MyPath will contain the full path of MyGui.gc GUI. You can now assign this path, or use it to AppVar various other GUI names and load them. There is a much easier way though, and that's by putting a ":" character in front of the filename or icon name.. > GuiLoad :MyGui.gc Gui4Cli will automatically convert the ":" character to the full path of the GUI in which this command exists. This method also works with icons, so you can do : > xIcon 10 10 :MyIcon and the icon will be loaded from the current file's path. Also, with the File argument in a xLISTVIEW. 2. Locating a file in the path ---------------------------------- It is very important to make sure that you start-up Gui4Cli via the c:GUI command, or run it via a shell, so that it inherits your CLI path. Even so you will many times need to get the full path of some command or utility, since you can do this: > RUN "Resident MyProg PURE ADD" and Gui4Cli will find the "Resident" command and run it, but the "Resident" command will *not* find the "MyProg" command, even if its in c:, since it does not search through your path! To find the full path of a file in your path you can use Extract: > File = DPaint > Extract File FULLPATH File Now "File" will either contain something like "DH0:mydir/DPaint" or, if DPaint was not found in your path, "" (nothing). @ENDNODE @NODE Programming HOW TO MAKE A Gui4Cli PROGRAM --------------------------------- The structure of a Gui4Cli program may, in the beginning, be a little confusing to understand since it is not like other languages. Once you understand it though, it is very easy. @{FG shine}*@{FG text} Start with G4C First of all, every Gui4Cli program MUST start with the letters G4C These must be the first letters of the first line of every GUI, so that Gui4Cli knows it is a loadable file. @{FG shine}*@{FG text} @{" GLOBAL Commands : " LINK "c_global"} Then come the GLOBAL COMMANDS (if any). These can appear in any place in the file, but it is best to put them at the beginning of the program, for clarity's sake. The Global Commands specify the window size and type as well as other general characteristics of the GUI, such as the screen it should open on etc. The most important of the Global Commands is "WinBig", which describes the size of the window. If this command is not declared, no window will open. @{FG shine}*@{FG text} @{" GRAPHICS Events : " LINK "c_graphics"} GRAPHICS are like normal Events (see below) but since they can not be selected, they never "happen". They are simple drawing routines, enabling you to tart-up your GUI withy things like colored text, lines, boxes, circles etc.. @{FG shine}*@{FG text} @{" EVENTS : " LINK "c_events"} EVENTS are what drives Gui4Cli. They usually start with an "x" e.g. xBUTTON, xLISTVIEW, xONOPEN, xONCLOSE etc. Events can be gadgets, menus, routines, AppItems or User actions. For example : xBUTTON is a Gadget xMENU is a Menu xONCLOSE is a user action (i.e. if the window is closed) xROUTINE is a routine xAPPMENU is an AppMenu Item (WB Tools menu) All events, of whatever type are treated in the same way. Whenever an event "happens", the commands attached to it will be executed in the order they appear. The Gadget and Menu type events, also specify the type and specifics of the gadget or menu. A button type gadget (EVENT), for example, can be declared as follows : xBUTTON 10 20 100 15 "Click me!" This declares a button positioned 10 pixels from the left side of the window and 20 pixels from the top. The size of the button is 100 pixels wide and 15 pixels high, and it will bear the title "Click me!". Most gadgets, will have a variable where they will put their value. @{FG shine}*@{FG text} @{" EVENT MODIFIERS : " LINK "c_gadmod"} Gadgets have standard settings - for example, the text in a text gadget will, by default, be right justified. Many of these default settings can be changed however, by attaching Event Modifiers to them, such as GadText LEFT. @{FG shine}*@{FG text} EVENT COMMANDS : Event Commands are "attached" to Events. You can attach any number of event commands to any event, making small sub-programs (like routines or functions in other languages), which will be executed every time the event they are attached to "happens". These commands do different things.. @{" Controling Gadgets " LINK "c_gadcontrol"} SetGad, Update, Redraw.. @{" Control Statements " LINK "c_control"} if/endif, ifexists, Gosub, stop ..the ones below can also be sent as arexx commands.. @{" DOS commands " LINK "c_dos"} Run/Launch, SendRexx, Wait, Action.. @{" Handling guis " LINK "c_handle"} GuiLoad, GuiOpen, Info... @{" Handling variables " LINK "c_vars"} SetVar, ParseVar, Extract, RepVar.. @{" Listview commands " LINK "LV_Commands"} LVUse, LVDel, LVAdd, LVClip... @{" Various commands " LINK "c_various"} ReqFile, EZReq, MakeScreen, BreakTask.. An event command can be ARexx capable or not. I've marked them above. If they are, it means that they can be passed to Gui4Cli from other programs as ARexx commands and will be executed as if they were attached to an Event. There is no special statement that ends an Event. Each event routine ends when another Event is declared. EXAMPLE PROGRAM : For example, this is a little "Hello World" program. We'll name it "Hello.gc" ------------------------Start of file G4C ; You must put this at the beginning. WINBIG 100 20 100 50 TEST ; Specify a window xONLOAD ; To be done on loading the GUI GuiOpen Hello.gc ; Open the GUI's window. xBUTTON 10 12 80 15 HERE! ; Specify a button SAY "Hello World!" ; Attach a command to it. ------------------------End of file. When you run this program, a window will open with a button in it. When the button is clicked on, a standard con: window will appear (since you have not specified otherwise) and the words Hello World! will be echoed. If you click on the window's close gadget, the window will close but the GUI will remain in memory, since we have not told it to quit. If we wanted the GUI unloaded from memory as soon as the window closed, we would add the following Event : xONCLOSE GuiQuit Hello.gc Note that the commands can be in capitals or small letters. But careful - variables are case-sensitive! We did not use "translation" in this program, since we did not have to. Let's make a simple program using translation. (call it Hello2.gc) ------------ G4C WINBIG 0 0 100 50 "2nd Test" xONLOAD ; upon loading of the gui Var1 = "Hello World" ; declare variable Var1 GUIOPEN Hello2.gc ; and open the gui xBUTTON 10 15 80 15 "Hit Me" SAY "$Var1" ; print the variable IF $Var1 = "Goodbye World.." ; see explanation.. GUIQUIT Hello2.gc ELSE Var1 = "Goodbye World.." ENDIF ------------ Here, in the beginning, we put the words "Hello World" into Var1, and open our window. When the button is clicked on, we print the value of the variable, and afterwards we set it to "Goodbye World..", so that the second time the user clicks on the button, after "Goodbye World.." is printed, the GUI will quit. Ok.. enough talking - you can see how easy it is. The best way to learn to write GUIs, is to look at the @{" tutorials " SYSTEM "gui GUIs:Docs/tutorials.gc"}, so go look at them. You can change them in any way you want and see what happens. You will be impressed at what can be achieved (I hope :) @ENDNODE @NODE Quit QUIT QUIT will quit Gui4Cli. It will close all open windows, executing any xOnClose events (if any) and will unload all guis, executing any xOnQuit events. QUIT can also be chosen from the STATUS requester. @ENDNODE @NODE ReadVar READVAR FileName Start Length Variable Reads part of a file into a variable > ReadVar ram:myfile 0 100 myvar will read the first 100 bytes of file "ram:myfile" into variable "myvar". Remember that variable length is limited to 1024 bytes unless you enlarge it with the @{" SET " LINK "Set"} BUFFERS command (also a ToolType option). That means that you can not read more than that into the variable. @ENDNODE @NODE RecSort RECSORT %FieldName This is for DataBase listviews. It will sort the CURRENT record into a DB listview according to the given field. If you have a listview sorted according to (say) the amount, then if you added a new record, or edited one and changed the amount then you'd have to sort the whole listview again.. Using this command, you can sort only the record you changed so it's much faster.. ex: ; use an lv and select the 1st record.. lvuse mygui 1 lvgo first ; change the %amount field of the 1st record.. %amount = 5000 ; resort it.. RecSort %amount @ENDNODE @NODE Redraw REDRAW GuiFile This command will Re-Draw the GuiFile's window, taking into account any changes you may have made to the GUI with the ChangeGad command or with the SetGad command (with the SHOW|HIDE keywords). Use it after using ChangeGad or SetGad on all the gadgets you want to change. example : setgad mygui.gc 1 HIDE setgad mygui.gc 2 SHOW redraw mygui.gc A cooler redrawing can be achieved with the @{" PartRedraw " link partredraw } command. @ENDNODE @NODE Rename RENAME OldName NewName Will rename the given file or dir. @ENDNODE @NODE RepVar REPVAR Variable OldString NewString CI|CS Will replace all occurances of OldString in Variable with NewString. CS means case sensitive, CI case insensitive. example : x = "This is a test string" RepVar x "is" "XXX" CI ; now x will contain "ThXXX XXX a test string" If you want to make replacements on *all* the records of a listview you can use the - LVREP OldString NewString CI|CS - command. @ENDNODE @NODE ReqFile - ReqFile L T W H Title SAVE|LOAD|MULTI|DIR Variable DirName This is an ASL file requester. You must have the asl.library in your LIBS: directory. (L)eft, (T)op, (W)idth and (H)eight are the starting position and size of the requester. If you resize it thereafter, the new sizes will be used. TITLE is the title in the requester window title bar. SAVE, LOAD, MULTI, DIR are the types or requesters you can use. VARIABLE is the name of the variable, where the names of any file(s) that were chosen will be placed. If its a multiple selection, the files will be listed one after the other. If the file names contain spaces, they will be quoted. DIRNAME is the starting directory that the requester will open on. The DirName will be remembered, and the next time the requester opens it will open at the dir you were at last time, however.. You can put a # character in front of DirName, to force the requester to open at the same dir every time: #mydir You can also give "" as the DirName. This will use the last dir used by other ReqFile commands, or sys: in case no other ReqFiles have been executed yet. ALSO - you can give a filename with the dirname : ReqFile -1 -1 300 200 "Choose" LOAD var #df0:mydir/myfile In this case, the name of the file will be placed in the File gadget of the requester. Gui4Cli will check if it's a file or a dir and act correctly. Also ReqFile will no longer be confused by quoted file names etc. Also, ASL requesters (and EZreqs) will now open on the front screen, if the window that called them is not open, or, if the font screen is not public, on the workbench. It's generally a little smarter than it used to be. Unlike me.. @ENDNODE @NODE ResInfo RESINFO FontHeight ScreenWidth ScreenHeight This is a Global command which gives some info to Gui4Cli regarding the screen mode & font size that the gui was originally designed for, so as to enable it to resize it correctly under other fonts/resolutions. Example : ResInfo 8 640 256 - this tells Gui4Cli that your gui was designed on a 640x256 screen using an 8 point font. That's what my WB is.. If, the gui's screen has the same size font, no resizing will take place. Otherwise an incredibly profound calculation will take place to magically divine the perfect new size for you particular screen mode & font height.. And it sometimes looks good too.. :) @ENDNODE @NODE ReSize RESIZABLE GUIs : ===================================================================== - How to make them : All you have to do in order to make a GUI resizable is declare the border gadgets with the @{" WinType " link "wintype"} command. Resizing is usually proportional, but you can controll how each gadget should resize itself through the @{" Resize " LINK "at_resize"} attribute. - Notes on resizing : Gui4Cli is (or tries its best to be) @{" font-sensitive " link "fonts"} This means that it will automatically resize a GUI to fit the font you use. However, the best method of getting and keeping the GUI size you want on your system, is to use the CONTROL-W short cut : When you press CONTROL-W on a window, a requester will appear which will tell you the current window size & position and have the following choices : BIG : Save this window size as the default size it opens with Small : Save this window size as the minimum size Adjust : Resets the current minimum window size and allows you to resize the window to any size. CANCEL : You know... Saving the window sizes, instructs Gui4Cli to append one of 2 commands : RESIZE_SMALL Left Top Width Height - or RESIZE_BIG Left Top Width Height to the specified GUI file. This command will instruct Gui4Cli to resize the window to the specified size, upon loading it. Note that when Gui4Cli loads the file, it can encounter many such RESIZE_xx commands, since you may have saved the window sizes many times. It will only use the last ones it encounters, so you may as well delete any others.. NOTE : When you resize a GUI, the gadgets are redrawn to their new sizes positions etc. and with the values they currently have. The xLISTVIEW's current value, is the line number of the last line you clicked on it (if any, otherwise 0), and so when redrawn it will show this line as the 1st one. This may cause some confusion.... It's the fault of the GadTools library, so leave me out of it.. @ENDNODE @NODE Run Two commands give you the means to run CLI commands : CLI CommandLine RUN CommandLine Both are AREXX capable. The CommandLine is anything that can be typed at a shell command prompt. Note that the command line is a single argument, so, if it has spaces in it (which it probably will), you MUST enclose it in quotes (single quotes preferably). Example : RUN 'Dpaint $Myfile' The difference between the 2 commands is : RUN - will run the command line asynchronously CLI - will run the command synchronously. BE CAREFUL with the CLI command, as it will stop all processing of Gui4Cli until the command you have given it has finished executing (unless you have given something like : CLI 'run >NIL: Dpaint'). Both commands will set the @{" $$RETCODE " link Variables_IntList } internal variable which you can check to see if the command you issued worked or failed. 0 means OK. This, usually, is only useful when using the CLI command, and then, only if you don't "run" it. Use @{" IFEXISTS " link IfExists }, @{" WAIT " link Wait } and other methods if you want to make sure that you have run the program successfully. IMPORTANT : Some programs require a large amount of stack to run. The default stack passed with the above CLI/RUN commands is 4000 bytes. You can change this with the @{" SetStack " link SetStack } command, to any number you want. @ENDNODE @NODE Say SAY Text This command writes the Text you give it to your window's default output window (if any). ex : Roses = "red" Violets = "blue" SAY "Roses are $Roses, violets are $Violets \n" This should print out "Rose are red, violets are blue" The \n is a @{" Special character " link "command_lines" } @ENDNODE @NODE Screen Screen PublicScreenName Specifies the name of the Public screen that the window will open on. If you do not declare this command, the gui will open on the FRONT most screen. This is the most intuitive setting as the guis will follow the user to whichever screen he is currently at. In all cases, the front screen can be denoted with '*' (asterisk) If the screen is not found, the window will open on WorkBench, if available. Example : Screen CygnusEdScreen1 Note : ***** SCREEN NAMES ARE CASE-SENSITIVE ! ***** @ENDNODE @NODE SearchVar SEARCHVAR Variable String CI|CS FIRST|NEXT This command will search a variable for a string. Variable is the variable you want to search String is the string you are looking for CI or CS means Case-Sensitive (CI) or Case-Insensitive (CI) FIRST|NEXT is used to let you find multiple occurances of the string you're looking (see below) The result, if found, can be read from @{" internal variables " LINK "iv_search"}. Example : x = 'That is a test string' SearchVar x "is" CI FIRST ; now $$Search.pos will = 5 which is the character that "is" ; starts at pos = $$Search.pos say "$x[$pos]\n" ; will print out : "is a test string" SearchVar x is CI NEXT ; now $$Search.pos will = "" (nothing) because there are no more ; occurances of the word "is" in variable x. @ENDNODE @NODE SendRexx SENDREXX RexxPortName CommandLine This is the command used to send ARexx messages to other programs. RexxPortName is the name of the Rexx port to which you want to send the command. * Port names are always Case Sensitive ! CommandLine is the Rexx command you want to send. example : SendRexx rexx_ced 'open $Myfile' - will send the command to load a specified file to the rexx port of the CygnusEd editor. "rexx_ced" is CygnusEd's rexx port name. This command sets the following internal variables : @{" $$RETCODE " LINK "iv_retcode"} contains the value returned by ARexx - 0 means OK @{" $$REXXRET " LINK "iv_rexxret"} contains the value returned in RESULT2, if any. If you don't know anything about ARexx, you're not alone - neither do I. You don't have to know anything though to use this command. Most programs provide ARexx commands. All you have to know, is what these are and use them as you would use CLI commands. You can do a lot with this command, as you will see. Example : @{" Run Gui " system "gui guis:docs/tutorials/Clock.gc"} @{" Gui4Cli Source " link "guis:docs/tutorials/Clock.gc/Main"} @{" ARexx Source " link "guis:docs/tutorials/Clock.rexx/Main"} @ENDNODE @NODE Set SET [parameter] [value] With this command you can set the following GLOBAL parameters : BUFFERS BufferSize Gui4Cli uses about 14 internal buffers to do all translating, command line forming etc. Their size is, by default, 1024 bytes. This means that your command lines, variables, listview lines, rexx commands etc, can *not* be longer than this size. You can increase (or decrease) the buffer size with this seting. ex: Set Buffers 2000 Set buffer size to 2000 bytes - remember Gui4Cli will allocate 14 of these buggers.. Note: you can learn the current buffer size with $$G4C.BUFFERS LVSORT NORMAL|DATE|SIZE|EXTENTION Will globally set the method by which @{" Directory listviews " LINK "DirList"} will sort their list. If you give DATE for example, the most recent dirs/files will go to the top. The default (NORMAL) is to sort them alphabetically. ImDEV/ImVOL/ImASN/ImDIR/ImFILE ImageAlias Will set the @{" images " LINK "Images"} that will be displayed in Dir LVs, for the respective items. So will cause the image named "mydevimage" (which must have been loaded first with LoadImage) to be displayed in front of every Device name in the Device list.. Looks great :) Note also that you can show images anywhere in listviews by stating: > this is a ESC\MyImage\ test.. (where ESC is the escape char) SndOpen/SndClose/SndGad/SndRMB/SndKey Alias Will set the default @{" sound " LINK "Sound"} that will be used everytime the given event happens. So, will cause the sample "MySample" (which must have already been loaded) to be played every time a window closes. "SndGAD" - happens everytime any gadget (for which you have not declared another specific sound with the Attr/SetAttr commands) is selected. Respectively, "SndRMB" happens when the RightMouseButton is pressed and "SndKey" when any key is hit. You can set all these very easily from the Gui4Cli.gc gui. SPEAK Rate/Pitch/Sex/Mode/Volume/Freq Set parameters for speaking voice (see @{" Speak " LINK "Speak"}) DEBUG ON|OFF This will enable or disable the internal debugger of Gui4Cli. Use CONTROL-D to do the same thing.. You can get debug information in two ways : One is by starting Gui4Cli in @{" DEBUG " LINK "Options" 13} mode. This will show you exactly which line is executed, as it is written in your file. Or you can use this new form of DEBUG which can be started/stopped at any time, without having to start up G4C in debug mode. The new one will show you cryptic statements instead of KeyWords and Opera- tors, but is otherwise same. Also, if you press any key while in any debug mode you'll get it's Code & Qualifier values. DEBUGVARS ON|OFF After v3.5 the DEBUG mode will no longer print out the GET:/SET: variable value - statements any longer. You can SET DEBUGVARS ON|OFF, if you prefer the old method. DEBUGSTEP ON|OFF If you set this ON, Gui4Cli will pop up a requester before every command line is executed, when in DEBUG mode. This allows you to control execution. You'll probably never need it - I used it in tracking down enforcer hits.. HELP ON|OFF Will start/stop the on-line help system. See also @{" GadHelp " link GadHelp} GRID GridSize Will set the Grid size for @{" Visual Editing " link GuiEdit } ex : Set grid 5 LOAD_DIR DirName Will set the directory that the @{" Status " LINK "Status"} Requester LOAD button will open on. TRANSLATION ON|OFF Usually all arguments will be @{" translated " LINK "Translation"} by Gui4Cli. In some cases though you may not want something translated. With this command, you can set the translation OFF. This will last for one round of command executions. Translate will automatically be set on again after all commands have executed. DEEPTRANS ON|OFF Setting DEEPTRANS OFF will stop Gui4Cli from translating variables within variables. As with TRANSLATION, this will only last for one execution cycle. This comes useful in many situations such as the filetype checking routines in @{" guis:tools/getfiletyle " LINK "GUIs:Tools/Rtn/GetFileType/MAIN"} which are now much faster. OUTPUT ConsoleSpecification All output from CLI commands or Gui4Cli error reports, will go to the @{" default console " LINK "Options" 36}. If you want to change this console you can do it with this. You can specify KCon: for example, or NIL: FILEPATTERN FilePattern The default file pattern for all file requesters, is : ~(#?.(bak|info|auts))") You can change this with this command. EDITOR EditorName The default editor which will be called upon to edit the window when the user presses CONTROL-E, is "c:ed". Change it with this. GUIPATTERN NewPattern The default GUI file name extension for Gui4Cli is #?.gc (i.e. anything ending in ".gc" - subfiles end with ".g", ".g1" or any other scheme that you may want to make up..) You can change this (but it is not a good idea) NOVOL ON/OFF Global flag to Show or Hide the Volumes when showing the device list in directory listviews. MARGINS Side/Top/TopDistance Globally sets the title (TITLE Attribute) margins: Side : the distance the title will be from the side of the gadget (if the title is LSIDE or RSIDE) Top : The distance it will be from the left ot right side when the title is ABOVE or BELOW the gadget TopDistance : How far the text should be placed from the top or bottom sides of the gadget. - The default setting is : 5/10/1 TBMARGINS Horizontal/Vertical Globally set xTEXTBOX inner margins, ie the distance the text should be from the side of the box. (default = 5/4) @ENDNODE @NODE SetColor SETCOLOR GuiFile ColorNumber R G B This command allows you to change the color of a screen. GuiFile Is the Gui4Cli file who is, or will, open on the screen whose color you want to change. ColorNumber The number of the color you want to change. The first color (the background) is 0. R G B 3 numbers, ranging from 0 to 15, specifying the values for Red, Green and Blue respectively. Ex : SetColor MyGui 0 10 8 8 - will set the background of the screen that MyGui is (or will) open on, to a yukky brownish color. @ENDNODE @NODE SetGad SETGAD GuiFile GadID/range ON|OFF|SHOW|HIDE This command will set the specified gadget ON or OFF or make it appear (SHOW) or disappear (HIDE) @{" GuiFile " LINK "GuiNames"} - The name of the GUI file the gadgets reside in. GadID - The @{" ID number " LINK "GadID"} you have given to the gadget, *or* a range of gadgets denoted as First/LastGadget Example : SetGad MyGui.gc 10 OFF - will set Gad No.10 off SetGad MyGui.gc 5/15 HIDE - will hide gadgets Nos. 5 to 15 inclusive The SHOW and HIDE keywords will have no immediate visible effect unless and until the @{" ReDraw " link "redraw" } command is used. ------->>>> A note about ListViews: LVs get updated if OFF, but not updated if HIDEn (even if visible) It is *much* faster to HIDE an lv and act on it (with commands like lvadd, lvput etc) and then SHOW it again, than to have the LV updated continuously while actions are going on. When you show it again, you must "nudge" it into redrawing itself - with LVMULTI SHOW or LVMOVE 0 @ENDNODE @NODE SetGadValues - SETGADVALUES GuiName Will store the values of all the gadgets of a gui into their respective variables. When you declare a gadget which has a value, say : xHSlider L T W H Title Variable Min Max Current ShowStr (here the value is the Current level) or... xTextIn L T W H Title Variable StartingText Bufflength (here the value is the StartingText) Gui4Cli does *not* automatically place the starting value of the gadget in it's Variable. You must do this manually - usually in the xONLOAD event. This provides better control (but can also be a pain..) With this command (which you would also issue, most probably, in the xONLOAD event) you can set the starting values for all the gadgets in a gui, in one go. @ENDNODE @NODE SetPointer SETPOINTER GuiFile #Image/DEFAULT/HIDE Will allow you to change the pointer which will be used whenever the given gui's window is active. The pointers you can set are: * #Image This will take an image (which you must have loaded previously with the @{" LoadImage " LINK "Images"} command) and make it the window's current pointer. You must precede the image name (ie its alias) with a '#' character : Pointers have restrictions. They must be drawn using only the first 4 colors of the screen's palette, and must be a maximum of 16 pixels wide. Otherwise it will look lousy.. * DEFAULT Set the user's default preferences pointer. * HIDE Hide the current pointer. Note that when when hidden, the pointer is still ative, ie you can click with it - you just can't see where it is.. If you want to block user input, use <@{" GuiWindow " LINK "GuiWindow"} gui Wait> !!! IMPORTANT !!! If you have set a custom pointer and then free the image while the pointer is active you'll get a crash like you wouldn't believe. To avoid this, Gui4Cli will warn you with an ERROR message and abort. The correct way to quit a gui which has a custom pointer is : xOnClose SetPointer #this default ; use the default pointer FreeImage MyPointerImage ; now you can free the pointer GuiQuit #this ; quit now if you want.. @ENDNODE @NODE SetScreen SETSCREEN GuiFile ScreenName This will reset the name of the screen the GUI should open on. If the window is already open, you will have to close it and reopen it in order for the new screen to take effect. If the screen is not found, the GUI will open on the Workbench (if available) To state the "Front most Screen" you can give an '*' (asterisk). See also the @{" Screen " link screen} global command. @ENDNODE @NODE SetScreenTitle SETSCREENTITLE GuiFile NewTitle Will set the title shown in the Screen's TitleBar of the Screen that GuiFile is open on, to "NewTitle". This will be visible whenever the given window is the active one. Otherwise the default screen title will be shown. Ex: > SetScreenTitle MyGui.gc "My gui's window is active" @ENDNODE @NODE SetStack SETSTACK StackSize You may need this command when using RUN or CLI commands. Gui4Cli provides each program you run with 4000 bytes of stack. Some programs need more than that though. This command is how you do it. example : SetStack 10000 RUN "ABigProgram" SetStack 4000 Note that we change the stack size before we call the RUN or CLI command, and we change it back to the default size after RUNning, so that the next RUN/CLI does not inherit the big stack size. @ENDNODE @NODE SetVar SetVar Variable String With this command you can put a value (String) into a variable. If the variable does not already exist, it will be created. Variable - The name of the variable String - Any character, sentence, text, number - whatever. Example : SetVar MyVariable "This is my variable and nobody touch it!" *** NEW with V2.2 is that you can do this : MyVariable = "This is my variable and nobody touch it!" instead of using SetVar. It is much more logical. SetVar still works though. @ENDNODE @NODE SetWintitle SETWINTITLE GuiFile NewTitle Will set the title shown in the Window's TitleBar to "NewTitle". Ex: > mydir = $$G4C.DIR > SetWinTitle MyGui.gc "The current dir is $mydir" @ENDNODE @NODE ShareMenu SHAREMENU GuiName This command will allow a gui (call it Gui1) to share the menus of an other gui (call it Gui2). > ShareMenu Gui2 When Gui1 is opened, it will have the same menus as Gui2. When a menu is selected it will be as if the menus of Gui2 was selected and all commands attached to it will be executed. The gui whose menus are being shared by others will *not* be allowed to quit unless all the sharers have been closed first, since we need it's commands. Gui4Cli will look for Gui2 when Gui1 tries to open - not when it tries to load itself. So when Gui1 is closed, Gui2 is free to quit (unless there are other open guis sharing it's menus). If Gui2 is not found when Gui1 tries to open, Gui1 will open without menus. The best way of using this in a multi-gui application would be to have a menu-only file that you would load and let all guis share it. @ENDNODE @NODE Sound Sound Effects Standard mono IFF Samples, up to 64k in length, can now be loaded and used as sound effects or reminders. The commands that handle them, are similar to the image handling commands : - LOADSOUND FileName Alias - will load the sample and name it "Alias" - FREESOUND Alias - will free the above sample - PLAYSOUND Alias - will play the sound once - SETSOUND Alias VOLUME/SPEED value Will set the VOLUME (1-64) or the SPEED (124-1000) ie the pitch. Sounds can be used as effects on all types of gadgets, and on other events like window open/close, RMB and xOnKey. There are 2 ways you can do this. 1.- You can define the sound effects globally, and these will be used in all guis: > @{" SET " LINK "Set"} SndOpen/SndClose/SndGad/SndRMB/SndKey Alias The easiest way to set these is from the Gui4Cli.gc gui (called from the main Gui4Cli requester in the WB tools menu) 2.- Or, you can define a different sound for every gadget, or key or window etc, using the Attribute system, with: > @{" SETATTR " LINK "Attr"} mygui.gc/1 SOUND mysound ATTR SOUND mysound The sound will be played every time the event is triggered. An attribute, if defined, will take precedence over a global sound. Note that with ATTR, sounds can also be attached to xONOPEN, xONCLOSE, xRMB and xONKEY events. Example: (set the sound globally for all windows opening) FreeSound MySound ; free the old alias (if any) LoadSound DH0:SomeSound MySound ; load new sample under same alias Set SndOpen MySound ; set the sound Example: (set a different sound for a specific window opening) xOnLoad ; load the sound in the xOnLoad event LoadSound DH0:SomeSound MySound xOnOpen ; Set the attribute for this window opening ATTR SOUND MySound xOnQuit ; free sound on exit FreeSound MySound @ENDNODE @NODE Speak SPEAK TextString Will use the "translator.library" (LIBS:) and the "narrator.device" (DEVS:), both of which you must have, to speak the given text. The speaking is done synchronously - i.e. Gui4Cli will stop and wait for the speaking to finish before proceeding (I tried to make it asynch, but couldn't get it to work..) > Speak 'What a nice day!' There are several speaking parameters which can be adjusted. This can be done with the SET command : - SET SPEAK Rate/Pitch/Sex/Mode/Volume/Freq Will change the voice used in speaking to the new values you give. These can be: Default Min Max Rate 150 40 400 Pitch 110 65 320 Sex 0 0 1 (0=Male, 1=Female) Mode 0 0 2 (0=Natural, 1=Robot, 2=Manual) Volume 64 0 64 Freq 22200 5000 28000 So, if you want to reset the defaults, you would say: > SET Speak 150/110/0/0/64/22200 Example : @{" Run Gui " system "gui guis:docs/tutorials/Speak.gc"} @{" Source " link "guis:docs/tutorials/Speak.gc/Main"} There is also an extended structure with more settings, things like "pertrubation" and "centralization" but I've no idea what they do or mean, so I'll leave them alone.. If you know and can tell me which are important and how they can be easily implemented, tell me.. @ENDNODE @NODE Status STATUS This is a command that opens the "Status" requester, from which you can see how many GUIs are loaded/open as well as Load, Open, or Unload GUI files. From here you can also QUIT. Upon quitting, all xOnClose event commands are executed for windows which were open, and all xOnQuit event commands for all loaded files (if any are defined). Note that the meaning of the GUI file name extensions, are : MyFile.gc - This is GUI Command file (.gc) MyFile.g - This is a GUI help file, i.e. a GUI which is supposed to be loaded and in general operated from another GUI There is no difference in the structure of the files. The difference is in their operation only. You need not use the above naming conventions if you don't want to. @ENDNODE @NODE Stop STOP (No arguments) This will stop all execution of commands, DEAD! When a STOP command is found, the program will return to its normal state of waiting for something to happen. Use it for getting out of trouble, from wherever you may be. @ENDNODE @NODE System Things you can WAIT for or see if they exist (with IFEXISTS) ================================================================= With the @{" IFEXISTS " LINK "IfExists"} and the @{" WAIT " LINK "Wait"} commands, you can either wait, or see if the following system items exist : FILE - Full path and filename PORT - Public Message Port Name SCREEN - Public Screen Name GUI - Gui4Cli file (True if file is loaded) WINDOW - Gui4Cli Window (True if the gui's window is open) VARIABLE - the name of an internal Gui4Cli variable - Env: variables can be checked by filename with the FILE keyword DIRECTORY- name of the directory DEVICE - A Dos Device such as DF0 - WITHOUT the : (Ram NOT Ram:) VOLUME - A Dos Volume - WITHOUT the : ASSIGN - An assignment - WITHOUT the : DOS - A Device OR a Volume OR an Assignment (i.e. any of the above 3) Gui4Cli Files and Windows are referred to by their file names only and not the full path of the file. Note : If you want to use RX to launch ARexx programs, you may want to check first that RexxMast has been started up. RexxMast opens 2 ports REXX and AREXX, so you can do this: IfExists PORT REXX ; Ok - RexxMast is running else cli 'RexxMast' endif @ENDNODE @NODE Text Text L T W H Text Length BOX|NOBOX This event is a simple text display with a BOX or with NOBOX drawn around it. The L T W H are the same as for other gadgets. The Text is the default text to be shown in the beginning. This can easily be changed with the update command. Length, specifies the length of the buffer you want - i.e. the maximum number of characters likely to be shown in this text box. It is important that you set this number correctly, otherwise the text will be clipped. BOX or NOBOX are keywords denoting whether you want a BOX drawn around the text or not. IMPORTANT : No commands other than Gadget modifiers (GadID, GadFont etc) can be attached to this event, as these will never be executed (since the gadget can not be selected and so never "happens") @ENDNODE @NODE TextFile TEXTFILE FileName -----> ### This is a PARSER command - i.e. it is executed while Gui4Cli is reading your file. It will create a file named whatever "FileName" you give and will start writing into the file all the lines following this command, untill the ending marker ### is reached. example : TEXTFILE ram:MyFile This is some sample text etc.. blah.. blah... My life story.. etc.. ### NOTE that the "###" which marks the end of the file *MUST* be at the begining of a line otherwise it will not be recognised. This is a nice command for embedding small files into a gui, such as ARexx scripts, data for listviews etc. It can appear anywhere in a gui and does not change the flow in any way - i.e. it's like it doesn't exist. Example : @{" Run Gui " system "gui guis:docs/tutorials/TextFile.gc"} @{" Source " link "guis:docs/tutorials/TextFile.gc/Main"} @ENDNODE @NODE Translation TRANSLATION Translation is the the process whereby Gui4Cli will substitute the contents of a variable for it's name, if the $ (dollar sign character) is placed in front of the variable name. Example : > MyVar = "This is my variable" > Say $MyVar Here we put the string into the variable and then print the variable contents. The output will be : > This is my variable Translation is a *very* important concept in Gui4Cli, and one which you *must* understand. Translation is done automatically by Gui4Cli on ALL arguments of all EVENT COMMANDS (be they numbers or strings), making it very flexible. You can, for example, say : > Update $MyGui $MyGadgetID $MyNewValue and Gui4Cli will update the given gadget in the given GUI, to the given NewValue, according to whatever these variables contain. BTW : AmigaDOS also does this translation stuff, substituting the contents of an Environment (ENV:) variable, when ever a $ sign is found. @ENDNODE @NODE TTGet TTGET FullPath/IconName (Without the ".info" extension) This command reads ALL the tooltypes in your GUI's icon and automatically converts them into @{" variables " link "variables"}. This is useful for any situation where you need to give your GUI a configuration. Tooltypes for GUI icons MUST contain an equal "=" character. An example tooltype would be: > EDITOR=Work:Text/Editors/Editor TTGET would understand this as: > VariableName=VariableContents Everything BEFORE the "=" character becomes the NAME of the variable. VariableName must NOT contain spaces. Using the example tooltype, you would get a variable called: > $EDITOR Everything AFTER the "=" would become the variable's CONTENTS. So we have a variable called $EDITOR which contains: > Work:Text/Editors/Editor The Variable's Name will always be converted to Upper case to avoid confusion, since Gui4Cli variables are case sensitive, and will be added to the GLOBAL variable list. To use TTGET in your GUI, you must first initialize (set the default value) of the variable, preferably early on in the script. For example: > EDITOR = "default value" TTGet Dh0:MyDir/MyGui.gc When using TTGET you must supply the FULL path and filename of your GUI icon, without the ".info" file extension. @ENDNODE @NODE Update UPDATE GuiFile GadID Value This command will update the specified gadget to display the new value you have specified. GuiFile - The name of the GUI file the gadget resides in. GadID - The @{" ID number " LINK "GadID"} you have given to the gadget Different gadgets have different update values you must give, as follows : xButton - No update xCheckbox - 1 = Checked, 0 = Unchecked xSlider(s) - New current level of slider xListview - New line number - 1st line is line 0 xRadio - Number of chosen button - 1st choice is No 0 xCycler - Number of current choice - 1st choice is No 0 xTextIn - New Text Text - New Text xTimer - New Time/Interval - will also re-start the timer xNotify - Name of new file/dir xHotKey - New HotKey combination xTextBox - New text - note that when the textbox is redrawn by update, it will cover any other gadgets that may be overlayed on it! Example : For a xTextIn type gadget in file MyGui.gc, having an ID of 3 : > Update MyGui.gc 3 "New Text" For a Cycler type gadget.. make the 3rd choice the current one. > Update MyGui.gc 5 2 @ENDNODE @NODE UseTopaz USETOPAZ (No arguments) Forces the GUI to use Topaz.font, no matter what gadget fonts or WinFonts are declared. Use this to override fonts specified which you may not have. @ENDNODE @NODE Variables VARIABLES =================================================================== Variables are like small temporary files. They provide a place where you can store some text, and refer to it whenever you need it, by using the name of the variable. Gui4Cli has 3 types of Variables : @{" Normal Variables " link "Variables_Normal" } - These are the standard Gui4Cli variables (Case Sensitive) @{" ENV: variables " link "Variables_Env" } - ENV: Variables are actually small files in the ENV: directory which is in your Ram disk. @{" Internal Variables " link "Variables_Int" } - Internal variables are there to provide you with information about the current state of the system. You can read them, but you can NOT set them. When working with variables you use the following notation : MyVariable - is the name of a Gui4Cli Variable called MyVariable $MyVariable - is the contents of this Variable .MyVariable - is the name of an ENV: Variable called .MyVariable $.MyVariable - is its contents $$G4C.Path - is the contents of an Internal variable containing Gui4Cli current path. These vars can not be set. ALL of the parameters of ALL EVENT COMMANDS are translated before being executed, so if you give the command : > SetScreen $ScreenName ... and if the Variable ScreenName contains the words "MyScreen", > SetScreen MyScreen ... will be the command that will be executed. @ENDNODE @NODE Variables_Env ENV: Variables An ENV: Variable MUST start with a . (full stop character) SetVar .MyVar "This is my env variable" or .MyVar = "This is my env variable" will both create a small file in the env directory called ".MyVar" and containing the above string. You can also declare/set an env variable with a double full stop : ..MyVar = "This is my env variable" This will create a env: variable by the name of "MyVar" i.e. 2 fullstops will result in a variable without full stops. This comes in useful when you want access to env: variables set by other programs. Env variables can be used just as if they were normal vaiables. The [start][length] will also work on them. Env Variables are much slower than normal variables (although quite usable), but since they are actual files which AmigaDOS can refer to they are sometimes extremely useful. @ENDNODE @NODE Variables_Int INTERNAL VARIABLES : ============================================================= Internal variables do what functions would in other languages. They are there, so you can get various information about the system and the guis running. You can *not* set them - only read them. They can be accessed by placing a double dollar sign in front of them : > curdir = $$G4C.DIR for example, will store the name of the current dir Gui4Cli is at, in variable "curdir". These are the currently defined @{" Internal Variables " link "Variables_IntList"} It is very important to understand how internal variables work, before using them extensively. Internal variables always try to show the values of the last thing that happened. You can, if you need these values later, store them into variables, as they are going to change the next time something happens. Gui4Cli works in "Command Execution Cycles" (Sounds much more impressive than it is :) This means that it sits around waiting for an event to happen, like the clicking of the mouse, a keypress etc.. When such an event happens, if it is declared in the gui it happens in, the commands attached to this event start executing. Gui4Cli may, while executing, jump to subroutines in other files, come back etc and it will finally stop. That's the end of the "command execution cycle" - The DEBUG mode will show this clearly. All the internal variables below, will (unless otherwise stated) remain valid throughout the life of such a cycle. Thereafter the user might have done anything and you can't be sure that the values are correct. For example, when a button is hit, the GAD.L etc values will be correct for that button, throughout the life of a command execution cycle (unless you issue an INFO command and thereby change the gadget that Gui4Cli thinks of as "current") When something else happens, the above values are history. The values returned will be the ones of the new event. example : (file name = test.gc) ; Slider (gadget No 1) has a width of 100 xHSlider 10 10 100 15 Title Var 0 100 50 %2ld gadID 1 ; button (gadget No 2) is 200 pixels wide xButton 10 50 200 50 button2 gadID 2 ; here $$GAD.W = 200 i.e. the width of the button we clicked ; now we tell Gui4Cli that we want information on the slider Info GAD test.gc/1 ; now $$GAD.W = 100 - i.e. the width of the slider Only the User (through his actions) or the INFO command will ever change the value of a variable. -------------------------------------- HOW GUI4CLI SEES INTERNAL VARIABLES : -------------------------------------- In order to make these functions as fast as possible, the checking of the variable names is done only by checking the first 1-2 letters. So : - $$SYS.Time - can also be written as $$SYS.T or $$SYS.TeriyakiSauce and Gui4Cli wouldn't know the difference. The checking is done on as many letters as it takes to avoid any possible conflict between variable names, so, for example $$sys.date and $$sys.day have the 1st 3 letters checked. You should *not* however depend on this behaviour, since other conflicting vars may be added later.. @ENDNODE @NODE Variables_IntList INTERNAL VARIABLES ==================================================================== Internal variables tell you various things about the present state of the system. You access them by putting a double dollar sign in front - ex: $$G4C.PATH. This is a full list of the available vars: @{" G4C " LINK "iv_g4c"} Gui4Cli's internal parameters (current dir etc..) @{" RetCode " LINK "iv_retcode"} Return code from dos and arexx commands @{" RexxRet " LINK "iv_rexxret"} Result_2 from arexx @{" Call.Ret " LINK "call"} Return from a Call command @{" Win " LINK "iv_window"} Current Gui4Cli window @{" Screen " LINK "iv_screen"} Screen of current window @{" Gad " LINK "iv_gadget"} Current (most recently selected) gadget @{" Mouse " LINK "iv_mouse"} Mouse coordinates etc @{" Palette " LINK "iv_palette"} Current Palette gadget @{" LV " LINK "iv_listview"} Current Listview @{" TextIn " LINK "iv_textin"} Current TextIn gadget @{" Image " LINK "iv_image"} Image information @{" Help " LINK "xOnHelp"} For the xOnHelp event @{" Parse " LINK "iv_parsevar"} Results of ParseVar command @{" Key " LINK "iv_gadkey"} RawKey & VanKey values @{" Search " LINK "iv_search"} Results from the SearchVar and LVSearch commands @{" Sys " LINK "iv_system"} Info on the system (active window title etc) @{" Rand " LINK "iv_rand"} Random number generator @{" Mem " LINK "iv_mem"} Memory information @{" Files " LINK "iv_file"} Info on a given file @{" Variables " LINK "iv_var"} Info on a given variable @{" Obsolete " LINK "iv_obsolete"} Forget them.. @ENDNODE @NODE Variables_Normal NORMAL VARIABLES : ===================================================================== Normal variables are the most common in Gui4Cli. They are the ones you can declare with a simple statement like : myvar = 3 - or myvar = 'This is my variable' - or SetVar myvar 'This is my variable' You can thereafter refer to their contents by putting a $ sign in front : > say '$myvar' > should print out : This is my variable *** Important : Normal variables are CASE SENSITIVE (i.e. myvar is not the same as MyVar) Note that you can hit CONTROL-V to get a full listing of all variables currently declared by all guis loaded. Furthermore, you can "Set Debug On" to see when and how variables are set or read while the guis are executing commands. NORMAL VARIABLE TYPES: ====================================================================== GUI Variables ------------------------------- Normal variables are kept in lists. Each GUI has such a list, where it keeps all it's variables. You can get/set the variables of your gui's list, by just declaring: > MyVar = "Something" If you want to get/set another Gui's variables, you can do this: > OtherGui.gc/MyVar = "SomethingElse" This will set variable "MyVar" of Gui "OtherGui.gc" to "SomethingElse" Similarly, to get the results, you would do: Say $MyVar --> would print: "Something" Say $OtherGui.gc/MyVar --> would print: "SomethingElse" LOCAL (Event) Variables ------------------------------- Variables can also be attached to each and every EVENT. To do this however, you must declare the variables you want to use with the @{" LOCAL " link Local } command : xRoutine ExampleRoutine ; an event such as a routine or whatever Local var1/var2/var3 ; declare 3 variables var1 = 'something' ; use as normal variables.. say '$va1[0][4]\n' ; but only in this event Local variables are only visible within the Event in which they are declared. They can not be seen or set from anywhere else. This is usefull for throw-away variables you want to use for temporary storage places etc.. GLOBAL Variables : ------------------------------ There is also a "GLOBAL" variable list, which is always present and which can be accessed from any gui, anytime, by putting a '*' character in front of the name. So, to set a Global variable, you would do : > *MyGlobalVar = "Something" and to read it: > Say $*MyGlobalVar Global variables are usefull since they are accessible from everywhere. I.e. you do not have to rely on a certain gui being loaded to have them available. The VARPATH command : ------------------------------ If you are building a multi-gui application you can use the @{" VarPath " link VarPath } command, with which you can declare a "Variable Search Path" and in effect "merge" the variables of many guis. FULL VARIABLE NOTATION : ====================================================================== Although for normal use you just declare the variable name as above, normal variables may have the following full template : gui/name[+-start][+-length] and Global variables *name[+-start][+-length] In all the above, only the name is required. All others are optional. THE RULES OF THE GAME : ----------------------- - As we said, the 'gui' part, is the name of the Gui that the variable belongs to. If no 'gui' name is given the variable is automatically assumed to belong to the gui it resides in. - [start] is the character of the variable you want to start at. - [length] is how many characters to consider - If you give a [start] which is more than the length of the variable you'll get "". - If you give a length that will pass the end of the variable, then only the actual length of the variable will be considered. Variables will *not* be expanded to accommodate [start] or [length]. - If the [start] is omited it means '0' i.e. from the start of the var. - If the [length] is omited it means the rest of the variable. - If [start] is negative it means from the *end* of variable. - If [length] is negative it means "count from right to left" EXAMPLES : ------------------------ var = '0123456789' res = $var[3][3] res will now be = '345' If these variables were in an other file called "mygui" and you wanted to refer to them, you would do : mygui/var = '0123456789' res = $mygui/var[3][4] now res will equal '3456' or if 'var' was a global variable: *var = '0123456789' res = $*var[3][4] ok, up to now ?.. res = $var[3] res is now '3456789' since we did not give a length. res = $var[3][20000000] res is still '3456789' since res will not be expanded. And what's more, it works both ways: var[3][2] = 'xx' or var[3][2] = 'xxxxxxxxxxxxxxxxx' will both set var to: '012xx56789' More stuff : var[-1][1] ; is the last character of a variable var[-3][3] ; are the last 3 characters of a variable var[3][-3] ; are the first 3 characters of a variable var[0][3] ; are, again, the first 3 chars and so on... Variables in the brackets : --------------------------- - In the "Gui/Name[start][length]" notation, for internal, pain-in-the-ass related reasons, the "Gui" and "Name" parts can *not* themselves be variables. (There are ways of circumventing this if needed - see below). However, you can use variables for [start] and [length] : var = "01234556789" c = 0 while $c < 10 say '$var[$c][$c]\n' ++c endwhile Important : Variable "c" as is used above, *must* be a simple direct variable - i.e. it can not contain other variables. Variables within variables : ---------------------------- See also @{" Variables within variables " LINK "Var_in_var"} if you need variable "Arrays" @ENDNODE @NODE VarPath VARPATH VariableSearchPath This command allows you to "Merge" the variables of many guis. First of all, read the section on @{" Normal Variables " link "Variables_Normal"} to understand it. Now.. If you're making an application which will have many guis, you may want to "Merge" their variables, so you don't have to state the GUI part of the name each time, or remember in which of your guis a certain variable was declared: > VarPath "gui1/gui2" will search your gui's variables (always done first) and if not found will continue and search the vars of gui1 then gui2 So if you declare : MyVar = 5 - Gui4Cli will search your gui for variable MyVar. - If not found, it will search gui1, then gui2. - If it finds a variable by that name, it will set it to 5. - If if doesn't find it, it will create a new variable for *your* gui and set it to 5 Similarly, in reading a variable: say $MyVar - Will search your gui, then the varpath, and if not found will return with "" (nothing) You can also have the GLOBAL variable list in your varpath. This is denoted with the '*' character : > VarPath "gui1/*/gui2/gui3" - will search your gui first (always), then gui1, then the global variable list, then gui2 then gui3. The normal way to use Private vars in a multi-gui application, would be to declare VARPATH with all the names of the guis the application uses after it and access the global variables (if needed) using the *MyVar system. You don't have to declare the name of *your* gui in the varpath. This will ALWAYS be checked first. If you do declare it, then it will be searched twice. If the variable is not found anywhere in the varpath and needs to be created, then it will be added to *your* gui's variables. (Unless specifically declared, as in - MyOtherGui.gc/MyVar = 5) @ENDNODE @NODE Var_in_var Variables within variables --------------------------- This is very usefull in many situations such as when you need "Arrays" (or compound variables - or stem variables in arexx..) As explained in @{" Command lines " LINK "Command_Lines"} Gui4Cli will consider \$ as plain $. It will not give it the significance that it starts a variable name. Say you have a variable "X" which contains the name of another variable (say "Y") and you want to know what is in that other variable (Y). > Z = "\$$X" Gui4Cli will translate the above into: > Z = "$Y" i.e. the $ which is preceded by a slash will be written literally and left to stand in front of the contents of $X, resulting in $Y. So, to get at the contents of Y you could do: > Z = \$$X > Say "X contains var $X which contains $Z' This indirection is *very* usefull in many situations, since it allows you to pass variable names as arguments, forming a sort of "array". Example: In GUI "One.gc" > myvar.price = 1000 > myvar.date = "22/10/99" > myvar.name = Dimitris > gosub Two.gc MyRoutine "One.gc/myvar" Now in GUI "Two.gc" we have a routine named "MyRoutine" > xROUTINE MyRoutine VarName As you read in @{" passing arguments " LINK "Passing_Args"}, when this routine is called, the variable "VarName" will be initialised to contain "One.gc/myvar" Now, this is how we can get at the contents of "myvar.price": > price = \$$VarName\.price Now variable "price" will contain "$One.gc/myvar.price" So you can therefafter say: > Say "myvar.price is equal to $price \n" And Gui4Cli will translate "$price" into "$One.gc/myvar.price", see that there is a variable still untranslated and continue and translate "$One.gc/myvar.price" into "1000", i.e. the value we want. This may seem confusing and you'll seldom need it, but its there if you ever do, because we, at Gui4Cli central headquarters, believe that it is every programmers duty to... etc.. @ENDNODE @NODE Wait WAIT @{" SYSTEM " link "system"} Name|~Name Timeout WAIT will wait until the specified SYSTEM items (FILE, PORT etc) are ready or until the timeout is reached. If the item is already ready, the command will return immediately. This command will set the @{" $$RETCODE " link Variables_IntList } internal variable to show you if the given item appeared within the TimeOut limit you specified. 0 = OK. This command is useful when starting up programs, or when writing to files. It does the same job as the @{" IFEXISTS " link IfExists } command, but in a different way. You can also have it's negative form by putting a ~ in front of the Name of the item you want to wait for. The Timeout is in ticks (1/50th of a second) examples : WAIT PORT Gui4Cli 100 - wait for a public message port called "Gui4Cli". If it hasn't appeared in 100 ticks, return, setting $$RETCODE to an error status (i.e. over 0). WAIT SCREEN ~MyScreen 10 - wait for a public screen named "MyScreen" to close. If it hasn't disappered in 10 ticks return, setting $$RETCODE to over 0 @ENDNODE @NODE While WHILE Argument @{" OPERATOR " link "operator"} Argument ENDWHILE AND, OR =================================================================== You use this command as follows : var = 1 ; set var equal to 1 WHILE $var < 10 ; while var is less than 10 say '$var\n' ; print the current value of var ++var ; increase var by 1 ENDWHILE ; go back to WHILE and do it again, ; until $var is 10 - this will print out numbers 1-9 The arguments and operators have the same meaning as for IF, so see it for explanation. OR and AND can be attached to WHILE, just like to IF. You can have While within While, up to 126 levels. A while statement is often called a "LOOP" because it just keeps looping and re-doing the code in between the while/endwhile until the condition you set in the while statement has been satisfied. This is *very* useful in many situations, so learn how to use it! @ENDNODE @NODE WinBackGround WINBACKGROUND SOLID|PATTERN|ICON|IMAGE APen|IconName BPen This command allows you to have nice backgrounds for your window and you can thank Michael Van Elst for giving me the needed backfill hook code for it. The background used can be : SOLID : A Solid color which will be of color APen. - ex : WinBackground SOLID 3 0 Here the last argument (0) is disregarded. PATTERN : A Hash pattern made up of 2 colors. - ex : WinBackground PATTERN 3 1 Here, the background is a pattern made up of colors No 3 and 1 ICON : An Icon which will be tiled to the background of your window. - ex : WinBackground ICON DF0:MyIcon 0 Here, again, the last argument is disregarded. The 2nd argument is the full path & name of the icon, without the .info extension. @{"IMAGE " LINK "Images"}: An image, which *MUST* have already been loaded with the LOADIMAGE command, will be tiled to your windows background. - ex : WinBackground IMAGE ImageAlias(name) 0 The loading of the image can be done in the xONLOAD event, before you have opened the window, so its there, loaded and ready to be used when the window opens. NOTE : The GadTools library was not designed to be used with colored backgrounds, so some gadgets (such as listviews or text-in gadgets) have parts of them which should (if this was a perfect world) have been blanked out by GadTools, instead filled in with the BackGround you give. As I said.. it's not a perfect world.. @ENDNODE @NODE WinBig WINBIG L T W H Title Defines a window at Left(L), Top(T), Width(W), Height(H) Title is a string that will be shown in the TitleBar. ex: WinBig 10 10 200 100 "My first window!" - If Left = -1 the window is centered on the width of the screen - If Top = -1 the window is centered on the height of the screen. - If Top = -10 the window top will be just under the screen title bar. If Width is negative, then the width of the window will be the size of the screen it opens on, minus this negative number. Same for the Height. Example : WinBig -1 -1 -1 -10 "My Window" This is a window centered horizontally and vertically on the screen, of a size -> Width = ScreenWidth-1, and Height = ScreenHeight-10. If Width or Height are more than the screen size, they are reduced so that the window fits in the screen. Windows always have the following 4 gadgets, unless told otherwise (by the WinType command) : - The close button - Closes the window - The Drag Bar - This consists of all parts of the window's Title bar not taken up by other gadgets. - The zoom button - Zips the window to the size defined by the WinSmall command, or, if this command is not defined to size 100, 11 at 0, 11. - The Depth arrangement gadget Window Types can be changed with the @{" WinType " LINK "WinType"} command, with which you can define which of the above gadgets you want and make the window borderless and/or backdrop and/or resizable. All windows have a number of @{" Default Shortcuts " link "winshortcuts" } @ENDNODE @NODE WinFont WINFONT FontName Size UL|BD|IT If you do not specify any gadget fonts (with the GADFONT command), then the default font (the Screen's font) will be used. You may change this, by declaring a global default font (for this GUI) with this command. FontName - The name of the font e.g. Topaz.font Size - The size of the font. If the size is not found, the diskfont library will scale the font to the size requested, but this will not look good. UL|BD|IT - A Mask (see WinType command) specifying whether the font will be UL (Underlined), BD (Bold) or IT (Italic) 010 for example is a Bold font. @ENDNODE @NODE WinOnMouse WinOnMouse LeftOffset TopOffset This command instructs the window to disregard the Left and Top offsets given in the WinBig command and instead open relative to the current mouse position. LeftOffset & TopOffset are the offset from the current mouse position that the window's Left & Top will be. This is a useful command for making small borderless sub-windows. @ENDNODE @NODE WinOnWin WinOnWin GuiName LeftOffset TopOffset This command instructs the window to disregard the Left and Top offsets given in the WinBig command and instead open relative to a "GuiName's" window. GuiName : The name of the Gui File whose window will be used LeftOffset : Left Offset from the GuiName window position TopOffset : Top Offset from GuiName window position @ENDNODE @NODE WinOut WinOut "ConsoleSpecification" Specifies a console window to be used to send any output of CLI commands that are called by the program (if any). It is best NOT to use this command, unless you must, since each new console that you specify with WinOut, takes up extra memory. If there is output, and no console window has been specified, the default window will be used. If Gui4Cli is started from a shell, the shell itself is the default window. If you give the command Run >NIL: (or >NIL: if -1 then the small window will be placed flush to the right side of the screen. Top => if -1 it will be placed under the screen bar if -2 it will be placed at the bottom of the screen Width => if -1 the window will be wide enough to fit the title. Height => if < 0 the height will be the size of the Screen title bar. This size is also the minimum size it will ever be. The default size, if you do not declare a winsmall command, is : 0, -1, 150, -1 @ENDNODE @NODE WinType WinType MASK WinType lets you specify all the gadgets in the window. The MASK argument is a series of 8 numbers which can be 1 or 0 Each number has the following meaning ( 1=Yes, 0=No ) 1st : Close Gadget 2nd : DragBar 3rd : Zoom Gadget 4th : Depth arrangement Gadget 5th : Borderless 6th : Backdrop 7th : Right Resize bar - makes window resizable 8th : Bottom Resize bar - makes window resizable example : WinType 11110001 - This is a standard window with Close,DragBar,Zoom and Depth gadgets since the first 4 numbers are "1". - It is not Borderless or Backdrop, since the next 2 numbers are 0s. - It is resizable, having the resize gadget on the bottom border, since the 7th number is 0 and the 8th is 1. Note that if you want a borderless window, you should give "" as the window title, otherwise the title (and part of the window bar) will be shown. Resizing is usually proportional, but you can controll how each gadget should resize itself through the @{" Resize " LINK "at_resize"} attribute. @ENDNODE @NODE Workbench WORKBENCH OPEN|CLOSE - will open or close the Workbench Currently I have a weird problem with this, in that the Wrokbench will close down again as soon as I open it. I don't know if it's Gui4Cli or some other program doing it.. Stay tuned.. @ENDNODE @NODE xAppIcon xAPPICON L T IconName Title Variable ON|OFF This command defines an AppIcon on the workbench. L and T are the position that the appicon will appear at on the workbench. Negative values, allow the Workbench to decide where to put them. IconName : The name of the icon to be used (no .info extension) Title : The Title that will appear beneath the icon Variable : The name of the variable where the names of any files whose icons were selected when the user clicked on the AppIcon, will be placed. ON|OFF : The starting state of the Gadget. If OFF, it will not appear if ON, it will. You can declare a GadID for this event and SetGad it ON or OFF at any time. @ENDNODE @NODE xAppMenu xAPPMENU AppMenuName Variable ON|OFF This Event will place an AppMenuItem at the Tools Menu of the workbench. The Variable is where the names of any files whose icons were selected when the user chose the AppMenuItem, will be placed. ON or OFF is the starting state of the menu item. If it is OFF, it will not be shown. You can give an ID number (see the GadID command) to this event and SetGad it ON or OFF whenever you want. @ENDNODE @NODE xAppWindow xAPPWINDOW Variable Variable : The name of the variable where the names of any files whose icons were dropped into the AppWindow will be placed. When you declare this event, you also make the window an AppWindow. No other action is needed. An AppWindow can not (currently) be switched ON or OFF. Only one xAppWindow event can be declared per GUI. If you declare 2, the 2nd one will be disregarded. @ENDNODE @NODE xArea xAREA L T W H COMP|BOX|NONE This is a area hit gadget, like an invisible Button. Nothing will be shown unless the gadget is hit, whereupon it will COMP = complement the area, or BOX = draw a box around it, or NONE = leave it alone. This event is useful, if you want to make something like an image map, for example. @ENDNODE @NODE xButton xBUTTON L T W H Title Specifies a Button Type gadget, at (L)eft, (T)op and of size (W)idth, (H)eight with the "Title" text on it. Example : xButton 10 20 100 15 "My Button" Buttons are buttons - you just press them and they do their commands Icons (xICON) can be used in exactly the same way. Example : @{" Run Gui " system "gui guis:docs/tutorials/Buttons.gc"} @{" Source " link "guis:docs/tutorials/Buttons.gc/Main"} @ENDNODE @NODE xCheckBox xCheckBox L T W H Title Variable OnText OffText ON|OFF Specifies a checkbox type gadget at Left, Top, sized Width Height. The Title will be placed next to the gadget. Variable is the name of the variable that will hold the value. Checkbox type gadgets have two states : Checked (ON) & Unchecked (OFF) If the gadget is ON, OnText will be placed in Variable, otherwise, OffText. ON|OFF specify the starting state of the gadget, when the window first opens. Example : xCheckBox 30 15 16 16 "CheckBox" ChkVar "Yes" "No" OFF Here, if the user checks the gadget, then the variable ChkVar will contain the word "Yes" Example gui : @{" Run Gui " system "gui guis:docs/tutorials/CheckBoxes.gc"} @{" Source " link "guis:docs/tutorials/CheckBoxes.gc/Main"} @ENDNODE @NODE xCycler xCYCLER L T W H Title Variable This is a cycler at L, T of Width, Height. It's value will be placed in Variable. The Title (if any) will be placed to the left. You MUST tell a cycler what fields you want it to have, i.e. what will be written on it's face every time the user clicks it. You do this by attaching to it CSTR (Cycler-String) commands, as follows : xCYCLER L T W H Title Variable CSTR Title Value CSTR Title Value .. etc .., up to 12 CSTRs The Title of the CSTR is what will be placed on the face of the button and the value is what will go into the Variable. The 1st field in cyclers & radio buttons is No 0. Example : @{" Run Gui " system "gui guis:docs/tutorials/Cycler.gc"} @{" Source " link "guis:docs/tutorials/Cycler.gc/Main"} @ENDNODE @NODE xHotKey xHOTKEY KeyCombination ON|OFF Gui4Cli now installs a Commodities Exchange Broker through which you can define various HotKeys. These have the advantage that that they can be "heard" from anywhere - i.e. even if they are entered in a non - Gui4Cli window. The KeyCombination is a string specifying the combination of keys that the user must hit to make this event happen. They are defined as follows : [class] {[-](qualifier|synonym)} [[-]upstroke] [highmap|ANSICode] [class] can be one of the following words: rawkey rawmouse event pointerpos timer newprefs diskremoved diskinserted [-][qualifier] can be : lshift rshift capslock control lalt ralt lcommand rcommand numericpad repeat midbutton rbutton leftbutton relativemouse - A "-" (negative sign) in front, means that they may or may not occur - i.e. we don't care either way. [-][synonym] can be : shift caps alt - These mean that (eg) any shift (lshift or rshift) is ok. - A "-" in front means these may or may not appear. [-]upstroke is the actual word "upstroke" : - It means that we want to hear the upstroke of the key, only. - if preceeded by a "-" it means we want both upstroke and downstroke. The default is to hear only downstrokes. [highmap] can be one of these: space backspace tab enter return esc del up down right left f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 help [ANSICode] - can be a normal letter, such as "a" > example: "lshift a" With these you can describe almost any key combination, ex: > xHOTKEY "rawkey lshift alt f2" ON -or- > xHOTKEY "rawmouse rbutton" OFF As with other events, you can give it a @{" GADID " LINK "GadID"} and @{" SETGAD " LINK "SetGad"} it ON|OFF. You can also @{" UPDATE " LINK "Update"} it, giving a new KeyCombination. @ENDNODE @NODE xIcon xICON L T IconName (no .info) Icons act like buttons. Although they take up more space than the respective brush would take, they are very easy to implement. The (L)eft and (T)op are where the icon will be placed and IconName is the full path of the icon file you want to use, without the ".info" extension You can give "" as the icon name, if you want. This means that you will give the icon name later. ------------------------------------------------------------------- @{b}See also :@{b} @{" ChangeIcon " link ChangeIcon } @ENDNODE @NODE xLVHook Listview Hooks : xLVDirHook HookID/GadID xLVHook HookID/GadID These two events act according to what happens to the ListView which has the same "HookID". The HookID of a listview is the same as it's GadID number, unless you want to be picky and change it with the @{" LVDirHook " link lvhook} gadget modifier (You no longer need to use the LVDirHook modifier - just use the GadID instead - it's better). xLVDirHook - will "Happen" if the Dir ListView that has the same HookID changes directories (by the user double clicking on it). When this happens, you can, for example, refresh the place where you display the path the dir-listview is currently at. xLVHook - will happen if the MULTI or DIR listview that has the same HookID is clicked once (otherwise, the LV itself will only happen if the user double-clicks on it) The $$LV_DIR, $$LV_GUI, and $$LV_ID @{"Internal Variables" link Variables_IntList} will contain the appropriate values. ex : ; This is a DIR listview with an ID of 1 xListview 0 10 200 100 '' Variable sys: 0 DIR GadID 1 ; This is it's dirhook - happens whenever a dir is double-clicked xLVDirHook 1 SetWinTitle MyGui '$$LV.DIR ' ; This is it's simple-hook - happens whenever the list is single-clicked xLVHook 1 Say 'File chosen is $Variable\n' @ENDNODE @NODE xMenu xMENU MenuName ItemName SubItemName Shortcut This is a menu. MenuName : The Menu Titles shown in the screen bar. ItemName : An Item in the above Menu (or BARLABEL) SubItemName : A SubItem in the above Item of the above Menu. ShortCut : A letter to be used as a short cut (Amiga Key + Letter) Example : @{" Run Gui " system "gui guis:docs/tutorials/Menus.gc"} @{" Source " link "guis:docs/tutorials/Menus.gc/Main"} You MUST define a MenuName and an ItemName in each xMENU command. If there is no SuItemName declared, i.e. if you write "" (empty string) then the Event is a MenuItem. If you give a SubItemName, then the Event is a SubItem. In this case, if there is no ItemName by that name, it will be created. You may give a "" for shortcut also. If you give the "BARLABEL" keyword instead of the item name, then the item will be a divider line. You can also have icons in your menus! All you have to do is declare the ItemName or SubItemName you want to be an icon by preceding it with a # character. example : xMENU Project #MyIcon "" "" - will put the icon named MyIcon.info in the Project menu. Note that the MenuName can NOT be an icon. Menus may be a little confusing at first, till you get it. Try them out in all combinations and see what happens. @ENDNODE @NODE xNotify xNOTIFY File|Directory ON|OFF Will set up notification on a file or directory and will "happen" every time the given file/dir changes in some way (i.e. if it is written to or deleted or whatever). > xNOTIFY Ram:MyFile ON If the file/dir doesn't exist, you will get notified if and when it is created. As with other events, you can give it a @{" GADID " LINK "GadID"} and @{" SETGAD " LINK "SetGad"} it ON|OFF at any time. You can also @{" UPDATE " LINK "Update"} it, giving a new file/dir name. > UPDATE MyGui.gc 1 "Ram:SomeOtherFile" @ENDNODE @NODE xOnHelp xONHELP ON|OFF|AUTO Normally you can set Help ON/OFF globally (if help is defined for the given gadget via the @{" GadHelp " LINK "GadHelp"} command) by using the HELP key. Help text will be shown in the screen's titlebar. If this event is declared, the help messages will NOT appear on the screen's title bar, but instead, this event will happen whenever the mouse pointer hovers over a gadget. > If GadHelp was defined for that gadget, you will get the help text via the following 2 @{" Internal variables " LINK "Variables_Int"} : $$HELP.TEXT - will contain the text defined with GadHelp $$HELP.GADID - will contain the GadId of the given gadget You can then show them anywhere you want. > This gadget can be set to ON, OFF or AUTO ON, OFF : sets the help state for this gui only AUTO : lets the gui be controlled globally together with all the other guis (through the HELP key). > You can change its state by giving it @{" GADID " LINK "GadID"} and then @{" SETGAD " LINK "SetGad"} it to ON|OFF|AUTO. @ENDNODE @NODE xOnJump xOnJump Variable With V2.1 you can press CONTROL-J on a GUI and this will cause it to jump to the next available Public Screen. When this happens, this event will be executed, if defined. The Variable will contain the name of the new screen. This allows you to SetScreen any other accompanying GUIs to the same screen. @ENDNODE @NODE xOnKey xONKEY #R or #V or Letter or #KeyValue Commands attached to this event will be executed when the specified key is pressed. You may specify any of the following : xOnKey L do commands on pressing of the letter L (or any letter) xOnKey #13 do commands on hitting ENTER - or other values (13 is the ASCII value of the ENTER key) xONKEY #R do commands upon the pressing of any raw key (raw keys are the function keys, the arrows, help etc) xONKEY #V do commands upon the pressing of any "normal" or as they say, "vanilla" key. Raw keys are the arrows, help & function keys - all others are called "Vanilla" keys (God knows why..) The internal vars $$RAWKEY.CODE, $$RAWKEY.QUAL, $$VANKEY.CODE $$VANKEY.QUAL, $$VANKEY.LETTER, will contain the relevant key codes and qualifiers (qualifiers are the shift, alt etc keys). This is useful for the #R and #V commands, which will "happen" whenever *any* key of their type is pressed. You can then see what the key pressed was (by looking at the internal vars) and react accordingly. To find out what code number each key has, use SET DEBUG ON, to enter the debug mode and while in it, the values of any keys pressed will printed out. Example : @{" Run Gui " system "gui guis:docs/tutorials/OnKey.gc"} @{" Source " link "guis:docs/tutorials/OnKey.gc/Main"} (see also the GadKey command) @ENDNODE @NODE xOnLoad_etc xONLOAD etc These are very important events, which take place : xOnLOAD -> upon loading of the GUI xOnOPEN -> upon opening of the GUI's window xOnCLOSE -> upon Closing of the GUI's window (with GuiClose or Close gadget) xOnQUIT -> upon Quitting of the GUI xONRELOAD -> When you call GuiLoad, if the file you want loaded is already loaded, then nothing will happen. You can declare this event if you want something to happen. For a simple gui you may have something like the following : xOnLoad MyVar = something ; set any variables you need to set first.. SetGad MyGui.gc 1 OFF ; set any gadgets on/off/show/hide etc GuiOpen MyGui.gc ; to open the gui window upon loading xOnClose GuiQuit MyGui.gc ; to quit (unload) the gui upon the closing of ; it's window. The above is only an example. You may have many commands, actions etc upon the happening of any of the above events. These events (apart from xOnReload) can also take @{" ARGUMENTS " link Passing_Args } These arguments can be defined in the event's command line: > xONLOAD arg1 arg2... arg6 This is specially usefull in xOnLoad, as it allows you to make small guis and use them as "functions". Examples of such fuctions can be found in the GUIs:tools/rtn directory. @ENDNODE @NODE xOnReturn xONRETURN LaunchID This event will be executed when a @{" LAUNCH " link launch} command with the same LaunchID as this event, has finished executing. @ENDNODE @NODE xOn_Various OTHER Events : ================================================================= These are various events (things that the user may do), for which commands may be declared. The commands attached will be executed every time the given event happens. No arguments are passed. xOnRMB Will happen upon the clicking of the Right Mouse Button Only works if there are no menus declared. xOnACTIVE When the window is activated by the user xOnINACTIVE When the window is made inactive xONDOUBLECLICK Upon the double-clicking of the window, on an area not taken up by a gadget. - If this event is not declared, the default is to bring the window to front. xONCLICK Will happen whenever the user clicks in any part of the window that is not taken up by a gadget. Note that if you double-click you'll get one xOnClick and one xOnDoubleClick (if both defined). xONFAIL The commands of this event are executed if the return code of a program launched by a CLI command, is equal to or exceeds 10, or any other ErrorNumber you have set with the @{" FAILAT " LINK "FailAt"} command. xBEFORE Attach commands to be executed before every other execution starts. This will be called every time a gadget is clicked on, and be executed before the gadget's commands. It does not apply to the above events (xOnLOAD etc) xAFTER Same as xBEFORE, but these commands are executed after the Gadget commands. xONDISKIN Happens whenever a disk is inserted (currently there is no way to find out *which* disk was inserted - not my fault!!) xONDISKOUT Whenever a disk is removed. xONFART not yet implemented... @ENDNODE @NODE xPalette xPALETTE L T W H This is a palette gadget from which you can choose colors. Every time a color is selected, the palette will "happen" and the internal variables COLOR.R, COLOR.G, COLOR.B, COLOR.NUM, COLOR.TOTAL will contain the R G B values, the color number and the total number of colors. Look at the Internal Variables for more info. The number of colors is taken from the screen that the window with the palette gadget will open on. You can update a palette by choosing another color : > update GuiName gadID NewColorNumber Look at the guis:tools/palette.gc gui to see an example @ENDNODE @NODE xPipe xPIPE PipeName ON|OFF This is the event that will enable you to use the output that cli programs produce. Example : @{" Run Gui " system "gui guis:docs/tutorials/Pipe.gc"} @{" Source " link "guis:docs/tutorials/Pipe.gc/Main"} A PIPE: is an amigados device which exists in all versions of the OS from V2.0 and up (AFAIK). In order to be able to use it you MUST have the file PIPE in your DEVS/DOSDRIVERS directory and the Queue-handler in your L: dir. You probably already have them set up as above, as this is the standard Amiga OS set-up. What a pipe: does, is provide a "holding place" for the output of CLI programs, until Gui4Cli can get around to reading it. PipeName - should be the name of a pipe: file ON|OFF - is the starting state of the pipe (You can give the xPIPE a gadid and set it ON|OFF - or CLEAN it). xPIPE PIPE:AnyName ON Thereafter, you can launch/run/cli any command and redirect it's output to this pipe: file, like so: RUN 'c:search >PIPE:AnyName dh0:MirrorOnWall FairestOfAll' Now, if the c:search program produces any output, this will go to the PIPE: file you stated and the above xPIPE event will "happen". Inside the xPIPE event, there is one internal variable which will be valid : $$PIPE.TXT. Every time the xPIPE event happens it will mean that an other line of text is ready for you and stored into this variable. ------------------- example: ; a button to start the search xButton 10 10 60 12 'Search' run 'c:Search >PIPE:SearchResults dh0:Universe TrueLove' ; the pipe event that the results will be sent to xPIPE PIPE:SearchResults ON say '$$PIPE.TXT\n' In the above example, every time a line of text is output from the c:search command, it will be printed. ------------------- Handling a pipe ----------------------- You can start off a gui with the pipe ON or OFF. If you give the pipe event a GADID, you can then switch it ON or OFF or CLEAN it, at any time. These will have the following effect : SetGad gui id ON : Will start (create) the pipe. SetGad gui id OFF : Will continue sending text to the xPIPE event and when all the text has been sent, it will delete the pipe. SetGad gui id CLEAN : Will immediately stop sending text to the xPIPE event, clean up any text that was in the pipe and go back to waiting for some text to be sent to it. It will not quit the pipe. If you want to immediately stop and quit the pipe, you can declare "SetGad gui id CLEAN" and then again "SetGad gui id OFF". ------------------- ** IMPORTANT ** ----------------------- In order to implement the PIPE:, Gui4Cli will start a new process which will sit quietly in the background and monitor the PIPE: file. If any text comes, it will read it and send it to Gui4Cli line by line. That means there is quite a lot of overhead involved in each xPIPE you declare (about 10k), so don't fill the place with them.. YOU MAY WELL ask, "why should I use a pipe and not a simple file in ram: to redirect stuff to and then read it from there.." - Well, a pipe: is actually a file, but one which you can read while an other program may be writting to it (i.e. outputing text in to the pipe). - Moreover, a pipe will notify you when it has something to tell you, where as with a file you have to go check yourself. - (Unless I add an xOnNotify event - which I'm thiiiis much away from persuading myself to do...) @ENDNODE @NODE xRadio xRADIO L T W H Variable Spacing xRadios are similar to cyclers, in that they have up to 12 fields. These are denoted with RSTR : xRADIO L T W H Variable Spacing RSTR Title Value RSTR Title Value .. etc .., up to 12 CSTRs The spacing is the distance that the radio buttons will have from each other (vertically), in pixels. Example : @{" Run Gui " system "gui guis:docs/tutorials/Radio.gc"} @{" Source " link "guis:docs/tutorials/Radio.gc/Main"} - Width & Height : People who know a lot more than me and you about this, suggest that the size for HiRes non-interlace screens, should be : Width = 17, Height = 9 @ENDNODE @NODE xRoutine xROUTINE RoutineName This is a "procedure" or "gosub" in other languages. The commands attached to this event will never be executed, unless called by another event. Say you define an xROUTINE with the name of "Hello" : xROUTINE Hello Then from another event in the program you can call this routine with : GoSub GuiName Hello The commands attached to xROUTINE "Hello" will be executed and when finished, control will be returned to the command after "Gosub GuiName Hello" Starting with V3.2, Routines can take/return @{" Arguments " link Passing_Args } Arguments may be accesses as internal variables $$ARG.0 to $$ARG.5, or even better, defined in the routine's definition line : > XROUTINE MyRoutine Arg1 Arg2 SomeArgName Arg6 @ENDNODE @NODE xSlider xVSlider L T W H Title Variable Min Max Current ShowStr xHSlider L T W H Title Variable Min Max Current ShowStr These two gadgets are Sliders : xVSlider is a vertical slider and xHSlider a horizontal one. L T W H Title and Variable have the same meaning as other gadgets. Min : The minimum value of the slider Max : The maximum Value Current : The starting Value of the slider ShowStr : This is a printf style string specifying the format of the value to be shown next to the slider : You can specify "%3d" or "%5d Widgets" for example. The simplest is to specify "%5d" (the Number 5 means the maximum length of the number that the slider can show). The Title will be placed to the left of the gadget unless told otherwise by the GadTitle command Example : @{" Run Gui " system "gui guis:docs/tutorials/Sliders.gc"} @{" Source " link "guis:docs/tutorials/Sliders.gc/Main"} @ENDNODE @NODE xTextBox xTEXTBOX L T W H Title Text A xTEXTBOX is a very versatile graphic that can serve a lot of purposes. It main purpose is to display text easily and colourfully but it can also be used as a container to differentiate different parts of a gui etc. A xTEXTBOX is a graphic, not a gadget, since it can not be selected. You can, however, give it a @{" GADID " LINK "GadID"} and @{" SetGad " LINK "SetGad"} it HIDE/SHOW and also you can @{" UPDATE " LINK "Update"} its text. The basic xTEXTBOX takes as arguments its size and position, its title and its text. A lot more, however, can be configured through the following @{" Attributes " LINK "Attr"} : Attribute to control the look of the text within the box : ----------------------------------------------------------- * TBSTYLE apen/bpen/drawmode/justify - apen, bpen : are the pens that will be used to draw the text. "bpen" will be used as the shadow or outline. - drawmode : can be PLAIN or SHADOW or OUTLINE. - justify : can be LEFT or CENTER or RIGHT and will justify the text accordingly within the bounds of the box. The inner horizontal & vertical margins can be set globally with @{" SET " LINK "Set"} TBMARGINS Horizontal/Vertical (default is 5/4 pixels) Example : > xTEXTBOX 10 10 100 20 "My Title" "Some sample text here.." ATTR TBSTYLE 2/1/SHADOW/CENTER Attribute to control the look of the box itself : -------------------------------------------------------------- * TBOX apen/bpen/bgpen/border/recess - apen, bpen : these are the pens that will be used to draw the title text. "bpen" will be used as shadow/outline - bgpen : this is the background color of the textbox. You can give a -1 if you do not want a background. - drawmode : PLAIN or SHADOW or OUTLINE - border : NONE, PLAIN, BUTTON, RIDGE or ICONDROP (and I'm not going to explain what each one is..) - recess : "IN" to have the border recessed, OUT otherwise. Example : > ATTR TBOX 2/1/3/RIDGE/OUT @{FG shine}Example@{FG text} : @{" Run Gui " system "gui guis:docs/tutorials/xTextBox.gc"} @{" Source " link "guis:docs/tutorials/xTextBox.gc/Main"} The title (if it's not "", ie empty) will be drawn in plain style above and left of the gadget. You can leave this field empty though by giving "" and declare a @{" TITLE " LINK "at_title"} attribute instead. The text inside the xTEXTBOX can be changed with the UPDATE command. > Update #this 3 "Other text.." If you may want to show the contents of a File in a xTextBox, you can use the @{" READVAR " LINK "ReadVar"} command to get the file (or part of it) into a variable and then update the xTextBox : > ReadVar Ram:MyFile 0 500 myvar ; read the first 500 bytes into myvar > Update #this 3 $myvar ; update the xTextBox.. @ENDNODE @NODE xTextIn xTEXTIN L T W H Title Variable StartingText Bufflength This is one of these little boxes where you can input text or numbers. L T W H is the size of the box & Title will be placed to the left. StartingText is the text the window will open with. Bufflength is the size of the buffer : A "buffer" is a place where the program can put the things you write into this gadget. Since the program does not know how long the text you write into this gadget will be, you have to tell it beforehand. A buffer of size 100 means that it is 100 characters long. The gadget will not allow you to enter more characters. xTextIn gadgets can be controlled through the use of @{" Attributes " LINK "Attr"}. Also, you can get information on the current xTextIn gadget though @{" Internal Variables " LINK "iv_textin"} @{FG shine}Example :@{FG text} @{" Run Gui " system "gui guis:docs/tutorials/TextIn.gc"} @{" Source " link "guis:docs/tutorials/TextIn.gc/Main"} Used to be that this gadget would not realize that you had entered anything, unless and until you pressed the ENTER key. Through excellent programming on my part, this is all ancient history now.. :) @ENDNODE @NODE xTimer xTIMER TIME|SINGLE|REPEAT TIME|INTERVAL ON|OFF The xTIMER event uses the Amiga's timer.device to provide acurate, system friendly timming events. There is three ways you can ask to be notified : TIME - trigger event at the given time SINGLE - trigger event after given interval REPEAT - trigger event *every* given interval example : xTimer time 7:30 ON - event happens at 7:30 xTimer single 5 ON - event happens in 5 hours xTimer repeat 0:1:30 ON - event happens every 1 min, 30 secs ===========>>> Time format The time must be given as 24HOURS:MINUTES:SECONDS, i.e. 7 means 7 hours (use 24 hour notation) 7:30 means 7 hours and 30 minutes 0:0:30 means 30 seconds (could also be 00:00:30) - note : for separators you can use ':', '/', '-', or '.' ==========>>> SETGAD the xTimer ON|OFF : This Event can start as ON or OFF. When it starts as ON, the request to the timer.device is sent as the gui file is getting loaded - as soon as the parser reads the event. You can give it a @{" GADID " LINK "GadID"} and thereafter @{" SETGAD " LINK "SetGad"} Gui ID ON|OFF whenever you want. If you set it OFF (or when you quit the gui) if there are any pending timer requests they are aborted. NOTE : *every* time you SETGAD a timer ON the time request is issued again - even if the xTimer is type 'SINGLE'. The HIDE and SHOW keywords have no effect on timers. =========>>> Updating the xTimer : The @{" UPDATE " LINK "Update"} command can be used to change the time interval: Update gui id 10:30:25 This will have the following effect, according to the timer type : TIME - will set the time to be woken to 10:30:25 SINGLE - will wake you up in 10:30:25 hrs from the time you issue this setgad command - if there were any requests already issued they are cancelled. REPEAT - will wake you up every 10:30:25 hrs Again, all pending requests (for *this* timer) will be cancelled. ==========>>> Behaviour The Timer is as accurate as possible. However, Gui4Cli is a multi-tasking program and there may be something else going on when the timer event is triggered - maybe you're using the menus or have a ez-requester open, or commands are executing.. If this happens you will 'hear' the event *after* whatever you are doing finishes and Gui4Cli gets around to notifying you. If this happens in a REPEAT timer, and if while you are busy many such events happen (i.e. if you set the interval to 1 sec and many seconds pass while you are messing around with something) then you will hear only *one* of the events - i.e. the REPEAT events will *not* be stacked. ==========>>> Related stuff : See also the @{" $$SYS.TIME " LINK "iv_system"} related @{" Internal variables " LINK "Variables_Int"} Example (an alarm clock) : RUN gui - See Source @ENDNODE @NODE INDEX Guide INDEX : @{" Action " link "Action"} @{" Advantages " link "Advantages"} @{" All_Commands " link "All_the_Commands"} @{" Append " link "Append"} @{" AppVar " link "AppVar"} @{" ARexx " link "ARexx"} @{" Assign " link "Assign"} @{" Attr " link "Attr"} @{" at_frame " link "at_frame"} @{" at_lvs " link "at_lvs"} @{" at_resize " link "at_resize"} @{" at_textin " link "at_textin"} @{" at_title " link "at_title"} @{" BreakTask " link "BreakTask"} @{" CalcVar " link "CalcVar"} @{" Call " link "Call"} @{" CD " link "CD"} @{" ChangeArg " link "ChangeArg"} @{" ChangeGad " link "ChangeGad"} @{" ChangeIcon " link "ChangeIcon"} @{" Clipboard " link "Clipboard"} @{" Command_Lines " link "Command_Lines"} @{" Copy " link "Copy"} @{" Counter " link "Counter"} @{" CutVar " link "CutVar"} @{" c_control " link "c_control"} @{" c_dos " link "c_dos"} @{" c_events " link "c_events"} @{" c_gadcontrol " link "c_gadcontrol"} @{" c_gadmod " link "c_gadmod"} @{" c_global " link "c_global"} @{" c_graphics " link "c_graphics"} @{" c_Gui " link "c_Gui"} @{" c_handle " link "c_handle"} @{" c_multimedia " link "c_multimedia"} @{" c_parser " link "c_parser"} @{" c_programs " link "c_programs"} @{" c_various " link "c_various"} @{" c_vars " link "c_vars"} @{" DBase_LVs " link "DBase_LVs"} @{" DBSum " link "DBSum"} @{" Delay " link "Delay"} @{" Delete " link "Delete"} @{" DelVar " link "DelVar"} @{" DirList " link "DirList"} @{" DoCase " link "DoCase"} @{" Extract " link "Extract"} @{" EZReq " link "EZReq"} @{" FailAt " link "FailAt"} @{" Flash " link "Flash"} @{" Fonts " link "Fonts"} @{" Font_Sensing " link "Font_Sensing"} @{" GadFont " link "GadFont"} @{" GadHelp " link "GadHelp"} @{" GadID " link "GadID"} @{" GadKey " link "GadKey"} @{" GadRedraw " link "GadRedraw"} @{" GadTitle " link "GadTitle"} @{" GadTxt " link "GadTxt"} @{" Gauge " link "Gauge"} @{" GoSub " link "GoSub"} @{" Graphics " link "Graphics"} @{" GuiEdit " link "GuiEdit"} @{" GuiLoad " link "GuiLoad"} @{" GuiNames " link "GuiNames"} @{" GuiRename " link "GuiRename"} @{" GuiScreen " link "GuiScreen"} @{" GuiWindow " link "GuiWindow"} @{" If " link "If"} @{" IfExists " link "IfExists"} @{" Images " link "Images"} @{" Important_Topics " link "Important_Topics"} @{" Info " link "Info"} @{" Introduction " link "Introduction"} @{" iv_file " link "iv_file"} @{" iv_g4c " link "iv_g4c"} @{" iv_gadget " link "iv_gadget"} @{" iv_gadkey " link "iv_gadkey"} @{" iv_image " link "iv_image"} @{" iv_listview " link "iv_listview"} @{" iv_mem " link "iv_mem"} @{" iv_mouse " link "iv_mouse"} @{" iv_obsolete " link "iv_obsolete"} @{" iv_palette " link "iv_palette"} @{" iv_parsevar " link "iv_parsevar"} @{" iv_rand " link "iv_rand"} @{" iv_retcode " link "iv_retcode"} @{" iv_rexxret " link "iv_rexxret"} @{" iv_screen " link "iv_screen"} @{" iv_search " link "iv_search"} @{" iv_system " link "iv_system"} @{" iv_textin " link "iv_textin"} @{" iv_var " link "iv_var"} @{" iv_window " link "iv_window"} @{" JoinFile " link "JoinFile"} @{" KillScreen " link "KillScreen"} @{" Launch " link "Launch"} @{" Licence " link "Licence"} @{" ListView " link "ListView"} @{" Local " link "Local"} @{" LTWH " link "LTWH"} @{" LVAction " link "LVAction"} @{" LVAdd " link "LVAdd"} @{" LVChange " link "LVChange"} @{" LVClear " link "LVClear"} @{" LVClip " link "LVClip"} @{" LVColors " link "LVColors"} @{" LVDel " link "LVDel"} @{" LVDir " link "LVDir"} @{" LVFind " link "LVFind"} @{" LVGo " link "LVGo"} @{" LVHook " link "LVHook"} @{" LVInsert " link "LVInsert"} @{" LVMode " link "LVMode"} @{" LVMove " link "LVMove"} @{" LVMulti " link "LVMulti"} @{" LVPut " link "LVPut"} @{" LVRep " link "LVRep"} @{" LVSave " link "LVSave"} @{" LVSearch " link "LVSearch"} @{" LVSort " link "LVSort"} @{" LVSwitch " link "LVSwitch"} @{" LVUse " link "LVUse"} @{" LV_Commands " link "LV_Commands"} @{" MakeDir " link "MakeDir"} @{" MakeScreen " link "MakeScreen"} @{" Mark " link "Mark"} @{" Maths " link "Maths"} @{" MoveScreen " link "MoveScreen"} @{" NewFile " link "NewFile"} @{" Operation " link "Operation"} @{" Operator " link "Operator"} @{" Options " link "Options"} @{" Palette " link "Palette"} @{" ParseVar " link "ParseVar"} @{" PartRedraw " link "PartRedraw"} @{" Passing_Args " link "Passing_Args"} @{" Paths " link "Paths"} @{" Programming " link "Programming"} @{" Quit " link "Quit"} @{" ReadVar " link "ReadVar"} @{" RecSort " link "RecSort"} @{" Redraw " link "Redraw"} @{" Rename " link "Rename"} @{" RepVar " link "RepVar"} @{" ReqFile " link "ReqFile"} @{" ResInfo " link "ResInfo"} @{" ReSize " link "ReSize"} @{" Run " link "Run"} @{" Say " link "Say"} @{" Screen " link "Screen"} @{" SearchVar " link "SearchVar"} @{" SendRexx " link "SendRexx"} @{" Set " link "Set"} @{" SetColor " link "SetColor"} @{" SetGad " link "SetGad"} @{" SetGadValues " link "SetGadValues"} @{" SetPointer " link "SetPointer"} @{" SetScreen " link "SetScreen"} @{" SetScreenTitle " link "SetScreenTitle"} @{" SetStack " link "SetStack"} @{" SetVar " link "SetVar"} @{" SetWintitle " link "SetWintitle"} @{" ShareMenu " link "ShareMenu"} @{" Sound " link "Sound"} @{" Speak " link "Speak"} @{" Status " link "Status"} @{" Stop " link "Stop"} @{" System " link "System"} @{" Text " link "Text"} @{" TextFile " link "TextFile"} @{" Translation " link "Translation"} @{" TTGet " link "TTGet"} @{" Update " link "Update"} @{" UseTopaz " link "UseTopaz"} @{" Variables " link "Variables"} @{" Variables_Env " link "Variables_Env"} @{" Variables_Int " link "Variables_Int"} @{" Var_IntList " link "Variables_IntList"} @{" Variables_Normal " link "Variables_Normal"} @{" VarPath " link "VarPath"} @{" Var_in_var " link "Var_in_var"} @{" Wait " link "Wait"} @{" While " link "While"} @{" WinBackGround " link "WinBackGround"} @{" WinBig " link "WinBig"} @{" WinFont " link "WinFont"} @{" WinOnMouse " link "WinOnMouse"} @{" WinOnWin " link "WinOnWin"} @{" WinOut " link "WinOut"} @{" WinShortcuts " link "WinShortcuts"} @{" WinSmall " link "WinSmall"} @{" WinType " link "WinType"} @{" Workbench " link "Workbench"} @{" xAppIcon " link "xAppIcon"} @{" xAppMenu " link "xAppMenu"} @{" xAppWindow " link "xAppWindow"} @{" xArea " link "xArea"} @{" xButton " link "xButton"} @{" xCheckBox " link "xCheckBox"} @{" xCycler " link "xCycler"} @{" xHotKey " link "xHotKey"} @{" xIcon " link "xIcon"} @{" xLVHook " link "xLVHook"} @{" xMenu " link "xMenu"} @{" xNotify " link "xNotify"} @{" xOnHelp " link "xOnHelp"} @{" xOnJump " link "xOnJump"} @{" xOnKey " link "xOnKey"} @{" xOnLoad_etc " link "xOnLoad_etc"} @{" xOnReturn " link "xOnReturn"} @{" xOn_Various " link "xOn_Various"} @{" xPalette " link "xPalette"} @{" xPipe " link "xPipe"} @{" xRadio " link "xRadio"} @{" xRoutine " link "xRoutine"} @{" xSlider " link "xSlider"} @{" xTextBox " link "xTextBox"} @{" xTextIn " link "xTextIn"} @{" xTimer " link "xTimer"} @ENDNODE