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	view_flag_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	-
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 [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.

---