Image Widget¶

Overview¶

The Image widget displays a compressed bitmap image stored in flash or RAM. Images are pre-processed by the mGui image compressor tool into a mgui_compressed_image_t structure and included as a C header.

Enable¶

No feature flag required — the Image widget is always available.

Image Format¶

The compressor produces a header that declares two symbols — a raw byte array and a mgui_compressed_image_t descriptor:

// bell3_rle.h (generated)
const uint8_t img_bell3_compressed[] = { /* RLE data */ };

const mgui_compressed_image_t img_bell3 = {
    .compression_type = COMPRESSION_TYPE_RLE,
    .width  = 150,
    .height = 150,
    .compressed_size = sizeof(img_bell3_compressed),
    .data   = img_bell3_compressed,
    .palette = NULL,
    .palette_size = 0,
    .bits_per_index = 0,
};

Include the generated header and pass &img_bell3 to mgui_widget_image_set_source.

Creation¶

mgui_widget_t* img = mgui_allocate_widget(
    parent,
    MGUI_WIDGET_IMAGE,
    (mgui_area_t){x, y, width, height},
    MGUI_COLOR_CRIMSON   // background fill color
);

API Reference¶

Set Image Source¶

// Assign a compressed image descriptor
mgui_widget_image_set_source(img, &img_bell3);

Tint Colors¶

// image_color = foreground/ink tint, bg_color = background behind the image
mgui_widget_image_set_color(img, MGUI_COLOR_ELEM_BRIGHT_GREEN, MGUI_COLOR_CRIMSON);

Call this at runtime to swap tint colors without reloading the image data.

Common Helpers¶

mgui_widget_set_pos(img, x, y);
mgui_widget_set_size(img, width, height);
mgui_widget_align(img, MGUI_ALIGN_CENTER);
mgui_widget_set_visible(img, true);
mgui_widget_click_handler(img, my_click_cb);

Common Combinations¶

Use Case	Setup
Clickable icon	Image + `mgui_widget_click_handler` to toggle tint or open a panel
Status icon in a box	Small image placed inside a parent box (e.g., battery in a status bar)
Splash / boot logo	Large centered image on a full-screen box
Two-state icon	Toggle between two tint color pairs on click

Examples¶

Clickable Bell Icon with Tint Toggle¶

A 150×150 bell icon on the main screen. Each tap swaps the foreground and background tint colors — covers mgui_widget_image_set_source, mgui_widget_image_set_color, and a click handler.

Bell Icon

ui.json (Live Simulator)C Code

{
  "elements": [
    {
      "type": "box",
      "name": "Screen",
      "x": 0, "y": 0, "w": 320, "h": 240,
      "color": "0xC6C6C6",
      "children": [
        {
          "type": "image",
          "name": "BellIcon",
          "x": 85, "y": 45, "w": 150, "h": 150,
          "color": "0xEF3F2E",
          "image_color": "0x00FF00",
          "bg_color":    "0xEF3F2E",
          "src": "bell3_rle"
        }
      ]
    }
  ]
}

#include "tools/image_compressor/bell3_rle.h"

mgui_widget_t* screen = mgui_allocate_widget(
    NULL, MGUI_WIDGET_BOX,
    (mgui_area_t){0, 0, 320, 240},
    MGUI_COLOR_LIGHT_GRAY);

mgui_widget_t* bell_icon = mgui_allocate_widget(
    screen, MGUI_WIDGET_IMAGE,
    (mgui_area_t){85, 45, 150, 150},
    MGUI_COLOR_CRIMSON);
mgui_widget_image_set_color(bell_icon,
    MGUI_COLOR_ELEM_BRIGHT_GREEN,   // foreground tint
    MGUI_COLOR_CRIMSON);            // background fill
mgui_widget_image_set_source(bell_icon, &img_bell3);

static bool tint_toggle = false;

static void on_bell_click(mgui_widget_t* obj, mgui_event_t event) {
    tint_toggle = !tint_toggle;
    if (tint_toggle) {
        mgui_widget_image_set_color(obj,
            MGUI_COLOR_ELEM_BRIGHT_GREEN, MGUI_COLOR_CRIMSON);
    } else {
        mgui_widget_image_set_color(obj,
            MGUI_COLOR_CRIMSON, MGUI_COLOR_ELEM_BRIGHT_GREEN);
    }
}
mgui_widget_click_handler(bell_icon, on_bell_click);

Battery Icon in a Status Box¶

A small 58×78 battery icon embedded inside a parent box — covers placing an image as a child widget and calling mgui_widget_image_set_source with a separate image (img_battery).

Battery Icon

ui.json (Live Simulator)C Code

{
  "elements": [
    {
      "type": "box",
      "name": "Screen",
      "x": 0, "y": 0, "w": 320, "h": 240,
      "color": "0xC6C6C6",
      "children": [
        {
          "type": "box",
          "name": "StatusBar",
          "x": 0, "y": 0, "w": 320, "h": 120,
          "color": "0x5900CC",
          "children": [
            {
              "type": "image",
              "name": "BatIcon",
              "x": 10, "y": 20, "w": 58, "h": 78,
              "color": "0x5900CC",
              "src": "battery_rle"
            }
          ]
        }
      ]
    }
  ]
}

#include "tools/image_compressor/battery_rle.h"

mgui_widget_t* screen = mgui_allocate_widget(
    NULL, MGUI_WIDGET_BOX,
    (mgui_area_t){0, 0, 320, 240},
    MGUI_COLOR_LIGHT_GRAY);

mgui_widget_t* status_bar = mgui_allocate_widget(
    screen, MGUI_WIDGET_BOX,
    (mgui_area_t){0, 0, 320, 120},
    MGUI_COLOR_PURPLE);

mgui_widget_t* bat_icon = mgui_allocate_widget(
    status_bar, MGUI_WIDGET_IMAGE,
    (mgui_area_t){10, 20, 58, 78},
    MGUI_COLOR_PURPLE);
mgui_widget_image_set_source(bat_icon, &img_battery);

Compression Types¶

Type	Description
`COMPRESSION_TYPE_RLE`	Run-length encoded — good for icons with large uniform areas
Indexed (I8)	8-bit palette indexed — compact for multi-color sprites
Grayscale 8-bit	Single-channel grayscale images

Enable¶

No feature flag required — the Image widget is always available.

Image Format¶

Images are compressed with the bell3_rle / battery_rle style compressor (RLE or indexed palette) and declared in a header file:

#include "tools/image_compressor/bell3_rle.h"
#include "tools/image_compressor/battery_rle.h"

Each header exposes a mgui_compressed_image_t structure:

typedef struct {
    const uint8_t* data;
    uint16_t width;
    uint16_t height;
    compression_type_t compression;
    // ...
} mgui_compressed_image_t;

Creation¶

mgui_widget_t* img = mgui_allocate_widget(
    parent,
    MGUI_WIDGET_IMAGE,
    (mgui_area_t){x, y, width, height},
    MGUI_COLOR_BLACK   // background / transparent fill
);

API Reference¶

// Assign a compressed image source
mgui_widget_image_set_source(img, &bell3_rle);
mgui_widget_image_set_source(img, &battery_rle);

Common Helpers¶

mgui_widget_set_pos(img, x, y);
mgui_widget_set_size(img, width, height);
mgui_widget_align(img, MGUI_ALIGN_CENTER);
mgui_widget_set_visible(img, bool visible);

Examples¶

Display a Static Icon¶

#include "tools/image_compressor/bell3_rle.h"

mgui_widget_t* icon = mgui_allocate_widget(screen, MGUI_WIDGET_IMAGE,
    (mgui_area_t){10, 10, 48, 48}, MGUI_COLOR_BLACK);
mgui_widget_image_set_source(icon, &bell3_rle);

Battery Status Icon (dynamic swap)¶

#include "tools/image_compressor/battery_rle.h"

mgui_widget_t* bat_icon = mgui_allocate_widget(status_bar, MGUI_WIDGET_IMAGE,
    (mgui_area_t){740, 5, 40, 20}, MGUI_COLOR_BLACK);
mgui_widget_image_set_source(bat_icon, &battery_rle);

// Swap image at runtime:
// mgui_widget_image_set_source(bat_icon, &battery_low_rle);

Centered Logo on Splash Screen¶

mgui_widget_t* splash = mgui_allocate_widget(NULL, MGUI_WIDGET_BOX,
    (mgui_area_t){0, 0, 800, 480}, MGUI_COLOR_BLACK);

mgui_widget_t* logo = mgui_allocate_widget(splash, MGUI_WIDGET_IMAGE,
    (mgui_area_t){0, 0, 128, 64}, MGUI_COLOR_BLACK);
mgui_widget_image_set_source(logo, &my_logo_rle);
mgui_widget_align(logo, MGUI_ALIGN_CENTER);

Compression Types¶

Type	Description
RLE	Run-length encoded — good for icons with large uniform areas
Indexed (I8)	8-bit palette indexed — compact for multi-color sprites
Grayscale 8-bit	Single-channel grayscale images

Common Combinations¶

Use Case	Setup
App icon in header bar	Small image (32×32) aligned top-right of a status box
Splash / boot logo	Large centered image on a full-screen black box
Battery / signal icons	Small images swapped at runtime based on value
Button with icon	Image widget as sibling of a label inside a button box