uGFX Wiki - User contributions [en]

PushButton

2024-09-09T13:51:19Z

Tectu: Update example code

A push button is a stand-alone [[widgets|widget]] with a static size and a text where the text is drawn centered inside the button area. A push button can have the state '''pressed''' or '''unpressed'''.

== API Reference ==
The API reference for the push button widget can be found [http://api.ugfx.org/group___button.html here].

== Custom Draw Routines ==
The button widget predefines a number of custom draw routines. They can be set using <code>gwinSetCustomDraw()</code> or by specifying the custom draw routine in the GWidgetInit structure during creation. Some require certain features to be turned on in your [[gfxconf.h]] file. The predefined custom draw routines are:
{| class="wikitable"
! scope="col"|Custom Draw Routine
! scope="col"|Requires
! scope="col"|Description
|-
|gwinButtonDraw_Normal
|
| The standard button look
|-
|gwinButtonDraw_Rounded
| GDISP_NEED_ARC
| A button with rounded corners
|-
|gwinButtonDraw_Ellipse
| GDISP_NEED_ELLIPSE
| An elliptical button
|-
|gwinButtonDraw_ArrowUp
| GDISP_NEED_CONVEX_POLYGON
| An up arrow
|-
|gwinButtonDraw_ArrowDown
| GDISP_NEED_CONVEX_POLYGON
| An down arrow
|-
|gwinButtonDraw_ArrowLeft
| GDISP_NEED_CONVEX_POLYGON
| An left arrow
|-
|gwinButtonDraw_ArrowRight
| GDISP_NEED_CONVEX_POLYGON
| An right arrow
|-
|gwinButtonDraw_Image
| GDISP_NEED_IMAGE
| An image button. The param must be a gdispImage pointer. See the API documentation for details.
|}

== Cancel feature ==
The button implementation allows it to cancel a button pressed event: When you push a button but release it outside of it's area, the action is canceled. However, this feature can become a problem with touchscreen systems which have a lot of noise on the output coordinates. When you have a small button, the chance that just one point is outside of the area of a small button is very high.

To fix this issue, there's the macro <code>GWIN_BUTTON_LAZY_RELEASE</code> available. When you set it to '''TRUE''' in your [[gfxconf.h]], the cancel feature get's disabled.

Of course the real solution is to fix the noise. One of the things that may help is reducing your SPI frequency if your touch is connected via SPI. There is a demo program that allows you to fine-tune the parameters for your touch driver in ''tools/ginput_touch_driver_test''. Compile and run it and each step will help you adjust one of the touch parameters. Unfortunately the parameters are not run-time changable. You need to run a test, alter the paremter, recompile and then run it again. Also don't try to do all the parameters at the same time as the setting of one can affect the setting of others - so do the tests one step at a time.

== Example ==
The following example shows how to use a push button widget:
<syntaxhighlight lang=c>
#include "gfx.h"

static GListener gl;
static GHandle ghButton1;

static void createWidgets(void) {
GWidgetInit wi;

// Apply some default values for GWIN
gwinWidgetClearInit(&wi);
wi.g.show = TRUE;

// Apply the button parameters
wi.g.width = 100;
wi.g.height = 30;
wi.g.y = 10;
wi.g.x = 10;
wi.text = "Push Button";

// Create the actual button
ghButton1 = gwinButtonCreate(NULL, &wi);
}

int main(void) {
GEvent* pe;

// Initialize the display
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// create the widget
createWidgets();

// We want to listen for widget events
geventListenerInit(&gl);
gwinAttachListener(&gl);

while(1) {
// Get an Event
pe = geventEventWait(&gl, TIME_INFINITE);

switch(pe->type) {
case GEVENT_GWIN_BUTTON:
if (((GEventGWinButton*)pe)->gwin == ghButton1) {
// Our button has been pressed
printf("Button clicked\r\n");
}
break;

default:
break;
}
}

return 0;
}
</syntaxhighlight>

[[Category:Widget]]

Pixmaps

2023-12-04T16:02:48Z

Tectu: Fix broken URL

Pixmaps provide dynamic frame buffers. A pixmap of any size can by dynamically created and destroyed during runtime. A pixmap represents itself as a virtual display to the user. Hence a pixmap can be treated like a regular display and all the available [[GDISP]] drawing routines can be performed inside the pixmap frame buffer. A pixmap can be rendered at any location of a real display at any time.

Note that pixmaps always use the system pixel format. See [[GDISP#Color_format|color formats]] for more information.

== API reference ==
The API reference of the pixmap can be found [https://api.ugfx.io/group___pixmap.html here].

== Limitations ==
In µGFX < v3.0, pixmaps are not supported when using the [[Getting_Started#Single_File_Inclusion|single file inclusion]] mechanism as pixmaps rely on multi-display capabilities.

== Creating and destroying a pixmap ==
Pixmaps can be created and destroyed at any time during runtime using <code>gdispPixmapCreate()</code> and <code>gdispPixmapDelete()</code>.

== Accessing the pixmap ==
A pixmap can be treated as either a virtual display or as a memory frame buffer surface.

=== Virtual display ===
<code>gdispPixmapCreate()</code> returns a [[GDISP#GDisplay|GDisplay]] pointer. Hence the pixmap can be treated like a regular display and all the [[GDISP]] operations (including orientations) can be used on a pixmap.

=== Frame buffer surface ===
The memory of a created pixmap can be accessed directly in order to use it like a regular frame buffer surface. <code>gdispPixmapGetBits()</code> returns a pointer to the first pixel of the pixmap.

=== Image access ===
It's possible to treat a pixmap as an image. <code>gdispPixmapGetMemoryImage()</code> returns a pointer to a native GDISP image (<code>gdispImage*</code>). This allows to use a pixmap as the image for image rendering routines.

== Displaying a pixmap ==
A pixmap can be displayed on a real display at any time using the <code>gdispBlitArea()</code> function. Note that this call allows to display the pixmap at any location on the screen, not only at the display origin. Therefore, this can be used to implement scrolling and other animations.

== Example ==
The following example will show how to create a pixmap and access it both as a virtual display and as a frame buffer surface. Once the pixmap is created it will be blitted incrementally across the entire screen (The pixmap will move across the screen).
<syntaxhighlight lang="c">
#include "gfx.h"

#define PIXMAP_WIDTH 40
#define PIXMAP_HEIGHT 10

static GDisplay* pixmap;
static pixel_t* surface;

int main(void)
{
coord_t width, height;
coord_t i, j;

// Initialize and clear the display
gfxInit();

// Get the screen size
width = gdispGetWidth();
height = gdispGetHeight();

// Create a pixmap and get a pointer to the bits
pixmap = gdispPixmapCreate(PIXMAP_WIDTH, PIXMAP_HEIGHT);
surface = gdispPixmapGetBits(pixmap);

// A pixmap can be treated either as a virtual display or as a memory framebuffer surface.
// We demonstrate writing to it using both methods.

// First demo drawing onto the surface directly
for(j = 0; j < PIXMAP_HEIGHT; j++)
for(i = 0; i < PIXMAP_WIDTH; i++)
surface[j*PIXMAP_WIDTH + i] = RGB2COLOR(0, 255-i*(256/PIXMAP_WIDTH), j*(256/PIXMAP_HEIGHT));

// Secondly, show drawing a line on it like a virtual display
gdispGDrawLine(pixmap, 0, 0, gdispGGetWidth(pixmap)-1, gdispGGetHeight(pixmap)-1, White);

i = j = 0;
while(TRUE) {
// Clear the old position
gdispFillArea(i, j, PIXMAP_WIDTH, PIXMAP_HEIGHT, Black);

// Change the position
i += PIXMAP_WIDTH/2;
if (i >= width - PIXMAP_WIDTH/2) {
i %= width - PIXMAP_WIDTH/2;
j = (j + PIXMAP_HEIGHT/2) % (height - PIXMAP_HEIGHT/2);
}

// Blit the pixmap to the real display at the new position
gdispBlitArea(i, j, PIXMAP_WIDTH, PIXMAP_HEIGHT, surface);

// Wait
gfxSleepMilliseconds(100);
}

// Clean up
gdispPixmapDelete(pixmap);
}
</syntaxhighlight>

== Double buffering ==
Pixmaps can be used to implement application level double buffering if the underlying hardware doesn't support it. More information can be found in this [https://community.ugfx.io/topic/960-flicker community forum topic].

[[Category:GDISP]]

Creating a custom rendering routine

2023-08-20T12:39:05Z

Tectu: Fix typo

Every [[Widgets|widget]] comes with a custom render interface. The default style in which a widget is drawn is very basic and minimalistic in order to make it run on the even lowest performance systems smoothly. However, the custom render interface allows you to submit your own rendering routines. This does not only provide a very flexible way to render a widget matching to your systems performance, but it gives you also the possibility to render a widget matching your applications style.

== The interface ==
Every widget provides a function to submit a custom rendering function:
<syntaxhighlight lang="c">
void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void* param);
</syntaxhighlight>

The ''CustomWidgetDrawFunction'' is a typedef'ed function pointer:
<syntaxhighlight lang=c>
typedef void (*CustomWidgetDrawFunction)(GWidgetObject* gw, void* param);
</syntaxhighlight>

The ''param'' parameter can be used to pass a custom parameter such as an image pointer in case of you're rendering routine needs to draw an image. However, in most of the cases, this parameter will be '''NULL'''.

'''''Note:''' The pointer to the custom rendering routine can also be passed through the initialization struct (the ''customDraw'' field).

'''''Note:''' Do never use the <code>gwinDrawXxx()</code> calls inside a rendering routine as this would lock the widget again. Use <code>gdispDrawXxx()</code> instead ''

== Widget information ==
In order to render the widget you need some information about it (eg. position, size, font, ...). All these information can be fetched from the ''GWidgetObject'' struct which is passed as a parameter to the custom rendering function. This is the only time where you're not only allowed to but even obligated to directly access the struct members directly instead of using the equivalent GWIN API calls to retrieve these information. Do never access struct members directly outside of the custom rendering routine!

'''''Important:''' Do never use the <code>gwinDrawXxx()</code> calls inside a rendering routine as this would lock the widget again. Use <code>gdispDrawXxx()</code> instead.''

To retrieve all the widget specific information the ''GWidgetObject'' struct needs to be casted to the actual widget type object.

'''''Important:''' All drawing operations must take place inside of the widget area. Do not draw outside of the widget area.''

== Example ==
We are now going to show on a real world example how a custom rendering routine can be implemented. We will write a custom rendering routine for the button widget that will allow to display an icon on the left side of the text. We will keep it as simple as possible: We won't do color blending for gradients and other things that would make this look nicer in order to focus on the things that are actually important. The expected result can be seen in the image on the right.
[[File:Buttons custom rendering.png|thumbnail|The expected result. The ''Settings'' button on the right side is being pressed]]

=== Implementation ===
<source lang="c" line="1">
void myButtonRendering(GWidgetObject* gw, void* param)
{
const GColorSet* colors;

// Get the icon/image. User must open the image beforehand.
gdispImage* icon = (gdispImage*)param;
if (!icon) {
return;
}

// Get the appropriate color pallete from the widget style
if (!gwinGetEnabled((GHandle)gw))
colors = &gw->pstyle->disabled;
else if ((gw->g.flags & GBUTTON_FLG_PRESSED))
colors = &gw->pstyle->pressed;
else
colors = &gw->pstyle->enabled;

// Draw the basic rectangle with border
gdispGFillArea(gw->g.display, gw->g.x+1, gw->g.y+1, gw->g.width-2, gw->g.height-2, colors->fill);
gdispGDrawBox(gw->g.display, gw->g.x, gw->g.y, gw->g.width, gw->g.height, colors->edge);

// Draw the string. Use StringBox() for proper justification and word-wrapping support
gdispGDrawStringBox(gw->g.display, gw->g.x+gw->g.height, gw->g.y, gw->g.width-gw->g.height, gw->g.height, gw->text, gw->g.font, colors->text, justifyLeft);

// Draw the image
gdispGImageDraw(gw->g.display, icon, gw->g.x+(gw->g.height-icon->width)/2, gw->g.y+(gw->g.height-icon->height)/2, icon->width, icon->height, 0, 0);
}
</source>

=== Usage ===
The following program will show how the same rendering routine can be applied to two buttons that are using two different icons:
<source lang="c" line="1">
#include "gfx.h"

GHandle ghButton1;
GHandle ghButton2;
gdispImage iconWrench;
gdispImage iconUgfx;
font_t font1;
font_t font2;

void myButtonRendering(GWidgetObject* gw, void* param)
{
const GColorSet* colors;

// Get the icon/image
gdispImage* icon = (gdispImage*)param;
if (!icon) {
return;
}

// Get the appropriate color pallete from the widget style
if (!gwinGetEnabled((GHandle)gw))
colors = &gw->pstyle->disabled;
else if ((gw->g.flags & GBUTTON_FLG_PRESSED))
colors = &gw->pstyle->pressed;
else
colors = &gw->pstyle->enabled;

// Draw the basic rectangle with border
gdispGFillArea(gw->g.display, gw->g.x+1, gw->g.y+1, gw->g.width-2, gw->g.height-2, colors->fill);
gdispGDrawBox(gw->g.display, gw->g.x, gw->g.y, gw->g.width, gw->g.height, colors->edge);

// Draw the string. Use StringBox() for proper justification and word-wrapping support
gdispGDrawStringBox(gw->g.display, gw->g.x+gw->g.height, gw->g.y, gw->g.width-gw->g.height, gw->g.height, gw->text, gw->g.font, colors->text, justifyLeft);

// Draw the image
gdispGImageDraw(gw->g.display, icon, gw->g.x+(gw->g.height-icon->width)/2, gw->g.y+(gw->g.height-icon->height)/2, icon->width, icon->height, 0, 0);
}

static void createWidgets(void) {
GWidgetInit wi;

// Prepare the images
gdispImageOpenFile(&iconWrench, "settings.gif");
gdispImageOpenFile(&iconUgfx, "padlock.gif");

// Apply some default values for GWIN
gwinWidgetClearInit(&wi);
wi.g.show = TRUE;

// Create a regular button
wi.g.width = 180;
wi.g.height = 52;
wi.g.y = 10;
wi.g.x = 10;
wi.customParam = &iconWrench;
wi.customDraw = myButtonRendering;
wi.text = "Setting";
ghButton1 = gwinButtonCreate(0, &wi);

// Create a regular button
wi.g.width = 180;
wi.g.height = 52;
wi.g.y = 70;
wi.g.x = 10;
wi.customParam = &iconUgfx;
wi.customDraw = myButtonRendering;
wi.text = "Lock";
ghButton2 = gwinButtonCreate(0, &wi);
}

int main(void)
{
gfxInit();

gwinSetDefaultFont(gdispOpenFont("*"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

createWidgets();

while(1) {
gfxSleepMilliseconds(250);
}
}
</source>

Graph

2023-05-04T20:47:18Z

Tectu: Fix API doc link

[[File:Graph_demo_640x480.gif|right|thumb|Output of the graph demo. Click to see without artifacts.]]
The graph window allows to easily draw curves and other sets of data with different colors and shapes in a rectangular window. The graph doesn't take any user input.

== API reference ==
The API reference of the graph window can be found [https://api.ugfx.io/group___graph.html here].

== Style ==
The graph window provides an interface to modify the appearance of the graph itself and the data it displays. This contains the following properties:

* Point
** Type (None / Dot / Square / Circle)
** Radius
** Color
* Lines
** Type (None / Solid / Dot / Dash)
** Thickness
** Color
* X-Axis line
** Type (Solid / Dot / Dash)
** Thickness
** Color
* Y-Axis
** Type (Solid / Dot / Dash)
** Thickness
** Color
* X-Axis grid
** Type (Solid / Dot / Dash)
** Thickness
** Color
** Spacing
* Y-Axis grid
** Type (Solid / Dot / Dash)
** Thickness
** Color
** Spacing
* Flags
** Arrows

== Example ==
The following example draws three curves with different colors and shapes within the same graph widget. Make sure you got the math library included into your build path (<code>-lm</code>).
<syntaxhighlight lang=c>
#include "gfx.h"
#include "math.h"

// A set of data points that will be displayed in the graph
static const point data[5] = {
{ -40, -40 },
{ 70, 40 },
{ 140, 60 },
{ 210, 60 },
{ 280, 200 }
};

// The graph object
static GGraphObject g;

// A graph styling
static GGraphStyle GraphStyle1 = {
{ GGRAPH_POINT_DOT, 0, Blue }, // Point
{ GGRAPH_LINE_NONE, 2, Gray }, // Line
{ GGRAPH_LINE_SOLID, 0, White }, // X axis
{ GGRAPH_LINE_SOLID, 0, White }, // Y axis
{ GGRAPH_LINE_DASH, 5, Gray, 50 }, // X grid
{ GGRAPH_LINE_DOT, 7, Yellow, 50 }, // Y grid
GWIN_GRAPH_STYLE_POSITIVE_AXIS_ARROWS // Flags
};

// Another graph styling
static const GGraphStyle GraphStyle2 = {
{ GGRAPH_POINT_SQUARE, 5, Red }, // Point
{ GGRAPH_LINE_DOT, 2, Pink }, // Line
{ GGRAPH_LINE_SOLID, 0, White }, // X axis
{ GGRAPH_LINE_SOLID, 0, White }, // Y axis
{ GGRAPH_LINE_DASH, 5, Gray, 50 }, // X grid
{ GGRAPH_LINE_DOT, 7, Yellow, 50 }, // Y grid
GWIN_GRAPH_STYLE_POSITIVE_AXIS_ARROWS // Flags
};

int main(void) {
GHandle gh;
uint16_t i;

gfxInit();

// Create the graph window
{
GWindowInit wi;

wi.show = TRUE;
wi.x = wi.y = 0;
wi.width = gdispGetWidth();
wi.height = gdispGetHeight();
gh = gwinGraphCreate(&g, &wi);
}

// Set the graph origin and style
gwinGraphSetOrigin(gh, gwinGetWidth(gh)/2, gwinGetHeight(gh)/2);
gwinGraphSetStyle(gh, &GraphStyle1);
gwinGraphDrawAxis(gh);

// Draw a sine wave
for(i = 0; i < gwinGetWidth(gh); i++) {
gwinGraphDrawPoint(gh, i-gwinGetWidth(gh)/2, 80*sin(2*0.2*M_PI*i/180));
}

// Modify the style
gwinGraphStartSet(gh);
GraphStyle1.point.color = Green;
gwinGraphSetStyle(gh, &GraphStyle1);

// Draw a different sine wave
for(i = 0; i < gwinGetWidth(gh)*5; i++) {
gwinGraphDrawPoint(gh, i/5-gwinGetWidth(gh)/2, 95*sin(2*0.2*M_PI*i/180));
}

// Change to a completely different style
gwinGraphStartSet(gh);
gwinGraphSetStyle(gh, &GraphStyle2);

// Draw a set of points
gwinGraphDrawPoints(gh, data, sizeof(data)/sizeof(data[0]));

while(TRUE) {
gfxSleepMilliseconds(100);
}
}
</syntaxhighlight>

[[Category:Window]]

FreeBSD

2022-06-06T13:29:58Z

Tectu: Add missing parenthesis

µGFX can be compiled into native FreeBSD applications. This is especially useful for developing µGFX applications on a Desktop machine.
The SDL2 library is used to spawn a desktop window. Mouse & keyboard inputs are supported.

= Dependencies =
The following dependencies are required:
* GCC (eg. <code>[https://www.freshports.org/lang/gcc10 lang/gcc10]</code>, <code>[https://www.freshports.org/lang/gcc11 lang/gcc11]</code>)
* <code>[https://www.freshports.org/devel/gmake/ devel/gmake]</code>
* <code>[https://www.freshports.org/devel/sdl2 devel/sdl2]</code>

= Makefile =
A sample Makefile can be found under <code>/boards/base/FreeBSD-SDL/example/Makefile</code>. Copy it to your project directory.

From there, set the <code>GFXLIB</code> variable in the Makefile to point to the root directory of the µGFX library.

If the <code>GFXDEMO</code> variable is set to non-empty (it has to point to one of the demo directories in <code>/demos</code>, the corresponding demo will be compiled. If you want to compile your own application code, add the source files to the <code>SRC</code> variable.

FreeBSD

2021-09-24T00:14:42Z

Tectu: /* Makefile */

µGFX can be compiled into native FreeBSD applications. This is especially useful for developing µGFX applications on a Desktop machine.
The SDL2 library is used to spawn a desktop window. Mouse & keyboard inputs are supported.

= Dependencies =
The following dependencies are required:
* GCC (eg. <code>[https://www.freshports.org/lang/gcc10 lang/gcc10]</code>, <code>[https://www.freshports.org/lang/gcc11 lang/gcc11]</code>
* <code>[https://www.freshports.org/devel/gmake/ devel/gmake]</code>
* <code>[https://www.freshports.org/devel/sdl2 devel/sdl2]</code>

= Makefile =
A sample Makefile can be found under <code>/boards/base/FreeBSD-SDL/example/Makefile</code>. Copy it to your project directory.

From there, set the <code>GFXLIB</code> variable in the Makefile to point to the root directory of the µGFX library.

If the <code>GFXDEMO</code> variable is set to non-empty (it has to point to one of the demo directories in <code>/demos</code>, the corresponding demo will be compiled. If you want to compile your own application code, add the source files to the <code>SRC</code> variable.

GOS

2021-09-24T00:03:32Z

Tectu: /* Existing ports */

GOS is the module which builds the abstraction layer between µGFX and the underlying system. The underlying system can be an RTOS such as [http://chibios.org ChibiOS] or [http://freertos.org FreeRTOS], or also just a bare metal system. The GOS module allows to write completely platform independent application code.

== API reference ==
The API reference of the GOS module can be found [http://api.ugfx.org/group___g_o_s.html here].

== Configuration ==
There are several configuration options for the GOS module inside the [[Configuration|configuration file]]. Note that none of these configuration settings need to be specified in 99% of the cases as everything comes with a reasonable default implementation/setting.

=== Compiler ===
The <code>GFX_COMPILER</code> configuration setting allows enabling compiler specific optimization code. Please note that this setting usually doesn't have to be set manually by the user as the used compiler will be auto-detected. If <code>GFX_SHOW_COMPILER</code> is set to <code>TRUE</code> a compiler warning will be generated showing the name of the compiler that was manually set or automatically detected.

Available values for <code>GFX_COMPILER</code> are:
{| class="wikitable"
! scope="col"|Option
! scope="col"|Description
|-
|GFX_COMPILER_UNKNOWN
|Unknown compiler. This is the default and should always work.
|-
|GFX_COMPILER_ACC
|ACC Compiler
|-
|GFX_COMPILER_ALTIUM
|Altium MicroBlaze C
|-
|GFX_COMPILER_ALTIUMHW
|Altium C-to-Hardware
|-
|GFX_COMPILER_AMSTERDAM
|Amsterdam Compiler Kit
|-
|GFX_COMPILER_ARMCC
|ARM Compiler
|-
|GFX_COMPILER_AZTEC
|Aztec C
|-
|GFX_COMPILER_BORLAND
|Borland C++
|-
|GFX_COMPILER_CC65
|CC65
|-
|GFX_COMPILER_CLANG
|CLang (LLVM) compiler
|-
|GFX_COMPILER_COMEAU
|Comeau C++
|-
|GFX_COMPILER_COMPAQ
|Compaq C
|-
|GFX_COMPILER_COMPCERT
|Compcert Compiler
|-
|GFX_COMPILER_CONVEX
|Convex C
|-
|GFX_COMPILER_CRAY
|Cray C/C++
|-
|GFX_COMPILER_CYGWIN
|Cygwin (x86) unix emulator compiler for windows
|-
|GFX_COMPILER_DAIB
|Diab C/C++
|-
|GFX_COMPILER_DEC
|The older DEC C Compiler
|-
|GFX_COMPILER_DICE
|DICE C Compiler
|-
|GFX_COMPILER_DIGNUS
|Dignus Systems C++ Compiler
|-
|GFX_COMPILER_DJGPP
|DJGPP
|-
|GFX_COMPILER_DMARS
|Digital Mars
|-
|GFX_COMPILER_EDG
|EDG C++
|-
|GFX_COMPILER_EKOPATH
|EKOPath Compiler
|-
|GFX_COMPILER_FUJITSU
|Fujitsu C++ Compiler
|-
|GFX_COMPILER_GCC
|Standard GCC/G++ (Also use this when using <code>arm-none-eabi-gcc</code>)
|-
|GFX_COMPILER_GREENHILL
|Green Hill C/C++
|-
|GFX_COMPILER_HIGHC
|Metaware High C/C++
|-
|GFX_COMPILER_HP
|HP C/aC++
|-
|GFX_COMPILER_IAR
|IAR C/C++
|-
|GFX_COMPILER_IBMXL
|IBM XL C/C++ Compiler
|-
|GFX_COMPILER_IMAGECRAFT
|ImageCraft C Compiler
|-
|GFX_COMPILER_INTEL
|Intel ICC/ICPC Compiler
|-
|GFX_COMPILER_KAI
|Kai C++
|-
|GFX_COMPILER_KEIL
|Keil (use this when working with uVision IDE)
|-
|GFX_COMPILER_LCC
|LCC
|-
|GFX_COMPILER_METROWORKS
|Metroworks
|-
|GFX_COMPILER_MICROTEC
|Microtec C/C++
|-
|GFX_COMPILER_MICROWAY
|Microway NDP C
|-
|GFX_COMPILER_MINGW32
|MingW32 (x86) compiler for windows
|-
|GFX_COMPILER_MINGW64
|MingW64 (x64) compiler for windows
|-
|GFX_COMPILER_MIPSPRO
|MIPS Pro
|-
|GFX_COMPILER_MIRACLE
|Miracle C
|-
|GFX_COMPILER_MPW
|MPW C++
|-
|GFX_COMPILER_NORCROFT
|Norcroft ARM
|-
|GFX_COMPILER_NWCC
|NWCC
|-
|GFX_COMPILER_OPEN64
|Open64
|-
|GFX_COMPILER_OSS
|Oracle Solaris Studio
|-
|GFX_COMPILER_PACIFIC
|Pacific C
|-
|GFX_COMPILER_PALM
|Palm C/C++
|-
|GFX_COMPILER_PELLES
|Pelles C
|-
|GFX_COMPILER_PGCC
|Portland PGCC/PGCPP
|-
|GFX_COMPILER_RENESAS
|Renesas C/C++
|-
|GFX_COMPILER_SASC
|SAS/C
|-
|GFX_COMPILER_SCO
|SCO OpenServer
|-
|GFX_COMPILER_SDCC
|Small Device C Compiler
|-
|GFX_COMPILER_SN
|SN Compiler
|-
|GFX_COMPILER_STRATUS
|Stratus VOS C
|-
|GFX_COMPILER_SYMANTEC
|Symantec C++
|-
|GFX_COMPILER_TENDRA
|TenDRA C/C++
|-
|GFX_COMPILER_THINK
|Think C
|-
|GFX_COMPILER_TI
|Texas Instruments C/C++
|-
|GFX_COMPILER_TINYC
|Tiny C
|-
|GFX_COMPILER_TURBOC
|Borland Turbo C
|-
|GFX_COMPILER_ULTIMATE
|Ultimate C/C++
|-
|GFX_COMPILER_USL
|USL C
|-
|GFX_COMPILER_VBCC
|VBCC
|-
|GFX_COMPILER_VS
|Microsoft Visual Studio
|-
|GFX_COMPILER_WATCOM
|Watcom
|-
|GFX_COMPILER_ZTC
|Zortech C++
|}

=== CPU ===
The <code>GFX_CPU</code> configuration setting allows enabling CPU specific optimization code.
Available settings:
{| class="wikitable"
! scope="col"|Option
! scope="col"|Description
|-
|GFX_CPU_UNKNOWN
|Unknown CPU. This is the default setting.
|-
|GFX_CPU_CORTEX_M0
|Cortex M0
|-
|GFX_CPU_CORTEX_M1
|Cortex M1
|-
|GFX_CPU_CORTEX_M2
|Cortex M2
|-
|GFX_CPU_CORTEX_M3
|Cortex M3
|-
|GFX_CPU_CORTEX_M4
|Cortex M4
|-
|GFX_CPU_CORTEX_M4_FP
|Cortex M4 with hardware floating point unit
|-
|GFX_CPU_CORTEX_M7
|Cortex M7
|-
|GFX_CPU_CORTEX_M7_FP
|Cortex M7 with hardware floating point unit
|-
|GFX_CPU_X86
|Intel x86
|-
|GFX_CPU_X64
|Intel x64
|-
|GFX_CPU_IA64
|Intel Itanium
|-
|GFX_CPU_POWERPC32
|PowerPC 32-Bit
|-
|GFX_CPU_POWERPC64
|PowerPC 64-Bit
|-
|GFX_CPU_SPARC
|Sparc
|}

=== Endian ===
The <code>GFX_CPU_ENDIAN</code> setting enables optimisations that are CPU-endian specific. It does not need to be specified as reasonable defaults and various auto-detection will happen as required.
{| class="wikitable"
! scope="col"|Option
! scope="col"|Description
|-
|GFX_CPU_ENDIAN_UNKNOWN
|Unknown endianness. This is the default.
|-
|GFX_CPU_ENDIAN_LITTLE
|Little endian
|-
|GFX_CPU_ENDIAN_BIG
|Big endian
|-
|GFX_CPU_ENDIAN_WBDWL
|Words are big endian, DWords are little endian. For example: Honeywell 316
|-
|GFX_CPU_ENDIAN_WLDWB
|Words are little endian, DWords are big endian. For example: PDP-11
|}

=== Inlining ===
Certain functions of the µGFX library are inlined for performance reasons. Setting <code>GFX_NO_INLINE</code> to <code>TRUE</code> will disable the inlining of all functions.
This setting should only be touched in case of there are any compile time errors for unsupported compilers. Disabling inlining will have huge impacts on performance.

=== Initialization ===
For code portability reasons the underlying system will be automatically initialized when <code>gosInit()</code> is called unless <code>GFX_OS_NO_INIT</code> is set to <code>TRUE</code> in the [[Configuration|configuration file]].

=== Warnings ===
By default the GOS module will print out a warning during compile time to notify the user that he needs to make sure that his OS has been initialized before calling <code>gfxInit()</code>. Setting <code>GFX_OS_INIT_NO_WARNING</code> to <code>TRUE</code> will suppress this warning.
Note that this warning is only printed out when the GOS module cannot initialize the operating system automatically. This is the case when eg. the RAW32 port is used (see [[BareMetal]]) or when <code>GFX_OS_NO_INIT</code> has been set to <code>TRUE</code> to prevent <code>gfxInit()</code> from initializing the underlying systems automatically.

=== Extra functions ===
It is possible to submit code that is executed when µGFX is being initialized and deinitialized through <code>GFX_OS_EXTRA_INIT_FUNCTION</code> and <code>GFX_OS_EXTRA_DEINIT_FUNCTION</code>. The functions have to have no parameters and <code>void</code> as return type.

=== Emulating Malloc ===
An uGFX application should '''always''' use <code>gfxAlloc()</code> and <code>gfxFree()</code> instead of the corresponding C library functions to ensure portability. However, sometimes external libraries are used within an uGFX applications. External libraries might call <code>malloc()</code> and <code>free()</code> which can lead to both compile-time and run-time errors when mixing with the corresponding uGFX functions due to multiple reasons:
* uGFX allows to compile programs without a clib
* On certain platforms uGFX will implements its own heap manager that cannot be used together with the clib one

To avoid this problem, <code>GFX_EMULATE_MALLOC</code> can be set to <code>TRUE</code> in the [[Configuration|configuration file]].
When <code>GFX_EMULATE_MALLOC</code> is enabled, the <code>malloc()</code> and <code>free()</code> functions will be defined as wrappers to the corresponding <code>gfxAlloc()</code> and <code>gfxFree()</code> functions:
<source lang="c">
#if GFX_EMULATE_MALLOC
#include <stdlib.h>

void* malloc(size_t size)
{
return gfxAlloc(size);
}

void free(void* ptr)
{
gfxFree(ptr);
}
#endif
</source>

== Threading ==
It is highly recommended to use the uGFX API to create and manage threads. This way the application is fully portable. In most cases these are just 1:1 wrappers to the calls from the underlying operating systems so there is no additional overhead.

Please take a look at the [http://api.ugfx.org/master/group___g_o_s.html API reference] of the GOS module to learn about all the available functions.

The following demos which can be found in the uGFX repository show how to properly use the threading API:
* ''/demos/modules/gos/threads''
* ''/demos/modules/gos/threads_advanced''

=== Thread priority ===
The number of different thread priorities is not clearly defined as every underlying operating system implements this feature differently. However, the GOS module ensures that the following three priority levels are defined:
<syntaxhighlight lang=c>
LOW_PRIORITY
NORMAL_PRIORITY
HIGH_PRIORITY
</syntaxhighlight>
As thread priorities are usually implemented in form of integer variables, you can increment and decrement these defines in order to further split the thread priorities. For example:
<syntaxhighlight lang=c>
/* Normal priority thread */
NORMAL_PRIORITY

/* High priority thread */
HIGH_PRIORITY

/* A thread that has a slightly higher priority than the normal priority but with a still smaller priority than the high priroty thread */
NORMAL_PRIORITY + 1
</syntaxhighlight>

=== Terminating a thread ===
The uGFX API does not provide any function to terminate a running thread. This is due to the fact that only very few operating systems provide the feature to terminate a running thread from within another thread. However, it's still possible to ''tell'' a thread to terminate itself. This can for example be accomplished by implementing a 'falling over the edge' algorithm where a variable is passed to the custom parameter of the thread function. The thread will frequently check this variable which tells whether the thread should return or not. As the variable is only passed as a pointer it can be modified out of another thread.

The ''/demos/modules/gos/threads_advanced'' demo shows how to implement such an algorithm. Basically it looks like this:
<syntaxhighlight lang=c>
threadreturn_t threadFunction(void* param)
{
/* Cast the paramter into a bool pointer so we can use it */
bool_t* doExit = (bool_t*)param;

/* Execute this until we shall be terminated */
while (*doExit == FALSE) {
/* Do the actual work... */
}

/* Don't return anything (or return something) */
return (threadreturn_t)0;
}

int main(void)
{
bool_t exitThread = FALSE;

/* Start the thread and pass the variable as a parameter to tell the thread to terminate later */
gfxThreadCreate(NULL, 128, NORMAL_PRIORITY, threadFunction, (void*)&exitThread);

/* Tell the thread to return */
exitThread = TRUE;
}
</syntaxhighlight>

== Memory management ==
It is highly recommended to use the uGFX API for memory management. This way the application is fully portable. In most cases these calls are just 1:1 wrappers to the calls from the underlying operating system so there is no additional overhead.
Have a look at [[GOS#Emulating_Malloc|Emulating Malloc]] in case of you have to use external libraries that use <code>malloc()</code> and <code>free()</code>.

Please take a look at the [[#API_reference|API reference]] of the GOS module to learn about all the available functions.

== Existing ports ==
The following ports already exist and are part of the official repository:

* BareMetal (no OS at all)
* ChibiOS/RT
* CMSIS RTOS
* eCos
* Zephyr
* FreeRTOS
* Keil RTX
* NIOS-II
* rawrtos
* Arduino
* Teensy
* SylixOS
* Linux
* FreeBSD
* Mac OS X
* Windows
* And most likely more because we forgot to update this list.

Please have a look at the '''Using µGFX on...''' section on the [[Main Page]] to find links to the corresponding articles that give information about each of these ports.

=== BareMetal ===
It's possible to run µGFX directly on a bare-metal system without any underlying OS using the RAW32 port.

== Porting ==
Porting uGFX to a new underlying system is fairly easy. Only a couple of functions and data types have to be implemented and declared.

=== Functions ===
<syntaxhighlight lang=c>
void gfxHalt(const char *msg);
void gfxExit(void);
void* gfxAlloc(size_t sz);
void* gfxRealloc(void *p, size_t oldsz, size_t newsz);
void gfxFree(void *ptr);
void gfxYield(void);
void gfxSleepMilliseconds(delaytime_t ms);
void gfxSleepMicroseconds(delaytime_t ms);
systemticks_t gfxSystemTicks(void);
systemticks_t gfxMillisecondsToTicks(delaytime_t ms);
void gfxSystemLock(void);
void gfxSystemUnlock(void);
void gfxMutexInit(gfxMutex *pmutex);
void gfxMutexDestroy(gfxMutex *pmutex);
void gfxMutexEnter(gfxMutex *pmutex);
void gfxMutexExit(gfxMutex *pmutex);
void gfxSemInit(gfxSem *psem, semcount_t val, semcount_t limit);
void gfxSemDestroy(gfxSem *psem);
bool_t gfxSemWait(gfxSem *psem, delaytime_t ms);
void gfxSemSignal(gfxSem *psem);
void gfxSemSignalI(gfxSem *psem);
semcount_t gfxSemCounter(gfxSem *pSem);
semcount_t gfxSemCounterI(gfxSem *pSem);
gfxThreadHandle gfxThreadCreate(void *stackarea, size_t stacksz, threadpriority_t prio, DECLARE_THREAD_FUNCTION((*fn),p), void *param);
threadreturn_t gfxThreadWait(gfxThreadHandle thread);
gfxThreadHandle gfxThreadMe(void)
void gfxThreadClose(gfxThreadHandle thread);
</syntaxhighlight>

=== Examples ===
When creating a new port, taking a look at existing ones can help a lot. The existing ports can be found under ''/src/gos/''

[[Category:Module]]

FreeBSD

2021-09-24T00:00:37Z

Tectu:

FreeBSD

2021-09-23T23:56:26Z

Tectu: /* Dependencies */

FreeBSD

2021-09-23T23:54:15Z

Tectu:

FreeBSD

2021-09-23T23:52:22Z

Tectu: Created page with "µGFX can be compiled into native FreeBSD applications. This is especially useful for developing µGFX applications on a Desktop machine. The SDL2 library is used to spawn a d..."

µGFX can be compiled into native FreeBSD applications. This is especially useful for developing µGFX applications on a Desktop machine.
The SDL2 library is used to spawn a desktop window. Mouse & keyboard inputs are supported.

= Dependencies =
As of today, we recommend using GCC for compiling µGFX applications on FreeBSD.

Main Page

2021-09-23T23:48:59Z

Tectu:

<div class="div-header">Welcome to the µGFX wiki!</div>
<div class="div-block">This is the official documentation of the [http://ugfx.io µGFX] library. Please note that this is just the documentation, the official project website can be found at [http://ugfx.io ugfx.io]. The API reference can be found at [http://api.ugfx.io api.ugfx.io].

If you're new to µGFX, begin by reading [[Getting Started]].
</div>
<div style="width: 50%; float: left;">
<div class="div-header" style="margin-right: 5px;">General</div>
<div class="div-block" style="margin-right: 5px;">
* [[Getting Started]]
* [[Configuration]]
* [[Architecture]]
* [[Board File]]
* [[Types]]
* [[API Reference]]
* [[Changes from V2.x to V3.0]]
</div>
<div class="div-header" style="margin-right: 5px;">Using µGFX on...</div>
<div class="div-block" style="margin-right: 5px;">
* [[BareMetal]]
* [[CMSIS RTOS]]
* [[ChibiOS/RT]]
* [[FreeRTOS]]
* [[RawOS]]
* [[eCos]]
* [[Zephyr]]
* [[Using_Keil_µVision_5_MDK-ARM|Keil RTX]]
* [[Teensy]]
* [[Raspberry Pi]]
* [[Linux]]
* [[Win32]]
* [[Mac OS X]]
* [[FreeBSD]]
</div>
<div class="div-header" style="margin-right: 5px;">Using IDEs</div>
<div class="div-block" style="margin-right: 5px;">
* [[Using Keil µVision 5 MDK-ARM|Keil µVision 5 MDK-ARM]]
* [[Using IAR embedded workbench|IAR embedded workbench]]
* [[Using Eclipse|Eclipse]]
* [[Using PSoC Creator|PSoC Creator]]
* [[Using ChibiStudio|ChibiStudio]]
</div>
<div class="div-header" style="margin-right: 5px;">Developer Guides</div>
<div class="div-block" style="margin-right: 5px;">
* [[Your First Compile - Windows]]
* [[Creating a custom rendering routine]]
* [[Creating a widget]]
* [[Use_uGFX_repository_as_Git_Submodule|Advanced git guide]]
</div>
<div class="div-header" style="margin-right: 5px;">µGFX Design Choices</div>
<div class="div-block" style="margin-right: 5px;">
* [[Display Driver Model]]
</div>
</div>
<div style="width: 50%; float: right;">
<div class="div-header" style="margin-left: 5px;">Modules</div>
<div class="div-block" style="margin-left: 5px;">
* [[GWIN]]
** [[Windows]]
*** [[Console]]
*** [[Graph]]
** [[Widgets]]
*** [[Label]]
*** [[PushButton]]
*** [[RadioButton]]
*** [[CheckBox]]
*** [[List]]
*** [[Slider]]
*** [[Progressbar]]
*** [[ImageBox]]
*** [[TextEdit]]
*** [[Keyboard]]
** [[Containers]]
*** [[Container]]
*** [[Tabset]]
*** [[Frame]]
* [[GAUDIO]]
* [[GFILE]]
* [[GOS]]
* [[GDISP]]
** [[Drawing]]
** [[Font rendering]]
** [[Images]]
* [[GINPUT]]
* [[GTRANS]]
* [[GEVENT]]
* [[GTIMER]]
* [[GQUEUE]]
</div>
</div>

__NOTOC__

Creating a widget

2021-09-09T10:09:12Z

Tectu: /* Examples */

It's possible to implement custom widgets. A custom widget can be declared and implemented outside of the µGFX library. This means that it can be part of the actual project and that it's not necessary to do any modification of the µGFX library itself. The first half of this article will explain how widgets are implemented an whats needed to create a custom widget. The second half of the article is a step-by-step guide that will show how to actually implement a custom widget based on an example.

It's vital that you've read the [[GWIN]] article and the corresponding sub-articles about [[windows]], [[widgets]] and [[containers]] before following this guide.

'''''Note:''' If you just want to change the look of an existing widget, please have a look at [[Widgets#Widget_Style|WidgetStyles]] and [[Creating_a_custom_rendering_routine|custom rendering functions]].''

== Theory of operation ==
A widget consists of three main parts: The '''object structure''', the '''VMT''' and the '''rendering routine'''.
A widget is usually split into two source files: The header file and the source file (for example <code>mywidget.h</code> and <code>mywidget.c</code>. The header file contains the '''object structure''' and the public API functions. The source file contains the '''VMT''', the '''rendering routine''' and the implementations of all the required functions.

=== Object structure ===
The C language is not object oriented - yet it's possible to write object oriented software without any problems. The philosophy is to create a struct which is ''the object'' and to pass that struct as the first parameter to any function that has to have access to the object. A widget is an object and hence it needs a struct that defines the object. The only thing that makes the widget object struct become a ''widget'' struct is that the very first field is a <code>GWidgetObject</code>:
<source lang="c">
typedef struct StatusbarObject_t {
GWidgetObject w; // Base Class
} StatusbarObject;
</source>
Note that it is '''absolutely mandatory''' that the <code>GWidgetObject</code> is the very first field in the struct. This is needed to implement inheritance and polymorphism. After that first field you can add any field you want to the widget object struct. For example, a slider would add fields to hold the ''minimum'', ''maximum'' and ''current'' value. A list widget would hold a list of items here. A text edit (line edit) would hold the current cursor position and so on. In terms of an object oriented language this is the <code>private</code> area of the class.
<source lang="c">
typedef struct widgetObject_t {
GWidgetObject w; // Base Class

uint8_t myVariable1;
char* someOtherStuff;
uint16_t currentValue;
} WidgetObject;
</source>
The <code>GWidgetObject</code> itself is based on a <code>GWindowObject</code> as explained in the article about [[widgets]]. Therefore, the following attributes are already part of our <code>WidgetObject</code> and don't need to be added manually:
* Position relative to parent (x, y)
* Dimensions (width, height)
* Parent
* [[Font_rendering|Font]]
* Text
* [[Widgets#Widget_Style|WidgetStyle]]
* [[Widgets#Tag|Widget Tag]]
* Flags
The widget object is the widget itself: It's what the user of the widget will create an instance of. The widget object must be available to the outside world. Therefore, the widget object must be declared in the header file (referred to as <code>mywidget.h</code> above).

==== Flags ====
The flags need some explanation: The <code>GWindowObject</code> contains a field of the type <code>uint32_t</code> and can therefore represent 32 flags. Some of these flags are used by the GWIN module internally to store certain information like the enable state, the visibility, whether the widget was allocated dynamically and so on. However, the first 8 bits are reserved for widget internal use. For example, the [[PushButton|pushbutton widget]] uses one of these bits to keep record of the pressed/release state. The [[Label|label widget]] uses the flags to keep the information whether the a border around the text should be rendered and so on.
Flags are usually used to define the state of a widget and are therefore often used in the rendering routine. For example, the [[PushButton]] widget uses the flags to store the ''pressed/released'' state. As it's possible to create a [[custom rendering routine]] outside of the widget the author of the custom rendering routine needs to have access to those flags. Therefore, the flags should be defined in the header file.

=== VMT ===
The VMT ([https://en.wikipedia.org/wiki/Virtual_method_table virtual method table]) is a mechanism to implement dynamic function binding. In case of C it's a simple struct containing [https://en.wikipedia.org/wiki/Function_pointer function pointers]. The VMT technique allows to implement ''virtual methods'' in our C-classes.
The VMT is defined by the GWIN module. The custom widget simply creates an instance of that struct and fills in the functions pointers.
The GWIN module defines a VMT for each type of GWIN element: [[Window]], [[widget]] and [[container]]. As a widget inherits from the window the widget VMT actually contains the window VMT. The VMTs declarations look like this (taken from ''/src/gwin/gwin_class.h''):
<source lang="c">
/**
* @brief The Virtual Method Table for a GWIN window
* @{
*/
typedef struct gwinVMT {
const char * classname; /**< The GWIN classname (mandatory) */
size_t size; /**< The size of the class object */
void (*Destroy) (GWindowObject *gh); /**< The GWIN destroy function (optional) */
void (*Redraw) (GWindowObject *gh); /**< The GWIN redraw routine (optional) */
void (*AfterClear) (GWindowObject *gh); /**< The GWIN after-clear function (optional) */
} gwinVMT;
/** @} */

/**
* @brief The Virtual Method Table for a widget
* @note A widget must have a destroy function. Either use @p _gwidgetDestroy() or use your own function
* which internally calls @p _gwidgetDestroy().
* @note A widget must have a redraw function. Use @p _gwidgetRedraw().
* @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
* @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
* @{
*/
typedef struct gwidgetVMT {
struct gwinVMT g; /**< This is still a GWIN */
void (*DefaultDraw) (GWidgetObject *gw, void *param); /**< The default drawing routine (mandatory) */
#if GINPUT_NEED_MOUSE
struct {
void (*MouseDown) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse down events (optional) */
void (*MouseUp) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse up events (optional) */
void (*MouseMove) (GWidgetObject *gw, coord_t x, coord_t y); /**< Process mouse move events (optional) */
};
#endif
#if GINPUT_NEED_KEYBOARD || GWIN_NEED_KEYBOARD
struct {
void (*KeyboardEvent) (GWidgetObject *gw, GEventKeyboard *pke); /**< Process keyboard events (optional) */
};
#endif
#if GINPUT_NEED_TOGGLE
struct {
uint16_t toggleroles; /**< The roles supported for toggles (0->toggleroles-1) */
void (*ToggleAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Assign a toggle to a role (optional) */
uint16_t (*ToggleGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
void (*ToggleOff) (GWidgetObject *gw, uint16_t role); /**< Process toggle off events (optional) */
void (*ToggleOn) (GWidgetObject *gw, uint16_t role); /**< Process toggle on events (optional) */
};
#endif
#if GINPUT_NEED_DIAL
struct {
uint16_t dialroles; /**< The roles supported for dials (0->dialroles-1) */
void (*DialAssign) (GWidgetObject *gw, uint16_t role, uint16_t instance); /**< Test the role and save the dial instance handle (optional) */
uint16_t (*DialGet) (GWidgetObject *gw, uint16_t role); /**< Return the instance for a particular role (optional) */
void (*DialMove) (GWidgetObject *gw, uint16_t role, uint16_t value, uint16_t max); /**< Process dial move events (optional) */
};
#endif
} gwidgetVMT;
/** @} */

/**
* @brief The Virtual Method Table for a container
* @note A container must have a destroy function. Either use @p _gcontainerDestroy() or use your own function
* which internally calls @p _gcontainerDestroy().
* @note A container must have a gwin redraw function. Use @p _containerRedraw().
* @note If toggleroles != 0, ToggleAssign(), ToggleGet() and one or both of ToggleOff() and ToggleOn() must be specified.
* @note If dialroles != 0, DialAssign(), DialGet() and DialMove() must be specified.
* @{
*/
typedef struct gcontainerVMT {
gwidgetVMT gw;
coord_t (*LeftBorder) (GHandle gh); /**< The size of the left border (mandatory) */
coord_t (*TopBorder) (GHandle gh); /**< The size of the top border (mandatory) */
coord_t (*RightBorder) (GHandle gh); /**< The size of the right border (mandatory) */
coord_t (*BottomBorder) (GHandle gh); /**< The size of the bottom border (mandatory) */
void (*NotifyAdd) (GHandle gh, GHandle ghChild); /**< Notification that a child has been added (optional) */
void (*NotifyDelete) (GHandle gh, GHandle ghChild); /**< Notification that a child has been deleted (optional) */
} gcontainerVMT;
/** @} */
</source>
Note how the VMTs reflect the inheritance of the GWIN elements: [[Windows]], [[widgets]] and [[containers]]. If you want to implement a widget, you don't have to implement the container VMT.

As the VMT is private to the widget itself it's declared in the source file (earlier referred to as <code>mywidget.c</code>). To have access to the different predefined VMTs the source file must include the file ''src/gwin/gwin_class.h'': <code>#include "src/gwin/gwin_class.h"</code>.

==== Function pointers ====
The function pointer declarations in the VMT specify the signature of a function (the return type and the parameters the function takes). In order to be able to register a function in the VMT, the function must match that exact signature. Let's have a look at the function to render/draw the widget:
<source lang="c">
void (*DefaultDraw) (GWidgetObject* gw, void* param);
</source>
This means that our own function that we will write to render the widget must look like this:
<source lang="c">
void myRenderingFunction(GWidgetObject* gw, void* param) { ... }
</source>
Note that the function pointer in the VMT doesn't specify the name of the function. The name '''DefaultDraw''' is only used internally by the GWIN module to ''call'' the function. You can assign a function with any name as long as the function signature matches the one from the function pointer declaration.
Once a function has been declared it can be added to the VMT by simply typing the actual function name in the corresponding field in the VMT:
<source lang="c" highlight="1,16">
void myRenderingFunction(GWidgetObject* gw, void* param)
{
...
}

...

static const gwidgetVMT mywidgetVMT = {
{
"MyWideget", // The classname
sizeof(MyWidgetObject), // The object size
_gwidgetDestroy, // The destroy routine
_gwidgetRedraw, // The redraw routine
0, // The after-clear routine
},
myRenderingFunction, // The default drawing routine
#if GINPUT_NEED_MOUSE
{
0, // Process mouse down events
0, // Process mouse up events
...
...
...
};
</source>

==== Available functions ====
The following table contains a short explanation for each field in the VMT:
{| class="wikitable"
! scope="col" style="white-space: nowrap;"|Name
! scope="col" style="white-space: nowrap;"|Type
! scope="col" style="white-space: nowrap;"|Required
! scope="col" style="white-space: nowrap;"|Description
|-
|classname
|const char*
|Yes
|The name of the class (the widget name).
|-
|size
|size_t
|Yes
|The size of the class (usually <code>sizeof(WidgetObject)</code>).
|-
|Destroy
|Function Pointer
|Yes
|A function that is called when the object is destroyed. Use <code>_gwidgetDestroy</code> as a default value.
|-
|Redraw
|Function Pointer
|Yes
|A function that is called when the need to be redrawn. Note that for widget types this '''is not''' the rendering routine. Use <code>_gwidgetRedraw</code> as a default value.
|-
|AfterClear
|Function Pointer
|No
|A function that will be called after the widget has been redrawn. Can be used to manually redraw some features as [[windows]] don't know how to draw themselves. Example: [[graph]].
|-
|DefaultDraw
|Function Pointer
|Yes
|The default rendering function for a widget.
|-
|MouseDown
|Function Pointer
|No
|The function that is called when a ''mouse-down'' event occurs inside the widget area. Coordinates passed as parameters are relative to the widgets coordinates.
|-
|MouseUp
|Function Pointer
|No
|The function that is called when a ''mouse-up'' event occurs inside the widget area. Coordinates passed as parameters are relative to the widgets coordinates.
|-
|MouseMove
|Function Pointer
|No
|The function that is called when a ''mouse-move'' event occurs inside the widget area. Coordinates passed as parameters are relative to the widgets coordinates.
|-
|KeyboardEvent
|Function Pointer
|No
|The function that is called when a keyboard key has been pressed while the widget has focus. Note that the source of the key press can be a physical keyboard connected through the [[GINPUT]] module or the [[keyboard]] widget.
|-
|}
Note that the ''"Required"'' value just specified whether the value can be a null pointer or not. The VMT struct '''must be fully filled'''. See the example in the second part of this article.

=== Rendering routine ===
This is the part that usually takes the most time when writing a custom widget: The rendering routine. A widget '''must''' have at least one built-in rendering routine which is registered as the ''default rendering routine'' in the VMT. The rendering routine is the function which draws/paints the widget on the screen. This function is called by the GWIN module whenever the widget needs to be redrawn (eg. when the visibility changed).

For further information about rendering routines it's recommended to carefully read the article about [[custom rendering routine]]s.

=== Creating the widget ===
So far we looked at how a widget is defined and how the VMT is filled in. However, we still need to actually ''create'' the widget so we can use it - the widget needs a constructor. The constructor (from here on also referred to as ''"the create function"'') is responsible for allocation and initializing the widget object and therefore the <code>GWidgetObject</code> base class.
The create function has to follow a couple of rules in order to blend into the GWIN module:
* It returns a GHandle ''(See [[GWIN#GHandle|GHandle]])''
* It takes a <code>GDisplay*</code> pointer ''(See [[GDISP#GDisplay|GDisplay]])''
* It takes a pointer to the widget object which it initializes
* It takes a pointer to a <code>GWidgetInit</code> structure ''(See [[Widgets#Initialization|widget initialization]])''
* If the widget object pointer is a null pointer the function has to dynamically allocate the widget object
An example would look like this:
<source lang="c">
GHandle mywidgetGCreate(GDisplay* g, WidgetObject* wo, GWidgetInit* pInit)
{
// Create the base class (the actual widget)
if (!(wo = (WidgetObject*)_gwidgetCreate(g, &wo->w, pInit, &mywidgetVMT))) {
return 0;
}

// Initialize the object struct
wo->myVariable1 = 0;
wo->currentValue = 0;

// Set the initial visibility
gwinSetVisible((GHandle)wo, pInit->g.show);

// Return a proper GHandle
return (GHandle)wo;
}
</source>
Furthermore, it's recommended to have a <code>#define</code> that creates an alias for the create function that doesn't take the <code>GDisplay*</code> pointer but uses the default display instead:
<source lang="c">
#define mywidgetCreate(so, pI) mywidgetGCreate(GDISP, so, pI)
</source>
Besides those rules it's possible to pass additional parameters that change the behavior of the widget. For example, the [[frame]] widget takes an additional ''flags'' parameters which specify whether there are close and min-max buttons in the widget decoration.

== Examples ==
Various examples can be found in the download section: https://community.ugfx.io/files/category/1-%C2%B5gfx-library/

ROMFS

2021-08-23T18:02:10Z

Tectu:

ROMFS is used to store files in the flash (or anywhere else) of your target system. The file system (the files and folders it contains) are listed in a file called <code>romfs_files.h</code> which you have to provide yourself.
All files you want in your ROMFS must be converted into a C array which then is #include'd into <code>romfs_files.h</code>. This is done using the <code>file2c</code> program which is part of the µGFX repository. It can be found under <code>/tools/file2c</code> and it comes with precompiled binaries for Linux and Windows. However, note that we do not take any responsibility for the binaries, use them on your own risk!

Let's take a look at the usage of file2c:
<pre>
file2c [-dbcs] [-n name] [-f file] [inputfile] [outputfile]
-? This help
-h This help
-d Add a directory entry for the ROM file system
-b Break the arrays for compilers that won't handle large arrays
-c Declare as const (useful to ensure they end up in Flash)
-s Declare as static
-n name Use "name" as the name of the array
-f file Use "file" as the filename in the ROM directory entry
</pre>
Any binary can be converted to a C-Header file using the following command. In this example we convert a GIF image. Note that the file will not be image decoded, the binary information is just expressed as a C-Array so we can include it into our project.
<pre>
./file2c -dcs image.gif image.h
</pre>
A simple <code>romfs_file.h</code> looks like the following:
<syntaxhighlight lang=c>
/**
* This file contains the list of files for ROMFS.
*
* The files have been converted using...
* file2c -dcs infile outfile
*/
#include "image1.h"
#include "image2.h"
#include "image3.h"
</syntaxhighlight>
The ROMFS does not provide directory handling as this would bloat. However, you can create a directory hierarchy yourself by changing the file names. For example, instead of <code>myFile.h</code> you can name it <code>dir1/dir2/myfile.h</code>.

[[Category:GFILE]]

ROMFS

2021-08-23T18:01:43Z

Tectu:

ROMFS is used to store files in the flash (or anywhere else) of your target system. The file system (the files and folders it contains) are listed in a file called <code>romfs_files.h</code> which you have to provide yourself.
All files you want in your ROMFS must be converted into a C header file which then is #include'd into <code>romfs_files.h</code>. This is done using the <code>file2c</code> program which is part of the µGFX repository. It can be found under <code>/tools/file2c</code> and it comes with precompiled binaries for Linux and Windows. However, note that we do not take any responsibility for the binaries, use them on your own risk!

Let's take a look at the usage of file2c:
<pre>
file2c [-dbcs] [-n name] [-f file] [inputfile] [outputfile]
-? This help
-h This help
-d Add a directory entry for the ROM file system
-b Break the arrays for compilers that won't handle large arrays
-c Declare as const (useful to ensure they end up in Flash)
-s Declare as static
-n name Use "name" as the name of the array
-f file Use "file" as the filename in the ROM directory entry
</pre>
Any binary can be converted to a C-Header file using the following command. In this example we convert a GIF image. Note that the file will not be image decoded, the binary information is just expressed as a C-Array so we can include it into our project.
<pre>
./file2c -dcs image.gif image.h
</pre>
A simple <code>romfs_file.h</code> looks like the following:
<syntaxhighlight lang=c>
/**
* This file contains the list of files for ROMFS.
*
* The files have been converted using...
* file2c -dcs infile outfile
*/
#include "image1.h"
#include "image2.h"
#include "image3.h"
</syntaxhighlight>
The ROMFS does not provide directory handling as this would bloat. However, you can create a directory hierarchy yourself by changing the file names. For example, instead of <code>myFile.h</code> you can name it <code>dir1/dir2/myfile.h</code>.

[[Category:GFILE]]

GTRANS

2021-08-23T17:25:52Z

Tectu: /* API reference */

The GTRANS module allows to manage language translations. The language of an application can be changed dynamically during runtime using the GTRANS module.

== API reference ==
The API reference of the GTRANS module can be found [http://api.ugfx.io/group___g_t_r_a_n_s.html here].

== Intended usage ==
Each translation is specified by a <code>transTable</code> struct which is essentially a table of strings:
<source lang="c">
typedef struct transTable {
unsigned numEntries; // The number of strings that this table contains
const char** strings; // The translated strings
} transTable;
</source>

A translatable application needs to have a base language. All translations happen relative to that base language. The base language is specified using <code>gtransSetBaseLanguage()</code>. The current language of the application is set using <code>gtransSetLanguage()</code>.
The actual translations take place by calling <code>gtransString()</code>. A string contained in the translation table of the base language is passed to <code>gtransString()</code>. The function returns the corresponding string of the current language that was set using <code>gtransSetLanguage()</code> or the passed string if none was found.

A wrapper macro named <code>gt()</code> around <code>gtransString()</code> is available to make writing and reading translatable applications easier:
<source lang="c">
#define gt(str) gtransString(str)
</source>

== Optimization ==
Calling <code>gt()</code> (or <code>gtransString()</code> directly) uses the <code>strcmp()</code> function of the standard C library to compare strings. This operation can take a lot of time. For performance critical applications or low-resource systems the application translation speed can be optimized by using <code>gtransIndex()</code> (instead of <code>gtransString()</code>) which directly takes the index of the string in the translation table. However, this introduces the limitation that each string in each of the translation tables need to be at the same position (the same index). Using <code>gtransString()</code> allows to have translation tables of unequal sizes due to the nature of the translation being based on string comparison rather than index accessing of the table.

== Example ==
Complete examples can be found under ''/demos/modules/gtrans/'' in the uGFX library directory.

=== Basic Example ===
The following code is a very simple usage example showing how the GTRANS module is used. This is a very minimalistic example with no dependencies other than the [[GDISP]] module to interface a display.
<source lang="c">
#include <stdio.h>
#include "gfx.h"

#define COLOR_BACKGROUND Silver
#define COLOR_TEXT Black

gFont font;

// English Translation
static const char* EnglishStrings[] = {
"Welcome",
"The temperature is %d degrees",
"Goodbye",
"This is a translated uGFX application"
};
static const transTable EnglishTranslation = { sizeof(EnglishStrings)/sizeof(EnglishStrings[0]), EnglishStrings };

// German translation
static const char* GermanStrings[] = {
"Herzlich Willkommen",
"Die Temperatur beträgt %d Grad",
"Auf Wiedersehen",
"Das ist eine übersetzte uGFX Anwendung"
};
static const transTable GermanTranslation = { sizeof(GermanStrings)/sizeof(GermanStrings[0]), GermanStrings };

// French translation
static const char* FrenchStrings[] = {
"Bienvenue",
"La température est de %d degrés",
"Au revoir",
"Ceci est une application traduit uGFX"
};
static const transTable FrenchTranslation = { sizeof(FrenchStrings)/sizeof(FrenchStrings[0]), FrenchStrings };

void updateText()
{
coord_t width = 400;
coord_t height = 30;

// Translate some basic strings
gdispFillStringBox(20, 20, width, height, gt("Welcome"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 60, width, height, gt("This is a translated uGFX application"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 100, width, height, gt("Goodbye"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);

// A more complex example using string formatting
char buffer[128];
sprintf(buffer, gt("The temperature is %d degrees"), 18);
gdispFillStringBox(20, 140, width, height, buffer, font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();
gdispClear(COLOR_BACKGROUND);

// Take the first font we find
font = gdispOpenFont("*");

// Set the base language of the application
gtransSetBaseLanguage(&EnglishTranslation);

// Loop through the languages
while (TRUE) {
// English
gtransSetLanguage(&EnglishTranslation);
updateText();
gfxSleepMilliseconds(3000);

// German
gtransSetLanguage(&GermanTranslation);
updateText();
gfxSleepMilliseconds(3000);

// French
gtransSetLanguage(&FrenchTranslation);
updateText();
gfxSleepMilliseconds(3000);
}

return 0;
}
</source>

=== Example with widgets ===
The GTRANS module can also be used to translate widget texts. GWIN doesn't do anything with the text set by <code>gwinSetText()</code> except displaying it. Therefore, the <code>gtransString()</code> (or <code>gt()</code> respectively) function can be used directly inside of the <code>gwinSetText()</code> call. When the current language changes, the <code>gwinSetText()</code> function must be re-called manually. There's currently no way to tell GWIN to automatically use the string for the currently active language as this would add a lot of overhead to both the GWIN core module as well as to each widget rendering function in order to support parameter substitution.

Example:
<source lang="c">
gwinSetText(ghMyButton, gt("The temperature is %d degrees"));
</source>

GTRANS

2021-08-23T13:57:14Z

Tectu: /* Basic Example */

The GTRANS module allows to manage language translations. The language of an application can be changed dynamically during runtime using the GTRANS module.

== API reference ==
The API reference of the GTRANS module can be found [http://api.ugfx.org/group___g_t_r_a_n_s.html here].

== Intended usage ==
Each translation is specified by a <code>transTable</code> struct which is essentially a table of strings:
<source lang="c">
typedef struct transTable {
unsigned numEntries; // The number of strings that this table contains
const char** strings; // The translated strings
} transTable;
</source>

A translatable application needs to have a base language. All translations happen relative to that base language. The base language is specified using <code>gtransSetBaseLanguage()</code>. The current language of the application is set using <code>gtransSetLanguage()</code>.
The actual translations take place by calling <code>gtransString()</code>. A string contained in the translation table of the base language is passed to <code>gtransString()</code>. The function returns the corresponding string of the current language that was set using <code>gtransSetLanguage()</code> or the passed string if none was found.

A wrapper macro named <code>gt()</code> around <code>gtransString()</code> is available to make writing and reading translatable applications easier:
<source lang="c">
#define gt(str) gtransString(str)
</source>

== Optimization ==
Calling <code>gt()</code> (or <code>gtransString()</code> directly) uses the <code>strcmp()</code> function of the standard C library to compare strings. This operation can take a lot of time. For performance critical applications or low-resource systems the application translation speed can be optimized by using <code>gtransIndex()</code> (instead of <code>gtransString()</code>) which directly takes the index of the string in the translation table. However, this introduces the limitation that each string in each of the translation tables need to be at the same position (the same index). Using <code>gtransString()</code> allows to have translation tables of unequal sizes due to the nature of the translation being based on string comparison rather than index accessing of the table.

== Example ==
Complete examples can be found under ''/demos/modules/gtrans/'' in the uGFX library directory.

=== Basic Example ===
The following code is a very simple usage example showing how the GTRANS module is used. This is a very minimalistic example with no dependencies other than the [[GDISP]] module to interface a display.
<source lang="c">
#include <stdio.h>
#include "gfx.h"

#define COLOR_BACKGROUND Silver
#define COLOR_TEXT Black

gFont font;

// English Translation
static const char* EnglishStrings[] = {
"Welcome",
"The temperature is %d degrees",
"Goodbye",
"This is a translated uGFX application"
};
static const transTable EnglishTranslation = { sizeof(EnglishStrings)/sizeof(EnglishStrings[0]), EnglishStrings };

// German translation
static const char* GermanStrings[] = {
"Herzlich Willkommen",
"Die Temperatur beträgt %d Grad",
"Auf Wiedersehen",
"Das ist eine übersetzte uGFX Anwendung"
};
static const transTable GermanTranslation = { sizeof(GermanStrings)/sizeof(GermanStrings[0]), GermanStrings };

// French translation
static const char* FrenchStrings[] = {
"Bienvenue",
"La température est de %d degrés",
"Au revoir",
"Ceci est une application traduit uGFX"
};
static const transTable FrenchTranslation = { sizeof(FrenchStrings)/sizeof(FrenchStrings[0]), FrenchStrings };

void updateText()
{
coord_t width = 400;
coord_t height = 30;

// Translate some basic strings
gdispFillStringBox(20, 20, width, height, gt("Welcome"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 60, width, height, gt("This is a translated uGFX application"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 100, width, height, gt("Goodbye"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);

// A more complex example using string formatting
char buffer[128];
sprintf(buffer, gt("The temperature is %d degrees"), 18);
gdispFillStringBox(20, 140, width, height, buffer, font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();
gdispClear(COLOR_BACKGROUND);

// Take the first font we find
font = gdispOpenFont("*");

// Set the base language of the application
gtransSetBaseLanguage(&EnglishTranslation);

// Loop through the languages
while (TRUE) {
// English
gtransSetLanguage(&EnglishTranslation);
updateText();
gfxSleepMilliseconds(3000);

// German
gtransSetLanguage(&GermanTranslation);
updateText();
gfxSleepMilliseconds(3000);

// French
gtransSetLanguage(&FrenchTranslation);
updateText();
gfxSleepMilliseconds(3000);
}

return 0;
}
</source>

=== Example with widgets ===
The GTRANS module can also be used to translate widget texts. GWIN doesn't do anything with the text set by <code>gwinSetText()</code> except displaying it. Therefore, the <code>gtransString()</code> (or <code>gt()</code> respectively) function can be used directly inside of the <code>gwinSetText()</code> call. When the current language changes, the <code>gwinSetText()</code> function must be re-called manually. There's currently no way to tell GWIN to automatically use the string for the currently active language as this would add a lot of overhead to both the GWIN core module as well as to each widget rendering function in order to support parameter substitution.

Example:
<source lang="c">
gwinSetText(ghMyButton, gt("The temperature is %d degrees"));
</source>

GEVENT

2021-08-20T15:00:13Z

Tectu: /* A closer look */

The GEVENT module is a very powerful event system. It provides a way to create a '''many-to-many''' relationships between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons '''AND''' touchscreen inputs at the same time very easily.

The following guide will use terms like '''listener''' and '''sources'''. If you are not familiar with those terms or if you never worked with an event system before, please read the [[GEVENT FAQ]] first.

== API reference ==
The API reference of the GEVENT module can be found [http://api.ugfx.io/group___g_e_v_e_n_t.html here].

== Overview ==
Using GEVENT is a simple three step process:

#Create one or more listeners
#Attach one or more sources to this/those listeners
#Wait for events
But let's take a closer look to these steps:

== A closer look ==
After we have enabled the GEVENT module in the [[Configuration|configuration file]], we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered.

<syntaxhighlight lang=c>
void geventListenerInit(GListener* pl);
</syntaxhighlight>
Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener:

<syntaxhighlight lang=c>
gBool geventAttachSource(GListener* pl, GSourceHandle gsh, gU32 flags);
</syntaxhighlight>
And now we're ready to take off. We can now use the <code>geventEventWait()</code> routine to wait for an event:

<syntaxhighlight lang=c>
GEvent* geventEventWait(GListener* pl, gDelay timeout);
</syntaxhighlight>
Please note that the <code>geventEventWait()</code> routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using <code>geventEventWait()</code> will simply be skipped. The reason to implement this behavior can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.

== A real world example ==
You're asking why we created a many-to-many event system? Let me show you...

Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)

[[Category:Module]]

GEVENT

2021-08-20T14:59:12Z

Tectu: /* A closer look */

The GEVENT module is a very powerful event system. It provides a way to create a '''many-to-many''' relationships between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons '''AND''' touchscreen inputs at the same time very easily.

The following guide will use terms like '''listener''' and '''sources'''. If you are not familiar with those terms or if you never worked with an event system before, please read the [[GEVENT FAQ]] first.

== API reference ==
The API reference of the GEVENT module can be found [http://api.ugfx.io/group___g_e_v_e_n_t.html here].

== Overview ==
Using GEVENT is a simple three step process:

#Create one or more listeners
#Attach one or more sources to this/those listeners
#Wait for events
But let's take a closer look to these steps:

== A closer look ==
After we have enabled the GEVENT module in the [[Configuration|configuration file]], we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered.

<syntaxhighlight lang=c>
void geventListenerInit(GListener *pl);
</syntaxhighlight>
Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener:

<syntaxhighlight lang=c>
gBool geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags);
</syntaxhighlight>
And now we're ready to take off. We can now use the <code>geventEventWait()</code> routine to wait for an event:

<syntaxhighlight lang=c>
GEvent* geventEventWait(GListener *pl, systime_t timeout);
</syntaxhighlight>
Please note that the <code>geventEventWait()</code> routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using <code>geventEventWait()</code> will simply be skipped. The reason to implement this behavior can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.

== A real world example ==
You're asking why we created a many-to-many event system? Let me show you...

Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)

[[Category:Module]]

GEVENT

2021-08-20T14:58:07Z

Tectu: /* API reference */

The GEVENT module is a very powerful event system. It provides a way to create a '''many-to-many''' relationships between sources and listeners. This allows to create user interfaces which use different hardware controls such as buttons '''AND''' touchscreen inputs at the same time very easily.

The following guide will use terms like '''listener''' and '''sources'''. If you are not familiar with those terms or if you never worked with an event system before, please read the [[GEVENT FAQ]] first.

== API reference ==
The API reference of the GEVENT module can be found [http://api.ugfx.io/group___g_e_v_e_n_t.html here].

== Overview ==
Using GEVENT is a simple three step process:

#Create one or more listeners
#Attach one or more sources to this/those listeners
#Wait for events
But let's take a closer look to these steps:

== A closer look ==
After we have enabled the GEVENT module in the [[Configuration|configuration file]], we have to create at least one listener. A listener is that part of an event system which does something when a certain event has been triggered.

<syntaxhighlight lang=c>
void geventListenerInit(GListener *pl);
</syntaxhighlight>
Okay, so now we have a working listener but it's currently not listening to any event. We can now attach any event to that listener:

<syntaxhighlight lang=c>
bool_t geventAttachSource(GListener *pl, GSourceHandle gsh, unsigned flags);
</syntaxhighlight>
And now we're ready to take off. We can now use the <code>geventEventWait()</code> routine to wait for an event:

<syntaxhighlight lang=c>
GEvent* geventEventWait(GListener *pl, systime_t timeout);
</syntaxhighlight>
Please note that the <code>geventEventWait()</code> routine is a polling routine (therefore the timeout parameter). Furthermore, the current implementation of GEVENT does not provide an event queue. An event which is triggered while you are not listening for events using <code>geventEventWait()</code> will simply be skipped. The reason to implement this behavior can be found in the memory and CPU usage of such a system. However, GEVENT is not meant for critical event tasks but only for user space applications.

== A real world example ==
You're asking why we created a many-to-many event system? Let me show you...

Let's asume you're building some media player device. It's very likely that you will have hardware controlls (buttons, a slider or a dial) to control the volume. However, somewhere you want to be able to control the volume over a touchscreen input as well. You would now have to create two different callbacks and update the value of one versus the other. Sure, it's no problem to do that indeed, but wouldn't it be simpler just to attach two sources to one listener? ;-)

[[Category:Module]]

Containers

2021-08-19T13:56:58Z

Tectu:

'''''Note:''' Make sure you read the [[Widgets|widget]] article first!''

The container class is based on the widget. The main property of a container is that it can hold children. A child window inherits the attributes and properties of the parent.

== API reference ==
The reference of the common container API can be found [http://api.ugfx.io/group___containers.html here].

== Container Implementations ==
These are the currently implemented containers:
* [[Container]]
* [[Frame]]
* [[Tabset]]

== Container creation ==
Each container provides a creation call with is named <code>gwinXxxCreate()</code> where Xxx is the name of the container. The first parameter is either a pointer to a static container object or ''NULL''. If ''NULL'', the object will be allocated dynamically from the heap.
The second parameter is a pointer to a <code>GWidgetInit</code> struct. This struct contains all the attributes which are needed to create the container (position, size, font, colors...):
<syntaxhighlight lang=c>
typedef struct GWidgetInit {
GWindowInit g; // The GWIN initializer
const char* text; // The initial text
CustomWidgetDrawFunction customDraw; // A custom draw function - use NULL for the standard
void* customParam; // A parameter for the custom draw function (default = NULL)
const GWidgetStyle* customStyle; // A custom style to use - use NULL for the default style
} GWidgetInit;
</syntaxhighlight>
As the container class is based on the [[Widgets|widget]] and therefore the [[Windows|window]] class, the widget initialization structure contains a window initialization structure. See [[Windows#Window_creation|window creation]] to learn more about the window initialization structure.<br/>
Examples on how to use this struct correctly can be found on each container documentation page.

<code>gwinDestroy()</code> can be used to destroy a window that is no longer needed.

== Coordinates ==
The coordinates of a child are always relative to it's parent.

As a container can have a border, <code>gwinGetInnerWidth</code> and <code>gwinGetInnerHeight</code> can be used to retrieve the dimensions of the container area that is relevant for the children.

== Visibility ==
The children inherit the visibility state of their parent. However, a child can still be invisible although his parent is visible by using <code>gwinHide()</code> on the child itself.

== Enable state ==
The children inherit the enable state of their parent. However, a child can still be disabled although his parent is enabled by using <code>gwinDisable()</code> on the child itself.

[[Category:GWIN]]

Label

2021-08-19T13:38:45Z

Tectu: /* API reference */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the <code>gwinSetText()</code> routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.io/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;
gwinWidgetClearInit(&wi);

// Apply the label parameters
wi.g.show = gTrue;
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", gTrue);
gfxSleepMilliseconds(1000);

gwinSetText(ghLabel1, "Aaaand some other text", gTrue);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Label

2021-08-19T13:28:45Z

Tectu: /* Example */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the <code>gwinSetText()</code> routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;
gwinWidgetClearInit(&wi);

// Apply the label parameters
wi.g.show = gTrue;
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", gTrue);
gfxSleepMilliseconds(1000);

gwinSetText(ghLabel1, "Aaaand some other text", gTrue);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Label

2021-08-19T13:28:29Z

Tectu: /* Example */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the <code>gwinSetText()</code> routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;
gwinWidgetClearInit(&wi);

// Apply the label parameters
wi.g.show = gTrue;
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", TRUE);
gfxSleepMilliseconds(1000);
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Types

2021-08-12T14:44:16Z

Tectu: /* Rendering */

µGFX allows to write applications (eg. GUIs) that are completely portable as the library itself is highly agnostic. To achieve this goal, users should rely on the types exposed by µGFX as much as possible to prevent problems when migration to different systems.

== Pre-Processor ==
For pre-processing related boolean operations (eg. <code>#if MY_FEATURE</code>) use <code>GFXON</code> and <code>GFXOFF</code> accordingly.

== Basic ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gBool</code> || A boolean value. Use <code>gTrue</code> and <code>gFalse</code> for assignments & comparisons respectively.
|-
| <code>gI8</code> || Signed integer at least 8 bits wide.
|-
| <code>gU8</code> || Unsigned integer at least 8 bits wide.
|-
| <code>gI16</code> || Signed integer at least 16 bits wide.
|-
| <code>gU16</code> || Unsigned integer at least 16 bits wide.
|-
| <code>gI32</code> || Signed integer at least 32 bits wide.
|-
| <code>gU32</code> || Unsigned integer at least 32 bits wide.
|-
| <code>gAny</code> || Any type that fits into a memory pointer by type casting.
|-
| <code>gPtr</code> || A pointer to something in memory.
|-
| <code>gPtrDiff</code> || The difference between two pointers.
|}

== System ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gTicks</code> || Type to represent a number of system ticks.
|-
| <code>gDelay</code> || Type to represent a a delay. The unit depends on the semantics for example number of ticks or milliseconds.
|-
| <code>gMemSize</code> || Type to represent a size of memory (in bytes).
|-
| <code>gFileSize</code> || Type to represent the size of a file (in bytes).
|}

== Rendering ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gCoord</code> || A (cartesian) coordinate in pixels.
|-
| <code>gPoint</code> || A point on the drawing canvas (x & y).
|-
| <code>gRect</code> || A rectangle (top left / bottom right).
|-
| <code>gSize</code> || A size of an area (width & height).
|-
| <code>gArea</code> || An area (top left / width & height).
|-
| <code>gColor</code> || A color.
|-
| <code>gFont</code> || A font. See [[Font_rendering|font rendering]].
|-
| <code>gImage</code> || An image. See [[Images|images]].
|}

Types

2021-08-12T14:42:30Z

Tectu: /* Basic */

µGFX allows to write applications (eg. GUIs) that are completely portable as the library itself is highly agnostic. To achieve this goal, users should rely on the types exposed by µGFX as much as possible to prevent problems when migration to different systems.

== Pre-Processor ==
For pre-processing related boolean operations (eg. <code>#if MY_FEATURE</code>) use <code>GFXON</code> and <code>GFXOFF</code> accordingly.

== Basic ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gBool</code> || A boolean value. Use <code>gTrue</code> and <code>gFalse</code> for assignments & comparisons respectively.
|-
| <code>gI8</code> || Signed integer at least 8 bits wide.
|-
| <code>gU8</code> || Unsigned integer at least 8 bits wide.
|-
| <code>gI16</code> || Signed integer at least 16 bits wide.
|-
| <code>gU16</code> || Unsigned integer at least 16 bits wide.
|-
| <code>gI32</code> || Signed integer at least 32 bits wide.
|-
| <code>gU32</code> || Unsigned integer at least 32 bits wide.
|-
| <code>gAny</code> || Any type that fits into a memory pointer by type casting.
|-
| <code>gPtr</code> || A pointer to something in memory.
|-
| <code>gPtrDiff</code> || The difference between two pointers.
|}

== System ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gTicks</code> || Type to represent a number of system ticks.
|-
| <code>gDelay</code> || Type to represent a a delay. The unit depends on the semantics for example number of ticks or milliseconds.
|-
| <code>gMemSize</code> || Type to represent a size of memory (in bytes).
|-
| <code>gFileSize</code> || Type to represent the size of a file (in bytes).
|}

== Rendering ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gCoord</code> || A type to express a coordinate in pixels.
|-
| <code>gColor</code> || A color.
|-
| <code>gFont</code> || A font. See [[Font_rendering|font rendering]].
|-
| <code>gImage</code> || An image. See [[Images|images]].
|}

Types

2021-08-11T09:28:16Z

Tectu: /* System */

µGFX allows to write applications (eg. GUIs) that are completely portable as the library itself is highly agnostic. To achieve this goal, users should rely on the types exposed by µGFX as much as possible to prevent problems when migration to different systems.

== Pre-Processor ==
For pre-processing related boolean operations (eg. <code>#if MY_FEATURE</code>) use <code>GFXON</code> and <code>GFXOFF</code> accordingly.

== Basic ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gBool</code> || A boolean value. Use <code>gTrue</code> and <code>gFalse</code> for assignments & comparisons respectively.
|-
| <code>gI8</code> || Signed integer at least 8 bits wide.
|-
| <code>gU8</code> || Unsigned integer at least 8 bits wide.
|-
| <code>gI16</code> || Signed integer at least 16 bits wide.
|-
| <code>gU16</code> || Unsigned integer at least 16 bits wide.
|-
| <code>gI32</code> || Signed integer at least 32 bits wide.
|-
| <code>gU32</code> || Unsigned integer at least 32 bits wide.
|}

== System ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gTicks</code> || Type to represent a number of system ticks.
|-
| <code>gDelay</code> || Type to represent a a delay. The unit depends on the semantics for example number of ticks or milliseconds.
|-
| <code>gMemSize</code> || Type to represent a size of memory (in bytes).
|-
| <code>gFileSize</code> || Type to represent the size of a file (in bytes).
|}

== Rendering ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gCoord</code> || A type to express a coordinate in pixels.
|-
| <code>gColor</code> || A color.
|-
| <code>gFont</code> || A font. See [[Font_rendering|font rendering]].
|-
| <code>gImage</code> || An image. See [[Images|images]].
|}

BareMetal

2021-08-11T09:27:25Z

Tectu: /* Example */

µGFX can run on any system without any underlying OS or RTOS. The '''RAW32''' port provides all the required implementations to run on a bare metal system. The only thing required to implement by the user are two small functions which are used to calculate delays. See [[#SysTick]].

The '''RAW32''' port also provides a multi-tasker that you can use in your own applications. The threads created are co-operative (non-preemptive) threads (you have to use <code>gfxSleepMilliseconds()</code> or <code>gfxYield()</code> to give another task a chance to run). See [[GOS#Threading|GOS]].

== Using RAW32 ==
To run µGFX on a bare-metal platform without any underlying operating system, the Raw32 port has to be enabled by setting <code>GFX_USE_OS_RAW32</code> to <code>TRUE</code> in the [[Configuration|configuration file]].

== Memory Management ==
µGFX can run either completely on static memory or on dynamic memory. While the first is very important for security and time critical applications it can be very tedious in generic applications. The RAW32 provides a memory manager to work with dynamic memory on any bare metal system. The following two configuration options are available:
* Use the µGFX built-in memory manager
* Use the C runtime library memory manager

Which one is used depends on the value of <code>GFX_OS_HEAP_SIZE</code> inside of the [[Configuration|configuration file]].

=== Built-in memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to a value greater than 0 then the built-in memory manager of µGFX is used. In this case the value of <code>GFX_OS_HEAP_SIZE</code> specifies the size of the memory pool which the built-in memory manager will use.

=== C runtime library memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to 0 then the memory manager of the C runtime library will be used. In that case <code>gfxAlloc()</code> and <code>gfxFree()</code> are just wrappers around <code>malloc()</code> and <code>free()</code>.

Note that many C library implementations of <code>malloc()</code> and <code>free()</code> have bugs that cause them to crash if the stack is changed (as it is for threading as required by µGFX). For this reason, if you are getting strange crashes it is advisable to use the built-in memory manager and to avoid using ''malloc()'' and <code>free()</code> in your own code (use <code>gfxAlloc()</code> and <code>gfxFree()</code> instead).

== SysTick ==
Some parts of the µGFX library require how much time passed by. For this access to the systems tick counter (SysTick) is required. To give µGFX the ability to calculate how much time passed the following to functions need to be implemented in the users application code:
<syntaxhighlight lang="c">
gTicks gfxSystemTicks(void);
gTicks gfxMillisecondsToTicks(delaytime_t ms);
</syntaxhighlight>
The first one, <code>gfxSystemTicks()</code>, needs to return the current value of the systick counter. The second one, <code>gfxMillisecondsToTicks()</code> needs to convert the provided value in milliseconds to systicks.

=== Example ===
The following is an example showing how to implement the two functions when using an STM32F4 microcontroller using the STM32Cube HAL. Note that in this case the systick was set up to be incremented once every millisecond. If your systick updates in a different interval you need to do the corresponding calculations in ''gfxMillisecondsToTicks()''.
<syntaxhighlight lang="c">
#include "stm32f4xx_hal.h"
#include "gfx.h"

gTicks gfxSystemTicks(void)
{
return HAL_GetTick();
}

gTicks gfxMillisecondsToTicks(gDelay ms)
{
return ms;
}
</syntaxhighlight>
'''''Note:''' It is important that <code>gfx.h</code> is included after <code>stm32f4xx_hal.h</code> to avoid naming conflicts when using the CubeHAL with µGFX.

Types

2021-08-06T18:21:16Z

Tectu: /* System */

µGFX allows to write applications (eg. GUIs) that are completely portable as the library itself is highly agnostic. To achieve this goal, users should rely on the types exposed by µGFX as much as possible to prevent problems when migration to different systems.

== Pre-Processor ==
For pre-processing related boolean operations (eg. <code>#if MY_FEATURE</code>) use <code>GFXON</code> and <code>GFXOFF</code> accordingly.

== Basic ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gBool</code> || A boolean value. Use <code>gTrue</code> and <code>gFalse</code> for assignments & comparisons respectively.
|-
| <code>gI8</code> || Signed integer at least 8 bits wide.
|-
| <code>gU8</code> || Unsigned integer at least 8 bits wide.
|-
| <code>gI16</code> || Signed integer at least 16 bits wide.
|-
| <code>gU16</code> || Unsigned integer at least 16 bits wide.
|-
| <code>gI32</code> || Signed integer at least 32 bits wide.
|-
| <code>gU32</code> || Unsigned integer at least 32 bits wide.
|}

== System ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gTicks</code> || Type to represent a number of system ticks.
|-
| <code>gMemSize</code> || Type to represent a size of memory (in bytes).
|-
| <code>gFileSize</code> || Type to represent the size of a file (in bytes).
|}

== Rendering ==
{| class="wikitable"
|-
! Type !! Description
|-
| <code>gCoord</code> || A type to express a coordinate in pixels.
|-
| <code>gColor</code> || A color.
|-
| <code>gFont</code> || A font. See [[Font_rendering|font rendering]].
|-
| <code>gImage</code> || An image. See [[Images|images]].
|}

Label

2021-08-06T18:20:28Z

Tectu:

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the <code>gwinSetText()</code> routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;

// Apply some default values for GWIN
wi.customDraw = 0;
wi.customParam = 0;
wi.customStyle = 0;
wi.g.show = gTrue;

// Apply the label parameters
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", TRUE);
gfxSleepMilliseconds(1000);
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Label

2021-08-06T18:20:12Z

Tectu: /* Border */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the ''gwinSetText()'' routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using <code>gwinLabelSetBorder()</code>.

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;

// Apply some default values for GWIN
wi.customDraw = 0;
wi.customParam = 0;
wi.customStyle = 0;
wi.g.show = gTrue;

// Apply the label parameters
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", TRUE);
gfxSleepMilliseconds(1000);
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Label

2021-08-06T18:10:53Z

Tectu: /* Example */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the ''gwinSetText()'' routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using gwinLabelSetBorder().

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;

// Apply some default values for GWIN
wi.customDraw = 0;
wi.customParam = 0;
wi.customStyle = 0;
wi.g.show = gTrue;

// Apply the label parameters
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", TRUE);
gfxSleepMilliseconds(1000);
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

Label

2021-08-06T18:10:33Z

Tectu: /* Attribute */

A label is a simple rectangular widget which takes no input. The label will automatically redraw it the text changed. If the label is smaller than the text it displays, the text gets clipped.
The text of the label can be set using the ''gwinSetText()'' routine.

== API reference ==
The API reference of the label widget can be found [http://api.ugfx.org/group___label.html here].

== Border ==
The default drawing routine of the labels allows to enable or disable a border. This can be done using gwinLabelSetBorder().

== Auto scale ==
Applying a size of 0 to the width or the height of the label will automatically set the corresponding dimension to fit the entire label text. Updating the label text will update the label dimensions each time.
Note: If the the board is enabled the auto-sizing feature of the label will certainly change the look of the application.

== Justification ==
By default the text of the label is left justified. The justification of the label text can be controlled through different built-in rendering functions.

The following rendering functions are available:
* gwinLabelDrawJustifiedLeft
* gwinLabelDrawJustifiedRight
* gwinLabelDrawJustifiedCenter

== Font size and color ==
As with any other widget the look-and-feel of the label widget can be fully customized. The font can be changed by using <code>gwinSetFont()</code> and the font color is controlled through the [[Widgets#Widget_Style|widget styles]]. The widget rendering can be fully customized by implementing a [[Creating_a_custom_rendering_routine|custom rendering routine]].

== Attribute ==
Often you want to display multiple text elements below each other where an element consists of a static text which will always be the same and some variable one. The static text is called the attribute and can be optionally set through <code>gwinLabelSetAttribute()</code> once you enabled this feature in your [[configuration|configuration file]]. The function does also take a tab parameter which allows to align multiple labels vertically as the following example shows:

<pre>
Current IP: 192.168.1.42
Netmask: 255.255.255.0
DHCP: On
</pre>
'''IMPORTANT:''' Use of the attribute capability is discouraged. This feature should be considered deprecated and will be removed in future releases. The proper way of doing this is using two separate labels.

== Example ==
The following example shows how to create a label.
<source lang="php">
#include "gfx.h"

static GHandle ghLabel1;

static void createWidgets(void)
{
GWidgetInit wi;

// Apply some default values for GWIN
wi.customDraw = 0;
wi.customParam = 0;
wi.customStyle = 0;
wi.g.show = TRUE;

// Apply the label parameters
wi.g.y = 10;
wi.g.x = 10;
wi.g.width = 100;
wi.g.height = 20;
wi.text = "Label 1";

// Create the actual label
ghLabel1 = gwinLabelCreate(NULL, &wi);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();

// Set the widget defaults
gwinSetDefaultFont(gdispOpenFont("UI2"));
gwinSetDefaultStyle(&WhiteWidgetStyle, FALSE);
gdispClear(White);

// Create the widget
createWidgets();

while(1) {
gwinSetText(ghLabel1, "This is some text", TRUE);
gfxSleepMilliseconds(1000);
gwinSetText(ghLabel1, "Aaaand some other text", TRUE);
gfxSleepMilliseconds(1000);
}

return 0;
}
</source>

[[Category:Widget]]

BareMetal

2021-08-06T17:46:58Z

Tectu: /* SysTick */

µGFX can run on any system without any underlying OS or RTOS. The '''RAW32''' port provides all the required implementations to run on a bare metal system. The only thing required to implement by the user are two small functions which are used to calculate delays. See [[#SysTick]].

The '''RAW32''' port also provides a multi-tasker that you can use in your own applications. The threads created are co-operative (non-preemptive) threads (you have to use <code>gfxSleepMilliseconds()</code> or <code>gfxYield()</code> to give another task a chance to run). See [[GOS#Threading|GOS]].

== Using RAW32 ==
To run µGFX on a bare-metal platform without any underlying operating system, the Raw32 port has to be enabled by setting <code>GFX_USE_OS_RAW32</code> to <code>TRUE</code> in the [[Configuration|configuration file]].

== Memory Management ==
µGFX can run either completely on static memory or on dynamic memory. While the first is very important for security and time critical applications it can be very tedious in generic applications. The RAW32 provides a memory manager to work with dynamic memory on any bare metal system. The following two configuration options are available:
* Use the µGFX built-in memory manager
* Use the C runtime library memory manager

Which one is used depends on the value of <code>GFX_OS_HEAP_SIZE</code> inside of the [[Configuration|configuration file]].

=== Built-in memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to a value greater than 0 then the built-in memory manager of µGFX is used. In this case the value of <code>GFX_OS_HEAP_SIZE</code> specifies the size of the memory pool which the built-in memory manager will use.

=== C runtime library memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to 0 then the memory manager of the C runtime library will be used. In that case <code>gfxAlloc()</code> and <code>gfxFree()</code> are just wrappers around <code>malloc()</code> and <code>free()</code>.

Note that many C library implementations of <code>malloc()</code> and <code>free()</code> have bugs that cause them to crash if the stack is changed (as it is for threading as required by µGFX). For this reason, if you are getting strange crashes it is advisable to use the built-in memory manager and to avoid using ''malloc()'' and <code>free()</code> in your own code (use <code>gfxAlloc()</code> and <code>gfxFree()</code> instead).

== SysTick ==
Some parts of the µGFX library require how much time passed by. For this access to the systems tick counter (SysTick) is required. To give µGFX the ability to calculate how much time passed the following to functions need to be implemented in the users application code:
<syntaxhighlight lang="c">
gTicks gfxSystemTicks(void);
gTicks gfxMillisecondsToTicks(delaytime_t ms);
</syntaxhighlight>
The first one, <code>gfxSystemTicks()</code>, needs to return the current value of the systick counter. The second one, <code>gfxMillisecondsToTicks()</code> needs to convert the provided value in milliseconds to systicks.

=== Example ===
The following is an example showing how to implement the two functions when using an STM32F4 microcontroller using the STM32Cube HAL. Note that in this case the systick was set up to be incremented once every millisecond. If your systick updates in a different interval you need to do the corresponding calculations in ''gfxMillisecondsToTicks()''.
<syntaxhighlight lang="c">
#include "stm32f4xx_hal.h"
#include "gfx.h"

gTicks gfxSystemTicks(void)
{
return HAL_GetTick();
}

gTicks gfxMillisecondsToTicks(delaytime_t ms)
{
return ms;
}
</syntaxhighlight>
'''''Note:''' It is important that <code>gfx.h</code> is included after <code>stm32f4xx_hal.h</code> to avoid naming conflicts when using the CubeHAL with µGFX.

BareMetal

2021-08-06T17:46:44Z

Tectu: /* SysTick */

µGFX can run on any system without any underlying OS or RTOS. The '''RAW32''' port provides all the required implementations to run on a bare metal system. The only thing required to implement by the user are two small functions which are used to calculate delays. See [[#SysTick]].

The '''RAW32''' port also provides a multi-tasker that you can use in your own applications. The threads created are co-operative (non-preemptive) threads (you have to use <code>gfxSleepMilliseconds()</code> or <code>gfxYield()</code> to give another task a chance to run). See [[GOS#Threading|GOS]].

== Using RAW32 ==
To run µGFX on a bare-metal platform without any underlying operating system, the Raw32 port has to be enabled by setting <code>GFX_USE_OS_RAW32</code> to <code>TRUE</code> in the [[Configuration|configuration file]].

== Memory Management ==
µGFX can run either completely on static memory or on dynamic memory. While the first is very important for security and time critical applications it can be very tedious in generic applications. The RAW32 provides a memory manager to work with dynamic memory on any bare metal system. The following two configuration options are available:
* Use the µGFX built-in memory manager
* Use the C runtime library memory manager

Which one is used depends on the value of <code>GFX_OS_HEAP_SIZE</code> inside of the [[Configuration|configuration file]].

=== Built-in memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to a value greater than 0 then the built-in memory manager of µGFX is used. In this case the value of <code>GFX_OS_HEAP_SIZE</code> specifies the size of the memory pool which the built-in memory manager will use.

=== C runtime library memory manager ===
When <code>GFX_OS_HEAP_SIZE</code> is set to 0 then the memory manager of the C runtime library will be used. In that case <code>gfxAlloc()</code> and <code>gfxFree()</code> are just wrappers around <code>malloc()</code> and <code>free()</code>.

Note that many C library implementations of <code>malloc()</code> and <code>free()</code> have bugs that cause them to crash if the stack is changed (as it is for threading as required by µGFX). For this reason, if you are getting strange crashes it is advisable to use the built-in memory manager and to avoid using ''malloc()'' and <code>free()</code> in your own code (use <code>gfxAlloc()</code> and <code>gfxFree()</code> instead).

== SysTick ==
Some parts of the µGFX library require how much time passed by. For this access to the systems tick counter (SysTick) is required. To give µGFX the ability to calculate how much time passed the following to functions need to be implemented in the users application code:
<syntaxhighlight lang="c">
systemticks_t gfxSystemTicks(void);
systemticks_t gfxMillisecondsToTicks(delaytime_t ms);
</syntaxhighlight>
The first one, <code>gfxSystemTicks()</code>, needs to return the current value of the systick counter. The second one, <code>gfxMillisecondsToTicks()</code> needs to convert the provided value in milliseconds to systicks.

=== Example ===
The following is an example showing how to implement the two functions when using an STM32F4 microcontroller using the STM32Cube HAL. Note that in this case the systick was set up to be incremented once every millisecond. If your systick updates in a different interval you need to do the corresponding calculations in ''gfxMillisecondsToTicks()''.
<syntaxhighlight lang="c">
#include "stm32f4xx_hal.h"
#include "gfx.h"

gTicks gfxSystemTicks(void)
{
return HAL_GetTick();
}

gTicks gfxMillisecondsToTicks(delaytime_t ms)
{
return ms;
}
</syntaxhighlight>
'''''Note:''' It is important that <code>gfx.h</code> is included after <code>stm32f4xx_hal.h</code> to avoid naming conflicts when using the CubeHAL with µGFX.

Types

2021-08-06T16:20:24Z

Tectu: /* Rendering */

GINPUT

2021-08-03T18:53:26Z

Tectu: /* API reference */

[[File:Ginput architecture.png|right|frame|GINPUT architecture]]
GINPUT is a powerful module which provides an easy way to interface different hardware peripherals such as touchscreens to the rest of the library. It provides everything which these peripherals need in order to operate properly such as calibration routines for the touchscreens.

== API reference ==
The API reference of the GINPUT module can be found [http://api.ugfx.io/group___g_i_n_p_u_t.html here].

== Touchscreen ==
A touchscreen can be interfaced very easily through the GINPUT module. It doesn't matter if it is a [http://en.wikipedia.org/wiki/Touchscreen#Resistive resistive], [http://en.wikipedia.org/wiki/Touchscreen#Capacitive capacitive] or any other touchscreen technology.

=== Board file ===
The GINPUT module requires a [[Board File|board file]] for each driver instance. A board file template and corresponding examples can be found under ''/drivers/ginput/touch/xxx/''.

=== Calibration ===
See [[Touchscreen Calibration]].

== Digital input ==
Also known as the ''Toggle'' driver. This driver can be used to interface common digital inputs (GPIOs). Mostly this driver is used to attach hardware buttons to a [[GWIN]] [[Widgets|widget]].

== Analog input ==
Also known as the ''Dial'' driver. This driver can be used to interface slow analog inputs. Mostly this driver is used to attach an analog peripheral such as a potentiometer or a sensor to a [[GWIN]] [[Widgets|widget]].
It can also be used on digital inputs that emulate a graduated ratio output such as a digital "click" wheel (rotary encoder).

== Keyboard ==
The keyboard driver allows to interface physical keyboards to a µGFX application.
Note that there's also a virtual keyboard widget that provides an on-screen keyboard with customizable layouts. See [[keyboard]].

[[Category:Module]]

Use uGFX repository as Git Submodule

2021-08-03T16:59:50Z

Tectu: /* The Problem */

The following article is a guide on how to add the uGFX repository as a submodule in an existing git repository. This guide was written by one of our users. Check out his tech [http://wolinlabs.com/blog/ blog].

== The Problem ==
I am writing firmware for an embedded system which uses the uGFX graphics library. I use Git for source control, and wanted to use a Git submodule to embed uGFX's repository into my source repository. Additionally, I wanted to be able to add some custom board and driver files to uGFX which are needed for my project, but are of no value to uGFX (and won't be pushed back to their repository).

Initially, I merely added a Git submodule to my local repository, made some changes and commited them to the submodule's master branch. This worked smashingly... until I tried to make a local clone of my repository, using the recursive switch:

<syntaxhighlight lang=text>
git clone --recursive myrepo myrepo_clone
</syntaxhighlight>

and got an error:
<syntaxhighlight lang=text>
fatal: reference is not a tree: ca025c09ca2b7b82ca086309eeb0696d674cb1d0
Unable to checkout 'ca025c09ca2b7b82ca086309eeb0696d674cb1d0' in submodule path 'ugfx_submodule'
</syntaxhighlight>

The problem is that my changes to the submodule's master branch are in my local repository, but when Git tries to clone the uGFX submodule, it gets source from the Bitbucket repository, which obviously does not have my changes.

What I'm doing seems to me like a pretty common situation/workflow. Surprisingly, when I searched, I did not find documentation/examples about how to set this up properly so that recursive clones would work, etc.

'''Here's my requirements in more detail:'''
# I need to get code from the uGFX Bitbucket repository's master branch, pull in changes from that branch when available, and integrate them into my product after testing.
# I need to be able to add code to the local uGFX tree and keep these additions under source control, but not push them back to the uGFX repository (my code is specific to my project and proprietary h/w, trust me, uGFX doesn't want it. =)
# Other users must be able to clone my repository. They don't have to be able to update the uGFX tree with the Bitbucket changes (I will handle when those changes are integrated) - although they could if they made minor modifications to their repository.

== My Solution ==
I came up with a workable solution, involving a version of
[https://felipec.wordpress.com/2014/05/11/git-triangular-workflows Triangular Workflow], using an upstream repository. I used a Raspberry Pi + Raspbian for the upstream repository because I had one on my network running DNS/DHCP and thought it would be cool, you could just as easily use a second local repository on your disk, Bitbucket/Github, etc.

'''Here are the specifics for my solution:'''
* Create an upstream Git server. I used a Raspberry Pi and put the repos on a USB stick, because it was convenient, starting with [http://www.instructables.com/id/GitPi-A-Private-Git-Server-on-Raspberry-Pi/?ALLSTEPS this article]. I added some enhancements from [https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server the Git book], like adding a git user and some authorized public ssh keys, etc...

* Make two bare repositories on the Git server, for this example call them myproduct.git and myproduct_ugfx.git

* Push my repository's master branch to the myproduct.git repository. I didn't write this part down, but I believe I just added a remote for origin and pushed the master branch:
<syntaxhighlight lang=text>
git remote add origin git@pi-b:/mnt/git_repos/myproduct.git
git push
</syntaxhighlight>

* From the top directory of my repository, I add the uGFX submodule
<syntaxhighlight lang=text>
git submodule add https://git.ugfx.io/ugfx/ugfx.git ugfx_submodule
</syntaxhighlight>

* cd into the submodule's directory, and change the name of the submodule's master branch to updates
<syntaxhighlight lang=text>
git branch -m master updates
</syntaxhighlight>

* Rename the remote origin to bitbucket, which the updates (formerly master) branch tracks
<source lang="text">
git remote rename origin bitbucket
</source>

* At this point, run <span class="code">git branch -vv</span> as a check, and it should show one branch named updates which tracks remote bitbucket's master branch

* The submodule no longer has a master branch or origin. I wanted the submodule master branch to track my Pi Git server's uGFX repository, so I add a remote for origin, create a master branch, and push the master branch to the server (telling it to track that branch):
<syntaxhighlight lang=text>
git remote add origin git@pi-b:/mnt/git_repos/myproduct_ugfx.git
git checkout -b master
git push -u origin master
</syntaxhighlight>

* Now that I've pushed the submodule to my server, I change the uGFX submodule to point to my server, so when people clone the whole repo with --recursive, they get my master branch with my additions
<syntaxhighlight lang=text>
git config remote.origin.url git@pi-b:/mnt/git_repos/myproduct_ugfx.git
</syntaxhighlight>
At this point, I wanted to add a few files to the uGFX tree. I add them to the master branch, commit, and push (which goes to the Pi repository.) Remember to also go up a direcotry, outside of the submodule, run <span class="code">git submodule sync</span> (not sure if that's necessary), and then commit+push those changes to the main/outer repo.

Now, when there are changes on the Bitbucket repository, in the submodule I can pull them into my local updates branch, then when I've tested them and want to integrate them into the my product, I can merge updates with master, then commit and push master to the Pi repository.

Local recursive clones (like the one above that caused the initial error) will now work. If someone wants to clone the myproduct repository from the Pi, provided they have access to the Pi (see Git book for adding an ssh key) they can do it with
<syntaxhighlight lang=text>
git clone --recursive git@pi-b:/mnt/git_repos/myproduct.git
</syntaxhighlight>

== Links ==
* [https://felipec.wordpress.com/2014/05/11/git-triangular-workflows Triangular workflow example]
* [http://wolinlabs.com/blog Ross Wolin's Tech Blog]

GTRANS

2021-08-03T15:46:20Z

Tectu:

The GTRANS module allows to manage language translations. The language of an application can be changed dynamically during runtime using the GTRANS module.

== API reference ==
The API reference of the GTRANS module can be found [http://api.ugfx.org/group___g_t_r_a_n_s.html here].

== Intended usage ==
Each translation is specified by a <code>transTable</code> struct which is essentially a table of strings:
<source lang="c">
typedef struct transTable {
unsigned numEntries; // The number of strings that this table contains
const char** strings; // The translated strings
} transTable;
</source>

A translatable application needs to have a base language. All translations happen relative to that base language. The base language is specified using <code>gtransSetBaseLanguage()</code>. The current language of the application is set using <code>gtransSetLanguage()</code>.
The actual translations take place by calling <code>gtransString()</code>. A string contained in the translation table of the base language is passed to <code>gtransString()</code>. The function returns the corresponding string of the current language that was set using <code>gtransSetLanguage()</code> or the passed string if none was found.

A wrapper macro named <code>gt()</code> around <code>gtransString()</code> is available to make writing and reading translatable applications easier:
<source lang="c">
#define gt(str) gtransString(str)
</source>

== Optimization ==
Calling <code>gt()</code> (or <code>gtransString()</code> directly) uses the <code>strcmp()</code> function of the standard C library to compare strings. This operation can take a lot of time. For performance critical applications or low-resource systems the application translation speed can be optimized by using <code>gtransIndex()</code> (instead of <code>gtransString()</code>) which directly takes the index of the string in the translation table. However, this introduces the limitation that each string in each of the translation tables need to be at the same position (the same index). Using <code>gtransString()</code> allows to have translation tables of unequal sizes due to the nature of the translation being based on string comparison rather than index accessing of the table.

== Example ==
Complete examples can be found under ''/demos/modules/gtrans/'' in the uGFX library directory.

=== Basic Example ===
The following code is a very simple usage example showing how the GTRANS module is used. This is a very minimalistic example with no dependencies other than the [[GDISP]] module to interface a display.
<source lang="c">
#include <stdio.h>
#include "gfx.h"

#define COLOR_BACKGROUND Silver
#define COLOR_TEXT Black

font_t font;

// English Translation
static const char* EnglishStrings[] = {
"Welcome",
"The temperature is %d degrees",
"Goodbye",
"This is a translated uGFX application"
};
static const transTable EnglishTranslation = { sizeof(EnglishStrings)/sizeof(EnglishStrings[0]), EnglishStrings };

// German translation
static const char* GermanStrings[] = {
"Herzlich Willkommen",
"Die Temperatur beträgt %d Grad",
"Auf Wiedersehen",
"Das ist eine übersetzte uGFX Anwendung"
};
static const transTable GermanTranslation = { sizeof(GermanStrings)/sizeof(GermanStrings[0]), GermanStrings };

// French translation
static const char* FrenchStrings[] = {
"Bienvenue",
"La température est de %d degrés",
"Au revoir",
"Ceci est une application traduit uGFX"
};
static const transTable FrenchTranslation = { sizeof(FrenchStrings)/sizeof(FrenchStrings[0]), FrenchStrings };

void updateText()
{
coord_t width = 400;
coord_t height = 30;

// Translate some basic strings
gdispFillStringBox(20, 20, width, height, gt("Welcome"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 60, width, height, gt("This is a translated uGFX application"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
gdispFillStringBox(20, 100, width, height, gt("Goodbye"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);

// A more complex example using string formatting
char buffer[128];
sprintf(buffer, gt("The temperature is %d degrees"), 18);
gdispFillStringBox(20, 140, width, height, buffer, font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
}

int main(void)
{
// Initialize the uGFX library
gfxInit();
gdispClear(COLOR_BACKGROUND);

// Take the first font we find
font = gdispOpenFont("*");

// Set the base language of the application
gtransSetBaseLanguage(&EnglishTranslation);

// Loop through the languages
while (TRUE) {
// English
gtransSetLanguage(&EnglishTranslation);
updateText();
gfxSleepMilliseconds(3000);

// German
gtransSetLanguage(&GermanTranslation);
updateText();
gfxSleepMilliseconds(3000);

// French
gtransSetLanguage(&FrenchTranslation);
updateText();
gfxSleepMilliseconds(3000);
}

return 0;
}
</source>

=== Example with widgets ===
The GTRANS module can also be used to translate widget texts. GWIN doesn't do anything with the text set by <code>gwinSetText()</code> except displaying it. Therefore, the <code>gtransString()</code> (or <code>gt()</code> respectively) function can be used directly inside of the <code>gwinSetText()</code> call. When the current language changes, the <code>gwinSetText()</code> function must be re-called manually. There's currently no way to tell GWIN to automatically use the string for the currently active language as this would add a lot of overhead to both the GWIN core module as well as to each widget rendering function in order to support parameter substitution.

Example:
<source lang="c">
gwinSetText(ghMyButton, gt("The temperature is %d degrees"));
</source>

Types

2021-08-02T15:49:48Z

Tectu:

Types

2021-08-02T15:45:32Z

Tectu: /* Basic */

Types

2021-08-02T15:39:53Z

Tectu: /* Basic */

Types

2021-08-02T15:39:44Z

Tectu: /* Basic */

Types

2021-08-02T15:39:03Z

Tectu: Created page with "µGFX allows to write applications (eg. GUIs) that are completely portable as the library itself is highly agnostic. To achieve this goal, users should rely on the types expos..."

Images

2021-08-02T15:38:56Z

Tectu: /* Color Palettes */

The GDISP module comes with a built-in image decoder. The decoder allows it to open an image of various formats and display it. As the [[GFILE]] module is being used internally, the image can be stored on different sources such as the internal flash or external memory like an SD card.

Before you continue to read this documentation, please consider using the [[ImageBox]] widget as it is much simpler to use.

== API reference ==
The API reference for the image support can be found [http://api.ugfx.org/group___image.html here].

== RAM Usage ==
Image decoders use RAM to decode and display images. Whilst the image handlers have been written from scratch to use as little RAM as possible, for small microcontrollers with limited RAM the image formats used should be choosen carefully. The image handlers do not allocate RAM to store the full decompressed bitmap as do most other image decoders, instead the image is decoded again if it needs to be displayed. The only RAM used therefore is:
*Some RAM to hold information on the image itself - typically 200 to 300 bytes. This RAM is maintained while the image is opened. It may vary slightly for some images with some image formats (due to holding palettes etc).
*RAM allocated during the decoding process and freed once the decoding is done. The GIF image format requires around 12K of RAM to decode an image. BMP and NATIVE images do not require any extra RAM for decoding.
*If you decide to cache the image then RAM is required for the full decoded image. This should not be considered for low memory micros. For example, caching a 320x240 image on a 2 bytes per pixel display will take 150K of RAM (plus the normal decoding RAM).
*Stack space. You may need to increase your available stack space if you get exceptions when trying to decode images. Some image formats require a few hundred bytes of stack space to decode an image.

Our image decoders have been written from the ground up to keep the image decoders as lean and mean as possible. Our current decoders use significantly less than other decoding libraries available.

=== Accounting ===
It is possible to examine the exact amount of memory that is used by an image. Setting <code>GDISP_NEED_IMAGE_ACCOUNTING</code> to <code>TRUE</code> in the [[Configuration|configuration file]] will add the two members ''memused'' and ''maxmemused'' to the image struct (the ''gdispImage'' data type). The first one gives information about the '''currently''' used memory, the second one keeps track of the '''maximum''' amount of memory that was ever used by this image.

== Caching ==
It's possible to cache a decoded image into your ram using the '''gdispImageCache()''' call. When you don't cache an image, it will always be re-read again from flash, decoded and then displayed. When you cache your image, you just have to load it from RAM and display it. This is way faster, especially for PNG, JPG and GIF formats since these require quite complex decoding algorithms. However, caching an image requires A LOT of RAM. Especially when you're using multiframe GIF images or large sized images.

If you cache your image you still have to open() the image before it can be displayed. When close() is called, it will free all memory used by the decoder including any cached images.

Calling the caching routine doesn't guarantee that the image will be cached. For example, if not enough RAM is available the image won't be cached. Since caching is fully optional, the image will still be drawn when you call the drawing routine. It will simply be decoded again.

== A word about close() ==
The <code>gdispImageClose()</code> function performs a complete cleanup. Calling this routine will not only clean up all memory used by the decoder and the caching, it will also close the file system. Therefore, this should really just be called when you're done with the image and you won't re-draw it for a longer time period.

== Color Palettes ==
Certain image formats support color palettes. The following functions are available to access and modify the color palettes:
<source lang="c">
uint16_t gdispImageGetPaletteSize(gdispImage *img);
gColor gdispImageGetPalette(gdispImage *img, uint16_t index);
gBool gdispImageAdjustPalette(gdispImage *img, uint16_t index, color_t newColor);
</source>
Please check the [[Images#API_reference|API reference]] to learn more about these functions.

== Image formats ==
µGFX does currently come with the following image decoders:

{| class="wikitable"
! scope="col"|Format
! scope="col"|Description
|-
|BMP
|Including BMP1, BMP4, BMP4_RLE, BMP8, BMP8_RLE, BMP16, BMP24, BMP32
|-
|GIF
|Including transparency and multi-frame support (animations)
|-
|PNG
|Including transparency and alpha support
|-
|NATIVE
|Uses the display drivers native format. See below.
|-
|}
We plan to add decoders for other formats such as JPG in the future.

=== NATIVE ===
The native image format consists of an 8 byte header followed by an array of bytes in the format your display controller accepts. Whilst hardware dependant, this format displays extremely quickly and with the least amount of RAM usage. It is ideal for images stored in FLASH. The header is:

<pre>{ 'N', 'I', width.hi, width.lo, height.hi, height.lo, format.hi, format.lo }</pre>
Where the format word is equal to <code>GDISP_PIXELFORMAT</code> which is defined in the <code>conf.h</code> file of your GDISP driver.

=== BMP ===
The BMP format is very performance friendly as it is a bitmap of pixels. There's only little to no decoding required to display a BMP image. Therefore, it is often used for UI designs.
The advantage over the [[#NATIVE|Native]] format is it's portability.

=== GIF ===
The GIF decoder can handle animated images and transparency out of the box.

==== Animated images ====
The GIF decoder simply advances the image pointer by one frame on each <code>gdispImageDraw()</code> call. Therefore, displaying an animated image is simply a matter of calling <code>gdispDrawImage()</code> in a loop. However, the user manually has to impliment the delay before loading the next image. This can be done like this:
<syntaxhighlight lang=c>
while (1) {
gdispImageDraw(&myImage, 0, 0, myImage.width, myImage.height, 0, 0)
delay = gdispImageNext(&myImage);

gfxSleepMilliseconds(delay);
}
</syntaxhighlight>
'''''Note:''' This is just an illustrative example. A real world program would have to check for error return codes etc. A full example can be found under ''/demos/modules/gdisp/images_animated''.

=== PNG ===
The PNG image decoder can handle all PNG features including transparency except for interlacing. All the various PNG sub-formats and features can be turned on or off in the [[Configuration|configuration file]] in order to decrease code size. By default all supported formats are enabled whenever PNG images are enabled.

==== Alpha & Transparency ====
The decoder supports both transparency and alpha. When a background color is specified in the PNG file alpha and transparency are handled by color blending with the background color. If a background color has not been specified by the PNG file then any pixel alpha below <code>GDISP_NEED_PNG_ALPHACLIFF</code> is just not displayed.

==== RAM usage ====
Compared to other formats such as BMP or GIF, PNG images require vast amounts of RAM to be decoded. Therefore, using PNG images is usually discouraged on very small embedded systems where RAM is a scarce resource.

PNG images have the following RAM requirements:
* 64 bytes (or less) for the <code>gdispImage</code> structure and internal PNG image information
* Around 34k bytes + 2 image scan lines used only during image decoding
This means that even super huge PNG images of say 3072x2304 can be fully decoded and displayed using around 40k bytes of RAM.

Unfortunately there is nothing that can be done to further reduce the amount of RAM usage. There are a couple of big memory hogs in PNG decoding...
* A sliding window of 32K is needed for the inflate decompression. While some images may use less, because the inflate window size is non-deterministic while decoding the maximum sliding window has to be allocated up front.
* 2 scan lines of uncompressed data are required to perform PNG filtering. For a 16-bit RGB with alpha that amounts to (1 + 8 bytes per pixel * width) * 2. Obviously for an 8-bit palette based PNG it is (1 + 1 * width) * 2, and for a 1-bit palette PNG it is image (1 + width / 8) * 2
Unfortunately these overheads cannot be reduced as they are required by the PNG specification.

Most PNG decoders (and decoder libraries) require:
# A full copy of the input file in memory
# The PNG header information and palette storage overheads
# The 32K sliding window and scanline buffers (although this is often integrated into #4 below)
# A full copy of the decompressed byte stream in memory
# A full copy of the output image in PNG color format after scanline filtering
# A full copy of the output image in output device color format.
Obviously this is a huge amount of RAM, well beyond the capabilities of most embedded devices. We therefore wrote our decoder from scratch to remove those overheads where-ever possible. For our decoder we only need #2 and #3 and furthermore #3 is only needed while the decoding is actually happening.

==== GIF vs. PNG ====
We have not performed any speed tests comparing GIF's with PNG's. Both use similar technology to decode the image but the differences will determine the relative speeds. They use different compression algorithm's. GIF is also 8-bit palette pixel format only whereas PNG supports a multitude of internal pixel formats. Both support transparency but only PNG supports alpha blending. With GIF we support interlacing but not with PNG due to complexity. GIF supports animation, PNG does not. In conclusion, the differences in decoding speed between PNG and GIF is going to depend very much on the actual image.

There is however one exception to the above, when a GIF image is cached to RAM using <code>gdispImageCache()</code> we cache the decompressed byte stream. For PNG we cache the compressed byte stream. In this situation it is likely that cached GIF images will display faster than cached PNG images but will take more RAM to cache.

== Examples ==
The following code pieces shows how to use the GDISP image decoder correctly. Please refer to the [[GFILE]] article to learn how to use the different file systems.
<syntaxhighlight lang=c>
#include "gfx.h"

/**
* The image file must be stored on a GFILE file-system.
* Use either GFILE_NEED_NATIVEFS or GFILE_NEED_ROMFS (or both).
*
* The ROMFS uses the file "romfs_files.h" to describe the set of files in the ROMFS.
*/

static gdispImage myImage;

int main(void) {
gCoord swidth, sheight;

// Initialize uGFX and the underlying system
gfxInit();

// Get the display dimensions
swidth = gdispGetWidth();
sheight = gdispGetHeight();

// Set up IO for our image
gdispImageOpenFile(&myImage, "myImage.bmp");
gdispImageDraw(&myImage, 0, 0, swidth, sheight, 0, 0);
gdispImageClose(&myImage);

while(1) {
gfxSleepMilliseconds(1000);
}

return 0;
}
</syntaxhighlight>

== Troubleshooting ==
When troubleshooting, please check the return value of '''each''' function in order to track down the problem.

=== No image is shown ===
It is possible that the program compiles fine and that it runs without any crashes, but no image is being displayed. This behavior can be caused by a variety of different issues:
* The corresponding decoder has not been enabled in the [[Configuration|configuration file]]
* The image could not be opened
* The image decoder could not allocate enough memory
* When loading an image from a file, it's possible that the maximum number of file handles has been reached and opening the file fails. In that case, increase <code>GFILE_MAX_GFILES</code> in the [[Configuration|configuration file]] or close an already opened file that is no longer needed.

[[Category:GDISP]]

Images

2021-08-02T15:38:35Z

Tectu: /* Examples */

The GDISP module comes with a built-in image decoder. The decoder allows it to open an image of various formats and display it. As the [[GFILE]] module is being used internally, the image can be stored on different sources such as the internal flash or external memory like an SD card.

Before you continue to read this documentation, please consider using the [[ImageBox]] widget as it is much simpler to use.

== API reference ==
The API reference for the image support can be found [http://api.ugfx.org/group___image.html here].

== RAM Usage ==
Image decoders use RAM to decode and display images. Whilst the image handlers have been written from scratch to use as little RAM as possible, for small microcontrollers with limited RAM the image formats used should be choosen carefully. The image handlers do not allocate RAM to store the full decompressed bitmap as do most other image decoders, instead the image is decoded again if it needs to be displayed. The only RAM used therefore is:
*Some RAM to hold information on the image itself - typically 200 to 300 bytes. This RAM is maintained while the image is opened. It may vary slightly for some images with some image formats (due to holding palettes etc).
*RAM allocated during the decoding process and freed once the decoding is done. The GIF image format requires around 12K of RAM to decode an image. BMP and NATIVE images do not require any extra RAM for decoding.
*If you decide to cache the image then RAM is required for the full decoded image. This should not be considered for low memory micros. For example, caching a 320x240 image on a 2 bytes per pixel display will take 150K of RAM (plus the normal decoding RAM).
*Stack space. You may need to increase your available stack space if you get exceptions when trying to decode images. Some image formats require a few hundred bytes of stack space to decode an image.

Our image decoders have been written from the ground up to keep the image decoders as lean and mean as possible. Our current decoders use significantly less than other decoding libraries available.

=== Accounting ===
It is possible to examine the exact amount of memory that is used by an image. Setting <code>GDISP_NEED_IMAGE_ACCOUNTING</code> to <code>TRUE</code> in the [[Configuration|configuration file]] will add the two members ''memused'' and ''maxmemused'' to the image struct (the ''gdispImage'' data type). The first one gives information about the '''currently''' used memory, the second one keeps track of the '''maximum''' amount of memory that was ever used by this image.

== Caching ==
It's possible to cache a decoded image into your ram using the '''gdispImageCache()''' call. When you don't cache an image, it will always be re-read again from flash, decoded and then displayed. When you cache your image, you just have to load it from RAM and display it. This is way faster, especially for PNG, JPG and GIF formats since these require quite complex decoding algorithms. However, caching an image requires A LOT of RAM. Especially when you're using multiframe GIF images or large sized images.

If you cache your image you still have to open() the image before it can be displayed. When close() is called, it will free all memory used by the decoder including any cached images.

Calling the caching routine doesn't guarantee that the image will be cached. For example, if not enough RAM is available the image won't be cached. Since caching is fully optional, the image will still be drawn when you call the drawing routine. It will simply be decoded again.

== A word about close() ==
The <code>gdispImageClose()</code> function performs a complete cleanup. Calling this routine will not only clean up all memory used by the decoder and the caching, it will also close the file system. Therefore, this should really just be called when you're done with the image and you won't re-draw it for a longer time period.

== Color Palettes ==
Certain image formats support color palettes. The following functions are available to access and modify the color palettes:
<source lang="c">
uint16_t gdispImageGetPaletteSize(gdispImage *img);
color_t gdispImageGetPalette(gdispImage *img, uint16_t index);
bool_t gdispImageAdjustPalette(gdispImage *img, uint16_t index, color_t newColor);
</source>
Please check the [[Images#API_reference|API reference]] to learn more about these functions.

== Image formats ==
µGFX does currently come with the following image decoders:

{| class="wikitable"
! scope="col"|Format
! scope="col"|Description
|-
|BMP
|Including BMP1, BMP4, BMP4_RLE, BMP8, BMP8_RLE, BMP16, BMP24, BMP32
|-
|GIF
|Including transparency and multi-frame support (animations)
|-
|PNG
|Including transparency and alpha support
|-
|NATIVE
|Uses the display drivers native format. See below.
|-
|}
We plan to add decoders for other formats such as JPG in the future.

=== NATIVE ===
The native image format consists of an 8 byte header followed by an array of bytes in the format your display controller accepts. Whilst hardware dependant, this format displays extremely quickly and with the least amount of RAM usage. It is ideal for images stored in FLASH. The header is:

<pre>{ 'N', 'I', width.hi, width.lo, height.hi, height.lo, format.hi, format.lo }</pre>
Where the format word is equal to <code>GDISP_PIXELFORMAT</code> which is defined in the <code>conf.h</code> file of your GDISP driver.

=== BMP ===
The BMP format is very performance friendly as it is a bitmap of pixels. There's only little to no decoding required to display a BMP image. Therefore, it is often used for UI designs.
The advantage over the [[#NATIVE|Native]] format is it's portability.

=== GIF ===
The GIF decoder can handle animated images and transparency out of the box.

==== Animated images ====
The GIF decoder simply advances the image pointer by one frame on each <code>gdispImageDraw()</code> call. Therefore, displaying an animated image is simply a matter of calling <code>gdispDrawImage()</code> in a loop. However, the user manually has to impliment the delay before loading the next image. This can be done like this:
<syntaxhighlight lang=c>
while (1) {
gdispImageDraw(&myImage, 0, 0, myImage.width, myImage.height, 0, 0)
delay = gdispImageNext(&myImage);

gfxSleepMilliseconds(delay);
}
</syntaxhighlight>
'''''Note:''' This is just an illustrative example. A real world program would have to check for error return codes etc. A full example can be found under ''/demos/modules/gdisp/images_animated''.

=== PNG ===
The PNG image decoder can handle all PNG features including transparency except for interlacing. All the various PNG sub-formats and features can be turned on or off in the [[Configuration|configuration file]] in order to decrease code size. By default all supported formats are enabled whenever PNG images are enabled.

==== Alpha & Transparency ====
The decoder supports both transparency and alpha. When a background color is specified in the PNG file alpha and transparency are handled by color blending with the background color. If a background color has not been specified by the PNG file then any pixel alpha below <code>GDISP_NEED_PNG_ALPHACLIFF</code> is just not displayed.

==== RAM usage ====
Compared to other formats such as BMP or GIF, PNG images require vast amounts of RAM to be decoded. Therefore, using PNG images is usually discouraged on very small embedded systems where RAM is a scarce resource.

PNG images have the following RAM requirements:
* 64 bytes (or less) for the <code>gdispImage</code> structure and internal PNG image information
* Around 34k bytes + 2 image scan lines used only during image decoding
This means that even super huge PNG images of say 3072x2304 can be fully decoded and displayed using around 40k bytes of RAM.

Unfortunately there is nothing that can be done to further reduce the amount of RAM usage. There are a couple of big memory hogs in PNG decoding...
* A sliding window of 32K is needed for the inflate decompression. While some images may use less, because the inflate window size is non-deterministic while decoding the maximum sliding window has to be allocated up front.
* 2 scan lines of uncompressed data are required to perform PNG filtering. For a 16-bit RGB with alpha that amounts to (1 + 8 bytes per pixel * width) * 2. Obviously for an 8-bit palette based PNG it is (1 + 1 * width) * 2, and for a 1-bit palette PNG it is image (1 + width / 8) * 2
Unfortunately these overheads cannot be reduced as they are required by the PNG specification.

Most PNG decoders (and decoder libraries) require:
# A full copy of the input file in memory
# The PNG header information and palette storage overheads
# The 32K sliding window and scanline buffers (although this is often integrated into #4 below)
# A full copy of the decompressed byte stream in memory
# A full copy of the output image in PNG color format after scanline filtering
# A full copy of the output image in output device color format.
Obviously this is a huge amount of RAM, well beyond the capabilities of most embedded devices. We therefore wrote our decoder from scratch to remove those overheads where-ever possible. For our decoder we only need #2 and #3 and furthermore #3 is only needed while the decoding is actually happening.

==== GIF vs. PNG ====
We have not performed any speed tests comparing GIF's with PNG's. Both use similar technology to decode the image but the differences will determine the relative speeds. They use different compression algorithm's. GIF is also 8-bit palette pixel format only whereas PNG supports a multitude of internal pixel formats. Both support transparency but only PNG supports alpha blending. With GIF we support interlacing but not with PNG due to complexity. GIF supports animation, PNG does not. In conclusion, the differences in decoding speed between PNG and GIF is going to depend very much on the actual image.

There is however one exception to the above, when a GIF image is cached to RAM using <code>gdispImageCache()</code> we cache the decompressed byte stream. For PNG we cache the compressed byte stream. In this situation it is likely that cached GIF images will display faster than cached PNG images but will take more RAM to cache.

== Examples ==
The following code pieces shows how to use the GDISP image decoder correctly. Please refer to the [[GFILE]] article to learn how to use the different file systems.
<syntaxhighlight lang=c>
#include "gfx.h"

/**
* The image file must be stored on a GFILE file-system.
* Use either GFILE_NEED_NATIVEFS or GFILE_NEED_ROMFS (or both).
*
* The ROMFS uses the file "romfs_files.h" to describe the set of files in the ROMFS.
*/

static gdispImage myImage;

int main(void) {
gCoord swidth, sheight;

// Initialize uGFX and the underlying system
gfxInit();

// Get the display dimensions
swidth = gdispGetWidth();
sheight = gdispGetHeight();

// Set up IO for our image
gdispImageOpenFile(&myImage, "myImage.bmp");
gdispImageDraw(&myImage, 0, 0, swidth, sheight, 0, 0);
gdispImageClose(&myImage);

while(1) {
gfxSleepMilliseconds(1000);
}

return 0;
}
</syntaxhighlight>

== Troubleshooting ==
When troubleshooting, please check the return value of '''each''' function in order to track down the problem.

=== No image is shown ===
It is possible that the program compiles fine and that it runs without any crashes, but no image is being displayed. This behavior can be caused by a variety of different issues:
* The corresponding decoder has not been enabled in the [[Configuration|configuration file]]
* The image could not be opened
* The image decoder could not allocate enough memory
* When loading an image from a file, it's possible that the maximum number of file handles has been reached and opening the file fails. In that case, increase <code>GFILE_MAX_GFILES</code> in the [[Configuration|configuration file]] or close an already opened file that is no longer needed.

[[Category:GDISP]]

Main Page

2021-08-02T15:27:44Z

Tectu:

<div class="div-header">Welcome to the µGFX wiki!</div>
<div class="div-block">This is the official documentation of the [http://ugfx.io µGFX] library. Please note that this is just the documentation, the official project website can be found at [http://ugfx.io ugfx.io]. The API reference can be found at [http://api.ugfx.io api.ugfx.io].

If you're new to µGFX, begin by reading [[Getting Started]].
</div>
<div style="width: 50%; float: left;">
<div class="div-header" style="margin-right: 5px;">General</div>
<div class="div-block" style="margin-right: 5px;">
* [[Getting Started]]
* [[Configuration]]
* [[Architecture]]
* [[Board File]]
* [[Types]]
* [[API Reference]]
* [[Changes from V2.x to V3.0]]
</div>
<div class="div-header" style="margin-right: 5px;">Using µGFX on...</div>
<div class="div-block" style="margin-right: 5px;">
* [[BareMetal]]
* [[CMSIS RTOS]]
* [[ChibiOS/RT]]
* [[FreeRTOS]]
* [[RawOS]]
* [[eCos]]
* [[Zephyr]]
* [[Using_Keil_µVision_5_MDK-ARM|Keil RTX]]
* [[Teensy]]
* [[Raspberry Pi]]
* [[Linux]]
* [[Win32]]
* [[Mac OS X]]
</div>
<div class="div-header" style="margin-right: 5px;">Using IDEs</div>
<div class="div-block" style="margin-right: 5px;">
* [[Using Keil µVision 5 MDK-ARM|Keil µVision 5 MDK-ARM]]
* [[Using IAR embedded workbench|IAR embedded workbench]]
* [[Using Eclipse|Eclipse]]
* [[Using PSoC Creator|PSoC Creator]]
* [[Using ChibiStudio|ChibiStudio]]
</div>
<div class="div-header" style="margin-right: 5px;">Developer Guides</div>
<div class="div-block" style="margin-right: 5px;">
* [[Your First Compile - Windows]]
* [[Creating a custom rendering routine]]
* [[Creating a widget]]
* [[Use_uGFX_repository_as_Git_Submodule|Advanced git guide]]
</div>
<div class="div-header" style="margin-right: 5px;">µGFX Design Choices</div>
<div class="div-block" style="margin-right: 5px;">
* [[Display Driver Model]]
</div>
</div>
<div style="width: 50%; float: right;">
<div class="div-header" style="margin-left: 5px;">Modules</div>
<div class="div-block" style="margin-left: 5px;">
* [[GWIN]]
** [[Windows]]
*** [[Console]]
*** [[Graph]]
** [[Widgets]]
*** [[Label]]
*** [[PushButton]]
*** [[RadioButton]]
*** [[CheckBox]]
*** [[List]]
*** [[Slider]]
*** [[Progressbar]]
*** [[ImageBox]]
*** [[TextEdit]]
*** [[Keyboard]]
** [[Containers]]
*** [[Container]]
*** [[Tabset]]
*** [[Frame]]
* [[GAUDIO]]
* [[GFILE]]
* [[GOS]]
* [[GDISP]]
** [[Drawing]]
** [[Font rendering]]
** [[Images]]
* [[GINPUT]]
* [[GTRANS]]
* [[GEVENT]]
* [[GTIMER]]
* [[GQUEUE]]
</div>
</div>

__NOTOC__

Font rendering

2021-07-30T13:47:40Z

Tectu: /* Anti-Aliasing */

== Features ==
The µGFX font rendering engine provides the following features:

=== Word-Wrapping ===
The word wrapping feature can be enabled by setting <code>GDISP_NEED_TEXT_WORDWRAP</code> to <code>TRUE</code>.

Word wrapping only has an effect when using <code>gdispDrawStringBox()</code> or <code>gdispFillStringBox()</code>. When the word wrapping feature is not enabled the string will simply be cut-off at the border of the specified box.

=== Unicode ===
[http://en.wikipedia.org/wiki/Unicode Unicode] support can be enabled by setting <code>GDISP_NEED_TEXT_UTF8</code> to <code>TRUE</code>.

Unicode support allows to display fonts of many different languages such as English, French, German, Russian (Cyrillic), Chinese, Japanese and so on.
For information about cyrillic font support, see [[Cyrillic]].

=== Anti-Aliasing ===
To use the anti-aliasing font feature, the following three conditions have to be fulfilled:
# Using an anti-aliased font
# <code>GDISP_NEED_ANTIALIAS</code> needs to be set to <code>TRUE</code>
# Either have <code>GDISP_NEED_PIXELREAD</code> set to <code>TRUE</code> or using one of the [[Drawing#Text|text drawing functions]] that have a background color parameter.

Note that you can use normal (non anti-aliased) fonts along with anti-aliased ones without any problems.

=== Kerning ===
[http://en.wikipedia.org/wiki/Kerning Kerning] support can be enabled by setting <code>GDISP_NEED_TEXT_KERNING</code> to <code>TRUE</code>.

=== TrueType-Font support ===
Any [http://en.wikipedia.org/wiki/TrueType TrueType-Font] available in a *.ttf or a *.bdf file format can be used in uGFX. See [[Font_rendering#Adding Fonts|Adding Fonts]].

== Fonts ==
Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we already added a bunch of fonts in different sizes and versions which should cover most use cases. Use the '''Font name''' as the parameter of the <code>gdispOpenFont()</code> routine.
{| class="wikitable"
! scope="col"|Font
! scope="col"|Font name
|-
|DejaVu Sans 10
|DejaVuSans10
|-
|DejaVu Sans 12
|DejaVuSans12
|-
|DejaVu Sans 12 Bold
|DejaVuSansBold12
|-
|DejaVu Sans 12 Anti-Aliased
|DejaVuSans12_aa
|-
|DejaVu Sans 12 Anti-Aliased Bold
|DejaVuSansBold12_aa
|-
|DejaVu Sans 16
|DejaVuSans16
|-
|DejaVu Sans 16 Anti-Aliased
|DejaVuSans16_aa
|-
|DejaVu Sans 20
|DejaVuSans20
|-
|DejaVu Sans 20 Anti-Aliased
|DejaVuSans20_aa
|-
|DejaVu Sans 24
|DejaVuSans24
|-
|DejaVu Sans 24 Anti-Aliased
|DejaVuSans24_aa
|-
|DejaVu Sans 32
|DejaVuSans32
|-
|DejaVu Sans 32 Anti-Aliased
|DejaVuSans32_aa
|-
|Fixed 10x20
|fixed_10x20
|-
|Fixed 7x14
|fixed_7x14
|-
|Fixed 5x8
|fixed_5x8
|-
|UI1
|UI1
|-
|UI1 Double
|UI1 Double
|-
|UI1 Narrow
|UI1 Narrow
|-
|UI2
|UI2
|-
|UI2 Double
|UI2 Double
|-
|UI2 Narrow
|UI2 Narrow
|-
|Large numbers
|LargeNumbers
|}
Note that each of these fonts has to be enabled in your [[Configuration|configuration file]].

The UI fonts are created by the µGFX developers to provide a default font. The UI fonts stand under the GFX license and should therefore be used in preference to other fonts if suitable. The other fonts are under their own respective licenses.

== Usage ==
Before you can use a font, you first have to open it by calling <code>gdispOpenFont()</code>.
<syntaxhighlight lang=c>
gFont font = gdispOpenFont("DejaVuSans32_aa");
</syntaxhighlight>
'''''Note:''' When the font name specified could not be found, the last enabled font in the [[Configuration|configuration file]] will be used.''

You should call <code>gdispCloseFont()</code> to release any allocated resources if you don't need a font any longer:
<syntaxhighlight lang=c>
gdispCloseFont(font);
</syntaxhighlight>
After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may start by reading through the basic [[Drawing#Text|GDISP text drawing routines]] before you take a look at the different [[GWIN|GWIN]] system.

== Adding fonts ==
The following step-by-step guide will lead you through the process of adding a custom *.ttf font. This guide works for every font, not only ASCII but also cyrillic and any other unicode compatible ones.

=== 1. Acquire a font ===
First of all, you'll need a font in the *.ttf source. You can find plenty of these using google. Please notice their licenses.

=== 2. Convert the font ===
The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our [http://fonts.ugfx.org online converter].
The converter allows you to set the font size, enable or disable anti-aliasing and filter for certain characters. Filtering un-needed characters is essential to keep the font size low. This [http://en.wikipedia.org/wiki/Basic_multilingual_plane#Basic_Multilingual_Plane table] might help you choose the correct character range. A click on the button «Get .c file» will offer you a C file to download after a few moments. Please click that button just once. It can take up to a minute to convert a larger font.

=== 3. Implement the font ===
Place the downloaded c file inside your project directory and name it '''userfonts.h'''. Alternatively write a '''userfonts.h''' file that includes each of your downloaded font c files. In your [[gfxconf.h]], enable the following setting:
<syntaxhighlight lang=c>
#define GDISP_INCLUDE_USER_FONTS TRUE
</syntaxhighlight>

=== 4. Open the font ===
You can now open and use this font as any other one. If you're curious about the parameter of <code>gdispOpenFont()</code>, you can either use the ''full_name'' or the ''short_name'' field that can be found in the struct at the very bottom of the C file (first and second entry).
Please note that you need to configure your text editor to operate in UTF-8 mode, when you want to display those fonts successfully.

For a more detailed guide on how to add your own font, see [[Cyrillic]].

== Font metrics ==
The GDISP API provides several function to retrieve information about font metrics:

<source lang=c>
typedef enum fontmetric {
fontHeight,
fontDescendersHeight,
fontLineSpacing,
fontCharPadding,
fontMinWidth,
fontMaxWidth,
fontBaselineX,
fontBaselineY
} fontmetric_t;

gCoord gdispGetFontMetric(gFont font, fontmetric_t metric);
gCoord gdispGetCharWidth(char c, gFont font);
gCoord gdispGetStringWidth(const char* str, gFont font);
gCoord gdispGetStringWidthCount(const char* str, gFont font, uint16_t count);
</source>
[[Category:GDISP]]

== Disclaimer ==
µGFX comes with a built-in support of [https://code.google.com/p/mcufont/ mcufont]. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.

Font rendering

2021-07-30T13:46:57Z

Tectu: /* Usage */

== Features ==
The µGFX font rendering engine provides the following features:

=== Word-Wrapping ===
The word wrapping feature can be enabled by setting <code>GDISP_NEED_TEXT_WORDWRAP</code> to <code>TRUE</code>.

Word wrapping only has an effect when using <code>gdispDrawStringBox()</code> or <code>gdispFillStringBox()</code>. When the word wrapping feature is not enabled the string will simply be cut-off at the border of the specified box.

=== Unicode ===
[http://en.wikipedia.org/wiki/Unicode Unicode] support can be enabled by setting <code>GDISP_NEED_TEXT_UTF8</code> to <code>TRUE</code>.

Unicode support allows to display fonts of many different languages such as English, French, German, Russian (Cyrillic), Chinese, Japanese and so on.
For information about cyrillic font support, see [[Cyrillic]].

=== Anti-Aliasing ===
To use the anti-aliasing font feature, the following three conditions have to be fulfilled:
# Using an anti-aliased font
# <code>GDISP_NEED_ANTIALIAS</code> needs to be set to <code>TRUE</code>
# Either have <code>GDISP_NEED_PIXELREAD</code> set to <code>TRUE</code> or using one of the [[Drawing#Text|text drawing functions]] that have a background color parameter.

Note that you can use normal (not anti-aliased) fonts along with anti-aliased ones without any problems.

=== Kerning ===
[http://en.wikipedia.org/wiki/Kerning Kerning] support can be enabled by setting <code>GDISP_NEED_TEXT_KERNING</code> to <code>TRUE</code>.

=== TrueType-Font support ===
Any [http://en.wikipedia.org/wiki/TrueType TrueType-Font] available in a *.ttf or a *.bdf file format can be used in uGFX. See [[Font_rendering#Adding Fonts|Adding Fonts]].

== Fonts ==
Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we already added a bunch of fonts in different sizes and versions which should cover most use cases. Use the '''Font name''' as the parameter of the <code>gdispOpenFont()</code> routine.
{| class="wikitable"
! scope="col"|Font
! scope="col"|Font name
|-
|DejaVu Sans 10
|DejaVuSans10
|-
|DejaVu Sans 12
|DejaVuSans12
|-
|DejaVu Sans 12 Bold
|DejaVuSansBold12
|-
|DejaVu Sans 12 Anti-Aliased
|DejaVuSans12_aa
|-
|DejaVu Sans 12 Anti-Aliased Bold
|DejaVuSansBold12_aa
|-
|DejaVu Sans 16
|DejaVuSans16
|-
|DejaVu Sans 16 Anti-Aliased
|DejaVuSans16_aa
|-
|DejaVu Sans 20
|DejaVuSans20
|-
|DejaVu Sans 20 Anti-Aliased
|DejaVuSans20_aa
|-
|DejaVu Sans 24
|DejaVuSans24
|-
|DejaVu Sans 24 Anti-Aliased
|DejaVuSans24_aa
|-
|DejaVu Sans 32
|DejaVuSans32
|-
|DejaVu Sans 32 Anti-Aliased
|DejaVuSans32_aa
|-
|Fixed 10x20
|fixed_10x20
|-
|Fixed 7x14
|fixed_7x14
|-
|Fixed 5x8
|fixed_5x8
|-
|UI1
|UI1
|-
|UI1 Double
|UI1 Double
|-
|UI1 Narrow
|UI1 Narrow
|-
|UI2
|UI2
|-
|UI2 Double
|UI2 Double
|-
|UI2 Narrow
|UI2 Narrow
|-
|Large numbers
|LargeNumbers
|}
Note that each of these fonts has to be enabled in your [[Configuration|configuration file]].

The UI fonts are created by the µGFX developers to provide a default font. The UI fonts stand under the GFX license and should therefore be used in preference to other fonts if suitable. The other fonts are under their own respective licenses.

== Usage ==
Before you can use a font, you first have to open it by calling <code>gdispOpenFont()</code>.
<syntaxhighlight lang=c>
gFont font = gdispOpenFont("DejaVuSans32_aa");
</syntaxhighlight>
'''''Note:''' When the font name specified could not be found, the last enabled font in the [[Configuration|configuration file]] will be used.''

You should call <code>gdispCloseFont()</code> to release any allocated resources if you don't need a font any longer:
<syntaxhighlight lang=c>
gdispCloseFont(font);
</syntaxhighlight>
After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may start by reading through the basic [[Drawing#Text|GDISP text drawing routines]] before you take a look at the different [[GWIN|GWIN]] system.

== Adding fonts ==
The following step-by-step guide will lead you through the process of adding a custom *.ttf font. This guide works for every font, not only ASCII but also cyrillic and any other unicode compatible ones.

=== 1. Acquire a font ===
First of all, you'll need a font in the *.ttf source. You can find plenty of these using google. Please notice their licenses.

=== 2. Convert the font ===
The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our [http://fonts.ugfx.org online converter].
The converter allows you to set the font size, enable or disable anti-aliasing and filter for certain characters. Filtering un-needed characters is essential to keep the font size low. This [http://en.wikipedia.org/wiki/Basic_multilingual_plane#Basic_Multilingual_Plane table] might help you choose the correct character range. A click on the button «Get .c file» will offer you a C file to download after a few moments. Please click that button just once. It can take up to a minute to convert a larger font.

=== 3. Implement the font ===
Place the downloaded c file inside your project directory and name it '''userfonts.h'''. Alternatively write a '''userfonts.h''' file that includes each of your downloaded font c files. In your [[gfxconf.h]], enable the following setting:
<syntaxhighlight lang=c>
#define GDISP_INCLUDE_USER_FONTS TRUE
</syntaxhighlight>

=== 4. Open the font ===
You can now open and use this font as any other one. If you're curious about the parameter of <code>gdispOpenFont()</code>, you can either use the ''full_name'' or the ''short_name'' field that can be found in the struct at the very bottom of the C file (first and second entry).
Please note that you need to configure your text editor to operate in UTF-8 mode, when you want to display those fonts successfully.

For a more detailed guide on how to add your own font, see [[Cyrillic]].

== Font metrics ==
The GDISP API provides several function to retrieve information about font metrics:

<source lang=c>
typedef enum fontmetric {
fontHeight,
fontDescendersHeight,
fontLineSpacing,
fontCharPadding,
fontMinWidth,
fontMaxWidth,
fontBaselineX,
fontBaselineY
} fontmetric_t;

gCoord gdispGetFontMetric(gFont font, fontmetric_t metric);
gCoord gdispGetCharWidth(char c, gFont font);
gCoord gdispGetStringWidth(const char* str, gFont font);
gCoord gdispGetStringWidthCount(const char* str, gFont font, uint16_t count);
</source>
[[Category:GDISP]]

== Disclaimer ==
µGFX comes with a built-in support of [https://code.google.com/p/mcufont/ mcufont]. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.

Font rendering

2021-07-30T13:46:47Z

Tectu: /* Font metrics */

== Features ==
The µGFX font rendering engine provides the following features:

=== Word-Wrapping ===
The word wrapping feature can be enabled by setting <code>GDISP_NEED_TEXT_WORDWRAP</code> to <code>TRUE</code>.

Word wrapping only has an effect when using <code>gdispDrawStringBox()</code> or <code>gdispFillStringBox()</code>. When the word wrapping feature is not enabled the string will simply be cut-off at the border of the specified box.

=== Unicode ===
[http://en.wikipedia.org/wiki/Unicode Unicode] support can be enabled by setting <code>GDISP_NEED_TEXT_UTF8</code> to <code>TRUE</code>.

Unicode support allows to display fonts of many different languages such as English, French, German, Russian (Cyrillic), Chinese, Japanese and so on.
For information about cyrillic font support, see [[Cyrillic]].

=== Anti-Aliasing ===
To use the anti-aliasing font feature, the following three conditions have to be fulfilled:
# Using an anti-aliased font
# <code>GDISP_NEED_ANTIALIAS</code> needs to be set to <code>TRUE</code>
# Either have <code>GDISP_NEED_PIXELREAD</code> set to <code>TRUE</code> or using one of the [[Drawing#Text|text drawing functions]] that have a background color parameter.

Note that you can use normal (not anti-aliased) fonts along with anti-aliased ones without any problems.

=== Kerning ===
[http://en.wikipedia.org/wiki/Kerning Kerning] support can be enabled by setting <code>GDISP_NEED_TEXT_KERNING</code> to <code>TRUE</code>.

=== TrueType-Font support ===
Any [http://en.wikipedia.org/wiki/TrueType TrueType-Font] available in a *.ttf or a *.bdf file format can be used in uGFX. See [[Font_rendering#Adding Fonts|Adding Fonts]].

== Fonts ==
Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we already added a bunch of fonts in different sizes and versions which should cover most use cases. Use the '''Font name''' as the parameter of the <code>gdispOpenFont()</code> routine.
{| class="wikitable"
! scope="col"|Font
! scope="col"|Font name
|-
|DejaVu Sans 10
|DejaVuSans10
|-
|DejaVu Sans 12
|DejaVuSans12
|-
|DejaVu Sans 12 Bold
|DejaVuSansBold12
|-
|DejaVu Sans 12 Anti-Aliased
|DejaVuSans12_aa
|-
|DejaVu Sans 12 Anti-Aliased Bold
|DejaVuSansBold12_aa
|-
|DejaVu Sans 16
|DejaVuSans16
|-
|DejaVu Sans 16 Anti-Aliased
|DejaVuSans16_aa
|-
|DejaVu Sans 20
|DejaVuSans20
|-
|DejaVu Sans 20 Anti-Aliased
|DejaVuSans20_aa
|-
|DejaVu Sans 24
|DejaVuSans24
|-
|DejaVu Sans 24 Anti-Aliased
|DejaVuSans24_aa
|-
|DejaVu Sans 32
|DejaVuSans32
|-
|DejaVu Sans 32 Anti-Aliased
|DejaVuSans32_aa
|-
|Fixed 10x20
|fixed_10x20
|-
|Fixed 7x14
|fixed_7x14
|-
|Fixed 5x8
|fixed_5x8
|-
|UI1
|UI1
|-
|UI1 Double
|UI1 Double
|-
|UI1 Narrow
|UI1 Narrow
|-
|UI2
|UI2
|-
|UI2 Double
|UI2 Double
|-
|UI2 Narrow
|UI2 Narrow
|-
|Large numbers
|LargeNumbers
|}
Note that each of these fonts has to be enabled in your [[Configuration|configuration file]].

The UI fonts are created by the µGFX developers to provide a default font. The UI fonts stand under the GFX license and should therefore be used in preference to other fonts if suitable. The other fonts are under their own respective licenses.

== Usage ==
Before you can use a font, you first have to open it by calling <code>gdispOpenFont()</code>.
<syntaxhighlight lang=c>
font_t font = gdispOpenFont("DejaVuSans32_aa");
</syntaxhighlight>
'''''Note:''' When the font name specified could not be found, the last enabled font in the [[Configuration|configuration file]] will be used.''

You should call <code>gdispCloseFont()</code> to release any allocated resources if you don't need a font any longer:
<syntaxhighlight lang=c>
gdispCloseFont(font);
</syntaxhighlight>
After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may start by reading through the basic [[Drawing#Text|GDISP text drawing routines]] before you take a look at the different [[GWIN|GWIN]] system.

== Adding fonts ==
The following step-by-step guide will lead you through the process of adding a custom *.ttf font. This guide works for every font, not only ASCII but also cyrillic and any other unicode compatible ones.

=== 1. Acquire a font ===
First of all, you'll need a font in the *.ttf source. You can find plenty of these using google. Please notice their licenses.

=== 2. Convert the font ===
The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our [http://fonts.ugfx.org online converter].
The converter allows you to set the font size, enable or disable anti-aliasing and filter for certain characters. Filtering un-needed characters is essential to keep the font size low. This [http://en.wikipedia.org/wiki/Basic_multilingual_plane#Basic_Multilingual_Plane table] might help you choose the correct character range. A click on the button «Get .c file» will offer you a C file to download after a few moments. Please click that button just once. It can take up to a minute to convert a larger font.

=== 3. Implement the font ===
Place the downloaded c file inside your project directory and name it '''userfonts.h'''. Alternatively write a '''userfonts.h''' file that includes each of your downloaded font c files. In your [[gfxconf.h]], enable the following setting:
<syntaxhighlight lang=c>
#define GDISP_INCLUDE_USER_FONTS TRUE
</syntaxhighlight>

=== 4. Open the font ===
You can now open and use this font as any other one. If you're curious about the parameter of <code>gdispOpenFont()</code>, you can either use the ''full_name'' or the ''short_name'' field that can be found in the struct at the very bottom of the C file (first and second entry).
Please note that you need to configure your text editor to operate in UTF-8 mode, when you want to display those fonts successfully.

For a more detailed guide on how to add your own font, see [[Cyrillic]].

== Font metrics ==
The GDISP API provides several function to retrieve information about font metrics:

<source lang=c>
typedef enum fontmetric {
fontHeight,
fontDescendersHeight,
fontLineSpacing,
fontCharPadding,
fontMinWidth,
fontMaxWidth,
fontBaselineX,
fontBaselineY
} fontmetric_t;

gCoord gdispGetFontMetric(gFont font, fontmetric_t metric);
gCoord gdispGetCharWidth(char c, gFont font);
gCoord gdispGetStringWidth(const char* str, gFont font);
gCoord gdispGetStringWidthCount(const char* str, gFont font, uint16_t count);
</source>
[[Category:GDISP]]

== Disclaimer ==
µGFX comes with a built-in support of [https://code.google.com/p/mcufont/ mcufont]. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.