Raven manual  [ Guide | XML | C API ]

XML reference

A window, or any part of one, can be written in XML. The XML only builds the tree of widgets: once loaded, every element is an ordinary widget, found with Rwidget_find and driven with the C API. Everything the XML says can also be said from C, and the other way round.

This page lists 44 tags of the library, 194 attributes of their own, and 102 attributes every widget can take. The tables come from the library itself (Rxml_get_attribute_info), so they are exactly what the loader understands.

Contents

1. Loading a document
2. Rules of the syntax
3. Kinds of values
4. Actions
5. Attributes every widget has — widget · slot · colors · metrics
6. Windows and their shell — Window · HeaderBar · DockArea · Island · MenuBar · Menu · MenuItem
7. Panels — VBox · HBox · Grid · UniformGrid · Overlay · Border · SizeBox · Spacer · ScrollBox · Splitter · WrapBox · Canvas · Switcher · TabView · Expander · BackgroundBlur
8. Controls — Label · Button · Checkbox · Slider · ProgressBar · Image · TextInput · SpinBox · ComboBox · Separator · ListView · TreeView · TileView · TextEditor
9. Tools — ColorPicker · Timeline · NodeGraph · BlockEditor · FileBrowser · Viewport · Custom
10. Elements that are not widgets
11. Translations
12. Markdown
13. Declaring tags
14. Files that are loaded again
15. Tags made by code; WebView
16. Documents, for tools
17. Compiled XML (XMLC)

1. Loading a document

Rid window = Rwindow_create_from_xml_file("editor.xml");        /* the root is <Window> */
Rid panel  = Rwidget_create_from_xml(text, strlen(text));       /* any widget as the root */
Rid other  = Rwindow_create_from_xml(text, strlen(text));       /* a <Window> given as text */

Rid save = Rwidget_find(window, "save");                        /* Name="save" */
Rbutton_set_text(save, "Save all");
Rwidget_set_attribute(save, "Style", "Primary");                /* any attribute, as text */

A document read from a file is watched: when it is saved, the window follows (see Files that are loaded again). A text given from memory is not. Paths written in a document given as text are relative to Rxml_set_base_path.

A complete small window:

<Window Title="Tool" Width="800" Height="500">
    <Shortcut Keys="Ctrl+S" Action="file.save"/>
    <VBox Spacing="8" Slot.Padding="12">
        <Label TextSize="18">Settings</Label>
        <HBox Spacing="8">
            <TextInput Name="path" Placeholder="Folder..." Slot.Fill="1"/>
            <Button Text="Save" Style="Primary" OnClicked="file.save"/>
        </HBox>
        <ListView Name="files" Slot.Fill="1"/>
    </VBox>
</Window>

2. Rules of the syntax

• Tags are widget types; attributes are their properties. Names of tags and attributes are not case sensitive.
• Elements, attributes, text, comments, CDATA, the five entities (& < > " ') and numeric character references are understood. Files are UTF-8. There is no DTD and no namespace.
• Inside an attribute, < and & are written < and &: If="{Count < 3}".
• The text inside an element is its Text attribute: <Label>Hello</Label> is <Label Text="Hello"/>.
• Children are created first, then the attributes of their parent are applied, so Selected="1" or ActiveTab="2" can refer to children.
• An unknown tag or attribute, or a wrong value, is reported through the error callback (R_ERROR_XML, with its line and column) and loading goes on.
• Paths (Source, Font, Background...) are relative to the file, and a file is loaded once and shared by every widget that names it.
• Lengths are logical units: they are multiplied by the scale of the monitor.

3. Kinds of values

4. Actions

A widget has one action, the name of what its main event does. Action, OnClicked, OnChanged, OnCommitted and OnActivated are five spellings of it, kept for readability.

static void on_save(Rid sender, const char* action, void* user_data) {
    /* sender: the widget, action: "file.save" */
}

Raction_bind("file.save", on_save, NULL);
Raction_set_default_handler(on_any_action, NULL);   /* everything that has no binding of its own */
Raction_fire("file.save", R_INVALID_ID);            /* as if a widget had fired it */

The typed callbacks of the C API (Rbutton_set_clicked_callback, Rtext_input_set_changed_callback for every keystroke, Rlist_view_set_selection_changed_callback...) work beside actions and cover the other events.

5. Attributes every widget has

Every tag below also takes these. The slot attributes are read by the parent: each panel uses those that make sense for it (a VBox reads Slot.Fill and Slot.HAlign, a Grid reads Slot.Column...). The color and metric attributes override the theme for the widget and what it contains; with a glass theme, the alpha of a color is the strength of the tint of the glass (Color.Control="#FF375F60" is a pink glass button).

Attributes of every widget

Slot attributes: the place of a widget in its parent

Color attributes: Color.<Role>

Metric attributes: Metric.<Name>

Which panel reads which slot attribute

6. Windows and their shell

<Window> is only a root, read by Rwindow_create_from_xml_file and Rwindow_create_from_xml. It holds one widget, its content; optionally an <Island> that floats at its top; any number of <Shortcut> and <Widget> declarations.

<Window Title="Tool" Width="1100" Height="720" CustomHeader="true" Theme="GlassDark">
    <Shortcut Keys="Ctrl+S" Action="file.save"/>
    <Island>
        <Label Text="Ready"/>                                <!-- folded   -->
        <VBox Spacing="6" Slot.Padding="12">                 <!-- unfolded -->
            <Label Text="Build finished"/>
            <Button Text="Run" OnClicked="run"/>
        </VBox>
    </Island>
    <VBox>
        <HeaderBar>
            <MenuBar>
                <Menu Text="File">
                    <MenuItem Text="Open..." Shortcut="Ctrl+O" OnClicked="file.open"/>
                    <Separator/>
                    <MenuItem Text="Quit" Shortcut="Ctrl+Q" OnClicked="app.quit"/>
                </Menu>
            </MenuBar>
            <Button Text="Run" Style="Primary" Slot.HAlign="Right" OnClicked="run"/>
        </HeaderBar>
        <DockArea Slot.Fill="1">
            <TextEditor Name="code" Slot.Title="main.c" Language="C" LineNumbers="true"/>
            <TreeView Name="files" Slot.Title="Files" Slot.Dock="Left" Slot.DockSize="0.22"/>
            <TextEditor Name="log" Slot.Title="Output" Slot.Dock="Bottom" Slot.DockSize="0.3" ReadOnly="true"/>
        </DockArea>
    </VBox>
</Window>

A MenuItem with a Shortcut works without a <Shortcut> element: the window looks in its menus when keys are pressed. In a window with CustomHeader, the HeaderBar draws the title and the window buttons; dragging it moves the window, and any widget with WindowDrag="true" does the same.

<Window>

A window; it contains one element, and optionally an Island and Shortcut elements.

<HeaderBar>

The title bar of a window with a custom header; holds any widgets. (also written TitleBar; any number of child widgets)

<DockArea>

Panels the user arranges by dragging their tabs. (any number of child widgets)

<Island>

A pill at the top of the window that unfolds: first child folded, second unfolded. (also written Notch, DynamicIsland; any number of child widgets)

<MenuBar>

A bar of Menu elements. (any number of child widgets)

No attribute of its own: those of every widget and of its slot.

<Menu>

A menu: MenuItem, Separator and Menu elements. (any number of child widgets)

<MenuItem>

An item of a menu. (no child widget)

7. Panels

Panels place their children; how each child is placed is written on the child, in its slot (slot attributes).

<Grid Columns="auto,1" Rows="auto,auto,1" Spacing="8">
    <Label Text="Name"/>          <TextInput Slot.Column="1"/>
    <Label Text="Notes" Slot.Row="1"/>
    <TextEditor Slot.Row="1" Slot.Column="1" Slot.RowSpan="2" Height="120"/>
</Grid>

<Canvas>
    <!-- pinned to the bottom right corner, 16 units from it -->
    <Button Text="Help" Slot.Anchors="1,1" Slot.Alignment="1,1" Slot.Position="-16,-16"/>
    <!-- stretched over the whole width, 40 high -->
    <Border Background="#202020" Slot.Anchors="0,0,1,0" Slot.Size="0,40"/>
</Canvas>

<Splitter MinPaneSize="120">
    <TreeView Slot.Fill="1"/>
    <TextEditor Slot.Fill="3"/>
</Splitter>

<Border Padding="16" CornerRadius="14" Shadow="24,0,8" Material="FrostedGlass">
    <Label Text="On glass"/>
</Border>

<Border Effect="aurora" CornerRadius="18" Height="160">
    <Label Text="Tonight" TextSize="24" Slot.Padding="16" Slot.VAlign="Bottom"/>
</Border>

<VBox>

Stacks its children from top to bottom. (also written VerticalBox; any number of child widgets)

<HBox>

Lines its children up from left to right. (also written HorizontalBox; any number of child widgets)

<Grid>

Places its children in rows and columns (Slot.Column, Slot.Row). (also written GridPanel; any number of child widgets)

<UniformGrid>

Cells of the same size, filled in order. (also written UniformGridPanel; any number of child widgets)

<Overlay>

Puts its children on top of each other. (any number of child widgets)

No attribute of its own: those of every widget and of its slot.

<Border>

A surface with padding around one child. (one child widget)

<SizeBox>

Gives one child a size or a shape. (also written Box; one child widget)

<Spacer>

Empty space. (no child widget)

No attribute of its own: those of every widget and of its slot.

<ScrollBox>

Scrolls content that is larger than its place. (any number of child widgets)

<Splitter>

Panes separated by bars the user drags. (any number of child widgets)

<WrapBox>

Lines its children up and continues on the next line. (any number of child widgets)

<Canvas>

Places its children freely (Slot.Position, Slot.Size, Slot.Anchors). (also written CanvasPanel; any number of child widgets)

No attribute of its own: those of every widget and of its slot.

<Switcher>

Shows one of its children. (also written WidgetSwitcher; any number of child widgets)

<TabView>

Its children as tabs (Slot.Title). (also written Tabs; any number of child widgets)

<Expander>

A header that shows and hides one child. (also written ExpandableArea; one child widget)

<BackgroundBlur>

A panel that shows what is behind it out of focus, around one child. (one child widget)

8. Controls

<VBox Spacing="8">
    <Label Markdown="true" Wrap="true">**Bold**, *italic* and a [link](https://example.org).</Label>
    <Button Text="Delete" Class="danger" Tooltip="Deletes the file" OnClicked="file.delete"/>
    <Checkbox Text="Dark mode" Style="Switch" Checked="true" OnChanged="view.dark"/>
    <HBox Spacing="6">
        <Checkbox Text="Small" Style="Radio"/>
        <Checkbox Text="Large" Style="Radio" Checked="true"/>
    </HBox>
    <Slider Min="0" Max="100" Value="40" Step="5" OnChanged="volume"/>
    <SpinBox Min="0" Max="10" Value="2.5" Step="0.1" Decimals="1"/>
    <TextInput Name="email" Placeholder="you@example.com" OnCommitted="send"/>
    <ComboBox Items="Small|Medium|Large" Selected="1"/>
    <ListView Height="120">
        <Item Text="First"/>
        <Item Text="Second"/>
    </ListView>
    <TreeView Height="140">
        <Item Text="src" Expanded="true">
            <Item Text="main.c"/>
        </Item>
    </TreeView>
    <Image Source="logo.png" Width="64" Height="64" Stretch="Fit"/>
    <ProgressBar Value="0.6"/>
    <TextEditor Language="Python" LineNumbers="true" Height="200">print("hello")</TextEditor>
</VBox>

<Label>

Text. (also written Text, TextBlock; no child widget)

<Button>

A button, with a text or with one child. (one child widget)

<Checkbox>

A box to check, a radio button or a switch. (also written CheckBox; no child widget)

<Slider>

A value chosen by dragging. (no child widget)

<ProgressBar>

How far something is. (no child widget)

<Image>

A picture. (no child widget)

<TextInput>

One line of text to type. (also written TextBox, EditableText; no child widget)

<SpinBox>

A number to type or to step. (no child widget)

<ComboBox>

One choice in a list that drops down. (no child widget)

<Separator>

A line between things. (no child widget)

<ListView>

Rows of text, one selected; any number of them. (no child widget)

<TreeView>

Rows inside rows, made of Item elements. (no child widget)

<TileView>

A grid of tiles, an icon over a name, given by the application (Rtile_view_set_items). (no child widget)

<TextEditor>

Text of several lines: notes, code. (also written TextArea; no child widget)

9. Tools

<NodeGraph Name="graph" FrameAll="true">
    <Type Name="number" Color="#64D2FF"/>
    <Node Name="noise" Title="Noise" X="40" Y="60" Color="#FF9F0A">
        <Output Name="value" Label="Value" Type="number"/>
        <Slider Value="0.4" Width="150"/>
    </Node>
    <Node Name="blend" Title="Blend" X="320" Y="90">
        <Input Name="a" Label="A" Type="number"/>
    </Node>
    <Link From="noise.value" To="blend.a"/>
</NodeGraph>

<Timeline Duration="12" FrameRate="24" Height="180">
    <Track Name="Camera" Color="#0A84FF">
        <Clip Start="0" Length="3.5" Label="Wide shot"/>
        <Key Time="6"/>
    </Track>
    <Marker Time="4" Label="Intro"/>
</Timeline>

<ColorPicker Color="#3B82F6" Popup="true" Swatches="#FF453A, #0A84FF, white" OnChanged="color"/>

<BlockEditor Height="320">
    <Category Name="Events" Color="#FFBF00"/>
    <Category Name="Control" Color="#FFAB19"/>
    <Kind Name="start" Label="when started" Shape="Hat" Category="Events"/>
    <Kind Name="repeat" Label="repeat %n{10}" Shape="C" Category="Control"/>
</BlockEditor>

<FileBrowser Mode="Open" Filter="*.png;*.jpg" Height="360"/>

<ColorPicker>

Chooses a color: square, hues, opacity, code, numbers, swatches. (no child widget)

<Timeline>

A sequencer: Track elements holding Clip and Key elements, and Marker elements. (no child widget)

<NodeGraph>

Nodes linked by wires: Node elements (Input, Output, any widget), Link and Type elements. (no child widget)

<BlockEditor>

Blocks that snap into each other (Scratch): Kind elements (Name, Label, Shape, Category) and Category elements (Name, Color). (no child widget)

<FileBrowser>

Folders and files to choose from. (no child widget)

<Viewport>

A place the application draws in with its own renderer. (no child widget)

<Custom>

A widget painted and measured by the application. (any number of child widgets)

No attribute of its own: those of every widget and of its slot.

10. Elements that are not widgets

11. Translations

<Window Title="@app.title">
    <Strings Source="strings.csv"/>
    <VBox Spacing="8" Slot.Padding="16">
        <Label Text="@greeting"/>
        <Button Text="@menu.file" Tooltip="@menu.file.tip"/>
    </VBox>
</Window>

key,en,fr
app.title,Notes,Notes
greeting,Hello!,Bonjour !
menu.file,File,Fichier
menu.file.tip,Open and save files,Ouvrir et enregistrer

A text that starts with @ is a key: the widget shows the text of the language in use and follows it when the language changes (Rlocale_set_language). @@ writes a text that starts with @. The guide has everything about translations.

12. Markdown

<Label Markdown="true" Wrap="true">
    ## Notes
    Some **strong** and *emphasized* text, ~~struck~~, `code`,
    a [link](https://example.org) and an [action](action:file.open).

    - a list
    - [x] with a box

    | Key | Value |
    |-----|-------|
    | a   | 1     |
</Label>
<TextEditor Markdown="true"/>

On a Label the text is rendered: headings, strong, emphasis, struck, code, links, lists (nested, numbered, with boxes), quotes, code blocks (colored when they name a language of the text editor), tables, rules, line breaks and images (![description](path) on a line of its own; the path is relative to the document, or an https:// address loaded in the background). The text may be indented with the document; <![CDATA[ ... ]]> avoids escaping < and &. A link opens in the browser of the system; action:name fires an action; Rlabel_set_link_callback receives them all instead. On a TextEditor the text stays as typed and is styled where it stands.

13. Declaring tags

A document can declare its own tags. A <Widget> names a piece of interface, with parameters, and is then used like any tag of the library:

<Widget Name="Field" Label="Name" Hint="" Wide="false">
    <HBox Spacing="8">
        <Label Text="{Label}:" Width="{Wide ? 140 : 90}"/>
        <TextInput Placeholder="{Hint}" Slot.Fill="1"/>
        <Children/>
    </HBox>
</Widget>

<Field Label="Email" Hint="you@example.com" Name="email"/>
<Field Label="Password" Wide="true"><Button Text="Show"/></Field>

<Widget Name="Card" Title="">
    <Border Class="card" Padding="14">
        <VBox Spacing="6">
            <Label Text="{Title}" TextSize="17" If="{!empty(Title)}"/>
            <Children/>
            <HBox Spacing="6"><Children Name="footer"/></HBox>
        </VBox>
    </Border>
</Widget>

<Card Title="Upload">
    <Label Text="Drop files here"/>
    <Button Text="Send" Into="footer"/>
</Card>

<Repeat Count="3" Var="i">
    <Checkbox Text="Option {i + 1}"/>
</Repeat>
<ForEach Items="Red|Green|Blue" Var="c" Index="n">
    <Button Text="{n}: {c}" OnClicked="color.{lower(c)}"/>
</ForEach>
<Include Source="parts/toolbar.xml"/>

• The attributes of <Widget> other than Name are its parameters, with their default values. It contains exactly one element: what the tag stands for.
• Inside it, {...} is computed and replaced by its value; {{ and }} write a brace.
• Where the tag is used, the attributes that are parameters give their values; the others (Name, Slot.Fill, OnClicked, Material...) go to the element the tag stands for. The text inside the tag is its Text.
• <Children/> is replaced by the children given where the tag is used; <Children Name="footer"/> by those marked Into="footer".
• A declaration is known from the moment it is read until the library shuts down, in every document loaded afterwards. Declaring a name again replaces it. It cannot take the name of a tag of the library, and it cannot use itself.
• <Widgets> is the root of a file that only holds declarations. From C: Rxml_register_widgets, Rxml_register_widgets_from_file, Rxml_get_registered_widget_name.

Expressions. Numbers, texts between single quotes, parameters and variables; + - * / % (+ joins texts), == != < <= > >=, && || !, a ? b : c, parentheses; min(a, b), max(a, b), round, floor, ceil, abs, len(text), upper, lower, empty(text), default(value, fallback); {Instance} is a number that differs for each use of a tag (for unique names). False is false, 0 and the empty text. {...} is only computed inside a <Widget>, a <Repeat> or a <ForEach>: elsewhere braces are ordinary characters.

14. Files that are loaded again

What is created from a file (Rwindow_create_from_xml_file, Rwidget_create_from_xml_file, the files they include, the files of Rxml_register_widgets_from_file, the theme files, the CSV tables) is watched while the application runs. Save the file in any editor and the interface follows:

• an element still in the file keeps its widget: its handle, its callbacks, what was typed, scrolled or selected; only the attributes that changed are set again;
• elements are matched by Name, else by content, else by position among those of the same tag; new ones are built, those that are gone are deleted;
• a widget that manages its own content (ComboBox, Timeline, NodeGraph, menus...) is built again when what is inside it changes;
• a file with a mistake changes nothing and the error is reported.

static void on_reload(const char* path, int ok, void* user) {
    if (ok) g_status = Rwidget_find(g_window, "status");   /* widgets built again have new handles */
}
Rxml_set_reload_callback(on_reload, NULL);
Rxml_set_live_reload(R_FALSE);       /* a shipped application; or RAVEN_LIVE_RELOAD=0 */
Rxml_check_files();                  /* look now (else five times a second) */

15. Tags made by code; WebView

static Rid make_gauge(const char* tag, void* user) {
    Rid gauge = Rwidget_create(R_WIDGET_CUSTOM);
    Rcustom_set_paint_callback(gauge, paint_gauge, NULL);
    return gauge;
}

static int gauge_attribute(Rid widget, const char* name, const char* value, void* user) {
    if (strcmp(name, "Level") != 0) return R_FALSE;   /* not mine: Name, Width, Slot... are left to Raven */
    set_level(widget, (float)atof(value));
    return R_TRUE;
}

Rxml_register_tag("Gauge", make_gauge, gauge_attribute, NULL);
/* then, in any document:  <Gauge Level="0.7" Width="120" Height="24"/> */

Rxml_resolve_path gives the path of a file named in the document being loaded; Rwidget_set_destroy_callback tells when the widget is gone. <WebView> of raven_web.h is such a tag, registered by Rweb_register_xml:

<WebView Name="docs" Url="https://example.org" Slot.Fill="1" OnChanged="docs.navigated"/>
<WebView Source="pages/help.html" Zoom="1.25"/>
<WebView Frames="Jpeg" Quality="80"><![CDATA[<h1>Hello</h1><p>From <b>HTML</b>.</p>]]></WebView>

16. Documents, for tools

Rxml_document_parse reads a text into a tree of nodes that can be changed, written back with its comments (Rxml_document_to_string) and built (Rxml_document_create_widget, Rxml_document_create_window). A widget built from a document knows its node (Rwidget_get_xml_node), and a node its widget (Rxml_node_get_widget). Rxml_get_tag_count, Rxml_get_tag_name, Rxml_get_attribute_count and Rxml_get_attribute_info list the tags and their attributes: the tables of this page as data. The IDE is built on these functions.

RXmlError error;
Rid doc = Rxml_document_parse(text, strlen(text), &error);
if (doc == R_INVALID_ID) {
    printf("line %d, column %d: %s\n", error.line, error.column, error.message);
} else {
    Rid root = Rxml_document_get_root(doc);
    Rid button = Rxml_node_add_child(root, "Button", -1);      /* at the end */
    Rxml_node_set_attribute(button, "Text", "Added");
    Rid preview = Rxml_document_create_widget(doc);
    puts(Rxml_document_to_string(doc));
    Rxml_document_destroy(doc);                                /* what was built lives on */
}

/* every attribute of a tag, as the loader knows it */
int i, n = Rxml_get_attribute_count("Button");
for (i = 0; i < n; i++) {
    RXmlAttributeInfo info;
    Rxml_get_attribute_info("Button", i, &info);
    printf("%-20s %s\n", info.name, info.description);
}

17. Compiled XML (XMLC)

A document can be written next to its code in one file (.xmlc for C, .xmlrs for Rust, .xmlpy for Python...): ravenc turns the XML into tables of your language, built by Rwindow_create_from_compiled, and OnClicked="{on_save}" calls a function of the scripts. Everything on this page works the same compiled. See XMLC in the guide.

Raven 0.1 — Apache License 2.0 — raven home · source