H.U.G. 0.94 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.


OpenGL and Goo canvas

Since HUG 0.50 it is possible to use an OpenGL canvas. The system needs to have either the GtkGlArea or the GtkGlExt library installed. The command HUGOPTIONS can define if OpenGL should instead of the default GTK canvas. It will autodetect the available library. If no GL library can be found then HUG will fall back to the default GTK canvas.

Since HUG 0.86 also GooCanvas is supported. If no GooConvas library can be found then HUG will fall back to the default GTK canvas.

Any subsequent drawing to a canvas can only be done after HUG shows the GUI with the DISPLAY directive. As this always is the last directive in a HUG program, any function with canvas drawing commands must be invoked with the TIMEOUT directive.


Registering external widgets

Since HUG 0.60 also additional widgets can be added to HUG. First use the REGISTER function to announce the new widget to the internal HUG administration. This already allows the usage of ATTACH, CALLBACK and CALLBACKX for the new widget. Then, optionally, the METHOD function allows invocation of self-defined functions for GRAB$, TEXT, GET and SET.


Overview



The widgets

Button

Hseparator

Progressbar

Check

Hslider

Radio

Clipboard

Image

Spin

Combo

List

Stock

Edit

Mark

Toggle

Entry

Msgdialog

Vseparator

Filedialog

Notebook

Vslider

Frame

Password

Window


The methods

Disable

Get

Show

Enable

Grab$

Text

Focus

Hide

Unfocus

Font

Set



Graphical functions

Canvas

Line

Pixel

Circle

Out

Square

Draw

Picture



Generic functions

Attach

Hugoptions

Register

Callback

Init

Resetkey

Callbackx

Key

Screensize

Display

Method

Setproperty

Getproperty

Mouse

Sync

Huglib$

Quit

Timeout


Variables

Hugversion$

Widget

Markup


HUG functions


ATTACH

ATTACH(window, widget, x, y)

Type: directive

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).

This directive also can be used to position a Window on the screen. The first argument must then contain a 0, and the second argument must contain the Window ID.


BUTTON

BUTTON("caption", xsize, ysize)

Type: function

Creates a button with a caption, and a width of <xsize> and a height of <ysize>. Returns the ID of the created button.


CALLBACK

CALLBACK(widget, function)

Type: directive

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


CALLBACKX

CALLBACKX(widget, function, value)

Type: directive

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>. Returns the ID of the created canvas. 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.

Note that the canvas also can be created as an OpenGL canvas, provided that either the GtkGlArea library or the GtkGlext library is available on the system. To do so, use the CANVAS option in HUGOPTIONS before creating the canvas.


CHECK

CHECK("caption", xsize, ysize)

Type: function

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


CIRCLE

CIRCLE("color", xposition, yposition, width, height, fill)

Type: directive

Draws a circle on the default canvas, where the top left coordinate of the surrounding box is located 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). This directive is available for a GL canvas also.

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. Returns the ID of the created clipboard.


COMBO

COMBO("text", xsize, ysize)

Type: function

Creates a combobox with one entry, and a width of <xsize> and a height of <ysize>. Returns the ID of the created combobox.


DISABLE

DISABLE(widget)

Type: method

Freezes a widget so it cannot be used.


DISPLAY

DISPLAY

Type: directive

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


DRAW

DRAW(canvas)

Type: directive

Defines the default canvas where the drawing takes place.

In case of an OpenGL canvas where GL_FREEZE is enabled (see HUGOPTIONS), or in case non-HUG drawing is used, this function must be called first, as it will prepare the drawing buffer. Then after the actual drawing is finished, the GL canvas must be updated using the SYNC directive.

In all cases the DRAW directive returns the actual lowlevel drawing sub widget.


EDIT

EDIT(xsize, ysize)

Type: directive

Defines a multiline text widget with a width of <xsize> and a height of <ysize>. Returns the ID of the created text widget. See also MARKUP to set the layout of text in this widget.


ENABLE

ENABLE(widget)

Type: 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>. Returns the ID of the created text entry.


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. Returns the ID of the created dialog.


FOCUS

FOCUS(widget)

Type: method

Puts the focus to a widget.


FONT

FONT(widget, "Font name")

Type: directive

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>. Returns the ID of the created frame.


GET

GET(widget)

Type: 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

Hslider

Get the current value from the slider

Vslider

Get the current value from the slider


GETPROPERTY

GETPROPERTY(widget, "property", variable)

Type: directive

Retrieves the value of a property of a widget into a variable. Example:

DECLARE t$
GETPROPERTY(win, "title", ADDRESS(t$))


GRAB$

GRAB$(widget)

Type: 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

Returns the filename being displayed

Clipboard

Gets the text from the clipboard

Hslider

No effect

Vslider

No effect


HIDE

HIDE(widget)

Type: method

Hides a widget so it is invisible.


HSEPARATOR

HSEPARATOR(size)

Type: function

Creates a horizontal separator line with a length of <size>. Returns the ID of the created separator.


HSLIDER

HSLIDER(xsize, ysize, begin, end, step)

Type: function

Creates a horizontal slider with a width of <xsize> and a height of <ysize>. The range of values are determined by <begin> and <end> with a stepsize of <step>. Returns the ID of the created slider.


HUGLIB$

HUGLIB$("type")

Type: function

Returns the actual backend library currently used by HUG. Arguments can be one of the following:


HUGOPTIONS

HUGOPTIONS("option")

Type: directive

This function influences the behavior of the HUG library. Per invocation only one option can be set. The following options are recognized:


HUGVERSION$

HUGVERSION$

Type: variable

Contains the current version number of the Highlevel Universal Gui (HUG).


IMAGE

IMAGE("file", xsize, ysize)

Type: directive

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: directive

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>. See also RESETKEY.


LINE

LINE("color", xstart, ystart, xend, yend)

Type: directive

Draws a line on the default canvas from <xstart>, <ystart> to <xend>, <yend>. This directive is available for a GL canvas also.

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>. Returns the ID of the created list widget.


MARK

MARK("caption", xsize, ysize)

Type: function

Creates a label with a caption, and a width of <xsize> and a height of <ysize>. The caption may contain Pango Text Attribute Markup Language to set different styles and formats. Returns the ID of the created label.


MARKUP

MARKUP

Type: variable

Contains the markup definition for text inserted into any EDIT widget. It can be changed by using the PROPERTY directive. The available property names are defined in the GtkTextTag properties. Refer to the GTK documentation for details. Example:

PROPERTY(MARKUP, "foreground", "#FF00FF", "font", "Sans 12")


METHOD

METHOD(widget, functype, custom func)

Type: directive

After an external widget has been registered into HUG (see REGISTER), it is possible to define the default HUG methods also. This is an optional step. The widgetID needs to be passed as a first argument, then the type of HUG method as second argument, where 1 = GRAB$, 2 = TEXT, 3 = GET and 4 = SET.

The last argument must contain the name of the self-defined SUB or FUNCTION which implements the method. Subsequent invocations of GRAB$, TEXT, GET and SET for the external widget will now execute the self-defined implementation of these methods.


MOUSE

MOUSE(x)

Type: function

Returns the current information of the mouse on a canvas. Depending on the value of <x> a different result can be obtained:

x = 0: x-coordinate

x = 1: y-coordinate

x = 2: button number

x = 3: mousewheel direction (0 is up, 1 is down)

x = 4: canvas ID where the mouse is active

When the mouse is outside a canvas the returned values are -1.


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>. Returns the ID of the created dialog.

The type of dialog can be one of the following: 0 - informational, 1 - warning, 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 text may contain Pango Text Attribute Markup Language to set different styles and formats.

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 = GTK_RESPONSE_YES THEN
        <...your code here...>
    END IF
END SUB
ErrDlg = MSGDIALOG("Error", 300, 200, 3, 4)
CALLBACK(ErrDlg, HandleError)

For a full list of dialog response codes, please refer to the Appendix.


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>. Returns the ID of the created notebook.


OUT

OUT("text", "fgcolor", "bgcolor", xposition, yposition)

Type: directive

Draws text on the default canvas, starting top left at <xposition> and <yposition>. The text may contain Pango Text Attribute Markup Language to set different styles and formats.

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(xsize, ysize)

Type: function

Creates a password entry filled with a width of <xsize> and a height of <ysize>. The actual text is displayed with a special character to hide the actual contents. Returns the ID of the created password entry.


PICTURE

PICTURE("file", xposition, yposition, xsize, ysize)

Type: directive

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: directive

Draws a pixel on the default canvas at <xposition>, <yposition>. This directive is available for a GL canvas also.

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>. Returns the ID of the created progressbar.


PROPERTY

PROPERTY(widget, "property", value)

Type: directive

See the SETPROPERTY directive.


QUIT

QUIT

Type: directive

A convenience function to exit HUG and terminate the program.


RADIO

RADIO("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. Returns the ID of the created radio button.


REGISTER

REGISTER(widget, xsize, ysize, signal$, signal_listen, to_attach, set_font, set_focus)

Type: directive

In case an external widget needs to be visible for the HUG functions ATTACH and CALLBACK, this directive can be used to register the widget into the internal HUG adminstration. The meaning of the arguments:

See also METHOD to optionally register the functions GRAB$, TEXT, GET and SET to an external widget.


RESETKEY

RESETKEY

Type: function

Resets the last key pressed to '0' so subsequent calls to KEY return '0', until a new key is pressed.


SCREENSIZE

SCREENSIZE(dimension)

Type: function

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: 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

Hslider

Sets a value into the slider

Vslider

Sets a value into the slider


SETPROPERTY

SETPROPERTY(widget, "property", value)

Type: directive

Sets a property of a widget to a certain value. Examples:

SETPROPERTY(window, "decorated", TRUE)
SETPROPERTY(button, "tooltip-text", "Testing the properties")


SHOW

SHOW(widget)

Type: 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. Returns the ID of the created spin button.


SQUARE

SQUARE("color", xposition, yposition, width, height, fill)

Type: directive

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). This directive is available for a GL canvas also.

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>. Returns the ID of the created stock button.


SYNC

SYNC

Type: directive

Forces an intermediate update of the GUI.

In case of an OpenGL canvas, this directive will force a buffer swap also. This particularly should be used when the GL canvas has option GL_FREEZE enabled (see HUGOPTIONS), or in case a non-HUG drawing is applied, so when using plain OpenGL functions directly. In both cases, before the actual GL drawing is executed, the buffer should have been prepared with DRAW.


TEXT

TEXT(widget, "text")

Type: 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, empty text removes last line

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

Sets the filename to load

Clipboard

Sets text on the clipboard

Hslider

No effect

Vslider

No effect


TIMEOUT

TIMEOUT(millisec, sub|function)

Type: directive

Sets up a timeout while the main eventloop is executed. After the timeout in milliseconds, a self-defined <sub> or <function> is executed.

If the timeout should not occur again, then the executed function should return FALSE. Canceling a timeout cannot be done using a SUB.

The amount of milliseconds can be changed to another value during runtime. Example:

INCLUDE "hug.bac", INIT, GET, SET, WINDOW, PROGRESSBAR, ATTACH, TIMEOUT, DISPLAY
DECLARE pb, x, offset
offset = 1

FUNCTION set_value
    INCR x, offset
    IF x >= 100 OR x <= 0 THEN offset = -1*offset
    SET(pb, x)
    PRINT GET(pb)
    RETURN TRUE
END FUNCTION

INIT
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>. Returns the ID of the created toggle button.


UNFOCUS

UNFOCUS(widget)

Type: method

Disable the focus on a widget.


VSLIDER

VSLIDER(xsize, ysize, begin, end, step)

Type: function

Creates a vertical slider with a width of <xsize> and a height of <ysize>. The range of values are determined by <begin> and <end> with a stepsize of <step>. Returns the ID of the created slider.


VSEPARATOR

VSEPARATOR(ysize)

Type: function

Creates a vertical separator line with a length of <size>. Returns the ID of the created separator.


WIDGET

WIDGET

Type: variable

Contains the widgetID of the last created widget.


WINDOW

WINDOW("title", xsize, ysize)

Type: function

Creates a window with a title, and a width of <xsize> and a height of <ysize>. Returns the ID of the created window.


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 LibreOffice 3.6.2.2.
Back to top of document