Gui
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.
Functions
void | gui_start (void) |
void | gui_finish (void) |
void | gui_respack (...) |
void | gui_language (...) |
const char_t* | gui_text (...) |
const Image* | gui_image (...) |
const byte_t* | gui_file (...) |
void | gui_OnThemeChanged (...) |
Types and Constants
enum | orient_t |
enum | state_t |
enum | mouse_t |
enum | cursor_t |
enum | close_t |
enum | scale_t |
enum | window_flag_t |
enum | event_t |
struct | Control |
struct | Label |
struct | Button |
struct | PopUp |
struct | Edit |
struct | Combo |
struct | ListBox |
struct | UpDown |
struct | Slider |
struct | Progress |
struct | View |
struct | TextView |
struct | ImageView |
struct | TableView |
struct | SplitView |
struct | Layout |
struct | Cell |
struct | Panel |
struct | Window |
struct | Menu |
struct | MenuItem |
struct | EvButton |
struct | EvSlider |
struct | EvText |
struct | EvTextFilter |
struct | EvDraw |
struct | EvMouse |
struct | EvWheel |
struct | EvKey |
struct | EvPos |
struct | EvSize |
struct | EvWinClose |
struct | EvMenu |
The Gui library allows you to create graphical user interfaces in a simple and intuitive way. Only available for desktop applications for obvious reasons (Figure 1), unlike the rest of libraries that can also be used in command line applications.

Like Draw2D and Osbs Gui relies on the APIs of each operating system (Figure 2). In addition to the advantages already mentioned in these two cases, native access to interface elements will cause our programs to be fully integrated in the desktop and according to the visual theme present in each machine (Figure 3).


1. Declarative composition
The Gui library moves away from the concept of treating windows (or dialog boxes) as an external resource of the program. On the contrary, these are created directly from the source code avoiding layout by visual editors (Figure 4). We must bear in mind that window managers use different fonts and templates, so specifying specific positions and sizes for the elements will not be portable between platforms (Figure 5). On the contrary, in Gui the controls are located in a virtual grid called Layout, which will calculate its location and final size at runtime and depending on the platform (Figure 6).



In addition, another relevant fact is that interfaces are living objects subject to constant changes. A clear example is the translations, which alter the location of the elements due to the new dimension of the text (Figure 7). Gui will adapt to these events automatically, recalculating positions to maintain a consistent layout.

2. Anatomy of a window.
In (Figure 8) we have the main parts of a window. Controls are the final elements with which the user interacts to enter data or launch actions. The views are rectangular regions of relatively large size where information is represented by text and graphics, being able to respond to keyboard or mouse events. Finally, all these elements will be grouped into panels and will be layout by layouts.

- Label. Small blocks of descriptive text.
- Button. Push buttons, check boxes or radio buttons.
- PopUp. Button with drop-down list.
- Edit. Text edit box.
- Combo. Edit box with drop-down list.
- ListBox. List box.
- UpDown. Increment and decrement buttons.
- Slider. Sliding bar.
- Progress. Progress bar.
- View. Generic view where you can freely draw and capture user events. Useful for creating custom controls.
- TextView. View to show and edit texts, allowing to combine formats.
- ImageView. View to display images.
- TableView. Table view to display tabulated information in rows and columns.
- SplitView. View divided into two parts that allows, by means of a slider, to divide the total area between both zones.
- Layout. Virtual and invisible grid that divides the panel space into cells where we will place the different controls and views.
- Panel. Sub-window linked to the main window, without frame or border, where different controls can be grouped.
- Window. Main window with title bar and frame.
- Menu. List of options. Depending on the system they are part of the window (Windows, Ubuntu) or are displayed directly on the desktop (macOS).
- MenuItem. Each of the menu items.
3. GUI Events
Desktop applications are event driven, which means that they are continually waiting for the user to perform some action on the interface: Press a button, drag a slider, write a text, etc. When this occurs, the window manager detects the event and notifies the application (Figure 9), which must provide an event handler with the code to execute. For example in (Listing 1) we define a handler to respond to the press of a button. Obviously, if there is no associated handler, the application will ignore the event.
- Use event_params to obtain the parameters associated with the event. Each type of event has its own parameters. See (Table 1).
- Use event_result to write the response to the event. Very few events require sending a response.

1 2 3 4 5 6 7 8 9 |
static void i_OnClick(App *app, Event *e) { const EvButton *param = event_params(e, EvButton); if (param->state == ekON) create_new_file(app); } Button *button = button_push(); button_OnClick(button, listener(app, i_OnClick, App)); |
Event | Handler | Parameters | Response |
Click in label | label_OnClick | EvText | - |
Click on button | button_OnClick | EvButton | - |
Selection in PopUp | popup_OnSelect | EvButton | - |
Selection in ListBox | listbox_OnSelect | EvButton | - |
Press key on Edit | edit_OnFilter | EvText | EvTextFilter |
End of edit in Edit | edit_OnChange | EvText | - |
Key press on Combo | combo_OnFilter | EvText | EvTextFilter |
End of editing in Combo | combo_OnChange | EvText | - |
Slider movement | slider_OnMoved | EvSlider | - |
Click on UpDown | updown_OnClick | EvButton | - |
Draw the contents of a view | view_OnDraw | EvDraw | - |
The size of a view has changed | view_OnSize | EvSize | - |
The mouse enters the area of a view | view_OnEnter | EvMouse | - |
The mouse leaves the area of a view | view_OnExit | - | - |
The mouse moves over a view | view_OnMove | EvMouse | - |
A mouse button was pressed | view_OnDown | EvMouse | - |
A mouse button has been released | view_OnUp | EvMouse | - |
Click on a view | view_OnClick | EvMouse | - |
Dragging on a view | view_OnDrag | EvMouse | - |
Mouse wheel on a view | view_OnWheel | EvWheel | - |
Press key on a view | view_OnKeyDown | EvKey | - |
Release key on a view | view_OnKeyUp | EvKey | - |
Vista has received keyboard focus | view_OnFocus | bool_t | - |
Close a window | window_OnClose | EvWinClose | bool_t |
Window moving around the desk | window_OnMoved | EvPos | - |
Window is re-dimensioning | window_OnResize | EvSize | - |
Click on an item menu | menuitem_OnClick | EvMenu | - |
Color change | comwin_color | color_t | - |
enum orient_t
Orientation.
enum orient_t
{
ekHORIZONTAL,
ekVERTICAL
};
ekHORIZONTAL | Horizontal. |
ekVERTICAL | Vertical. |
enum state_t
State values.
enum state_t
{
ekOFF,
ekON,
ekMIXED
};
ekOFF | Off. |
ekON | On. |
ekMIXED | Medium/undetermined. |
enum mouse_t
Mouse buttons.
enum mouse_t
{
ekMLEFT,
ekMRIGHT,
ekMMIDDLE
};
ekMLEFT | Left. |
ekMRIGHT | Right. |
ekMMIDDLE | Center. |
enum cursor_t
Cursors. See window_cursor.
enum cursor_t
{
ekCARROW,
ekCHAND,
ekCIBEAM,
ekCCROSS,
ekCSIZEWE,
ekCSIZENS,
ekCUSER
};
ekCARROW | Arrow (default). |
ekCHAND | Hand. |
ekCIBEAM | Vertical bar (text editing). |
ekCCROSS | Cross. |
ekCSIZEWE | Horizontal resize (left-right). |
ekCSIZENS | Vertical resize (top-bottom). |
ekCUSER | Created from an image. |
enum close_t
Reason for closing a window.
enum close_t
{
ekCLESC,
ekCLINTRO,
ekCLBUTTON,
ekCLDEACT
};
ekCLESC | The |
ekCLINTRO | The |
ekCLBUTTON | The close button |
ekCLDEACT | The parent window has been hidden. |
enum scale_t
Scaling modes.
enum scale_t
{
ekAUTO,
ekSNONE,
ekASPECT,
ekASPECTDW
};
ekAUTO | Automatic scaling, the proportion may change. |
ekSNONE | No scaling. |
ekASPECT | Automatic scaling, but maintaining the proportion (aspect ratio). |
ekASPECTDW | Same as above, but does not increase the original size, only reduce it if appropriate. |
enum window_flag_t
Window creation attributes.
enum window_flag_t
{
ekWNFLAG,
ekWNEDGE,
ekWNTITLE,
ekWNMAX,
ekWNMIN,
ekWNCLOSE,
ekWNRES,
ekWNSTD,
ekWNSRES
};
ekWNFLAG | Default attributes. |
ekWNEDGE | The window draws an outer border. |
ekWNTITLE | The window has a title bar. |
ekWNMAX | The window shows the maximize button. |
ekWNMIN | The window shows the minimize button. |
ekWNCLOSE | The window shows the close button. |
ekWNRES | The window has resizable borders. |
ekWNSTD | Combination |
ekWNSRES | Combination |
enum event_t
Event type. See GUI Events.
enum event_t
{
ekEVLABEL,
ekEVBUTTON,
ekEVPOPUP,
ekEVLISTBOX,
ekEVSLIDER,
ekEVUPDOWN,
ekEVTXTFILTER,
ekEVTXTCHANGE,
ekEVFOCUS,
ekEVMENU,
ekEVDRAW,
ekEVRESIZE,
ekEVENTER,
ekEVEXIT,
ekEVMOVED,
ekEVDOWN,
ekEVUP,
ekEVCLICK,
ekEVDRAG,
ekEVWHEEL,
ekEVKEYDOWN,
ekEVKEYUP,
ekEVWNDMOVED,
ekEVWNDSIZING,
ekEVWNDSIZE,
ekEVWNDCLOSE,
ekEVCOLOR,
ekEVTHEME
};
ekEVLABEL | Click on a Label control. |
ekEVBUTTON | Click on a Button control. |
ekEVPOPUP | The selection of a PopUp control has been changed. |
ekEVLISTBOX | The selection of a control has been changed ListBox. |
ekEVSLIDER | You are moving an Slidercontrol. |
ekEVUPDOWN | Click on a UpDown control. |
ekEVTXTFILTER | |
ekEVTXTCHANGE | You have finished editing the text of a Edit or Combo control. |
ekEVFOCUS | A control has received keyboard focus. |
ekEVMENU | Click on a menu. |
ekEVDRAW | The view content must be redrawn. |
ekEVRESIZE | The size of a view has changed. |
ekEVENTER | The mouse has entered the view area. |
ekEVEXIT | The mouse has left the view area. |
ekEVMOVED | The mouse is moving on the view surface. |
ekEVDOWN | A mouse button was pressed. |
ekEVUP | A mouse button has been released. |
ekEVCLICK | Click on a view. |
ekEVDRAG | Dragging is being done over. |
ekEVWHEEL | Mouse wheel has moved. |
ekEVKEYDOWN | A key has been pressed. |
ekEVKEYUP | A key has been released. |
ekEVWNDMOVED | The window is moving across the desktop. |
ekEVWNDSIZING | The window is being resized. |
ekEVWNDSIZE | The window has been resized. |
ekEVWNDCLOSE | The window has been closed. |
ekEVCOLOR | An update color of comwin_color. |
ekEVTHEME | Desktop theme has changed. |
struct Control
Interface Control (abstract).
struct Control;
struct Label
Interface control that contains static text, usually limited to a single line. Label.
struct Label;
struct Button
Interface control representing a button. Button.
struct Button;
struct PopUp
Control button with drop-down list. PopUp.
struct PopUp;
struct Edit
Text editing control Edit.
struct Edit;
struct Combo
Control that combines an edit box with a drop-down list. Combo.
struct Combo;
struct ListBox
List control. ListBox.
struct ListBox;
struct UpDown
Control that shows two small increase and decrease buttons. UpDown.
struct UpDown;
struct Slider
Control that shows a bar with a slider. Slider.
struct Slider;
struct Progress
Progress bar. Progress.
struct Progress;
struct View
Custom View that allows to create our own controls, drawing what we want. View
struct View;
struct TextView
Text view with several paragraphs and different attributes. TextView.
struct TextView;
struct ImageView
Image viewer control. ImageView.
struct ImageView;
struct TableView
Table view with multiple rows and columns. TableView.
struct TableView;
struct SplitView
Resizable horizontal or vertical split view. SplitView.
struct SplitView;
struct Layout
Invisible grid where the controls of a Panel are organized. Layout.
struct Layout;
struct Cell
Each of the cells that form a Layout. Cell.
struct Cell;
struct Panel
Internal area of a window, which allows you to group different controls. Panel.
struct Panel;
struct Window
Interface window. Window.
struct Window;
struct Menu
Menu or submenu. Menu.
struct Menu;
struct MenuItem
Item within a menu. MenuItem.
struct MenuItem;
struct EvButton
Parameters of the OnClick event of a button or OnSelect of a popup.
struct EvButton { uint32_t index; state_t state; const char_t* text; };
index | Button or item index. |
state | State. |
text | Text. |
struct EvSlider
Parameters of the OnMoved event of a slider.
struct EvSlider { real32_t pos; real32_t incr; uint32_t step; };
pos | Normalized slider position (0, 1). |
incr | Increase with respect to the previous position. |
step | Interval index (only for discrete ranges). |
struct EvText
Parameters of the OnChange event of the text boxes.
struct EvText { const char_t* text; uint32_t cpos; };
text | Text. |
cpos | Cursor position (caret). |
struct EvTextFilter
Result of the OnFilter event of the text boxes.
struct EvTextFilter { bool_t apply; char_t* text; uint32_t cpos; };
apply |
|
text | New control text, which is a revision (filter) of the original text. |
cpos | Cursor position (caret). |
struct EvDraw
OnDraw event parameters.
struct EvDraw { DCtx* ctx; real32_t x; real32_t y; real32_t width; real32_t height; };
ctx | 2D drawing context. |
x | X coordinate of the drawing area (viewport). |
y | Y coordinate of the drawing area. |
width | Width of the drawing area. |
height | Height of the drawing area. |
struct EvMouse
Mouse event parameters.
struct EvMouse { real32_t x; real32_t y; mouse_t button; uint32_t count; };
x | Pointer x coordinate. |
y | Coordinate and pointer. |
button | Active button. |
count | Number of clicks. |
struct EvWheel
OnWheel event parameters.
struct EvWheel { real32_t x; real32_t y; real32_t dx; real32_t dy; real32_t dz; };
x | Pointer x coordinate. |
y | Pointer y coordinate. |
dx | Increase in x of the wheel or trackpad. |
dy | Increase in x of the wheel or trackpad. |
dz | Increase in x of the wheel or trackpad. |
struct EvKey
Keyboard event parameters.
struct EvKey { vkey_t key; };
key | Pulsed key or released. |
struct EvPos
Parameters of change of position events.
struct EvPos { real32_t x; real32_t y; };
x | X coordinate. |
y | Y coordinate. |
struct EvSize
Resize event parameters.
struct EvSize { real32_t width; real32_t height; };
width | Width (size in x). |
height | Height (size in y). |
struct EvWinClose
Window closing Event Parameters.
struct EvWinClose { close_t origin; };
origin | Origin of the close. |
struct EvMenu
Menu event parameters.
struct EvMenu { uint32_t index; state_t state; const char_t* str; };
index | Pressed item index. |
state | Pressed item status. |
str | Pressed item text. |
gui_start ()
Start the Gui library, reserving space for global internal structures. Internally call draw2d_start. It is called automatically by osmain.
void
gui_start(void);
gui_finish ()
Finish the Gui library, freeing up the space of global internal structures. Internally call draw2d_finish. It is called automatically by osmain.
void
gui_finish(void);
gui_respack ()
Register a resource package.
void gui_respack(FPtr_respack func_respack);
func_respack | Resource constructor. |
Remarks
See Resources.
gui_language ()
Set the language of the registered resources with gui_respack.
void gui_language(const char_t *lang);
lang | Language. |
Remarks
See Resources.
gui_text ()
Get a text string through its resource identifier.
const char_t* gui_text(const ResId id);
id | Resource Identifier. |
Return
The text string or NULL
if it is not found.
Remarks
The resource must belong to a package registered with gui_respack.
gui_image ()
Get an image through its resource identifier.
const Image* gui_image(const ResId id);
id | Resource Identifier. |
Return
The image or NULL
if it is not found.
Remarks
The resource must belong to a package registered with gui_respack. Do not destroy the image as it is managed by Gui.
gui_file ()
Get the contents of a file through its resource identifier.
const byte_t* gui_file(const ResId id, uint32_t *size);
id | Resource Identifier. |
size | Buffer size in bytes. |
Return
File data or NULL
if it is not found.
Remarks
The resource must belong to a package registered with gui_respack. The data is managed by Gui, so there is no need to free memory.
gui_OnThemeChanged ()
Set a handler to detect the change of the visual theme of the windows environment.
void gui_OnThemeChanged(Listener *listener);
listener | The event handler. |