GML-Syntax(5) - SerenityOS man pages

Name

GML Syntax

Description

Overview of the GML syntax.

Basic Syntax

For a start, GML can be thought of as a QML (Qt Markup Language) derivative. JSON is used as a sub-language in some places.

Each widget (or Core::Object, more generally) begins with @, with the name of the widget following. As this name refers to an actual C++ class, we need to include namespaces and separate them with :: as usual. To define the properties of this widget, we follow the object name with curly brackets and a list of properties.

// The base widget class, straight from LibGUI.
@GUI::Widget {

}
// Some other common classes:
@GUI::HorizontalBoxLayout {

}
// (for compactness)
@GUI::Button {}
@GUI::Label {}
@GUI::TabWidget {}

// If your application-specific widget is registered, you can do this:
@MyApplication::CoolWidget {

}

As seen above, C-style single line comments with // are possible.

Inside an object, we declare the properties of the object as well as all of its children. The children are other widgets, specified plainly, while the properties take the form key: value. For almost all properties, the value is a JSON value, and each property expects a different kind of value. The documentation for each widget object contains information about the supported properties, their possible values, and what the properties do. Quite some properties are common to all widgets, see GML-Widget(5).

// A 20x200 coolbar button with text.
@GUI::Button {
    width: 200
    height: 20
    text: "Operation failed successfully."
    button_style: "Coolbar"
}

// Two tabs, named "Tab 1" and "Tab 2", each containing a label.
@GUI::TabWidget {
    min_width: 150
    min_height: 200

    @GUI::Label {
        title: "Tab 1"
        text: "This is the first tab"
    }

    @GUI::Label {
        title: "Tab 2"
        text: "This is the second tab. What did you expect?"
    }
}

For layouting purposes, we use the special property layout which takes a layout object instead of a JSON value. The exact positioning of the children not only depends on the layout, but also on the container widget type. A widget's documentation contains information about such special cases if they exist.

// Make a frame that has two buttons horizontally laid out.
@GUI::Frame {
    min_height: 16
    min_width: 128

    layout: @GUI::HorizontalBoxLayout {
        // margin and spacing are frequent layouting properties.
        spacing: 5
    }
    @GUI::Button {
        text: "I'm the left button..."
    }
    @GUI::Button {
        text: "...and I'm the right button!"
    }
}

Properties

A property's value is required to be either a JSON value or another object. Objects are only used for a few special properties which are documented with the widgets that need them.

Among the supported JSON values, these types can be further distinguished:

Properties are never ended with ; or ,, and the property key is never enclosed in quotes or double quotes.

See also

Examples

GML files can be found in the SerenityOS source tree with the *.gml extension.

@GUI::Widget {
    name: "my_first_widget"
}
// A Browser window GML
@GUI::Widget {
    name: "browser"
    fill_with_background_color: true
    layout: @GUI::VerticalBoxLayout {}

    @GUI::HorizontalSeparator {
        name: "top_line"
        fixed_height: 2
        visible: false
    }

    @GUI::TabWidget {
        name: "tab_widget"
        container_margins: [0]
        uniform_tabs: true
        text_alignment: "CenterLeft"
    }
}
// A SystemMonitor GML (abbreviated)
// This makes use of quite some custom objects and properties.
@GUI::Widget {
    fill_with_background_color: true
    layout: @GUI::VerticalBoxLayout {}

    @GUI::Widget {
        layout: @GUI::VerticalBoxLayout {
            margins: [0, 4, 4]
        }

        @GUI::TabWidget {
            name: "main_tabs"

            @GUI::Widget {
                title: "Processes"
                name: "processes"

                @GUI::TableView {
                    name: "process_table"
                    column_headers_visible: true
                }
            }

            @GUI::Widget {
                title: "Performance"
                name: "performance"
                background_role: "Button"
                fill_with_background_color: true
                layout: @GUI::VerticalBoxLayout {
                    margins: [4]
                }

                @GUI::GroupBox {
                    title: "CPU usage"
                    name: "cpu_graph"
                    layout: @GUI::VerticalBoxLayout {}
                }

                @GUI::GroupBox {
                    title: "Memory usage"
                    fixed_height: 120
                    layout: @GUI::VerticalBoxLayout {
                        margins: [6]
                    }

                    @SystemMonitor::GraphWidget {
                        stack_values: true
                        name: "memory_graph"
                    }
                }

                @SystemMonitor::MemoryStatsWidget {
                    name: "memory_stats"
                    // A custom property that refers back up to the GraphWidget for the memory graph.
                    memory_graph: "memory_graph"
                }
            }

            @SystemMonitor::StorageTabWidget {
                title: "Storage"
                name: "storage"
                layout: @GUI::VerticalBoxLayout {
                    margins: [4]
                }

                @GUI::TableView {
                    name: "storage_table"
                }
            }

            @SystemMonitor::NetworkStatisticsWidget {
                title: "Network"
                name: "network"
            }
        }
    }

    @GUI::Statusbar {
        segment_count: 3
        name: "statusbar"
    }
}