Widget 型別詳解

; label.nxlay - one plain LABEL and one LABEL that can be clicked.
[panel]
ref_w=40
ref_h=4

[w.1]
type=LABEL
y=0
min_w=24
label=Firmware ready

[w.2]
type=LABEL
y=1
min_w=24
flags=ACTIVATABLE
label=Open datasheet

/**
 * @file    label.c
 * @brief   The clickable LABEL (flags=ACTIVATABLE); a plain LABEL has no runtime API.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match label.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the clickable label ([w.2] in label.nxlay). */
#define WID_DATASHEET 2

/**
 * @brief  Widget event handler.
 * @param[in] ctx       This mount's context.
 * @param[in] panel_id  Always 0 for now.
 * @param[in] widget_id Which widget.
 * @param[in] evt       The event, valid during the call only. For ACTIVATED,
 *                      evt->val is an NX_WKIND_U64 that packs the click
 *                      position (high 16 bits vertical, low 16 bits horizontal,
 *                      0..65535; a key press gives NX_WPOS_KEYBOARD).
 * @note   I2C Worker Thread. A LABEL has no value to set: its text comes from
 *         the layout file.
 */
void NX_CALL label_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                    const NxWidgetEvent *evt)
{
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_DATASHEET && evt->kind == NX_WEVT_ACTIVATED)
    {
        s_host->LogWrite(ctx, NX_LOG_INFO, "label: datasheet link clicked");
    }
}

; value.nxlay - "Version: <text>", the text is set from C.
[panel]
ref_w=40
ref_h=4

[w.1]
type=VALUE
y=0
min_w=20
weight=1
label=Version

/**
 * @file    value.c
 * @brief   Writing the text of a VALUE widget.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match value.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the VALUE ([w.1] in value.nxlay). */
#define WID_VERSION 1

/**
 * @brief  Shows text after the "Version" label.
 * @param[in] ctx  This mount's context.
 * @param[in] text New text (UTF-8); must not be NULL.
 * @return ERR_OK, or ERR_INVALID_PARAM when the widget is not a VALUE.
 * @note   Any thread; no event is generated for your own write.
 */
NxLong value_show(NxPluginCtx ctx, const char *text)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_STR;   /* a VALUE takes a string */
    v.u.str.ptr    = text;
    v.u.str.len    = (NxDword)strlen(text);
    return s_host->SetWidgetProp(ctx, 0, WID_VERSION, NX_WP_VALUE, &v);
}

; textbox.nxlay - a single-line text input.
[panel]
ref_w=40
ref_h=4

[w.1]
type=TEXTBOX
y=0
min_w=16
weight=1
label=Name

/**
 * @file    textbox.c
 * @brief   Reading what the user typed into a TEXTBOX, and writing the box.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match textbox.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the TEXTBOX ([w.1] in textbox.nxlay). */
#define WID_NAME 1

/** @brief The last committed text (copied: evt->val.u.str.ptr is only valid during the call). */
static char s_name[128] = "";

/**
 * @brief  Widget event handler.
 * @note   I2C Worker Thread. CHANGED arrives when the user commits the text
 *         (Enter, or moving focus away), not on every keystroke.
 */
void NX_CALL textbox_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                      const NxWidgetEvent *evt)
{
    size_t n;

    NX_UNUSED_ARG(ctx);
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_NAME && evt->kind == NX_WEVT_CHANGED &&
        evt->val.kind == NX_WKIND_STR && evt->val.u.str.ptr != (const char *)0)
    {
        n = evt->val.u.str.len;
        if (n > sizeof(s_name) - 1)
        {
            /* A TEXTBOX value can be far longer (32767 code points); this demo
             * keeps 127 bytes and may cut a multi-byte character. */
            n = sizeof(s_name) - 1;
        }
        memcpy(s_name, evt->val.u.str.ptr, n);
        s_name[n] = '\0';
    }
}

/**
 * @brief  Replaces the text in the box (e.g. after loading a saved setting).
 * @return ERR_OK or an error code. Does not trigger textbox_on_event().
 */
NxLong textbox_set(NxPluginCtx ctx, const char *text)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_STR;
    v.u.str.ptr    = text;
    v.u.str.len    = (NxDword)strlen(text);
    return s_host->SetWidgetProp(ctx, 0, WID_NAME, NX_WP_VALUE, &v);
}

; checkbox.nxlay - an on/off switch.
[panel]
ref_w=40
ref_h=4

[w.1]
type=CHECKBOX
y=0
min_w=14
label=Enable output

/**
 * @file    checkbox.c
 * @brief   Reacting to a CHECKBOX and setting it from code.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match checkbox.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the CHECKBOX ([w.1] in checkbox.nxlay). */
#define WID_ENABLE 1

/**
 * @brief  Widget event handler.
 * @note   I2C Worker Thread, so ExecSync() is allowed here.
 */
void NX_CALL checkbox_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                       const NxWidgetEvent *evt)
{
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_ENABLE && evt->kind == NX_WEVT_CHANGED &&
        evt->val.kind == NX_WKIND_I64)
    {
        s_host->LogWrite(ctx, NX_LOG_INFO,
                         (evt->val.u.i64 != 0) ? "checkbox: on" : "checkbox: off");
    }
}

/**
 * @brief  Ticks or clears the box.
 * @param[in] on Non-zero = checked.
 */
NxLong checkbox_set(NxPluginCtx ctx, int on)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_I64;
    v.u.i64        = (on != 0) ? 1 : 0;
    return s_host->SetWidgetProp(ctx, 0, WID_ENABLE, NX_WP_VALUE, &v);
}

; dropdown.nxlay - pick one of up to 8 items; the items come from C.
[panel]
ref_w=40
ref_h=4

[w.1]
type=DROPDOWN
y=0
min_w=20
weight=1
item_count=3
label=Mode

/**
 * @file    dropdown.c
 * @brief   Filling a DROPDOWN with items and reading the chosen index.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match dropdown.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the DROPDOWN ([w.1] in dropdown.nxlay). */
#define WID_MODE 1

/** @brief The items, static because the host copies them during the call only. */
static const char *const s_items[3] = { "Off", "Slow", "Fast" };

/**
 * @brief  Call once from init() (UI Thread).
 * @return ERR_OK or an error code.
 * @note   NX_WP_ITEMS is a BLOB: one NxItemHead per item, followed by the item
 *         text, each record padded to a multiple of 4 bytes. At most 4096 items.
 *         The value of the widget is the item INDEX. The host copies the blob
 *         during the call only.
 */
NxLong dropdown_setup(NxPluginCtx ctx)
{
    unsigned char buf[3 * 24];
    NxPropVal     v;
    NxItemHead    h;
    NxDword       pos = 0;
    NxDword       rec;
    int           i;

    for (i = 0; i < 3; i++)
    {
        h.text_len   = (NxWord)strlen(s_items[i]);
        h.detail_len = 0;
        h.item_id    = (NxDword)i;
        h.flags      = 0;
        rec = ((NxDword)sizeof(h) + h.text_len + 3u) & ~3u;
        memset(buf + pos, 0, rec);
        memcpy(buf + pos, &h, sizeof(h));
        memcpy(buf + pos + sizeof(h), s_items[i], h.text_len);
        pos += rec;
    }
    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_BLOB;
    v.u.blob.ptr   = buf;
    v.u.blob.len   = pos;
    return s_host->SetWidgetProp(ctx, 0, WID_MODE, NX_WP_ITEMS, &v);
}

/**
 * @brief  Widget event handler: evt->val.u.i64 is the chosen index (0-based).
 */
void NX_CALL dropdown_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                       const NxWidgetEvent *evt)
{
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_MODE && evt->kind == NX_WEVT_CHANGED &&
        evt->val.kind == NX_WKIND_I64 && evt->val.u.i64 >= 0 && evt->val.u.i64 < 3)
    {
        s_host->LogWrite(ctx, NX_LOG_INFO, s_items[(int)evt->val.u.i64]);
    }
}

/**
 * @brief  Selects an item from code; index must be smaller than the item count.
 */
NxLong dropdown_select(NxPluginCtx ctx, NxDword index)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_I64;
    v.u.i64        = (NxI64)index;
    return s_host->SetWidgetProp(ctx, 0, WID_MODE, NX_WP_VALUE, &v);
}

; button.nxlay - an action button.
[panel]
ref_w=40
ref_h=4

[w.1]
type=BUTTON
y=0
min_w=12
label=Read

/**
 * @file    button.c
 * @brief   Reacting to a BUTTON press with a hardware read.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match button.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the BUTTON ([w.1] in button.nxlay). */
#define WID_READ 1

/**
 * @brief  Widget event handler.
 * @note   I2C Worker Thread: read the hardware right here with ExecSync().
 *         A BUTTON has no state; evt->val is the click position (ignored here).
 */
void NX_CALL button_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                     const NxWidgetEvent *evt)
{
    NxJobRequest req;
    NxByte       reg;

    NX_UNUSED_ARG(panel_id);
    if (widget_id != WID_READ || evt->kind != NX_WEVT_ACTIVATED)
    {
        return;
    }
    memset(&req, 0, sizeof(req));
    req.size_of_struct = (NxDword)sizeof(req);
    req.op     = NX_JOB_READ;
    req.offset = 0x00;
    req.length = 1;
    if (s_host->ExecSync(ctx, &req, &reg, (NxWord)sizeof(reg)) == ERR_OK)
    {
        s_host->LogWrite(ctx, NX_LOG_INFO, "button: read ok");
    }
}

; table.nxlay - a table of name/value rows.
; The list is as tall as the distance to the next row's y (here 6 rows:
; y=0..5); its own h is ignored.
[panel]
ref_w=40
ref_h=8

[w.1]
type=TABLE
y=0
min_w=24
weight=1
label=Registers

[w.2]
type=SEPARATOR
y=6
min_w=0
weight=1

/**
 * @file    table.c
 * @brief   Filling a TABLE with rows.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match table.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the TABLE ([w.1] in table.nxlay). */
#define WID_REGS 1

/**
 * @brief  Appends one record of an NX_WP_ROWS blob: an NxRowHead, the name, the
 *         value, padded to a multiple of 4 bytes.
 * @return The offset just after the record.
 */
static NxDword add_row(unsigned char *buf, NxDword pos, const char *name,
                       const char *value, NxDword style)
{
    NxRowHead h;
    NxDword   rec;

    h.name_len  = (NxWord)strlen(name);
    h.value_len = (NxWord)strlen(value);
    h.style     = style;
    rec = ((NxDword)sizeof(h) + h.name_len + h.value_len + 3u) & ~3u;
    memset(buf + pos, 0, rec);
    memcpy(buf + pos, &h, sizeof(h));
    memcpy(buf + pos + sizeof(h), name, h.name_len);
    memcpy(buf + pos + sizeof(h) + h.name_len, value, h.value_len);
    return pos + rec;
}

/**
 * @brief  Replaces all rows of the list.
 * @return ERR_OK; ERR_FULL when the blob is over the capacity limit: the whole
 *         batch is refused, never truncated.
 * @note   Any thread. NX_WP_ROWS is a BLOB of row records (NxRowHead + name +
 *         value). Row data is state: it does not rebuild the panel, so calling
 *         this from a poll is fine. Scrolling belongs to the host.
 */
NxLong table_fill(NxPluginCtx ctx)
{
    unsigned char buf[2 * 32];
    NxPropVal     v;
    NxDword       pos;

    pos = add_row(buf, 0, "REG[00]", "0x1A", (NxDword)NX_COLOR_DEFAULT);
    pos = add_row(buf, pos, "REG[01]", "0xFF", (NxDword)NX_COLOR_WARN);
    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_BLOB;
    v.u.blob.ptr   = buf;
    v.u.blob.len   = pos;
    return s_host->SetWidgetProp(ctx, 0, WID_REGS, NX_WP_ROWS, &v);
}

; separator.nxlay - a rule between two labels.
; A SEPARATOR needs weight (or min_w) to have any width.
[panel]
ref_w=40
ref_h=4

[w.1]
type=LABEL
y=0
min_w=20
label=Above

[w.2]
type=SEPARATOR
y=1
min_w=0
weight=1

[w.3]
type=LABEL
y=2
min_w=20
label=Below

; meter.nxlay - a read-only bar, num_max must not be 0.
[panel]
ref_w=40
ref_h=4

[w.1]
type=METER
y=0
min_w=20
weight=1
num_min=0
num_max=100
label=Loading

/**
 * @file    meter.c
 * @brief   Moving a METER bar.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match meter.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the METER ([w.1] in meter.nxlay). */
#define WID_LOADING 1

/**
 * @brief  Sets the bar; values outside num_min..num_max are clamped.
 * @param[in] percent 0..100 here because the declaration says num_max=100.
 * @note   Any thread. The bar is read-only for the user (no event), unless
 *         you declare flags=ACTIVATABLE.
 */
NxLong meter_set(NxPluginCtx ctx, NxDword percent)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_I64;
    v.u.i64        = (NxI64)percent;
    return s_host->SetWidgetProp(ctx, 0, WID_LOADING, NX_WP_VALUE, &v);
}

; spin.nxlay - an integer stepper, -10..10 in steps of 1.
[panel]
ref_w=40
ref_h=4

[w.1]
type=SPIN
y=0
min_w=14
num_min=-10
num_max=10
num_step=1
label=Gain

/**
 * @file    spin.c
 * @brief   Reading a SPIN as a signed number and setting it.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match spin.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the SPIN ([w.1] in spin.nxlay). */
#define WID_GAIN 1

/** @brief The last value the user chose. */
static long s_gain = 0;

/**
 * @brief  Widget event handler.
 * @note  evt->val is an NX_WKIND_I64: a SPIN value is already signed, no cast
 *         needed (the range here is -10..10).
 */
void NX_CALL spin_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                   const NxWidgetEvent *evt)
{
    NX_UNUSED_ARG(ctx);
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_GAIN && evt->kind == NX_WEVT_CHANGED &&
        evt->val.kind == NX_WKIND_I64)
    {
        s_gain = (long)evt->val.u.i64;
    }
}

/**
 * @brief  Sets the spin; the value is clamped to num_min..num_max.
 */
NxLong spin_set(NxPluginCtx ctx, long gain)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_I64;
    v.u.i64        = (NxI64)gain;
    return s_host->SetWidgetProp(ctx, 0, WID_GAIN, NX_WP_VALUE, &v);
}

; choice.nxlay - pick exactly one of 3 options; the options come from C.
[panel]
ref_w=40
ref_h=4

[w.1]
type=CHOICE
y=0
min_w=30
item_count=3
label=Speed

/**
 * @file    choice.c
 * @brief   Filling a CHOICE group and reading the chosen option.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match choice.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the CHOICE ([w.1] in choice.nxlay). */
#define WID_SPEED 1

/** @brief Option texts; a CHOICE group fills its options the same way as a DROPDOWN (NX_WP_ITEMS). */
static const char *const s_speeds[3] = { "Slow", "Normal", "Fast" };

/**
 * @brief  Call once from init() (UI Thread).
 * @return ERR_OK or an error code.
 * @note   NX_WP_ITEMS is a BLOB: one NxItemHead per item, followed by the item
 *         text, each record padded to a multiple of 4 bytes. At most 8 items.
 *         The value of the widget is the item INDEX. The host copies the blob
 *         during the call only.
 */
NxLong choice_setup(NxPluginCtx ctx)
{
    unsigned char buf[3 * 24];
    NxPropVal     v;
    NxItemHead    h;
    NxDword       pos = 0;
    NxDword       rec;
    int           i;

    for (i = 0; i < 3; i++)
    {
        h.text_len   = (NxWord)strlen(s_speeds[i]);
        h.detail_len = 0;
        h.item_id    = (NxDword)i;
        h.flags      = 0;
        rec = ((NxDword)sizeof(h) + h.text_len + 3u) & ~3u;
        memset(buf + pos, 0, rec);
        memcpy(buf + pos, &h, sizeof(h));
        memcpy(buf + pos + sizeof(h), s_speeds[i], h.text_len);
        pos += rec;
    }
    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_BLOB;
    v.u.blob.ptr   = buf;
    v.u.blob.len   = pos;
    return s_host->SetWidgetProp(ctx, 0, WID_SPEED, NX_WP_ITEMS, &v);
}

/**
 * @brief  Widget event handler: evt->val.u.i64 is the chosen option (0-based).
 */
void NX_CALL choice_on_event(NxPluginCtx ctx, NxByte panel_id, NxWord widget_id,
                    const NxWidgetEvent *evt)
{
    NX_UNUSED_ARG(panel_id);
    if (widget_id == WID_SPEED && evt->kind == NX_WEVT_CHANGED &&
        evt->val.kind == NX_WKIND_I64 && evt->val.u.i64 >= 0 && evt->val.u.i64 < 3)
    {
        s_host->LogWrite(ctx, NX_LOG_INFO, s_speeds[(int)evt->val.u.i64]);
    }
}

/**
 * @brief  Selects an option; index must be smaller than the number of options.
 */
NxLong choice_select(NxPluginCtx ctx, NxDword index)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_I64;
    v.u.i64        = (NxI64)index;
    return s_host->SetWidgetProp(ctx, 0, WID_SPEED, NX_WP_VALUE, &v);
}

; groupbox.nxlay - a frame around other widgets.
; h is mandatory. flags=DECORATION lets it overlap the widgets it frames.
[panel]
ref_w=40
ref_h=6

[w.1]
type=GROUPBOX
y=0
min_w=30
h=3
flags=DECORATION
label=Output

[w.2]
type=CHECKBOX
y=1
x=2
min_w=16
label=Enable

; chart.nxlay - a small bar chart; the samples come from C (0..65535).
; num_min/num_max define the vertical range.
[panel]
ref_w=40
ref_h=6

[w.1]
type=CHART
y=0
min_w=24
weight=1
h=3
num_min=0
num_max=100
label=Signal

/**
 * @file    chart.c
 * @brief   Feeding a CHART with samples.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match chart.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the CHART ([w.1] in chart.nxlay). */
#define WID_SIGNAL 1

/**
 * @brief  Replaces the samples (0..65535 each, at most 256).
 * @param[in] samples Array of count values; NULL clears the chart.
 * @param[in] count   Number of samples; more than 256 refuses the whole batch.
 * @return ERR_OK, ERR_NOT_FOUND, or ERR_FULL.
 * @note   NX_WP_SERIES is a BLOB: an NxSeriesHead (format, count) followed by
 *         the samples as 16-bit little-endian values, written byte by byte so
 *         it does not depend on the host's byte order. Samples are state and do
 *         not rebuild the panel. The bars are scaled by the declared
 *         num_min..num_max.
 */
NxLong chart_feed(NxPluginCtx ctx, const NxWord *samples, NxWord count)
{
    unsigned char buf[4 + 2 * NX_WSERIES_MAX_SAMPLES];
    NxPropVal     v;
    NxWord        i;

    if (samples == (const NxWord *)0)
    {
        count = 0;
    }
    if (count > NX_WSERIES_MAX_SAMPLES)
    {
        return ERR_FULL;
    }
    buf[0] = (unsigned char)NX_WSERIES_FMT_U16;
    buf[1] = 0;
    buf[2] = (unsigned char)(count & 0xFF);
    buf[3] = (unsigned char)((count >> 8) & 0xFF);
    for (i = 0; i < count; i++)
    {
        buf[4 + 2 * i]     = (unsigned char)(samples[i] & 0xFF);
        buf[4 + 2 * i + 1] = (unsigned char)((samples[i] >> 8) & 0xFF);
    }
    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_BLOB;
    v.u.blob.ptr   = buf;
    v.u.blob.len   = (count == 0) ? 0 : (NxDword)(4 + 2 * count);   /* zero length = no samples */
    return s_host->SetWidgetProp(ctx, 0, WID_SIGNAL, NX_WP_SERIES, &v);
}

; image.nxlay - a bitmap. aux is a plain file name (BMP or ICO) that lives
; next to the plugin DLL; no path separators, no "..".
[panel]
ref_w=40
ref_h=6

[w.1]
type=IMAGE
y=0
min_w=10
h=3
aux=logo.bmp

; filepick.nxlay - a file chooser; aux is the filter shown in the dialog.
[panel]
ref_w=40
ref_h=4

[w.1]
type=FILEPICK
y=0
min_w=24
weight=1
aux=*.bin
label=Firmware

/**
 * @file    filepick.c
 * @brief   Reading the path a user picked in a FILEPICK.
 *          A reading aid for the tutorial page "widget-types", not a complete
 *          plugin: the functions below would be wired into an IcPlugin
 *          (on_widget_event) or called from init()/a Worker callback.
 *
 * @note    ASCII-only and C89 on purpose (VC6 / CP950 safe, and it must pass
 *          the syntax-only guard). The widget ids match filepick.nxlay.
 */

#include <string.h>

#include "nexus_plugin_api.h"

/** @brief The HostAPI table, saved by init() (not shown here). */
static const NxHostApi *s_host = (const NxHostApi *)0;

/** @brief widget id of the FILEPICK ([w.1] in filepick.nxlay). */
#define WID_FIRMWARE 1

/**
 * @brief  Reads the currently chosen path.
 * @param[in]  ctx  This mount's context.
 * @param[out] path Receives the path (empty string when nothing was chosen).
 * @param[in]  cap  Capacity of path; 264 bytes always fit (the path is at most 263 bytes plus the NUL).
 * @return ERR_OK; ERR_BUFFER_TOO_SMALL; ERR_NOT_FOUND when the widget does not exist.
 * @note   The path is the VALUE of the widget (a string). Picking a file also
 *         sends NX_WEVT_CHANGED, but reading it on demand, for example in the
 *         handler of a "Start" button, is just as good.
 */
NxLong filepick_path(NxPluginCtx ctx, char *path, NxDword cap)
{
    NxPropVal out;
    NxDword   needed = 0;

    memset(&out, 0, sizeof(out));
    out.SizeOfStruct = (NxDword)sizeof(out);
    return s_host->GetWidgetProp(ctx, 0, WID_FIRMWARE, NX_WP_VALUE, &out, path, cap, &needed);
}

/**
 * @brief  Presets the path shown in the box (e.g. the last used file).
 */
NxLong filepick_preset(NxPluginCtx ctx, const char *path)
{
    NxPropVal v;

    memset(&v, 0, sizeof(v));
    v.SizeOfStruct = (NxDword)sizeof(v);
    v.kind         = (NxWord)NX_WKIND_STR;
    v.u.str.ptr    = path;
    v.u.str.len    = (NxDword)strlen(path);
    return s_host->SetWidgetProp(ctx, 0, WID_FIRMWARE, NX_WP_VALUE, &v);
}