Circle Widget¶

Overview¶

The Circle widget draws a filled or outlined circle. It is used for indicators, status dots, decorations, and avatar placeholders. Like all widgets it participates in the parent-child layout hierarchy.

Enable¶

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

Creation¶

mgui_widget_t* circle = mgui_allocate_widget(
    parent,
    MGUI_WIDGET_CIRCLE,
    (mgui_area_t){x, y, diameter, diameter},
    MGUI_COLOR_RED
);

Tip: In JSON use "radius" — the generator computes w = h = radius * 2 automatically. In C pass diameter for both width and height.

API Reference¶

Shape¶

// Filled circle
mgui_widget_radius_property(circle, radius, true);

// Outlined ring (border color controls the ring color)
mgui_widget_radius_property(circle, radius, false);
mgui_widget_border_property(circle, MGUI_COLOR_WHITE, 2);

Appearance¶

mgui_widget_color_change(circle, MGUI_COLOR_GREEN);
mgui_widget_border_property(circle, MGUI_COLOR_WHITE, 2);
mgui_widget_align(circle, MGUI_ALIGN_CENTER);
mgui_widget_set_visible(circle, bool visible);

Events¶

static void circle_click(mgui_widget_t* obj, mgui_event_t event) {
    if (event == MGUI_EVENT_CLICKED) {
        mgui_widget_color_change(obj, MGUI_COLOR_YELLOW);
    }
}
mgui_widget_click_handler(circle, circle_click);

Event Constants¶

Event	Description
`MGUI_EVENT_CLICKED`	Finger released after a short tap
`MGUI_EVENT_PRESS_DOWN`	Finger touched the widget
`MGUI_EVENT_PRESS_UP`	Finger lifted

Common Combinations¶

Use Case	Setup
Online / offline indicator	Small filled circle, color = green / red
Loading spinner base	Large outlined circle
Avatar placeholder	Large filled circle with label on top
Decorative accent	Small filled circle inside a box header

Examples¶

Status Indicator Dot¶

A small filled circle centered on a light gray screen — the minimal starting point.

Status Indicator Dot

ui.json (Live Simulator)C Code

{
  "elements": [
    {
      "type": "box",
      "name": "Screen",
      "x": 0, "y": 0, "w": 320, "h": 240,
      "color": "0xC6C6C6",
      "children": [
        {
          "type": "circle",
          "name": "StatusDot",
          "x": 0, "y": 0,
          "radius": 12,
          "color": "0x2DA852",
          "align": "MGUI_ALIGN_CENTER",
          "corner": { "radius": 12, "filled": true }
        }
      ]
    }
  ]
}

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_dot = mgui_allocate_widget(
    screen, MGUI_WIDGET_CIRCLE,
    (mgui_area_t){0, 0, 24, 24},
    ((mgui_color_t){.value = 0x2DA852}));
mgui_widget_align(status_dot, MGUI_ALIGN_CENTER);
mgui_widget_radius_property(status_dot, 12, true);

Outlined Ring¶

A large outlined circle with a colored border — useful as a loading spinner base or decorative ring.

Outlined Ring

ui.json (Live Simulator)C Code

{
  "elements": [
    {
      "type": "box",
      "name": "Screen",
      "x": 0, "y": 0, "w": 320, "h": 240,
      "color": "0xC6C6C6",
      "children": [
        {
          "type": "circle",
          "name": "Ring",
          "x": 0, "y": 0,
          "radius": 50,
          "color": "0xC6C6C6",
          "align": "MGUI_ALIGN_CENTER",
          "corner": { "radius": 50, "filled": false },
          "border": { "color": "0x5900CC", "width": 4 }
        }
      ]
    }
  ]
}

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* ring = mgui_allocate_widget(
    screen, MGUI_WIDGET_CIRCLE,
    (mgui_area_t){0, 0, 100, 100},
    MGUI_COLOR_LIGHT_GRAY);
mgui_widget_align(ring, MGUI_ALIGN_CENTER);
mgui_widget_radius_property(ring, 50, false);
mgui_widget_border_property(ring, ((mgui_color_t){.value = 0x5900CC}), 4);

Traffic Light Row¶

Three filled circles side-by-side inside a dark panel — red, amber, green indicator strip.

Traffic Light Row

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": "Panel",
          "x": 80, "y": 80, "w": 160, "h": 80,
          "color": "0x222222",
          "corner": { "radius": 10, "filled": true },
          "children": [
            {
              "type": "circle",
              "name": "Red",
              "x": 18, "y": 20,
              "radius": 18,
              "color": "0xEF3F2E",
              "corner": { "radius": 18, "filled": true }
            },
            {
              "type": "circle",
              "name": "Amber",
              "x": 62, "y": 20,
              "radius": 18,
              "color": "0xFFA500",
              "corner": { "radius": 18, "filled": true }
            },
            {
              "type": "circle",
              "name": "Green",
              "x": 106, "y": 20,
              "radius": 18,
              "color": "0x2DA852",
              "corner": { "radius": 18, "filled": true }
            }
          ]
        }
      ]
    }
  ]
}

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* panel = mgui_allocate_widget(
    screen, MGUI_WIDGET_BOX,
    (mgui_area_t){80, 80, 160, 80},
    ((mgui_color_t){.value = 0x222222}));
mgui_widget_radius_property(panel, 10, true);

mgui_widget_t* red = mgui_allocate_widget(
    panel, MGUI_WIDGET_CIRCLE,
    (mgui_area_t){18, 20, 36, 36},
    ((mgui_color_t){.value = 0xEF3F2E}));
mgui_widget_radius_property(red, 18, true);

mgui_widget_t* amber = mgui_allocate_widget(
    panel, MGUI_WIDGET_CIRCLE,
    (mgui_area_t){62, 20, 36, 36},
    MGUI_COLOR_ORANGE);
mgui_widget_radius_property(amber, 18, true);

mgui_widget_t* green = mgui_allocate_widget(
    panel, MGUI_WIDGET_CIRCLE,
    (mgui_area_t){106, 20, 36, 36},
    ((mgui_color_t){.value = 0x2DA852}));
mgui_widget_radius_property(green, 18, true);