The Highlevel Universal GUI abstraction layer (HUG) is a simple set of functions to allow BaCon setting up graphical user interfaces in a fast and efficient manner. As a model, the set of widgets is limited to the widgets which are commonly found in HTML Forms. It is then extended with the powerful canvas widget and some drawing commands, and also with methods to query the keyboard and mouse events.
The implementation is based on GTK using the BaCon IMPORT statement to get the necessary functions from the GTK libraries. The advantage of this approach is, that the resulting executable has no dependency with GTK on binary level. It means that a program using HUG can be executed even when GTK is not available. It allows the programmer to setup a text interface instead, in the same program.
To setup a user interface, first a window is created, on which the needed widgets are defined. For most widgets it is possible to define a so-called 'callback'. This is in fact a user-defined function which is 'called back' when the widget is activated.
Once all widgets and callbacks are setup, the GTK mainloop is entered. This should be the last function in the HUG program as GTK never returns from this mainloop.
If an intermediate action is needed, it is possible to setup a timeout with the TIMEOUT function. This allows the programmer to call a defined function on regular basis, thereby interrupting the GTK mainloop.
The widgets |
||
---|---|---|
|
||
|
The methods |
||
---|---|---|
|
Graphical functions |
||
---|---|---|
|
Generic functions |
||
---|---|---|
ATTACH(window, widget, x, y)
Type: function
This function attaches a widget to a window at position <x>, <y>. The top left of the window should be taken as reference (0, 0).
BUTTON("caption", xsize, ysize)
Type: function
Creates a button with a caption, and a width of <xsize> and a height of <ysize>.
CALLBACK(widget, function)
Type: function
Defines a self-defined <function> where HUG should jump to when an event for <widget> occurs.
CALLBACKX(widget, function, value)
Type: function
Defines a self-defined <function> where HUG should jump to when an event for <widget> occurs, and pass <value> to that function. The arguments in the callback function should catch this value.
Example:
INCLUDE
"hug.bac"
SUB demo(NUMBER widget, NUMBER value)
PRINT value
END SUB
window = WINDOW("Hello",
200, 200)
button = BUTTON("press here", 100, 50)
ATTACH (window, button, 10, 10)
CALLBACKX(button, demo,
12345)
DISPLAY
CANVAS(xsize, ysize)
Type: function
Creates a canvas of width <xsize> and height <ysize>. The top left corner is defined as position(0, 0). The canvas created last is regarded as the default canvas where the drawing takes place. The default canvas can be changed with the function DRAW.
CHECK("caption", xsize, ysize)
Type: function
Creates a check button with a label, and a width of <xsize> and a height of <ysize>.
CIRCLE("color", xposition, yposition, width, height, fill)
Type: function
Draws a circle on the default canvas, centered at <xposition> and <yposition>. The total size of the circle is determined by <width> and <height>. If <fill> is not zero then the circle will be a full circle (e.g. filled, not a wire).
The color is a string of the format "#rrggbb" which is a hexadecimal triplet. This example defines the color red: "#FF0000".
CLIPBOARD
Type: function
Gets the clipboard object.
COMBO("text", xsize, ysize)
Type: function
Creates a ombobox with one entry, and a width of <xsize> and a height of <ysize>.
DISABLE(widget)
Type: function (method)
Freezes a widget so it cannot be used.
DISPLAY
Type: function
Starts executing the main event loop. This function should be called as the last function in the GUI creation.
DRAW(canvas)
Type: function
Defines the default canvas where the drawing takes place.
EDIT(xsize, ysize)
Type: function
Defines a multiline text widget with a width of <xsize> and a height of <ysize>.
ENABLE(widget)
Type: function (method)
Unfreezes a widget so it can be used.
ENTRY("text", xsize, ysize)
Type: function
Creates a text entry filled with some text, and a width of <xsize> and a height of <ysize>.
FILEDIALOG("title", "caption", xsize, ysize, action)
Type: function
Creates a dialog with a filebrowser. Depending on <action> the dialog maybe used for "Open File” (0), "Save File" (1), "Select Folder" (2) or "Create Folder" (3).
By default the dialog will be hidden. Use the SHOW function to make it visible.
FOCUS(widget)
Type: function (method)
Puts the focus to a widget.
FONT(widget, "Font name")
Type: function (method)
Defines a font for a widget. Example:
FONT(window,
"Luxi Mono 12")
FONT(button, "Arial 15")
FRAME(xsize, ysize)
Type: function
Defines a frame with a width of <xsize> and a height of <ysize>.
GET(widget)
Type: function (method)
Depending on the widget, gets a value from the widget. The current behavior is shown in the table below.
Widget |
Value behavior |
---|---|
Window |
0 = windowed, 1 = fullscreen |
Button |
0 = unpressed, 1 = pressed |
Toggle |
0 = unpressed, 1 = pressed |
Stock |
0 = unpressed, 1 = pressed |
Check |
0 = unchecked, 1 = checked |
Radio |
0 = unselected, 1 = selected |
Entry |
No effect |
Password |
0 = contents invisible, 1 = contents visible |
Mark |
0 = not selectable, 1 = selectable |
Combo |
Gets indexnumber of selected row in combo |
Progressbar |
Gets progress percentage of progressbar |
Hseparator |
No effect |
Vseparator |
No effect |
Frame |
No effect |
Edit |
Gets amount of lines of text |
List |
Gets indexnumber of selected row in the list |
Spin |
Gets the current value |
Notebook |
Gets current tabnumber |
Msgdialog |
No effect |
Filedialog |
No effect |
Image |
No effect |
Clipboard |
No effect |
GRAB$(widget)
Type: function (method)
Depending on the widget, gets the text. The current behavior is shown in the table below.
Widget |
Behavior |
---|---|
Window |
Returns the text from the title bar |
Button |
Returns caption on the button |
Toggle |
Returns caption on the button |
Stock |
Returns stock text from the button |
Check |
Returns the caption next to the check button |
Radio |
Returns the caption next to the radio button |
Entry |
Gets text from the entry |
Password |
Gets the text from the password |
Mark |
Gets the text from the label (Mark) |
Combo |
Get the current selection of the combobox |
Progressbar |
Gets the text from the progressbar |
Hseparator |
No effect |
Vseparator |
No effect |
Frame |
Gets the caption from a frame |
Edit |
Gets the full text from a multiline editor |
List |
Gets the current selected line from the list |
Spin |
No effect |
Notebook |
Returns caption in the active tab |
Msgdialog |
Returns the text in the message dialog |
Filedialog |
Returns the selected filename in the file dialog |
Image |
No effect |
Clipboard |
Gets the text from the clipboard |
HIDE(widget)
Type: function (method)
Hides a widget so it is invisible.
HSEPARATOR(size)
Type: function
Creates a horizontal separator line with a length of <size>.
HUGOPTIONS("option")
Type: function
This function influences the behavior of the HUG library. Per invocation only one option can be set. The following options are recognized.
"TABLE x y" - define a table as layer for the ATTACH function
"BASEXFTDPI x" - define the default font dpi for the current desktop. Default: 96
"SCALING" - the created GUI should be scaled to fit the desktop font (default)
"NOSCALING" - undo the scaling of the GUI
IMAGE("file", xsize, ysize)
Type: function
Loads a picture from a file and define this as a widget with a width of <xsize> and a height of <ysize>.
INIT
Type: function
Initializes the HUG library. This function only is needed when HUG is compiled as a shared library and its functions are imported from there. When HUG is included then this function will be executed automatically.
KEY
Type: function
Returns the last key pressed on the keyboard. The returned value follows the GDK header file <gdk/gdkkeysyms.h>.
LINE("color", xstart, ystart, xend, yend)
Type: function
Draws a line on the default canvas from <xstart>, <ystart> to <xend>, <yend>.
The color is a string of the format "#rrggbb" which is a hexadecimal triplet. This example defines the color green: "#00FF00".
LIST(xsize, ysize)
Type: function
Defines a multiline list widget with a width of <xsize> and a height of <ysize>.
MARK("caption", xsize, ysize)
Type: function
Creates a label with a caption, and a width of <xsize> and a height of <ysize>.
MSGDIALOG("text", xsize, ysize, type, buttons)
Type: function
Creates a dialog with a text, and a width of <xsize> and a height of <ysize>.
The type of dialog can be one of the following: 0 - informational, 1 - waring, 2 - question, - 3 - error and 4 – other.
The buttons can have the following values: 0 - no button, 1 - ok button, 2 - close, 3 - cancel, 4 - yes/no, and 5 – ok/cancel.
By default the dialog will be hidden. Use the SHOW function to make it visible.
The dialog can be connected to a callback function which should have two arguments, the first for the dialog and the second for the button. For example:
INCLUDE "hug.bac"
SUB
HandleError(NUMBER dialog, int button)
HIDE(dialog)
IF
button IS GTK_RESPONSE_YES THEN
<...your code
here...>
END IF
END SUB
ErrDlg = MSGDIALOG("Error",
300, 200, 3, 4)
CALLBACK(ResetMsg, HandleError)
For a full list of dialog response codes, please refer to the Appendix.
MOUSE(x)
Type: function
Returns the current position of the mouse. When <x> is 0 the x coordinate is returned, when <x> is 1 the y-coordinate, when <x> is 2 the button number is returned. When <x> is 3 the mousewheel direction is returned.
NOTEBOOK("caption", xsize, ysize)
Type: function
Creates a notebook with one tab containing a caption, and a width of <xsize> and a height of <ysize>.
OUT("text", "fgcolor", "bgcolor", xposition, yposition)
Type: function
Draws text on the default canvas, starting top left at <xposition> and <yposition>.
The colors are defined as a string of the format "#rrggbb" which is a hexadecimal triplet. This example defines the color yellow: "#FFFF00".
PASSWORD("text", xsize, ysize)
Type: function
Creates a password entry filled with some text, and a width of <xsize> and a height of <ysize>. The actual text is displayed with a special character to hide the actual contents.
PICTURE("file", xposition, yposition, xsize, ysize)
Type: function
Loads a picture from a file and draws this picture on the default canvas, starting top left at <xposition> and <yposition>. The horizontal size is defined by <xsize>, the vertical size by <ysize>. The file format of the picture is detected automatically.
PIXEL("color", xposition, yposition)
Type: function
Draws a pixel on the default canvas at <xposition>, <yposition>.
The color is a string of the format "#rrggbb" which is a hexadecimal triplet. This example defines the color blue: "#0000FF".
PROGRESSBAR("caption", xsize, ysize)
Type: function
Creates a progressbar with a caption, and a width of <xsize> and a height of <ysize>.
QUIT
A convenience function to exit HUG and terminate the program.
BUTTON("caption", xsize, ysize, group)
Type: function
Creates a radio button with a caption, and a width of <xsize> and a height of <ysize>. The group refers to a previous radiobutton with which the button excludes. The first radiobutton can use '0' for the value of group.
SCREENSIZE(dimension)
Type: function (method)
Gets the current screensize in pixels. If <dimension> is 0 then the horizontal size is retrieved, and if <dimension> is 1 the vertical size.
SET(widget, value)
Type: function (method)
Depending on the widget, sets a value into the widget. The current behavior is shown in the table below.
Widget |
Value behavior |
---|---|
Window |
0 = windowed, 1 = fullscreen |
Button |
0 = unpress, 1 = press |
Toggle |
0 = unpress, 1 = press |
Stock |
0 = unpress, 1 = press |
Check |
0 = uncheck, 1 = check |
Radio |
0 = unselect, 1 = select |
Entry |
No effect |
Password |
0 = contents invisible, 1 = contents visible |
Mark |
0 = not selectable, 1 = selectable |
Combo |
Select entry in combo |
Progressbar |
Set progress percentage of progressbar |
Hseparator |
No effect |
Vseparator |
No effect |
Frame |
No effect |
Edit |
Goto linenumber |
List |
Select row in list |
Spin |
Set integer value |
Notebook |
Select tabnumber |
Msgdialog |
No effect |
Filedialog |
No effect |
Image |
No effect |
Clipboard |
No effect |
SHOW(widget)
Type: function (method)
Shows a widget so it is visible. Most widgets are visible from the moment they are created.
SPIN(xsize, ysize, start, end, step)
Type: function
Creates a spinbutton with a width of <xsize> and a height of <ysize>. The range of integer values lays between <start> and <end>, and will be increased or decreased with <step> size.
SQUARE("color", xposition, yposition, width, height, fill)
Type: function
Draws a square on the default canvas, starting top left at <xposition> and <yposition>. The sizes of the box are defined by <width> and <height>. If <fill> is not zero then the box will be a full box (e.g. filled, not a wire).
The color is a string of the format "#rrggbb" which is a hexadecimal triplet. This example defines the color red: "#FF0000".
STOCK("stock-id", xsize, ysize)
Type: function
Creates a stock button if used with the correct stockID. These ID's are mentioned in the GTK documentation. The button has a width of <xsize> and a height of <ysize>.
SYNC
Type: function
Forces an intermediate update of the GUI.
TEXT(widget, "text")
Type: function (method)
Depending on the widget, sets the text. The current behavior is shown in the table below.
Widget |
Behavior |
---|---|
Window |
Sets the text in the title bar |
Button |
Sets text in the button |
Toggle |
Sets text in the button |
Stock |
Sets stock text and icon in the button |
Check |
Sets the label next to the check button |
Radio |
Sets the label next to the radio button |
Entry |
Sets text into the entry |
Password |
Sets text into the password |
Mark |
Sets the text into the label (Mark) |
Combo |
Adds a line to the combobox |
Progressbar |
Sets the text in the progressbar |
Hseparator |
No effect |
Vseparator |
No effect |
Frame |
Sets the caption in a frame |
Edit |
Sets text into a multiline editor |
List |
Adds a line with text to the list |
Spin |
No effect |
Notebook |
Adds a new tab with text |
Msgdialog |
Sets the text of the message dialog |
Filedialog |
Sets the filename in the file dialog |
Image |
No effect |
Clipboard |
Sets text on the clipboard |
TIMEOUT(millisec, function)
Type: function
Sets up a timeout while the main eventloop is executed. After the timeout in milliseconds, a self-defined <function> is executed. The function must return TRUE if the timeout must be executed again. The amount of milliseconds can be changed to another value during runtime. Example:
INCLUDE
"hug.bac"
DECLARE pb, x, offset
offset = 1
FUNCTION
set_value
INCR x, offset
IF x >= 100 OR x <= 0
THEN offset = -1*offset
PROGRESSBAR_SET(pb, x)
PRINT
PROGRESSBAR_GET(pb)
RETURN TRUE
END FUNCTION
win
= WINDOW("Progressbar", 200, 30)
pb =
PROGRESSBAR("demo", 200, 30)
ATTACH(win, pb, 0,
0)
TIMEOUT(100, set_value)
DISPLAY
TOGGLE("caption", xsize, ysize)
Type: function
Creates a toggle button with a caption, and a width of <xsize> and a height of <ysize>.
UNFOCUS(widget)
Type: function (method)
Disable the focus on a widget.
VSEPARATOR(ysize)
Type: function
Creates a vertical separator line with a length of <size>.
WINDOW("title", xsize, ysize)
Type: function
Creates a window with a title, and a width of <xsize> and a height of <ysize>.
Code |
Meaning |
---|---|
GTK_RESPONSE_ACCEPT |
Accept button was pressed |
GTK_RESPONSE_DELETE_EVENT |
Dialog was closed |
GTK_RESPONSE_OK |
OK button was pressed |
GTK_RESPONSE_CANCEL |
Cancel button was pressed |
GTK_RESPONSE_CLOSE |
Close button was pressed |
GTK_RESPONSE_YES |
Yes button was pressed |
GTK_RESPONSE_NO |
No button was pressed |
GTK_RESPONSE_APPLY |
Apply button was pressed |
GTK_RESPONSE_HELP |
Help button was pressed |
This
documentation © by Peter van Eerten.
Please report errors to:
REVERSE$("gro.retrevnoc-cisab@retep")
Created
with OpenOffice 3.2.
Back to top of document