🔘 Image Button

The Image Button (imgbtn) is a specialized version of the button widget that uses bitmap assets instead of procedurally drawn shapes. It is the preferred tool for creating high-fidelity, skeuomorphic, or brand-specific UI elements like textured switches or custom-designed icons.

---

⚙️ Properties (Props)

The Image Button configuration is defined by the ImageButtonWidget interface. It manages state transitions by swapping the active asset.

Property	Type	Description
Released Image	imageId	The asset shown when the button is idle.
Pressed Image	imageId	The asset shown while the user is touching the button.
Checked Image	imageId	The asset shown when the button is in a "toggled on" state.
Checkable	boolean	Enables toggle (sticky) behavior.

---

🛠 State Logic

The widget automatically handles state switching based on user input. For the best visual experience, ensure all three assigned images have the same pixel dimensions.

1. Idle: Displays the releasedImageId.
2. Interaction: Upon touch, the engine instantly swaps to the pressedImageId to provide tactile-style visual feedback.
3. Toggle: If checkable is true, the widget will remain in the checkedImageId state after the touch is released.

---

🎨 Asset Optimization

Since this widget relies on multiple images, memory management is key:

• Asset Packing: Use the Asset Packer to ensure these images are compressed or formatted correctly for your hardware.
• Shared Assets: You can use the same imageId for both Released and Checked if your design only requires a change during the actual press.

---

⚡ Runtime API (Lua)

You can programmatically swap the source assets or force state changes via the Logic and Events system.

-- Change the pressed state image dynamically
btn_power:set_src_pressed("icon_power_red_glow")

-- Manually set the button to a checked state
btn_power:set_state_checked(true)

-- Check the current state
if btn_mode:is_checked() then
    enable_high_performance()
end

---

note

If you only need to display a static graphic that does not change when clicked, use the Static Image widget to save memory.

---

🚀 Next Steps

• Static Image — For non-interactive decorative graphics.
• Button — For standard, vector-rendered buttons.
• Asset Packer — Learn how to import your PNG/JPG files as imageId references.