search
githubEdit

Runtime Configuration

In this chapter, we describe the MiniGUI runtime configuration, which affects the runtime behavior of MiniGUI. For example, you can use the runtime configuration to specify:

  • The effective graphics and input engines.

  • The fonts device to load.

  • The system fonts for caption, menu, and control.

  • The mouse cursors.

  • The icons, and bitmaps to decorate window.

Generally, the runtime configuration is loaded from MiniGUI.cfg file. But if you've configured MiniGUI with built-in resources in building stage, the runtime configuration will be compiled into the MiniGUI Core library.

In this chapter, we first describe the runtime configuration using the configuration file, then describe how to specify runtime configuration if you've configured MiniGUI with resources in MiniGUI Core . For convenience, we call the later situation as incore configuration.

hashtag
Configuration File

On Linux, after building and installing MiniGUI using the default configuration, the file etc/MiniGUI.cfg in MiniGUI source tree will be installed into /usr/local/etc/ directory. However, you can deploy your own version of MiniGUI.cfg in your home directory. And this version will have a higher priority.

Actually, when MiniGUI starts, it tries to locate the correct MiniGUI.cfg according to the following steps:

  1. search MiniGUI.cfg in current working directory. If not found,

  2. search .MiniGUI.cfg in home directory of the current user. If not found,

  3. search MiniGUI.cfg in /usr/local/etc. If not found,

  4. search MiniGUI.cfg in /etc/.

In other words, if you don't create MiniGUI.cfg file in the current directory or .MiniGUI.cfg file in your home directory either, MiniGUI will use the file MiniGUI.cfg in /usr/local/etc/ as the default configuration file.

The format of the MiniGUI configuration file is simple, and you can modify it easily. The following code shows the format:

The options in the configuration file are grouped in sections. The line which starts with the character # is a comment line. A line in the form of [section-name] defines a new section. And a pair of key and value in the form of key=value defines an option in a section.

Note that we often use the notation section_name.key_name to refer to an option with key_name in the section section_name.

Some important sections are listed as follow.

hashtag
Section system

You can use the section system to specify the effective NEWGAL engine and IAL engine. For historical reasons, you can also use this section to specify the mouse device and mouse protocol for console IAL engine.

The keys of this section are listed as follow:

  • gal_engine: The graphics engine.

  • defaultmode: The display mode for the graphics engine.

  • ial_engine: The input engine.

  • mdev: The mouse device file.

  • mtype: The mouse protocol type.

For a display mode, MiniGUI uses the following notation: <XRES>x<YRES>-<DEPTH>bpp. Here <XRES> means the horizontal resolution of the display mode, and <YRES> means the vertical resolution, and <DEPTH> means the color depth of bits per pixel. For example, 640x480-32bpp.

The default content of the section system is as follow:

Since MiniGUI 1.6.8, you can specify the graphics and input engines via environment variables. The definition of the environment variables will override the runtime configuration, whatever you are using the configuration file or the incore configuration. The environment variables are listed as follow:

  • MG_GAL_ENGINE: system.gal_engine

  • MG_IAL_ENGINE: system.ial_engine

  • MG_DEFAULTMODE: system.defaultmode

  • MG_MDEV: system.mdev

  • MG_MTYPE: system.mtype

For example, if you want to use fbcon NEWGAL engine and console IAL engine, you can use the following commands to specify the environment variables:

hashtag
Section pc_xvfb

The section pc_xvfb is only effective when you define the key system.gal_engine with value pc_xvfb.

The valid keys in the section pc_xvfb are listed as follow:

  • defaultmode: The display mode of graphics engine. This value will override the value defined by system.defaultmode.

  • window_caption: Window caption text of the XVFB window.

  • exec_file: the path of the execute file of the XVFB program.

The content of this section in the default MiniGUI.cfg is as follow:

hashtag
Section fbcon

The section fbcon is only effective when you define the key system.gal_engine with value fbcon.

The valid keys in the section fbcon are listed as follow:

  • defaultmode: The display mode of the graphics engine fbcon.

  • dpi: The pixel density of the display, in dots (physical pixels) per inch; the default value is 96.

The key defaultmode also defines the default display mode for the fbcon engine. This key value will override the value defined by system.defaultmode. When the section is undefined or the key value is invalid, the fbcon engine will use the key value of system.gal_engine.

The content of the section in the default MiniGUI.cfg is as follow:

hashtag
Section drm

This section is dedicated to the drm graphics engine which runs on Linux DRI (Direct Rendering Infrastructure). It is available since MiniGUI 4.0.4.

The section drm is only effective when you define the key system.gal_engine with value drm.

The valid keys in the section drm are listed as follow:

  • defaultmode: The display mode of the graphics engine fbcon.

  • dpi: The pixel density of the display, in dots (physical pixels) per inch; the default value is 96.

  • pixelformat: The pixel format.

  • device: The DRI device.

  • exdriver: The filename of the shared library for the external DRM driver.

The key defaultmode also defines the default display mode for the drm engine. This key value will override the value defined by system.defaultmode. If the section is undefined or the key value is invalid, the drm engine will use the key value of system.gal_engine.

For drm engine, we introduced a new key pixelformat to define the pixel format precisely. We use DRM fourcc code (like XR24) to define the pixel format of the video surface. For more information, please see the header file drm/drm_fourcc.h of libdrm. Note that only 8/16/24/32 bpp RGB formats are supported.

The key exdriver defines the filename of the shared library for the external driver for MiniGUI DRM NEWGAL engine. The default value is libhidrmdrivers.so.0. You can also change the value of this key by the system environment variable: MG_GAL_DRM_DRIVER.

The content of the section in the default MiniGUI.cfg is as follow:

hashtag
Section libinput

This section is dedicated to the libinput input engine which runs on Linux. It is available since MiniGUI 4.0.0.

The section libinput is only effective when you define the key system.ial_engine with value libinput.

The valid keys in the section libinput are listed as follow:

  • seat: The seat identifier; the default value is seat0.

The content of this section in the default MiniGUI.cfg is as follow:

hashtag
Section systemfont

The section systemfont defines system fonts. A system font is a logical font which will be used to render the text in the window captions, menus, and controls in MiniGUI.

A logical font (logfont for short) is an object used by MiniGUI app to render paragraphs, words, or characters. While a device font (devfont for short) is a underlying object containing the glyphs of all or some characters in a specific language or script. Basically, one logfont corresponds to one or multiple devfonts.

MiniGUI creates the system font by calling the function CreateLogFontFromName based on loaded device fonts, which are defined in sections such as rawbitmapfonts, varbitmapfonts, upf, qpf, and truetypefonts (see Sections for devfonts).

A logfont name is a string which has the following form:

The definitions of each part of a logfont name are as follow:

  • <type> specifies the desired device font type. For example, if you want to use TrueType fonts for this logfont, use ttf. If you do not want to specify the font type, use *.

  • <family> specifies the font face name, such as courier, times, and so on.

  • <style> is a string of six alphabets used to define the style of a logfont, such as italic, bold, underline, etc.

  • <width> specifies the width of the logfont in pixels. Usually do not need to specify the width, so use * instead.

  • <height> specifies the height of the logfont in pixels.

  • <charset> specifies the charset or encoding of the logfont created.

As an example, the logfont name rbf-FixedSys-rrncnn-8-16-ISO8859-1 will create a logfont by using RBF devfonts. The face name of the logfont is FixedSys, the height is 16, and the charset is ISO8859-1.

For more information about logfont, please refer to MiniGUI Programming Guide.

The valid keys in the section systemfont are listed as follow:

  • font_number: The number of system fonts to be created. Note that the maximal number of system logfonts is 6. You should not set this key value larger than 6.

  • font<NR>: The name for the logfont numbered <NR>.

  • default: The system default logfont in the default single-byte character set. Its value should be a valid system logfont number.

  • wchar_def: The system default logfont in the default multiple-byte character set. Its value should be a valid system logfont number.

  • fixed: The logfont with fixed width. Its value should be a valid system logfont number.

  • caption: The logfont for the text in the window caption. Its value should be a valid system logfont number.

  • menu: The logfont for the text in the menu items. Its value should be a valid system logfont number.

  • control: The logfont for the text in the controls. Its value should be a valid system logfont number.

You can change the number of system logfonts created. But note that the maximal number of system logfonts is 6.

You must create at least one logfont in a single-byte character set (e.g., ISO8859-1). MiniGUI defines the system default charsets according to default and wchar_def system fonts. And the logfont names for default and wchar_def will affect the return value of functions： GetSysCharset, GetSysCharWidth, GetSysCCharWidth and GetSysHeight. Commonly, default and wchar_def should be fixed width bitmap fonts.

The content of this section in the default MiniGUI.cfg is as follow:

hashtag
Changes in MiniGUI 4.0.0

Since version 4.0.0, you can specify up to 7 family names for a logfont name, for example:

In this way, you can specify a logfont to use multiple devfonts to render a complex text.

Moreover, the previous width field of a logfont name is used for the glyph orientation:

  • U: Glyphs stand upright (default).

  • S: Glyphs are rotated 90 degrees clockwise (sideways).

  • D: Glyphs are upside-down.

  • L: Glyphs are rotated 90 degrees counter-clockwise (sideways left).

hashtag
Section cursorinfo

This section specifies the cursors used by MiniGUI.

The valid keys in the section cursorinfo are listed as follow:

  • cursorpath: The path in which the cursor files are located.

  • cursornumber: The number of cursors to be loaded.

  • cursor<NR>: The cursor file the cursor numbered <NR>.

Note that the cursor numbers should correspond to the system cursor indices defined in minigui/minigui.h header file:

The content of this section in the default MiniGUI.cfg is as follow:

hashtag
Section resinfo

This section specifies the path of the resource files used by MiniGUI.

The valid key in section resinfo is listed as follow:

  • respath: The path in which the resource files located.

When MiniGUI loads a resource file, it will use the key value as the prefix for the ultimate full path of the resource file:

  • The icon files should be stored in the sub directory of icon/ of the resource path specified by the key resinfo.respath.

  • The font files should be stored in the sub directory of font/ of the resource path specified by the key resinfo.respath.

  • The image files should be stored in the sub directory of bmp/ of the resource path specified by the key resinfo.respath.

  • The cursor files should be stored in the sub directory of cursor/ of the resource path specified by the key resinfo.respath.

The content of this section in the default MiniGUI.cfg is as follow:

hashtag
Sections for devfonts

These sections specify the information of the devfonts which are loaded by MiniGUI.

MiniGUI can load a devfont from a font file or from font data stored in memory. Generally, you specify the devfonts which should be loaded at the starting stage of MiniGUI in the runtime configuration.

Note that since MiniGUI 3.0.0, there are some built-in devfonts compiled into the MiniGUI Core library by default. Therefore, if you do not specify any devfont to load in the runtime configuration, MiniGUI still runs.

In the runtime configuration, we use a section for each font type:

  • rawbitmapfonts for RBF (Raw Bitmap Font) fonts.

  • varbitmapfonts for VBF (Variable Bitmap Font) fonts.

  • upf for UPF (Unicode Pre-rendered Font) fonts.

  • qpf for QPF (Qt Pre-rendered Font) fonts.

  • truetypefonts for TrueType fonts. When using FreeType 2, also for OpenType and Adobe Type 1 fonts.

Each of these sections defines the following keys:

  • font_number: The number of devfonts to be loaded.

  • name<NR>: The name of the devfont numbered <NR>.

  • fontfile<NR>: The font file of the devfont numbered <NR>.

For example, you can define the upf section as follow to load one UPF devfont:

If you don't need to use a specific type of devfont, you can skip the configuration section by setting font_number=0.

Like logfont, a string is used as the devfont name to specify the family name, style, size, and charsets of a devfont object. The format of a devfont name is as follow:

The definitions for each part of the devfont name are as follow:

  • <fonttype>: The type of device font, for example, RBF, VBF, QPF, TrueType, and Adobe Type1 device fonts are rbf, vbf, qpf, ttf, and tlf.

  • <family>: The name of device font. Such as courier, Times etc.

  • <styles>: The style of device font, it is grouped into six alphabets. Such as bold, italic, underline etc. Generally the string is rrncnn.

  • <width>: The width of device font, for variable width fonts, set it to the maximal width; for vector fonts, set it to 0.

  • <height>: The height of device font, for vector fonts, set it to 0.

  • <charset1, charset2>: The charsets supported by the devfont.

For example,

It means that the devfont is a TrueType vector font, the family name of the devfont is Arial, the styles are represented by a string rrncnn, the size can be any value (a vector font can be arbitrarily scaled), and the charsets/encodings of the devfont are ISO8859-1 and UTF-8.

The content of these sections in the default MiniGUI.cfg is as follow:

hashtag
Changes in MiniGUI 4.0.0

Since version 4.0.0, you can specify the aliases for the family name of a devfont:

For example:

Note that the length of a devfont name can not exceed 255 bytes.

The following truetypefonts section uses new format for devfont name:

hashtag
Sections for appearance renderers

Since version 3.0, MiniGUI Core introduced the concept of appearance renderer (also called look and feel renderer). You can change the look and feel of a main window or a basic control by specifying an appearance renderer for it. An appearance renderer defines a set of operations to draw the window elements such as caption, borders, and scrollbars of a window. As in the previous version, you can only choose one style among three pre-defined window styles by using the compile-time configuration option.

The appearance renderer provides a very flexible implementation to customize the appearance of the main window and controls. You can easily customize the sizes and colors of a specific appearance renderer by specifying different values to the runtime configuration keys. Or you can change the appearance on the fly via MiniGUI APIs. You can even write your own appearance renderer to customize the look and feel of MiniGUI.

The MiniGUI component mGNCS, also uses the concept of appearance renderer to customize the look and feel of mGNCS controls.

For more information about appearance renderer, please refer to MiniGUI Programming Guide.

MiniGUI Core defines some attributes to control the rendering behaviours for main windows or controls. MiniGUI Core provides four appearance renderers:

  • classic renderer draws the window elements in 3D style like Windows XP.

  • flat renderer draws the window elements in flat style, which is suitable to gray screen.

  • skin renderer draws the window elements using bitmaps.

  • fashion renderer draws the window elements using macOS like style.

Note that the classic renderer is built-in MiniGUI Core library, you can not disable this renderer.

Note that MiniGUI Core does not implement the fashion renderer. This renderer draws the window elements by using 2D vector graphics functions, so it is implemented by mGPlus component.

In runtime configuration, MiniGUI uses classic, flat, skin, and fashion sections to define the options for these four appearance renderers.

The following table gives the key names for the options and the corresponding macros which referring to the specific window elements in MiniGUI code.

Table: Key names for various window elements

Key name
Macro
Comments

caption

WE_METRICS_CAPTION

Caption size

menu

WE_METRICS_MENU

Menu item, height of the menu bar

border

WE_METRICS_WND_BORDER

Window border width

scrollbar

WE_METRICS_SCROLLBAR

Scroll bar size

fgc_active_caption

WE_FGC_ACTIVE_CAPTION

Focus status caption foreground color

bgca_active_caption

WE_BGCA_ACTIVE_CAPTION

Focus status caption background color gradient starting color

bgcb_active_caption

WE_BGCB_ACTIVE_CAPTION

Focus Status caption background color gradient ending Color

fgc_inactive_caption

WE_FGC_INACTIVE_CAPTION

Non-focus status caption foreground color

bgca_inactive_caption

WE_BGCA_INACTIVE_CAPTION

Non-focus status caption background color gradient starting color

bgcb_inactive_caption

WE_BGCB_INACTIVE_CAPTION

Non-focus status caption background color gradient ending color

fgc_menu

WE_FGC_MENU

Menu foreground color

bgc_menu

WE_BGC_MENU

Menu background color

fgc_active_border

WE_FGC_ACTIVE_WND_BORDER

Focus status window border color

fgc_inactive_border

WE_FGC_INACTIVE_WND_BORDER

Non-focus status window border color

fgc_msgbox

WE_FGC_MESSAGEBOX

Message box foreground color

fgc_msgbox

WE_FONT_MESSAGEBOX

Message box font

fgc_tip

WE_FGC_TOOLTIP

Prompt box foreground color

bgc_tip

WE_BGC_TOOLTIP

Prompt box background color

fgc_window

WE_FGC_WINDOW

Window foreground

bgc_window

WE_BGC_WINDOW

Window background color

fgc_3dbox

WE_FGC_THREED_BODY

The color of the symbol on the surface of the 3D box, such as the color of check mark, arrow, etc.

mainc_3dbox

WE_MAINC_THREED_BODY

Three-dimensional box border and surface color

fgc_selected_item

WE_FGC_SELECTED_ITEM

The foreground color of the selected menu item (list item)

bgc_selected_item

WE_BGC_SELECTED_ITEM

The background color of the selected menu item (list item)

bgc_selected_lostfocus

WE_BGC_SELECTED_LOSTFOCUS

The background color after the selected menu item (list item) loses focus

fgc_disabled_item

WE_FGC_DISABLED_ITEM

Foreground color of invalid menu item (list item)

bgc_disabled_item

WE_BGC_DISABLED_ITEM

Invalid menu item (list item) background color

fgc_hilight_item

WE_FGC_HIGHLIGHT_ITEM

Highlight the foreground color of the menu item (list item)

bgc_hilight_item

WE_BGC_HIGHLIGHT_ITEM

Highlight the background color of the menu item (list item)

fgc_significant_item

WE_FGC_SIGNIFICANT_ITEM

Foreground color of important menu item (list item)

bgc_significant_item

WE_BGC_SIGNIFICANT_ITEM

Background color of important menu items (list items)

bgc_desktop

WE_BGC_DESKTOP

Desktop background color

In addition to the keys above, one renderer section must include the following keys:

  • iconnumber: The number of system icons to be loaded. Note that the maximal number of system icons is 5.

  • icon0: The default application icon (IDI_APPLICATION).

  • icon1: The hand/stop icon (IDI_HAND or IDI_STOP).

  • icon2: The question icon (IDI_QUESTION).

  • icon3: The exclamation icon (IDI_EXCLAMATION).

  • icon4: The information/asterisk icon (IDI_INFORMATION or IDI_ASTERISK).

  • dir: The icon used to represent a directory entry (OpenFileDialogBox).

  • file: The icon used to represent a file entry (OpenFileDialogBox).

  • treefold: The icon used to represent a folded tree node.

  • treeunfold: The icon used to represent a unfolded tree node.

  • radiobutton: The bitmap used by a radio button control.

  • checkbutton: The bitmap used by a check button control.

  • bgpicture: The desktop background image. Set to none if no background image.

  • bgpicpos: The position of the background image. Set to one of the following values:

    • center

    • upleft

    • downleft

    • upright

    • downright

    • upcenter

    • downcenter

    • vcenterleft

    • vcenterright

    • upleft

    • downleft

    • upright

    • downright

    • upcenter

    • downcenter

    • vcenterleft

    • vcenterright

    • none

For skin appearance renderer, it uses the following extra keys to define the bitmaps for various window elements:

  • skin_bkgnd: The window background.

  • skin_caption: The caption background.

  • skin_caption_btn: The buttons on caption.

  • skin_scrollbar_hshaft: The tray of horizontal scrollbar.

  • skin_scrollbar_vshaft: The tray of vertical scrollbar.

  • skin_scrollbar_hthumb: The thumb on the horizontal scrollbar.

  • skin_scrollbar_vthumb: The thumb on the vertical scrollbar.

  • skin_scrollbar_arrows: The arrows on the scrollbar.

  • skin_tborder: The top border.

  • skin_bborder: The bottom border.

  • skin_lborder: The left border.

  • skin_rborder: The right border.

  • skin_arrows: The arrows on menu item.

  • skin_arrows_shell:

  • skin_pushbtn: The push button.

  • skin_radiobtn: The radio button.

  • skin_checkbtn: The check button.

  • skin_tree:

  • skin_header:

  • skin_tab:

  • skin_tbslider_h:

  • skin_tbslider_v:

  • skin_trackbar_horz:

  • skin_trackbar_vert:

  • skin_progressbar_htrack:

  • skin_progressbar_vtrack:

  • skin_progressbar_hchunk:

  • skin_progressbar_vchunk:

The content of the appearance renderer sections in MiniGUI.cfg is as follow:

hashtag
Other sections

The section mouse defines parameters for mouse event.

The key in the section is as follow:

  • dblclicktime: The mouse button double click time in milliseconds.

The content of the section in the default MiniGUI.cfg is as follow:

The section event defines event timeout and auto-repeat time used by the internal event process.

The keys in the section are as follow:

  • timeoutusec: Event timeout time in microseconds.

  • repeatusec: Event repeat time in microseconds.

The content of the section in the default MiniGUI.cfg is as follow:

Generally, it is unnecessary to change these sections.

hashtag
Incore Configuration

If you compiled MiniGUI with --enable-incoreres option, MiniGUI will not use the file MiniGUI.cfg. Instead, you specify the runtime configuration options in the source file src/sysres/mgetc.c, and the options will be compiled into the MiniGUI Core library.

Therefore, except the options that can be changed via environment variables, you should change the source file to modify the runtime configuration options and rebuild MiniGUI Core library after changing the file.

Similar to the structure of MiniGUI.cfg, MiniGUI defines an structure ETCSECTION, an static array _etc_sections and a static variable _ETC in mgetc.c. The array mgetc_sections corresponds to the sections in the configuration file, and _ETC which has ETC_S type corresponds to the whole configuration file.

The following code snippet shows the skeleton of the mgetc.c source file:

The function __mg_get_mgetc returns the pointer to _ETC as a GHANDLE variable to the caller. After getting the handle to the ETC object, you can use MiniGUI APIs to get the value of a key in a section.

For more information, please refer to MiniGUI Programming Guide.

You can modify the file mgetc.c manually to reflect your runtime configuration. However, you can use the tool mgcfg-trans to generate your mgetc.c file based on a MiniGUI.cfg file.

For more information, please refer to Tools.

hashtag
Structure ETCSETCTION

The structure ETCSECTION is defined in the header file minigui/minigui.h:

The field key_nr_alloc is used internally, and must be set to 0. The field key_nr defines the number of the keys in section. The field name defines the name of section. The field keys and the field values are the string array of the keys and values. The size of the key array and the value array should match the number of key_nr.

hashtag
Structure ETC_S

ETC_S structure is also defined in the header file minigui/minigui.h:

The field sect_nr_alloc is used internally, and must be set to 0. The field section_nr specifies the number of the sections, and the field sections is the pointer to the array of ETCSECTION.

hashtag
Samples

In practice, we often change the section system, systemfont, and devfonts sections for a specific project. Therefore, the samples in this section will only give the changed sections.

The following sample runtime configuration comes from the MiniGUI.cfg used by mGUXDemo:

The following sample runtime configuration comes from the MiniGUI.cfg file used by CBPlusUI in mg-demos package:

<< Compile-time Configuration | Table of Contents | Tools >>

PreviousCompile-time ConfigurationNextTools

Last updated