#---------------------------------------------------------------------------
#
#  HHHHHHHHH     HHHHHHHHHUUUUUUUU     UUUUUUUU       GGGGGGGGGGGGG
#  H:::::::H     H:::::::HU::::::U     U::::::U    GGG::::::::::::G
#  H:::::::H     H:::::::HU::::::U     U::::::U  GG:::::::::::::::G
#  HH::::::H     H::::::HHUU:::::U     U:::::UU G:::::GGGGGGGG::::G
#    H:::::H     H:::::H   U:::::U     U:::::U G:::::G       GGGGGG
#    H:::::H     H:::::H   U:::::D     D:::::UG:::::G
#    H::::::HHHHH::::::H   U:::::D     D:::::UG:::::G
#    H:::::::::::::::::H   U:::::D     D:::::UG:::::G    GGGGGGGGGG
#    H:::::::::::::::::H   U:::::D     D:::::UG:::::G    G::::::::G
#    H::::::HHHHH::::::H   U:::::D     D:::::UG:::::G    GGGGG::::G
#    H:::::H     H:::::H   U:::::D     D:::::UG:::::G        G::::G
#    H:::::H     H:::::H   U::::::U   U::::::U G:::::G       G::::G
#  HH::::::H     H::::::HH U:::::::UUU:::::::U  G:::::GGGGGGGG::::G
#  H:::::::H     H:::::::H  UU:::::::::::::UU    GG:::::::::::::::G
#  H:::::::H     H:::::::H    UU:::::::::UU        GGG::::::GGG:::G
#  HHHHHHHHH     HHHHHHHHH      UUUUUUUUU             GGGGGG   GGGG
#
#---------------------------------------------------------------------------

This is some documentation for the High-level Universal GUI (HUG). To be
rewritten someday.

The Highlevel Universal GUI abstraction layer (HUG) is a simple set of
functions to allow BaCon setting up graphical user interfaces. 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.

#==========================================================================================================================================================================================
# Widgets
#==========================================================================================================================================================================================

WINDOW "title" xsize ysize			: Define a new window.
BUTTON "label" xsize ysize			: Define a button. Note: use '_' to underscore a character.
STOCK "stock-label" xsize ysize			: Define a stock button.
TOGGLE "label" xsize ysize			: Define a toggle button. Note: use '_' to underscore a character.
CHECK "label" xsize ysize			: Define a checkbutton.
RADIO "label" xsize ysize group			: Define a radiobutton. Note: group may point to a previous radiobutton with which it excludes.
ENTRY "text" xsize ysize			: Define a text entry.
PASSWORD xsize ysize				: Define a password entry.
MARK "text" xsize ysize				: Define a label.
COMBO "text" xsize ysize			: Define a droplist.
HSEPARATOR xsize				: Define a horizontal separator.
VSEPARATOR ysize				: Define a vertical separator.
FRAME xsize ysize				: Define a frame.
EDIT xsize ysize				: Define a multiline text.
LIST xsize ysize				: Define a multiline list widget.
SPIN xsize ysize start end step			: Define a spin button with range start-end and a stepsize.
NOTEBOOK "text" xsize ysize			: Define a notebook.
MSGDIALOG "text" xsize ysize type buttons	: Define a message dialog. Type: 0=info, 1=warning, 2=question, 3=error, 4=other / buttons: 0=none, 1=ok, 2=close, 3=cancel
FILEDIALOG "title" "btntext" xsize ysize action	: Define a file dialog. Action: 0-Open 1-Save 2-Selectfolder 3-Createfolder. Show dialog with SHOW, hide with HIDE.
IMAGE "file" xsize yszize			: Load a picture from a file and define as widget
CLIPBOARD					: Gets the cliboard object

#==========================================================================================================================================================================================
# Methods (setting and getting properties of above widgets)
#==========================================================================================================================================================================================

TEXT widget text				: Set text into a widget. Note: with combobox and list a line is added. Notebook adds a tab. Filedialog sets the filename. An empty string clears the widget.
GRAB$ widget					: Get text from a widget. Note: with combobox and list get current selection. Notebook gets string in active tab. Filedialog gets the selected filename.

SET widget value				: Set status of widget. Note: button: 0=normal, 1=pressed/selected, combobox and list: select row, multiline text: go to this linenr, notebook: select tab, passswd: char visible.
GET widget					: Get status of widget. Note: with combobox and list gets indexnr of row. With multiline text widget gets amount of lines. Notebook: get current tab, passwd: get visibility.

FOCUS widget					: Give focus to widget
UNFOCUS widget					: Disable focus on widget

DISABLE widget					: Disable widget
ENABLE widget					: Enable widget

HIDE widget					: Hide widget
SHOW widget					: Show widget

FONT widget font				: Set font in widget. Font examples: "Arial 15", "Luxi Mono 12".

#==========================================================================================================================================================================================
# Graphical stuff
#==========================================================================================================================================================================================

CANVAS xsize ysize				: Define a drawing canvas.
DRAW canvas					: Define the default canvas where we are drawing.
CIRCLE color x y xsize ysize fill		: Draw a circle on a canvas.
PIXEL color x y					: Draw a pixel on a canvas.
LINE color xstart ystart xend yend		: Draw a line on a canvas.
SQUARE color x y xsize ysize fill		: Draw a rectangle on a canvas.
OUT "text" fgcolor bgcolor x y			: Draw some text on a canvas. note: if bgcolor is empty string then background is transparent.
PICTURE "file" xpos ypos xsize ysize		: Draw picture from file to canvas at (xpos, ypos) with size (xsize, ysize)

#==========================================================================================================================================================================================
# Other generic functions
#==========================================================================================================================================================================================

HUGOPTIONS opts					: Define options for HUG. (1) "TABLE x y" -> use GtkTable with size x,y instead of GtkFixed (2) More options to be defined

ATTACH window widget x y			: Attach a widget on a parent Window at x,y

CALLBACK widget function			: Setup a callback to a function - note: surround function with ADDRESS

KEY						: Get last key pressed on keyboard
MOUSE arg					: Get mouse info. Notes: arg = 0 = x_coordinate, arg = 1 = y_coordinate, arg = 2 = button, arg = 3 = wheel

DISPLAY						: Execute main GTK eventloop.
SYNC						: Force update of the GUI
TIMEOUT seconds function			: Setup a timeout while GTK 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. Note: can be changed to another timeout value during runtime
END						: Cleanup and exit HUG.