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

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 the MARKUP property in HUGOPTIONS 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.

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.

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:

• "gtk" – current GTK library version

• "gdk" - current GDK library version

• "glib" - current Glib library version

• "gobject" - current Gobject library version

• "pango" - current Pango library version

• "glarea" - current GtkGlArea library version

• "glext" - current GtkGlExt library version

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:

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

• "WIDGET_SHOW x" - by default show widgets at creation (1) or not (0). Default: 1

• "FONT name$" - default font for all the widgets. Example: "FONT Arial 12"

• "CANVAS type$" - define canvas type (GL, GLAREA, GLEXT, GOO or GTK). The option GL tries to autodetect a suitable library. Example: "CANVAS GL"

• "GL_FREEZE x" – automatically update the GL canvas (0), or not (1). Enabling this option will achieve better performance. Default: 0

• "CLIPBOARD x" – define which ICCCM clipboard to use: 0 = CLIPBOARD, 1 = PRIMARY and 2 = SECONDAY. Default value: 0.

• "MARKUP <property>:<value>[,<property>:<value>,...]" - contains the markup definition for text inserted into the current EDIT widget. The available property names are defined in the GtkTextTag properties. Refer to the GTK documentation for details. Example: "MARKUP foreground:#FF0000"

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.

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:

• widget: the widget ID to register

• xsize: the width of the new widget

• ysize: the height of the new widget

• signal$: the actual name of the signal to emit when the widget is activated, for example: "activate", "clicked", "show", etc.

• the (sub-)widget which actually listens to the signal, 0 = default widget

• the (sub-)widget which actually is attached, 0 = default widget

• the (sub-)widget which actually displays text, 0 = default widget

• the (sub-)widget which actually can receive focus, 0 = default widget

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.

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.

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

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