Skip to main content
Version: v2.4.0 (Current)

Widget Control API (C)

The Artok Runtime provides a professional, status-based C API for your master firmware. This API acts as a polymorphic bridge; instead of managing raw pointers or complex structures, you interact with your HMI using the UUIDs (Universal Unique Identifiers) assigned within Artok Studio.

🚦 Execution Status​

Every API function returns an atk_api_status_t. This allows your business logic to handle errors gracefully, such as attempting to update a widget that was deleted in a newer UI version.

ConstantValueDescription
ATK_API_OK0x00Operation successful.
ATK_API_ERR_INVALID0x01Invalid parameters or malformed request.
ATK_API_ERR_NOT_FOUND0x02The UUID does not exist in the current ui.bin.
ATK_API_ERR_TYPE0x03Type mismatch (e.g., calling set_text on a Slider).

📝 Text & Numeric Control​

atk_api_set_text(uuid, text)​

Updates Labels, Buttons, or Text Areas.

  • Smart Resolution: If the UUID points to a Button, Artok automatically locates the label child and updates its content.

atk_api_set_value(uuid, value)​

A polymorphic setter for any widget with a numeric state. This includes Sliders, Bars, Arcs, Gauges, Switches, and Checkboxes.

atk_api_set_range(uuid, min, max)​

Dynamically adjusts the limits of numeric widgets (e.g., changing a Gauge scale from 0–100 to 0–500).

🎨 Visuals & Assets​

atk_api_set_color(uuid, hex_color)​

Applies a 24-bit color (e.g., 0xFF0000 for Red).

  • Semantic Logic: If the widget is label-like, it sets the text color. Otherwise, it sets the background color.

atk_api_set_image(uuid, img_uuid)​

Swaps an image or icon source using the Resource UUID from your project library.

atk_api_set_rotation(uuid, angle)​

Rotates an Image widget.

  • Angle: Units of 0.1° (e.g., 900 = 90°).

atk_api_set_animation(uuid, seq_uuid)​

Swaps the entire sequence of an animimg (Animated Image) widget.

📐 Advanced Geometry​

atk_api_set_geometry(uuid, angle, rotation)​

Directly controls the structural layout of complex widgets.

  • Arcs: Sets the total arc length and the starting offset.
  • Meters: Adjusts the scale distribution.

📥 Data Retrieval (Getters)​

The C API allows your firmware to "pull" the current state of the UI. This is essential for synchronizing hardware states with user interactions (e.g., reading a slider to set PWM brightness).

atk_api_get_value(uuid, &out_val)​

Retrieves the current numeric state of a widget.

atk_api_get_text(uuid, buf, buf_size)​

Copies the text content of a Label or Text Area into a provided buffer.

🛠️ Implementation Example​

This snippet demonstrates a typical sensor update loop using the Artok API.

void sensor_update_task() {
    char temp_str[16];
    int32_t raw_temp = read_thermistor();
    snprintf(temp_str, sizeof(temp_str), "%d C", raw_temp);

    // 1. Update the display label
    atk_api_set_text("LBL_TEMP_VAL", temp_str);

    // 2. Update the visual progress bar
    atk_api_set_value("BAR_TEMP_LEVEL", raw_temp);

    // 3. Conditional color alerting
    if (raw_temp > 60) {
        atk_api_set_color("LBL_TEMP_VAL", 0xFF0000); // Alert Red
    } else {
        atk_api_set_color("LBL_TEMP_VAL", 0xFFFFFF); // Normal White
    }
}