lbgui.h

This include file offers functions for creating standard GUI elements, such as Buttons, Windows, Checkboxes, Infoboxes, Listboxes, Progress bars, Sliders, Scrollbars, Rightclick menus, Comboboxes, and Editboxes. All GUI elements are built from basic PANEL and TEXT objects. It's also possible to put panels and text objects on GUI windows. The styles and images are completely customizable.

lbgui.h was developed by Lukas Brozio for the Summer 2010 contest. It is not directly included in Gamestudio, but comes with the goodies8.zip add-on package that is available for free download on the Gamestudio download page. Just open the package and copy lbgui.h into the Gamestudio include folder. The package also contains the 'green' default style as in the image above, and two self-explaining demos - smalldemo.c and demo.c. The LBGUI manual is also contained in the package. All GUI functions are described in the manual; in the following you'll just find a short overview.

Usage

At the beginning of your main script, after including acknex.h, you have to include the file lbgui.h, f.i.:

#include <acknex.h>
#include <default.c>
#include <lbgui.h>

Make sure that you copied the file lbgui.h into your include folder. Before you can use any of the functions of LBGUI, open the GUI with LBGUI_open() in your main function:

function main()
{
  ...
  LBGUI_open();

This will start the loop that manages all GUI elements, and another loop that takes the input for editboxes. If you don't need LBGUI anymore in your project, you have to close it with LBGUI_close():

LBGUI_close();

This will destroy all GUI objects and terminate the main loop and the editbox loop. If you need LBGUI all the time, which will propably be the case for most projects, I recommend doing this:

on_exit = LBGUI_close; // Close LBGUI when the project is closed

Structs

All LBGUI elements are stored in structs, just like the standard engine objects. The name of all structs (as well as the names of all functions) in LBGUI is preceeded by "LBG_" (e.g. LBG_BUTTON). This is to avoid any conflicts with the names of existing engine functions/objects, or with names in your own script.

All GUI structs start like this:

typedef struct LBG_STRUCTNAME // the name of the GUI element
{
	long ssize; // Size of the struct
	long stype; // Type of GUI element	
	struct LBG_STRUCTNAME* next; // Next object in the linked list
	struct LBG_STRUCTNAME* previous; // Previous object in the linked list
...

stype contains a number (1-18), meaning the following:
1 - Window
2 - Button
3 - Panel
4 - Text
6 - Checkbox
7 - Infobox
8 - Progress Bar
9 - Horizontal Scrollbar
10 - Vertical Scrollbar
11 - Slider
13 - Listbox
14 - List item
15 - Rightclick menu
16 - Combobox
17 - Digits
18 - Editbox

Because of the similiarity of the structs, it is possible to create functions that work for several or even all GUI elements. LBGUI functions that do that always use LBG_WINDOW as dummy struct. If you want to write a function for more than one specific GUI element, you can look into lbgui.h to see if they are compatible. Note that the order in which struct members are documented in the LBGUI manual may differ from the order in the struct definition. Some members aren't documented at all, because they are for internal use only.

All structs are contained in a linked list. These are the first instances of each struct:

LBG_WINDOW* LBG_WINDOW_FIRST = 0;
LBG_BUTTON* LBG_BUTTON_FIRST = 0;
LBG_PANEL* LBG_PANEL_FIRST = 0;
LBG_TEXT* LBG_TEXT_FIRST = 0;
LBG_CHECKBOX* LBG_CHECKBOX_FIRST = 0;
LBG_INFOBOX* LBG_INFOBOX_FIRST = 0;
LBG_PROGRESSBAR* LBG_PROGRESSBAR_FIRST = 0;
LBG_HSCROLLBAR* LBG_HSCROLLBAR_FIRST = 0;
LBG_VSCROLLBAR* LBG_VSCROLLBAR_FIRST = 0;
LBG_SLIDER* LBG_SLIDER_FIRST = 0;
LBG_LISTBOX* LBG_LISTBOX_FIRST = 0;
LBG_RIGHTCLICK* LBG_RIGHTCLICK_FIRST = 0;
LBG_COMBOBOX* LBG_COMBOBOX_FIRST = 0;
LBG_DIGITS* LBG_DIGITS_FIRST = 0;
LBG_EDITBOX* LBG_EDITBOX_FIRST = 0;

The next and previous element of an object can be accessed with object->next and object->previous.

There are also other structs, which don't contain GUI elements, but bitmaps for GUI elements.

Flags

All GUI elements have flags, stored in their flag member. All flag names are preceeded by "XF_", where "X" is replaced by a one or two letter abbreviation for the GUI elements, and "F" just stands for "flag", (e.g. BF_ACTIVE). Just like "normal" flags you can set, reset and toggle them with bit operators (|,&,~,^), or use the set(obj,flag), etc. macros.

The GUI itself also has flags, which are stored in the global long LBG_flags. The following flags are available:
LBGUI_RUNNING - The GUI is running (it has been opened).
LBGUI_DISABLED - Disables the whole GUI.
LBGUI_PROTECTMOUSE - If the mouse is outside the engine window, the GUI considers the mouse as at the border of the window. This prevents windows to be moved outside the window, where they would be lost.
LBGUI_STOPACTION - Stops an action that is normally executed after certain events. This flag is enabled by LBG_stop_action.

Some flags are for internal use and not documented in the manual.

Layers

All GUI elements have layers. They are NOT the same as the layers of "normal" engine objects (like panels/texts/views). The layers of the panels/texts of the GUI elements is calculated by their layer value. Windows obviously each have a different layer, which is set automatically. You should NOT change the layer value of a window directly! Always use the GUI functions for that.

The layers of the panels/texts of all child elements of a window are calculated by the layer of their parent window, and their own layer value. Their layer value can usually be left to default. It's only necessary to change them if they overlap. Note that GUI elements don't "recognize" other GUI elements that above them on the same window. If you really need e.g. two overlapping buttons, you can use button->Condition to prevent that they both react at the same time.

The layers the panels/texts of the GUI elements depend on those values, which are defined in lbgui.h:

Name:	Default:	Description:


LBG_lowest_layer	10	The lowest possible layer. Used by elements on the background.


LBG_highest_layer	1000	The assumed highest layer for all GUI elements. This is used e.g. by infoboxes. This does NOT prevent any GUI element to have a higher layer than this value!


LBG_winlayer	10	The lowest possible layer for a window, relative to LBG_lowest_layer.


LBG_layer_step	10	The "distance" between two windows.


LBG_butlayer_step	2	The layers of the panel/text of a GUI object with a layer value > 0 gets increased by layer*LBG_butlayer_step.

Those are no variables but defines. To change them for your project you can define them differently before you include lbgui.h.

Fonts

GUI elements, which have texts, get the following fonts by default:

FONT* LBG_window_font = "Arial#24b";
FONT* LBG_button_font = "Arial#24b";
FONT* LBG_checkbox_font = "Arial#24b";
FONT* LBG_infobox_font = "Arial#16";
FONT* LBG_progressbar_font = "Arial#24b";
FONT* LBG_listitem_font = "Arial#24b";
FONT* LBG_editbox_font = "Arial#24b";
FONT* LBG_digits_font = "Arial#24b";

You can change their fonts after you created them, or you can just replace the default fonts by your own fonts, like this:

ptr_remove(LBG_button_font); // Remove the old font
LBG_button_font = font_create("Arial#20bi"); // Create the new one

Please note that LBGUI has not been tested with Bitmap fonts.

Mouse cursor

LBGUI can also change the mouse cursor, like if it's over a button or editbox or resizing a window. But it doesn't change it directly, it only sets the global var LBG_mouse_cursor.
Its values mean the following:
0 - Standard mouse cursor
1 - Over a button (e.g. a hand or the standard arrow)
2 - Horizontal window resize
3 - Vertical window resize
4 - Diagonal window resize (topleft-buttomright)
5 - Diagonal window resize (topright-buttomleft)
6 - Over an editbox

It's up to the user to change the mouse cursor according to that variable.

Events

LBGUI elements have events, that are executed on different occasions, like when a button is clicked, or a window is closed. For each occasion, there is an other event. All event names begin with a capital letter. They can be assigned just like entity events, e.g.:

mywindow->Maximize = myfunction; // Execute myfunction when the maximize button of the window is pressed.

When an event is triggered, the GUI element that triggered it can be always accessed with LBG_event_object. There are also pointers that are specific for the object that triggered them, defined as follows:

LBG_WINDOW* LBG_event_object;
LBG_WINDOW* LBG_event_window;
LBG_BUTTON* LBG_event_button;
LBG_PANEL* LBG_event_panel;
LBG_TEXT* LBG_event_text;
LBG_CHECKBOX* LBG_event_checkbox;
LBG_INFOBOX* LBG_event_infobox;
LBG_PROGRESSBAR* LBG_event_progressbar;
LBG_HSCROLLBAR* LBG_event_scrollbar;
LBG_HSCROLLBAR* LBG_event_hscrollbar;
LBG_VSCROLLBAR* LBG_event_vscrollbar;
LBG_SLIDER* LBG_event_slider;
LBG_LISTBOX* LBG_event_listbox;
LBG_LISTITEM* LBG_event_listitem;
LBG_RIGHTCLICK* LBG_event_rightclick;
LBG_COMBOBOX* LBG_event_combobox;
LBG_DIGITS* LBG_event_digits;
LBG_EDITBOX* LBG_event_editbox;

Credits and License

LBGUI, the manual, and the demos were created by Lukas Brozio. The graphics are made by Spike. Some of them are made by Lukas Brozio, mostly by editing Spike's ones.

LBGUI is Open Source. You can use it for any commercial and non-commercial project when you mention its author in the credits of your project.