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

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

• 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. 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 *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	EvText	-
Click on button	button_OnClick	EvButton	-
Selection in PopUp	popup_OnSelect	EvButton	-
A mouse button was pressed	listbox_OnDown	EvMouse	bool_t
Selection in ListBox	listbox_OnSelect	EvButton	-
Press key on Edit	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
Slider movement	slider_OnMoved	EvSlider	-
Click on UpDown	updown_OnClick	EvButton	-
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 in TextView	textview_OnFilter	EvText	EvTextFilter
TextView has received or lost keyboard focus	textview_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_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

Scaling modes.

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

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

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

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 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_respack ()

Register a resource package.

void
gui_respack(FPtr_respack func_respack);

Remarks

See Resources.

gui_language ()

Set the language of the registered resources with gui_respack.

void
gui_language(const char_t *lang);

Remarks

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

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.

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.

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.

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.

gui_label_color ()

Returns the default color of text labels Label.

color_t
gui_label_color(void);

Return

The color.

gui_view_color ()

Returns the background color in controls View.

color_t
gui_view_color(void);

Return

The color.

gui_line_color ()

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

color_t
gui_line_color(void);

Return

The color.

gui_link_color ()

Returns the color of the text in hyperlinks.

color_t
gui_link_color(void);

Return

The color.

gui_border_color ()

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

color_t
gui_border_color(void);

Return

The color.

gui_resolution ()

Returns screen resolution.

S2Df
gui_resolution(void);

Return

Resolution.

gui_mouse_pos ()

Returns the position of the mouse cursor.

V2Df
gui_mouse_pos(void);

Return

Position.

gui_update ()

Refreshes all application windows, after a theme change.

void
gui_update(void);

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

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.