Cross-platform C SDK logo

Cross-platform C SDK

Gui

❮ Back
Next ❯
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

voidgui_start (void)
voidgui_finish (void)
voidgui_respack (...)
voidgui_language (...)
const char_t*gui_text (...)
const Image*gui_image (...)
const byte_t*gui_file (...)
voidgui_OnThemeChanged (...)

Types and Constants

enumorient_t
enumstate_t
enummouse_t
enumcursor_t
enumclose_t
enumscale_t
enumview_flag_t
enumwindow_flag_t
enumevent_t
structControl
structLabel
structButton
structPopUp
structEdit
structCombo
structListBox
structUpDown
structSlider
structProgress
structView
structTextView
structImageView
structTableView
structSplitView
structLayout
structCell
structPanel
structWindow
structMenu
structMenuItem
structEvButton
structEvSlider
structEvText
structEvTextFilter
structEvDraw
structEvMouse
structEvWheel
structEvKey
structEvPos
structEvSize
structEvWinClose
structEvMenu

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.

Gui library dependency tree.
Figure 1: Dependencies of Gui. See SDK reference.

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

Gui dependencies depending on each operating system.
Figure 2: Gui connects to the interface APIs of each operating system.
Image of the same program running on Windows, macOS and Linux.
Figure 3: The interfaces created with Gui will adapt to the style of each window environment.

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

Capture of the interface editor included in Xcode.
Figure 4: Resource editors are not good allies to create complex dynamic interfaces. Even less if we want to carry them between platforms.
Label and Button controls on Windows, macOS and Linux.
Figure 5: Using fixed dimensions for controls will not adapt well when migrating the program.
Label and Button controls on Windows, macOS and Linux.
Figure 6: The Layout calculates the position and size of the components at runtime.

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.

Translation of a runtime application.
Figure 7: The windows automatically adapt to runtime changes.

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.

Interface window where the most important parts are highlighted.
Figure 8: Notable parts in an interface window.
  • 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.


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 [ESC] key has been pressed (cancel).

ekCLINTRO

The [ENTER] key has been pressed (accept).

ekCLBUTTON

The close button [X] has been pressed in the title bar.

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 view_flag_t

Attributes for creating a custom view.

enum view_flag_t
{
    ekHSCROLL,
    ekVSCROLL
};
ekHSCROLL

With horizontal scrollbar.

ekVSCROLL

With vertical scrollbar.


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 ekWNTITLE | ekWNMIN | ekWNCLOSE.

ekWNSRES

Combination ekWNSTD | ekWNMAX | ekWNRES.


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

The text of a Edit or Combo control is being edited.

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;
};
pos

Normalized slider position (0, 1).

incr

Increase with respect to the previous position.


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

TRUE if the original control text should be changed.

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.

❮ Back
Next ❯