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

The widgets

Window

Mark

Spin

Button

Combo

Notebook

Stock

Progressbar

Msgdialog

Toggle

Hseparator

Filedialog

Check

Vseparator

Image

Radio

Frame

Clipboard

Entry

Edit


Password

List



The methods

Text

Focus

Show

Grab$

Unfocus

Hide

Set

Enable

Font

Get

Disable



Graphical functions

Canvas

Pixel

Out

Draw

Line

Picture

Circle

Square



Generic functions

Hugoptions

Screensize

Display

Attach

Key

Sync

Callback

Mouse

Timeout

Callbackx

Init

Quit


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.


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$

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

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.


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.


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

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.


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

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


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