fltk-decl

Use a declarative language (json5, json, yaml, xml, toml, s-exp) to describe your fltk-rs gui, with support for hot-reloading of your gui file. The crate is designed to be as permissive as possible. So wrong keys or values will be ignored. Normally only changing a widget's id at runtime would cause an error!

Usage

Using a fixed format, using features

Assuming we're using json for our gui description, we'll pull fltk-decl and fltk. We'll specify the feature that we need to be json since we're using json. In your Cargo.toml:

[dependencies]
fltk-decl = { version = "0.2", features = ["json"] }
fltk = "1.3.32"

For other formats, replace the json feature with your required feature. Possible values (json, json5, yaml, xml).

Since we're gonna use json, we'll create a json file and let's call it gui.json:

{
    "$schema": "https://raw.githubusercontent.com/MoAlyousef/fltk-decl/main/schemas/fltk-schema.json",
    "widget": "Column",
    "children": [
        {
            "widget": "Button",
            "label": "Inc",
            "fixed": 60,
            "id": "inc",
            "labelcolor": "#0000ff"

        },
        {
            "widget": "Row",
            "children": [
                {
                    "widget": "Frame",
                    "fixed": 30
                },
                {
                    "widget": "Frame",
                    "label": "0",
                    "id": "result",
                    "labelcolor": "#ff0000"
                },
                {
                    "widget": "Frame",
                    "fixed": 30
                }
            ]
        },
        {
            "widget": "Button",
            "label": "Dec",
            "fixed": 60,
            "id": "dec"
        }
    ]
}

Notice we point to the schema to get auto-completion and hinting on vscode, otherwise it's optional.

Import it into your app:

use fltk_decl::{DeclarativeApp, Widget};

fn main() {
    // use the filetype and extension that you require.
    // `run` a callback that runs at least once, or whenever the gui file changes.
    DeclarativeApp::new_json(200, 300, "MyApp", "examples/gui.json").run(|_| {}).unwrap();
}

Notice we use new_json which is made available by the json feature. The constructor comes in the form of DeclarativeApp::new or DeclarativeApp::new_<feature>, ex. new_json5, new_yaml, new_xml!

To handle callbacks:

use fltk::{prelude::*, *};
use fltk_decl::{DeclarativeApp, Widget};

// use the extension you require!
const PATH: &str = "examples/gui.json";

#[derive(Clone, Copy)]
struct State {
    count: i32,
}

impl State {
    pub fn increment(&mut self, val: i32) {
        let mut result: frame::Frame = app::widget_from_id("result").unwrap();
        self.count += val;
        result.set_label(&self.count.to_string());
    }
}

fn btn_cb(b: &mut button::Button) {
    let state = app::GlobalState::<State>::get();
    let val = if b.label() == "Inc" {
        1
    } else {
        -1
    };
    state.with(move |s| s.increment(val));
}

fn main() {
    app::GlobalState::new(State { count: 0 });
    DeclarativeApp::new_json(200, 300, "MyApp", PATH)
        .run(|_win| {
            app::set_scheme(app::Scheme::Oxy);
            if let Some(mut btn) = app::widget_from_id::<button::Button>("inc") {
                btn.set_callback(btn_cb);
            }
            if let Some(mut btn) = app::widget_from_id::<button::Button>("dec") {
                btn.set_callback(btn_cb);
            }
        })
        .unwrap();
}

Flexible, using any serde format and using a loading function (requires no features)

Assuming we're using json for our gui description, we'll pull fltk-decl, fltk and the deserialization library that we require, in this case it's serde_json: In your Cargo.toml:

[dependencies]
fltk-decl = "0.2"
fltk = "1.3.32"
serde_json = "1"

For the other data formats, you can pull the respective deserialization library:

serde_json5 = "0.1" # for json5
serde-xml-rs = "0.6" # for xml
serde_yaml = "0.9" # for yaml
toml = "0.7" # for toml
serde-lexpr = "0.1.2" # for an s-expression description

Since we're gonna use json, we'll create a json file and let's call it gui.json:

{
    "$schema": "https://raw.githubusercontent.com/MoAlyousef/fltk-decl/main/schemas/fltk-schema.json",
    "widget": "Column",
    "children": [
        {
            "widget": "Button",
            "label": "Inc",
            "fixed": 60,
            "id": "inc",
            "labelcolor": "#0000ff"

        },
        {
            "widget": "Row",
            "children": [
                {
                    "widget": "Frame",
                    "fixed": 30
                },
                {
                    "widget": "Frame",
                    "label": "0",
                    "id": "result",
                    "labelcolor": "#ff0000"
                },
                {
                    "widget": "Frame",
                    "fixed": 30
                }
            ]
        },
        {
            "widget": "Button",
            "label": "Dec",
            "fixed": 60,
            "id": "dec"
        }
    ]
}

Notice we point to the schema to get auto-completion and hinting on vscode, otherwise it's optional.

Import it into your app:

use fltk_decl::{DeclarativeApp, Widget};

// declare how you would like to deserialize
fn load_fn(path: &'static str) -> Option<Widget> {
    let s = std::fs::read_to_string(path).ok()?;
    // We want to see the serde error on the command line while we're developing
    serde_json5::from_str(&s).map_err(|e| eprintln!("{e}")).ok()
}

fn main() {
    // use the filetype and extension that you require.
    // `run` a callback that runs at least once, or whenever the gui file changes.
    DeclarativeApp::new(200, 300, "MyApp", "examples/gui.json", load_fn).run(|_| {}).unwrap();
}

To handle callbacks:

use fltk::{prelude::*, *};
use fltk_decl::{DeclarativeApp, Widget};

// use the extension you require!
const PATH: &str = "examples/gui.json";

#[derive(Clone, Copy)]
struct State {
    count: i32,
}

impl State {
    pub fn increment(&mut self, val: i32) {
        let mut result: frame::Frame = app::widget_from_id("result").unwrap();
        self.count += val;
        result.set_label(&self.count.to_string());
    }
}

fn btn_cb(b: &mut button::Button) {
    let state = app::GlobalState::<State>::get();
    let val = if b.label() == "Inc" {
        1
    } else {
        -1
    };
    state.with(move |s| s.increment(val));
}

fn load_fn(path: &'static str) -> Option<Widget> {
    let s = std::fs::read_to_string(path).ok()?;
    serde_json5::from_str(&s).map_err(|e| eprintln!("{e}")).ok()
}

fn main() {
    app::GlobalState::new(State { count: 0 });
    DeclarativeApp::new(200, 300, "MyApp", PATH, load_fn)
        .run(|_win| {
            app::set_scheme(app::Scheme::Oxy);
            if let Some(mut btn) = app::widget_from_id::<button::Button>("inc") {
                btn.set_callback(btn_cb);
            }
            if let Some(mut btn) = app::widget_from_id::<button::Button>("dec") {
                btn.set_callback(btn_cb);
            }
        })
        .unwrap();
}

Other data formats:

You can choose json5 (to benefit from comments, trailing commas and unquoted keys!):

{
    // main column
    widget: "Column",
    children: [
        {
            // our button
            widget: "Button",
            label: "Click me",
            color: "#ff0000",
            id: "my_button",
        }
    ],
}

However, you lose vscode's auto-completion since json5 extensions in vscode don't support schemas.

You could also use yaml (optionally along with a schema for autocompletion and validation):

# yaml-language-server: $schema=https://raw.githubusercontent.com/MoAlyousef/fltk-decl/main/schemas/fltk-schema.yaml

widget: Column
children:
- widget: Button
  label: Inc
  fixed: 60
  id: inc
  labelcolor: "#0000ff"
- widget: Row
  children:
  - widget: Frame
    fixed: 30
  - widget: Frame
    label: '0'
    id: result
    labelcolor: "#ff0000"
  - widget: Frame
    fixed: 30
- widget: Button
  label: Dec
  fixed: 60
  id: dec

You could also use xml: gui.xml

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <widget>Column</widget>
    <children>
        <widget>Button</widget>
        <label>Click Me</label>
        <id>my_button</id>
        <labelcolor>#0000ff</labelcolor>
    </children>
</root>

or toml!

widget = "Column"

[[children]]
widget = "Button"
label = "Click Me"
id = "my_button"

or s-expression format:

(
    (widget . "Column") 
    (children (
        (
            (widget . "Button") 
            (label "Inc") 
            (id "inc") 
            (fixed 60) 
            (labelcolor "#0000ff")
        )
        (
            (widget . "Frame")
            (id "result")
            (label "0")
        )
        (
            (widget . "Button") 
            (label "Dec") 
            (id "dec") 
            (fixed 60) 
            (labelcolor "#ff0000")
        )
    ))
)

Supported properties:

• widget: (Required) The widget type (string)
• label: The widget label (string)
• fixed: Whether the widget is fixed inside a Flex (integer)
• x: x coordinate
• y: y coordinate
• w: width
• h: height
• margin: A flex's margin
• left: A flex's left margin
• top: A flex's top margin
• right: A flex's right margin
• bottom: A flex's bottom margin
• id: The widget's id (string)
• labelcolor: The widget's label color (string, format #xxxxxx)
• color: The widget's color (string, format #xxxxxx)
• selectioncolor: The widget's selection color (string, format #xxxxxx)
• hide: Whether the widget is hidden (bool)
• visible: Whether the widget is visible (bool)
• deactivate: Whether the widget is deactivated (bool)
• resizable: Whether the widget is the resiable widget in a group (bool)
• tooltip: The widget's tooltip (string)
• image: A path to an image for the widget (string)
• deimage: A path to an image (deactivated) for the widget (string)
• labelfont: The label font (integer)
• labelsize: The label size (integer)
• align: The label's alignment (integer)
• when: The widget's callback trigger (integer)
• frame: The widget's frame type (string)
• downframe: The widget's down_frame type, for buttons (string)
• shortcut: The widget's shortcut, for buttons (string)
• pad: The Flex's padding (integer)
• minimun: The valuator's minimum value (floating point number)
• maximum: The valuator's maximum value (floating point number)
• slidersize: The valuator's slider size (floating point number)
• step: The valuator's step (floating point number)
• textcolor: The widget's text color (string)
• textsize: The widget's text size (integer)
• textfont: The widget's font (integer)
• children: an array of widgets representing the children of the widget (array of objects)

Supported widgets:

• Column (Flex column)
• Row (Flex row)
• Button
• CheckButton
• RadioButton
• ToggleButton
• RadioRoundButton
• ReturnButton
• Frame
• Group
• Pack
• Tile
• Tabs
• Scroll
• ColorChooser
• TextDisplay
• TextEditor
• Input
• IntInput
• FloatInput
• SecretInput
• FileInput
• MultilineInput
• Output
• MultilineOutput
• MenuBar
• SysMenuBar
• Choice
• Slider
• NiceSlider
• FillSlider
• ValueSlider
• Dial
• LineDial
• FillDial
• Counter
• Scrollbar
• Roller
• Adjuster
• ValueInput
• ValueOutput
• HorSlider
• HorNiceSlider
• HorFillSlider
• HorValueSlider
• Browser
• SelectBrowser
• HoldBrowser
• FileBrowser
• CheckBrowser
• MultiBrowser
• Table
• TableRow
• Tree
• Spinner
• Chart
• Progress
• InputChoice
• HelpView
• Window
• MenuWindow
• GlutWindow (requires the enable-glwindow feature)