H.U.G. 0.30 documentation

Introduction

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.

General usage

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.

Overview

HUG functions

ATTACH

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

BUTTON("caption", xsize, ysize)

Type: function

Creates a button with a caption, and a width of <xsize> and a height of <ysize>.

CALLBACK

CALLBACK(widget, function)

Type: function

Defines a self-defined <function> where HUG should jump to when an event for <widget> occurs.

CALLBACKX

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

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

CHECK("caption", xsize, ysize)

Type: function

Creates a check button with a label, and a width of <xsize> and a height of <ysize>.

CIRCLE

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

CLIPBOARD

Type: function

Gets the clipboard object.

COMBO

COMBO("text", xsize, ysize)

Type: function

Creates a ombobox with one entry, and a width of <xsize> and a height of <ysize>.

DISABLE

DISABLE(widget)

Type: function (method)

Freezes a widget so it cannot be used.

DISPLAY

DISPLAY

Type: function

Starts executing the main event loop. This function should be called as the last function in the GUI creation.

DRAW

DRAW(canvas)

Type: function

Defines the default canvas where the drawing takes place.

EDIT

EDIT(xsize, ysize)

Type: function

Defines a multiline text widget with a width of <xsize> and a height of <ysize>.

ENABLE

ENABLE(widget)

Type: function (method)

Unfreezes a widget so it can be used.

ENTRY

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

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

FOCUS(widget)

Type: function (method)

Puts the focus to a widget.

FONT

FONT(widget, "Font name")

Type: function (method)

Defines a font for a widget. Example:

FONT(window, "Luxi Mono 12")
FONT(button, "Arial 15")

FRAME

FRAME(xsize, ysize)

Type: function

Defines a frame with a width of <xsize> and a height of <ysize>.

GET

GET(widget)

Type: function (method)

Depending on the widget, gets a value from the widget. The current behavior is shown in the table below.

GRAB$

GRAB$(widget)

Type: function (method)

Depending on the widget, gets the text. The current behavior is shown in the table below.

HIDE

HIDE(widget)

Type: function (method)

Hides a widget so it is invisible.

HSEPARATOR

HSEPARATOR(size)

Type: function

Creates a horizontal separator line with a length of <size>.

HUGOPTIONS

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

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

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

KEY

Type: function

Returns the last key pressed on the keyboard. The returned value follows the GDK header file <gdk/gdkkeysyms.h>.

LINE

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

LIST(xsize, ysize)

Type: function

Defines a multiline list widget with a width of <xsize> and a height of <ysize>.

MARK

MARK("caption", xsize, ysize)

Type: function

Creates a label with a caption, and a width of <xsize> and a height of <ysize>.

MSGDIALOG

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

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

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

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

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

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

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

PROGRESSBAR("caption", xsize, ysize)

Type: function

Creates a progressbar with a caption, and a width of <xsize> and a height of <ysize>.

QUIT

QUIT

A convenience function to exit HUG and terminate the program.

RADIO

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

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

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.

SHOW

SHOW(widget)

Type: function (method)

Shows a widget so it is visible. Most widgets are visible from the moment they are created.

SPIN

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

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("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

SYNC

Type: function

Forces an intermediate update of the GUI.

TEXT

TEXT(widget, "text")

Type: function (method)

Depending on the widget, sets the text. The current behavior is shown in the table below.

TIMEOUT

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

TOGGLE("caption", xsize, ysize)

Type: function

Creates a toggle button with a caption, and a width of <xsize> and a height of <ysize>.

UNFOCUS

UNFOCUS(widget)

Type: function (method)

Disable the focus on a widget.

VSEPARATOR

VSEPARATOR(ysize)

Type: function

Creates a vertical separator line with a length of <size>.

WINDOW

WINDOW("title", xsize, ysize)

Type: function

Creates a window with a title, and a width of <xsize> and a height of <ysize>.

Appendix: Dialog Response Codes

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