fromHelp.gif (4612 bytes)

How a Gui4Cli program is structured
(This is from the manual - the links don't work here..)

A Gui4Cli program is a script that describes a gui and what it should do. It has an intuitive structure that allows you to think clearly. Here is the simplest form of a "Hello World" program:

G4C MyGui

Window 10 10 200 300 "My window"

xOnLoad
   GuiOpen MyGui

xButton 10 10 100 20 "Hello World"
   GuiQuit MyGui

If you write the above in a text editor and save the file under any name, giving it the ".gui" extension, then when you "Open" the file (double clicking it in the Explorer or some other method) you'll get a standard dialog type window with a button on it. When the button is clicked, the gui will "GuiQuit" and be unloaded.

The first word in a Gui file must be "G4C" followed by the NAME of the gui (ie "MyGui"). This name is important since you will need to address a gui in many commands and in variables, by giving its name. Note that if another gui by the same name is already loaded you will get an error report and the new gui will not be loaded.

Then comes the WINDOW declaration, without which there will be no window. (Note that a gui without a window is also allowed and is very usefull in many cases). We could go on and give some window attributes (like WinAttr Style, Shape, etc..) to change the look and behaviour of the window, but we'll keep it simple for now.

Then follows our first event - xOnLoad.

Events are very important. They are triggered when something happens, each according to its type. xOnLoad is triggered when the gui is first loaded. At that time, this event will "happen" and Gui4Cli will start executing all the commands attached to it.

The only command attached to this event is the "GuiOpen MyGui". This tells Gui4Cli that when it loads the gui it should also go ahead and open its window. If we did not declare this event the gui would be loaded and then just remain there, in memory, waiting for a command to open itself.

This time we only have this one command to execute, so Gui4Cli will execute and then stop and wait for something else to happen (like a mouse click in another gui, or whatever). We could have had as many commands as we wanted attached. Gui4Cli considers all commands following an event declaration as belonging to that event, until another event is declared. Or until the file ends, or another gui is declared.. These commands form routines which are executed every time the event "happens". They can call sub-routines in this or other files, open/close other guis, run programs, show pictures, etc, etc..

We can have as many events as we want, but in this gui there is only one more - the xBUTTON. This is a "Visual" event, in contrast with the xOnLoad event which is "Non-Visual". The xButton happens every time it is clicked. In our above gui, when we click it the gui will quit and be unloaded. End of story..

One thing which we haven't catered for is what happens if the user clicks the system X (close window) button. As it is, the gui's window would be closed but the gui would not be unloaded because the GuiQuit command would not have been executed.. The gui will just remain in memory, siting around until we open/unload it from somewhere else, or until Gui4Cli itself quits, unloading everything. To fix this we include another event which happens whenever the gui's window is closed (by whatever method):

xOnClose
   GuiQuit MyGui

The above is a simple as it gets. Something a little more complex with links to the commands so you can get more info..

G4C DirView

WINDOW 168 13 510 471 "Your Computer"
   WinAttr Style resize

xOnLoad
   GuiOpen #this

xOnClose
    guiquit #this

XLISTVIEW 185 0 323 472 "" "#disks" lvar1
   attr ID lv1
   attr frame sunk
   attr Style Grid/Drag/Drop/parent/disk
   Attr resize 0022
   if $lvar1 > ''
      run $lvar1
   endif

xOnLVDir lv1 // happens wherever LV changes dir
    gosub #this ChangeDir // change window title
    use tv #this tv1
    tv cd $dirname  // take treeview also to that dir..

XTREEVIEW 0 0 180 472 "#disks" tvdir
    attr ID tv1
    attr frame sunk
    attr resize 0002
    attr style drag/drop
    lvuse #this lv1
    lvchange $tvdir // Take LV to the same dir
    gosub #this ChangeDir // update window title

XSPLITER 180 0 6 680 tv1 lv1

xRoutine ChangeDir
    if $$lv.dir = ""  // empty means "disks" list
        setwintitle #this "Your Computer"
    else
        setwintitle #this $$lv.dir
    endif
The above, believe it or not, is a fully working program; a simple Explorer type file manager, complete with Listview, Treeview, Spliter bar, Resizable window, DragDrop, etc. You can browse your hard disks, copy or move files by drag and drop, run programs etc. There is full shell context menu support (by default) and a few Gui4Cli goodies, such as assigns, thrown in..

Several things to note..

First is the use of WinAttr Style, which declares a Window Attribute (ie a statement that alters the look and behaviour of the standard window). In this case the window style is modified and is made resizable.

Then there is the use of Attr (stands for attribute) which is similar to the above, but for Events. Here, the Style attribute will change the look and behaviour of the listview (adding drag and drop etc). The resize attribute tells the listview how to resize itself if its parent window is resized by the user. If not given, the listview would remain the same size.

The above statements (WinAttr and Attr) are only taken into account when the gui is first loaded. They tell Gui4Cli how the gui should look and behave in general. Thereafter they are forgotten and will never be executed.

An example of executable lines are the last 3 lines in the listview event. These are executed whenever the user double clicks on a file in the listview, causing the listview "event" to be triggered. In this case, the name of the file will be placed into the listview's variable, "lvar1". The If statement will first check if there is anything actually in the variable, and if there is, it will Run the file. This will, by default, Open the file, leaving it to windows to decide on the program it should use to do so.. Note that the user could also use the shell context menu (clicking on the right mouse button) to run, copy, etc the file.

And that's it.. You could add a whole bunch of other things too. Its up to you..

The order of the events doesn't usually matter. You can have your Window and xOnLoad events at the end of the file if you wanted, although its not a good idea.. A Gui file can contain many guis. Each new Gui starts with the NewGui command.
As you see, things are pretty simple, so don't stand around here reading this.. Write some guis.. A good place to start is the Tutorials.gui. Start it up and you'll get a list of simple guis which you can run and read and change and experiment on.

Hitting Control-E while the gui is active will load the gui's code into the defined editor so you can have a look at it and, if you want, change it..