iiowidget-patterns

IIOWidget Creation Patterns

Rules for creating IIOWidget instances to bind UI controls to IIO device attributes.

IIOWidgetBuilder Patterns

Range/Spinbox (with available attribute)

IIOWidget *widget = IIOWidgetBuilder(parent)
    .device(dev)  // or .channel(ch) if channel-specific
    .attribute("attr")
    .optionsAttribute("attr_available")
    .title("Attribute Display Name")
    .uiStrategy(IIOWidgetBuilder::RangeUi)
    .infoMessage("Hover tooltip text")
    .group(m_group)
    .buildSingle();

connect(this, &MyTool::readRequested, widget, &IIOWidget::readAsync);

Range/Spinbox (with explicit range)

IIOWidget *widget = IIOWidgetBuilder(parent)
    .device(dev)
    .attribute("attr")
    .optionsValues("MIN MAX STEP")  // e.g. "0 100 1"
    .title("Attribute Display Name")
    .uiStrategy(IIOWidgetBuilder::RangeUi)
    .group(m_group)
    .buildSingle();

Combo Box (with available attribute)

IIOWidget *widget = IIOWidgetBuilder(parent)
    .device(dev)
    .attribute("attr")
    .optionsAttribute("attr_available")
    .title("Attribute Display Name")
    .uiStrategy(IIOWidgetBuilder::ComboUi)
    .group(m_group)
    .buildSingle();

Combo Box (with custom values)

QMap<QString, QString> optionsMap;
optionsMap["value1"] = "Display_Text_1";
optionsMap["value2"] = "Display_Text_2";

QString optionsValues = "Display_Text_1 Display_Text_2";

IIOWidget *widget = IIOWidgetBuilder(parent)
    .device(dev)
    .attribute("attr")
    .optionsValues(optionsValues)
    .title("Attribute Display Name")
    .uiStrategy(IIOWidgetBuilder::ComboUi)
    .group(m_group)
    .buildSingle();

widget->setUItoDataConversion([optionsMap](QString displayValue) {
    return IIOWidgetUtils::comboUiToDataConversionFunction(displayValue, &optionsMap);
});
widget->setDataToUIConversion([optionsMap](QString attrValue) {
    return IIOWidgetUtils::comboDataToUiConversionFunction(attrValue, &optionsMap);
});

Checkbox

IIOWidget *widget = IIOWidgetBuilder(parent)
    .device(dev)
    .attribute("attr")
    .title("Attribute Display Name")
    .uiStrategy(IIOWidgetBuilder::CheckBoxUi)
    .group(m_group)
    .buildSingle();

Read-Only Status (with 2-failure stop timer)

IIOWidget *widget = IIOWidgetBuilder(parent)
    .channel(ch)
    .attribute("status_attr")
    .title("Status Display Name")
    .group(m_group)
    .buildSingle();
widget->setEnabled(false);

QTimer *timer = new QTimer(parent);
int *failCount = new int(0);
connect(timer, &QTimer::timeout, widget, &IIOWidget::readAsync);
connect(widget, &IIOWidget::currentStateChanged, timer,
    [timer, failCount](IIOWidget::State state, QString) {
        if(state == IIOWidget::Error) {
            (*failCount)++;
            if(*failCount >= 2) timer->stop();
        } else if(state == IIOWidget::Correct) {
            *failCount = 0;
        }
    });
timer->start(1000);

Scaling Conversions

When an attribute needs unit conversion (e.g., Hz to MHz), set ALL THREE functions:

widget->setDataToUIConversion([](QString data) {
    return QString::number(data.toDouble() / 1e6, 'f', 6);
});
widget->setRangeToUIConversion([](QString data) {
    return QString::number(data.toDouble() / 1e6, 'f', 6);
});
widget->setUItoDataConversion([](QString data) {
    return QString::number(data.toDouble() * 1e6, 'f', 0);
});

Critical Requirements

1. Every widget MUST connect readRequested -> readAsync (caller's responsibility)
2. RangeUi with scaling needs ALL THREE conversion functions
3. Read-only timer widgets use currentStateChanged signal (NOT readFailed/readSuccess — those don't exist)
4. Always include .group(m_group) in the builder chain
5. Use underscores in display values for custom combos: "Fast_Attack" not "Fast Attack"

Decision Tree

Range/Spinbox: Has *_available attr? YES -> use .optionsAttribute(). NO -> use .optionsValues("MIN MAX STEP")

Combo: Has *_available attr? YES -> .optionsAttribute(). NO -> custom values with .optionsValues() + conversion functions

Available UI Strategies

Each strategy has a dedicated file with real codebase examples:

Strategy	File	Use Case
RangeUi	range-widget.md	Numeric attributes with min/max/step (spinbox/slider)
ComboUi	combo-widget.md	Discrete options (dropdown)
CheckBoxUi	checkbox-widget.md	Boolean/enable toggle
EditableUi	editable-widget.md	Free-form text input (no range)
Read-only	readonly-widget.md	Disabled display with optional timer polling
TemperatureUi	temperature-widget.md	Temperature with critical threshold warnings