Gui

#Header

#include <gui/gui.h>

#Functions

#Types and Constants

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

#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 3). 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 4). 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 5).

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. Gui will adapt to these events automatically, recalculating positions and sizes to maintain a consistent layout. See Internationalization (i18n). Translations.

#2. Anatomy of a window.

In (Figure 6) 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.

• GuiControl. Different types of controls and views.
• Layout. Virtual and invisible grid where the controls will be located.
• Window. Main window with title bar and frame.
• Menu. Drop-down list with options.
• MenuItem. Each of the menu items.

#3. Native backends

Gui ultimately relies on the native graphics API of each operating system: Win32 on Windows, AppKit on macOS and GTK+3 on Linux. Most of an application's code is fully portable across the three, but it is worth knowing some particularities of each backend.

#3.1. Windows (Win32)

Win32 is Windows' native API since its origins in the 1980s, a C interface built around messages and handles, with no object-oriented concepts. It is remarkably stable: an application compiled twenty years ago still runs unchanged on Windows 11. GDI (Graphics Device Interface) is its 2D drawing subsystem, on top of which NAppGUI builds windows and controls.

The native Windows API (Win32/GDI) always works in physical pixels, with no logical point concept of its own. NAppGUI activates Windows' Per-Monitor-v2 DPI-awareness mode (available since Windows 10), which allows it to know the real DPI of each monitor and receive immediate notification of any change, performing the relevant point-to-pixel conversions internally in Win32/GDI. See High-density displays (HiDPI).

#3.2. macOS (AppKit)

AppKit is macOS's native interface framework, a direct descendant of NeXTSTEP and part of Cocoa. Unlike Win32, it is designed around objects (NSWindow, NSView, NSButton...) and the Objective-C runtime, so NAppGUI relies on that runtime from C in order to use it.

Cocoa already works natively in points; the operating system itself automatically multiplies by the monitor's scale factor (backingScaleFactor, typically 2 on Retina screens) when rasterizing. See High-density displays (HiDPI).

#3.3. Linux (GTK3)

Unlike Windows and macOS, Linux supports a multitude of desktop environments based on different libraries (or toolkits), GTK and Qt being the two most famous. NAppGUI uses GTK+3 for the graphical part since it is the base of the Gnome, Xfce, Lxde, etc (Table 1) environments present in many of the most widespread distributions. GTK+3 will be present naturally in all of them, with no other additional dependencies being necessary. To compile under GTK+3 the developer package must be installed (libgtk-3-dev).

Each environment also bundles its own window manager or compositor (Mutter, KWin, Xfwm...), responsible for decorating, compositing and positioning windows on screen. GTK3 and the compositor are parallel layers that converge on the same protocol (Wayland or X11): NAppGUI, through GTK3/GDK, never talks to the compositor directly, only to that protocol. On Wayland, the compositor, server and window manager are all the same process; on X11 they are two separate processes (the Xorg server and the window manager) that coexist, coordinating through the ICCCM/EWMH conventions.

	Environment	Window manager	Distributions
	Gnome	Mutter	Ubuntu, Debian, Fedora, Red Hat, CentOS, Manjaro, Suse, Arch, ...
	Xfce	Xfwm	Xubuntu, Debian, Fedora, Manjaro, ...
	Lxde	Openbox	Lubuntu, Raspbian, Debian, Fedora, Mandriva, ...
	Cinnamon	Muffin	Mint, Debian, Ubuntu, Fedora, OpenSuse, ...
	Mate	Marco	Ubuntu Mate, Mint, Debian, Fedora, OpenSuse, ...
	Pantheon	Gala	Elementary OS
	Sugar

GTK also exposes a logical coordinate system, internally resolving the scale factor of each monitor. See High-density displays (HiDPI).

#3.4. Wayland support

Historically, desktop applications on Linux have run on top of X11 (X Window System), the traditional windowing protocol of the Unix ecosystem, more than four decades old. In recent years, most distributions and desktop environments (GNOME, KDE Plasma) have adopted Wayland as the default session: a modern protocol, designed from scratch by the community to replace X11 and solve several of its structural limitations (Table 2). NAppGUI runs transparently on either of the two, without the application having to do anything special in most cases.

Advantages of Wayland over X11 in modern applications:

• Security: Wayland isolates each application, which can only draw and receive events from its own surfaces. It does not allow capturing the screen or intercepting keyboard and mouse events from other, unrelated windows.
• Compositing: No flickering or tearing.
• HiDPI: Each monitor can have its own scale factor natively managed by the protocol, something that has always been problematic in X11 and dependent on extensions bolted on afterwards. In NAppGUI-X11 applications, the application must be restarted after changing the scaling factor. This is not necessary in Wayland, which adapts seamlessly to "hot" changes without requiring a restart.
• Present and future: It is the active development direction of the Linux desktop. All the effort from distributions and desktop environments is focused on Wayland today, with X11 considered maintenance-only code.

Wayland limitations: By the design of the protocol itself, Wayland imposes a series of restrictions on all clients that make it impossible to implement certain features supported by NAppGUI:

• No screen coordinates: No window (main, modal, or secondary) can be positioned at an exact screen coordinate. window_origin has no effect. It is Wayland that always decides where it appears. For example, a modal window launched with window_modal will appear centered relative to its parent, with no way to indicate a different position. For the same reason, window_OnMoved will not receive window-move events either, since Wayland does not report the window's screen position to the client.
• window_overlay does allow precise positioning relative to the parent window, but only along one axis. On Wayland it is mandatory to implement it via GtkPopover, which draws a "bubble" frame showing a pointer at the anchor point (Figure 7).



• gui_mouse_pos cannot return a real, precise screen position on Wayland.
• gui_workarea returns the full monitor resolution on Wayland, without excluding the space occupied by the Dock, panels, or taskbar.

Forcing X11 in a modern application. A particular application may not be able to afford Wayland's limitations, needing full control over window positioning on screen. This is possible thanks to XWayland, an X11 compatibility server. X11 can be forced under Wayland environments in different ways:

• Externally, before launching the application, by setting the GDK_BACKEND=x11 environment variable.
• From the application's own code, passing the options string "-gdkbackend=x11" to osmain or osmain_sync (Listing 1) (there is also "-gdkbackend=wayland" to force the opposite). If this option is omitted, NAppGUI will respect the active session (Wayland on modern desktops), or a GDK_BACKEND already set externally.

osmain(i_create, i_destroy, "-gdkbackend=x11", App)

In the unlikely case that a distribution doesn't offer XWayland (X11 over Wayland), it would need to be installed explicitly (Listing 2):

sudo apt-get install xwayland

#4. High-density displays (HiDPI)

A HiDPI monitor packs many more physical pixels into the same surface than a conventional monitor of the same size (for example, a 27" 5K panel has 4 times the pixels of a 27" 1440p panel). If those extra pixels were used at "1 to 1" size, each interface element would occupy much less physical space and the interface would end up tiny and illegible. To avoid this, the operating system applies a scale factor (for example, 150% or 200%) that spreads several physical pixels across the representation of each interface element (Figure 8): its physical size stays comfortable, but it is now drawn with much more detail, gaining sharpness (Figure 9), (Figure 10).

When an application is not prepared for HiDPI, the operating system achieves this same effect in the simplest possible way: it renders the interface at its usual size and then stretches the result through a simple image scaling (bitmap stretching) (Figure 11). The result is an interface with the correct physical size, but visibly blurry, since a low-resolution bitmap is being shown enlarged.

NAppGUI solves this problem at its root: throughout the whole library, positions and sizes are always expressed in logical screen points, never in physical pixels. A logical point equals one physical pixel on a reference monitor (the historical 96 DPI standard on Windows, or a non-Retina Apple screen); on a HiDPI monitor at 200%, for example, each logical point will occupy 2x2 real physical pixels. Thus, a 600x400-point window will keep looking and being programmed as 600x400 on any monitor, while the actual number of pixels used to draw it will vary according to the density of each particular screen. The application doesn't need to perform any special calculation: it just needs to keep positioning and sizing controls as always.

The final conversion to physical pixels happens transparently, at the lowest level of each operating system's backend, right before every native drawing operation or window/control creation. Each backend resolves this step differently, see Native backends.

#5. Internationalization (i18n). Translations

NAppGUI allows translating the interface into multiple languages at runtime, without recompiling or restarting the application. The texts (and also images or files) for each language are grouped into a resource package, registered with gui_respack. To change the active language, just call gui_language from anywhere in the program (Listing 3).

1
2
3
4
5
6
7
8
9

static void i_OnLang(App *app, Event *e)
{
    const EvButton *p = event_params(e, EvButton);
    static const char_t *LANGS[] = { "en_US", "es_ES", "fr_FR" };
    gui_language(LANGS[p->index]);
}

PopUp *popup = popup_create();
popup_OnSelect(popup, listener(app, i_OnLang, App));

Changing the interface language brings a new relocation of the elements due to the change in the texts (Figure 12). Gui adapts to these events automatically, recalculating positions and sizes to maintain a consistent layout.

See Resources for a step-by-step guide to localize and translate a complete application.

#6. Theme support (Dark Mode)

Since it uses native controls, windows created with Gui automatically blend in with the light or dark theme active on the system, without needing any extra code. However, if the application defines its own colors or icons, it's worth taking this into account so they stay consistent in both themes.

• There is a set of "system" colors — for example gui_label_color — whose RGB value is resolved at runtime depending on the platform and the active theme. Using them, the application will always look consistent with the rest of the desktop. The Color table demo shows all these colors.
• gui_alt_color allows defining a custom color with two versions — one for light themes and another for dark ones — which Gui will resolve automatically in each case (Listing 4).

1	color_t kHOLDER = gui_alt_color(color_bgr(0x4681Cf), color_bgr(0x1569E6));

• For custom icons or images, both versions must be included in the resources, choosing one or the other depending on gui_dark_mode (Listing 5).

1	button_image(button, gui_dark_mode() ? LOGOUTD_PNG : LOGOUT_PNG);

• gui_OnThemeChanged notifies the application when the user switches the system theme on the fly, so custom icons and colors can be updated without restarting the application.

#7. 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 15), which must provide an event handler with the code to execute. For example in (Listing 6) 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 3).
• 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 *p = event_params(e, EvButton); if (p->state == ekGUI_ON) create_new_file(app); } Button *button = button_check(); button_OnClick(button, listener(app, i_OnClick, App));

Sometimes it may be necessary to fire an event while the application is in "standby mode", without processing any other pending events. This occurs when we want to launch a secondary or modal window as a consequence of another event, for example, the pressing of a button. It is advisable, to avoid blocking or unwanted artifacts, to let the first event conclude and schedule the response for a later time, where the application has no pending tasks.

• Use gui_OnIdle to raise an event when there are no other pending tasks.

1 2 3 4 5 6 7 8 9 10 11

static void i_OnIdle(App *app, Event *e) { window_modal(app->modal_window, app->main_window); } static void i_OnClick(App *app, Event *e) { // The modal window will be launched after // the OnClick event is totally processed. gui_OnIdle(listener(app, i_OnIdle, App)); }

Event	Handler	Parameters	Response
Click in label	label_OnClick	EvMouse	-
Click on button	button_OnClick	EvButton	-
Selection in PopUp	popup_OnSelect	EvButton	-
Keystroke or paste	edit_OnFilter	EvText	EvTextFilter
End of edit in Edit	edit_OnChange	EvText	bool_t
Edit has received or lost keyboard focus	edit_OnFocus	bool_t	-
Key press on Combo	combo_OnFilter	EvText	EvTextFilter
End of editing in Combo	combo_OnChange	EvText	bool_t
Combo has received or lost keyboard focus	combo_OnFocus	bool_t	-
Selection in Combo	combo_OnSelect	EvButton	-
Selection in Tabs	tabs_OnSelect	EvButton	-
A mouse button was pressed	listbox_OnDown	EvMouse	bool_t
Selection in ListBox	listbox_OnSelect	EvButton	-
Click on UpDown	updown_OnClick	EvButton	-
Slider movement	slider_OnMoved	EvSlider	-
Draw the contents of a view	view_OnDraw	EvDraw	-
Draw the overlay of a view	view_OnOverlay	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	-
View has received or lost keyboard focus	view_OnFocus	bool_t	-
View resing keyboard focus	view_OnResignFocus	-	bool_t
View accepts keyboard focus	view_OnAcceptFocus	-	bool_t
The scroll bars are being manipulated.	view_OnScroll	EvScroll	real32_t
Keystroke or paste	textview_OnFilter	EvText	EvTextFilter
TextView has received or lost keyboard focus	textview_OnFocus	bool_t	-
WebView has received or lost keyboard focus	webview_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	-
Inactivity	gui_OnIdle	-	-

#enum gui_orient_t

Orientation.

enum gui_orient_t
{
    ekGUI_HORIZONTAL,
    ekGUI_VERTICAL
};

#enum gui_pos_t

Relative position.

enum gui_pos_t
{
    ekGUI_POS_NONE,
    ekGUI_POS_LEFT,
    ekGUI_POS_TOP,
    ekGUI_POS_RIGHT,
    ekGUI_POS_BOTTOM
};

#enum gui_state_t

State values.

enum gui_state_t
{
    ekGUI_OFF,
    ekGUI_ON,
    ekGUI_MIXED
};

#enum gui_mouse_t

Mouse buttons.

enum gui_mouse_t
{
    ekGUI_MOUSE_LEFT,
    ekGUI_MOUSE_RIGHT,
    ekGUI_MOUSE_MIDDLE
};

#enum gui_cursor_t

Cursors. See window_cursor.

enum gui_cursor_t
{
    ekGUI_CURSOR_ARROW,
    ekGUI_CURSOR_HAND,
    ekGUI_CURSOR_IBEAM,
    ekGUI_CURSOR_CROSS,
    ekGUI_CURSOR_SIZEWE,
    ekGUI_CURSOR_SIZENS,
    ekGUI_CURSOR_USER
};

#enum gui_close_t

Reason for closing a window.

enum gui_close_t
{
    ekGUI_CLOSE_ESC,
    ekGUI_CLOSE_INTRO,
    ekGUI_CLOSE_BUTTON,
    ekGUI_CLOSE_DEACT
};

#enum gui_scale_t

Ways of scaling an image.

enum gui_scale_t
{
    ekGUI_SCALE_NONE,
    ekGUI_SCALE_AUTO,
    ekGUI_SCALE_ASPECT,
    ekGUI_SCALE_ASPECTDW,
    ekGUI_SCALE_ADJUST
};

#enum gui_scroll_t

Types of scroll.

enum gui_scroll_t
{
    ekGUI_SCROLL_BEGIN,
    ekGUI_SCROLL_END,
    ekGUI_SCROLL_STEP_LEFT,
    ekGUI_SCROLL_STEP_RIGHT,
    ekGUI_SCROLL_PAGE_LEFT,
    ekGUI_SCROLL_PAGE_RIGHT,
    ekGUI_SCROLL_THUMB
};

#enum gui_focus_t

Result when changing the keyboard focus.

enum gui_focus_t
{
    ekGUI_FOCUS_CHANGED,
    ekGUI_FOCUS_KEEP,
    ekGUI_FOCUS_NO_NEXT,
    ekGUI_FOCUS_NO_RESIGN,
    ekGUI_FOCUS_NO_ACCEPT
};

#enum gui_tab_t

Action that has motivated the change of keyboard focus.

enum gui_tab_t
{
    ekGUI_TAB_KEY,
    ekGUI_TAB_BACKKEY,
    ekGUI_TAB_NEXT,
    ekGUI_TAB_PREV,
    ekGUI_TAB_MOVE,
    ekGUI_TAB_CLICK
};

#enum gui_event_t

Event type. See GUI Events.

enum gui_event_t
{
    ekGUI_EVENT_LABEL,
    ekGUI_EVENT_BUTTON,
    ekGUI_EVENT_POPUP,
    ekGUI_EVENT_LISTBOX,
    ekGUI_EVENT_SLIDER,
    ekGUI_EVENT_UPDOWN,
    ekGUI_EVENT_TXTFILTER,
    ekGUI_EVENT_TXTCHANGE,
    ekGUI_EVENT_FOCUS_RESIGN,
    ekGUI_EVENT_FOCUS_ACCEPT,
    ekGUI_EVENT_FOCUS,
    ekGUI_EVENT_MENU,
    ekGUI_EVENT_DRAW,
    ekGUI_EVENT_OVERLAY,
    ekGUI_EVENT_RESIZE,
    ekGUI_EVENT_ENTER,
    ekGUI_EVENT_EXIT,
    ekGUI_EVENT_MOVED,
    ekGUI_EVENT_DOWN,
    ekGUI_EVENT_UP,
    ekGUI_EVENT_CLICK,
    ekGUI_EVENT_DRAG,
    ekGUI_EVENT_WHEEL,
    ekGUI_EVENT_KEYDOWN,
    ekGUI_EVENT_KEYUP,
    ekGUI_EVENT_SCROLL,
    ekGUI_EVENT_WND_MOVED,
    ekGUI_EVENT_WND_SIZING,
    ekGUI_EVENT_WND_SIZE,
    ekGUI_EVENT_WND_CLOSE,
    ekGUI_EVENT_COLOR,
    ekGUI_EVENT_THEME,
    ekGUI_EVENT_OBJCHANGE,
    ekGUI_EVENT_TBL_NROWS,
    ekGUI_EVENT_TBL_BEGIN,
    ekGUI_EVENT_TBL_END,
    ekGUI_EVENT_TBL_CELL,
    ekGUI_EVENT_TBL_SEL,
    ekGUI_EVENT_TBL_HEADCLICK,
    ekGUI_EVENT_TBL_ROWCLICK,
    ekGUI_EVENT_TBL_NCHILDREN,
    ekGUI_EVENT_TBL_NODEINFO,
    ekGUI_EVENT_TBL_EXPAND
};

#enum split_mode_t

Behavior of the divider in a SplitView.

enum split_mode_t
{
    ekSPLIT_NORMAL,
    ekSPLIT_FIXED0,
    ekSPLIT_FIXED1
};

#enum window_flag_t

Window creation attributes.

enum window_flag_t
{
    ekWINDOW_FLAG,
    ekWINDOW_EDGE,
    ekWINDOW_TITLE,
    ekWINDOW_MAX,
    ekWINDOW_MIN,
    ekWINDOW_CLOSE,
    ekWINDOW_RESIZE,
    ekWINDOW_RETURN,
    ekWINDOW_ESC,
    ekWINDOW_MODAL_NOHIDE,
    ekWINDOW_STD,
    ekWINDOW_STDRES
};

#enum gui_notif_t

Notifications sent by the gui library.

enum gui_notif_t
{
    ekGUI_NOTIF_LANGUAGE,
    ekGUI_NOTIF_WIN_DESTROY,
    ekGUI_NOTIF_MENU_DESTROY
};

#struct GuiControl

Interface Control (abstract).

struct GuiControl;

#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 Tabs

Control that displays several selection tabs. Tabs.

struct Tabs;

#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 WebView

Web content view. WebView.

struct WebView;

#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 Line

Separator lines. Line.

struct Line;

#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;
    gui_state_t state;
    const char_t* text;
};

#struct EvSlider

Parameters of the OnMoved event of a slider.

struct EvSlider
{
    real32_t pos;
    real32_t incr;
    uint32_t step;
};

#struct EvText

Parameters of the OnChange or OnFilter event of the text boxes.

struct EvText
{
    const char_t* text;
    uint32_t cpos;
    int32_t len;
};

#struct EvTextFilter

Result of the OnFilter event of the text boxes.

struct EvTextFilter
{
    bool_t apply;
    char_t* text;
    uint32_t cpos;
};

#struct EvDraw

OnDraw event parameters.

struct EvDraw
{
    DCtx* ctx;
    real32_t x;
    real32_t y;
    real32_t width;
    real32_t height;
};

#struct EvMouse

Mouse event parameters.

struct EvMouse
{
    real32_t x;
    real32_t y;
    real32_t lx;
    real32_t ly;
    gui_mouse_t button;
    uint32_t count;
    uint32_t modifiers;
    uint32_t tag;
};

#struct EvWheel

OnWheel event parameters.

struct EvWheel
{
    real32_t x;
    real32_t y;
    real32_t dx;
    real32_t dy;
    real32_t dz;
};

#struct EvKey

Keyboard event parameters.

struct EvKey
{
    vkey_t key;
    uint32_t modifiers;
};

#struct EvPos

Parameters of change of position events.

struct EvPos
{
    real32_t x;
    real32_t y;
};

#struct EvSize

Resize event parameters.

struct EvSize
{
    real32_t width;
    real32_t height;
};

#struct EvWinClose

Window closing Event Parameters.

struct EvWinClose
{
    gui_close_t origin;
};

#struct EvMenu

Menu event parameters.

struct EvMenu
{
    uint32_t index;
    gui_state_t state;
    const char_t* text;
};

#struct EvScroll

Scroll event parameters.

struct EvScroll
{
    gui_orient_t orient;
    gui_orient_t scroll;
    real32_t cpos;
};

#struct EvTbPos

Location of a cell in a table.

struct EvTbPos
{
    uint32_t col;
    uint32_t row;
    void* node;
};

#struct EvTbRow

Location of a row in a table.

struct EvTbRow
{
    bool_t sel;
    uint32_t row;
};

#struct EvTbRect

Group of cells in a table.

struct EvTbRect
{
    uint32_t stcol;
    uint32_t edcol;
    uint32_t strow;
    uint32_t edrow;
};

#struct EvTbSel

Selection in a table.

struct EvTbSel
{
    ArrSt(uint32_t)* sel;
};

#struct EvTbCell

Data from a cell in a table.

struct EvTbCell
{
    const char_t* text;
    align_t align;
};

#struct EvTbNode

Request for a node in tree mode. Parameters of the ekGUI_EVENT_TBL_NODEINFO event.

struct EvTbNode
{
    void* parent;
    uint32_t ichild;
};

#struct EvTbNodeInfo

Information about a node in tree mode. Result of the ekGUI_EVENT_TBL_NODEINFO event.

struct EvTbNodeInfo
{
    void* node;
    bool_t children;
    bool_t expanded;
};

#struct EvTbExpand

Expansion or contraction notification in tree mode. Parameters of the ekGUI_EVENT_TBL_EXPAND event.

struct EvTbExpand
{
    void* node;
    bool_t expanded;
};

#struct FocusInfo

Information about changing the keyboard focus.

struct FocusInfo
{
    gui_tab_t action;
    GuiControl* next;
};

#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_dpi_aware ()

Enables or disables adapting the interface to the monitor's real resolution (DPI). If needed, it must be called before creating the application's first window.

void
gui_dpi_aware(const bool_t aware);

Remarks

Only has effect on Windows. On macOS and Linux the interface always adapts natively to the monitor's resolution.

#gui_respack ()

Register a resource package.

void
gui_respack(FPtr_respack func_respack);

Remarks

See Internationalization (i18n). Translations and Resources.

#gui_language ()

Set the language of the registered resources with gui_respack.

void
gui_language(const char_t *lang);

Remarks

See Internationalization (i18n). Translations and Resources.

#gui_text ()

Get a text string through its resource identifier.

const char_t*
gui_text(const ResId id);

Return

The text string or NULL if it is not found.

Remarks

The resource must belong to a package registered with gui_respack. See Internationalization (i18n). Translations.

#gui_image ()

Get an image through its resource identifier.

const Image*
gui_image(const ResId id);

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. See Internationalization (i18n). Translations.

#gui_file ()

Get the contents of a file through its resource identifier.

const byte_t*
gui_file(const ResId id,
         uint32_t *size);

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. See Internationalization (i18n). Translations.

#gui_dark_mode ()

Determines if the window environment has a light or dark theme.

bool_t
gui_dark_mode(void);

Return

TRUE for Dark mode, FALSE for light mode.

Remarks

See Theme support (Dark Mode).

#gui_alt_color ()

Create a color with two alternative versions.

color_t
gui_alt_color(const color_t light_color,
              const color_t dark_color);

Return

The color.

Remarks

The system will set the final color based on the "lightness" of the window manager colors (Light/Dark). Nested alternate colors ARE NOT ALLOWED. The light and dark values ​​must be RGB or system colors. See Theme support (Dark Mode).

#gui_label_color ()

Returns the default color of text labels Label.

color_t
gui_label_color(void);

Return

The color.

Remarks

See Theme support (Dark Mode).

#gui_view_color ()

Returns the background color in controls View.

color_t
gui_view_color(void);

Return

The color.

Remarks

See Theme support (Dark Mode).

#gui_line_color ()

Returns the color of lines in tables or window separator elements.

color_t
gui_line_color(void);

Return

The color.

Remarks

See Theme support (Dark Mode).

#gui_link_color ()

Returns the color of the text in hyperlinks.

color_t
gui_link_color(void);

Return

The color.

Remarks

See Theme support (Dark Mode).

#gui_border_color ()

Returns the border color in button controls, popups, etc..

color_t
gui_border_color(void);

Return

The color.

Remarks

See Theme support (Dark Mode).

#gui_device ()

Returns the device type.

device_t
gui_device(void);

Return

Device.

#gui_resolution ()

Returns screen resolution.

S2Df
gui_resolution(void);

Return

Resolution.

#gui_workarea ()

Returns the useful work area, that is, the screen resolution removing the space occupied by the Dock, taskbar, menus, etc.

R2Df
gui_workarea(void);

Return

Work area.

Remarks

On Wayland it returns the full monitor resolution, without excluding the Dock or panels: the protocol does not expose that information to clients. See Wayland support.

#gui_mouse_pos ()

Returns the position of the mouse cursor.

V2Df
gui_mouse_pos(void);

Return

Position.

Remarks

On Wayland it cannot return a real, precise screen position, since the protocol does not expose that information to clients. See Wayland support.

#gui_update ()

Refreshes all application windows, after a theme or scrollbar style change.

void
gui_update(const bool_t theme,
           const bool_t scrollers);

Remarks

Normally it is not necessary to call this method. It is called automatically from osapp.

#gui_OnThemeChanged ()

Set a handler to detect the change of the visual theme of the windows environment.

void
gui_OnThemeChanged(Listener *listener);

Remarks

See Theme support (Dark Mode).

#gui_update_transitions ()

Update the automatic animations of the interface.

void
gui_update_transitions(const real64_t prtime,
                       const real64_t crtime);

Remarks

Normally it is not necessary to call this method. It is called automatically from osapp.

#gui_OnNotification ()

Sets up a handler to receive notifications from gui.

void
gui_OnNotification(Listener *listener);

Remarks

See gui_notif_t.

#gui_OnIdle ()

Sets a handler to raise an event when the application is in "standby mode".

void
gui_OnIdle(Listener *listener);

Remarks

The event will be raised once when the application's message loop is idle, that is, not processing other pending events. See GUI Events.

#gui_info_window ()

Displays an information window about the execution of the program. It is aimed at displaying anomaly messages or debugging messages. Do not use for user information.

uint32_t
gui_info_window(const bool_t fatal,
                const char_t *msg,
                const char_t *caption,
                const char_t *detail,
                const char_t *file,
                const uint32_t line,
                const ArrPt(String) *buttons,
                const uint32_t defindex);

1
2
3
4
5
6
7
8

uint32_t sel = 0;
ArrPt(String) *buttons = arrpt_create(String);
arrpt_append(buttons, str_c("Ok"), String);
arrpt_append(buttons, str_c("Bye"), String);
arrpt_append(buttons, str_c("Forget"), String);
arrpt_append(buttons, str_c("Ask again"), String);
sel = gui_info_window(TRUE, "Here an info window", "Something happens", "You do something wrong\nin the file passed as 'stream' parameter.", "your_file.txt", 43, buttons, 1);
arrpt_destroy(&buttons, str_destroy, String);

Return

Button number pressed.

#evbind_object ()

Gets the object linked to a layout within a callback function.

type*
evbind_object(Event *e,
              type);

Return

The object.

Remarks

See Notifications and calculated fields.

#evbind_modify ()

Checks, inside a callback function, if the object's field has been modified.

bool_t
evbind_modify(Event *e,
              type,
              mtype,
              mname);

Return

TRUE if the field has been modified.

Remarks

See Notifications and calculated fields.