RGBCube/serenity
1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-27 08:27:46 +00:00
Code Issues Activity Actions

Base: Move GML documentation into subsection

Browse source 
That was the whole point of this endeavour :^)
This commit is contained in:
kleines Filmröllchen 2022-12-14 17:13:22 +01:00 • committed by Andrew Kaster
parent f824a67b3b
commit ad6cbc4192
54 changed files with 89 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

14
Base/usr/share/man/man5/GML/CoreObject.md Normal file
View file

@ -0,0 +1,14 @@
## Name
A brief description of Core::Object and how it relates to GML.
## Description
All GML widgets inherit properties from `Core::Object`.
## Registered Properties
| Property | Type | Possible values | Description |
|-------------|-----------------|-----------------|------------------------------------------------|
| name | string | Any string | Name of widget, to be referenced later in C++. |
| class_name | readonly_string | Class name | Object class |

40
Base/usr/share/man/man5/GML/Define-property.md Normal file
View file

@ -0,0 +1,40 @@
## Name
GML Property Definition
## Description
How to register property to a widget.
**LibGUI** widget definitions contain macros that define the properties that can be used for a given widget. This is a useful feature to expose widget-type-specific configuration to GML.
Widgets understand all properties defined by their parents. Such as `x`, `y`, `name`, etc.
## `REGISTER_*` macros
There is one REGISTER macro for every generic property type, a list of which can be found in [GML Syntax(5)](help://man/5/GML/Syntax#Properties). If you need special behavior for one single property, it is usually enough to re-use one of the property types and do extra handling in the setter and getter.
The general syntax of the macros is as follows:
```cpp
REGISTER_TYPENAME_PROPERTY(property_name, getter, setter [, additional parameters...]);
```
The macros are to be called in the constructor. `property_name` is a string that GML can use to set this property. `getter` is the name of a member function on this class that acts as a getter for the property. The getter receives value of the property's type, which is a C++ value for `int`, `string`, `readonly_string`, `enum`, and `bool`, or a JSON value for anything else. `setter` is the name of a member function on this class that acts as a setter for the property, taking no arguments and returning the exact type that the getter expects. It is not possible to omit either of the functions, but they may be no-ops if needed. For non-settable strings `REGISTER_READONLY_STRING_PROPERTY` is used.
For some macros, additional parameters are required. Most of the macros and their parameters can be found in the `Core::Object` header; however some layout properties are situated in the `GUI::Layout` header.
## Examples
```cpp
REGISTER_STRING_PROPERTY("alt_text", alt_text, set_alt_text);
// The enum property requires that you specify all available enum fields plus their GML string representation.
REGISTER_ENUM_PROPERTY(
"button_style", button_style, set_button_style, Gfx::ButtonStyle,
{ Gfx::ButtonStyle::Normal, "Normal" },
{ Gfx::ButtonStyle::Coolbar, "Coolbar" });
```
## See also
- [GML Define widget(5)](help://man/5/GML/Define-widget)

50
Base/usr/share/man/man5/GML/Define-widget.md Normal file
View file

@ -0,0 +1,50 @@
## Name
Library or Application Defined Widgets
## Description
Some applications and libraries find it useful to define their own widgets.
This is done using `REGISTER_WIDGET()`, just as in **LibGUI**. The syntax of the macro is as follows:
```cpp
REGISTER_WIDGET(namespace, class_name)
```
This means that every registered widget has to be placed in a namespace. For applications that usually do not need their own namespace, a common approach is to use the application name as the namespace for these registered widgets.
Note that registered widgets need to be constructible without any arguments.
## Examples
```gml
@Web::OutOfProcessWebView {
name: "web_view"
min_width: 340
min_height: 160
visible: false
}
```
```cpp
// OutOfProcessWebView.cpp
REGISTER_WIDGET(Web, OutOfProcessWebView)
...
OutOfProcessWebView::OutOfProcessWebView()
{
set_should_hide_unnecessary_scrollbars(true);
set_focus_policy(GUI::FocusPolicy::StrongFocus);
create_client();
}
...
```
## See also
- [GML Define property(5)](help://man/5/GML/Define-property)

21
Base/usr/share/man/man5/GML/Layout-HorizontalBoxLayout.md Normal file
View file

@ -0,0 +1,21 @@
## Name
GML Horizontal Box Layout
## Description
Defines a horizontal GUI box layout. This is a layout object that lays out widgets side-by-side horizontally.
## Examples
```gml
@GUI::Widget {
layout: @GUI::HorizontalBoxLayout {
spacing: 2
}
}
```
## See also
- [Layout](help://man/5/GML/Layout)

21
Base/usr/share/man/man5/GML/Layout-VerticalBoxLayout.md Normal file
View file

@ -0,0 +1,21 @@
## Name
GML Vertical Box Layout
## Description
Defines a vertical GUI box layout. This is a layout object that lays out widgets side-by-side vertically.
## Examples
```gml
@GUI::Widget {
layout: @GUI::VerticalBoxLayout {
spacing: 2
}
}
```
## See also
- [Layout](help://man/5/GML/Layout)

19
Base/usr/share/man/man5/GML/Layout.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Layout object
## Description
Abstract base class for layout objects, not used directly. Common properties of all layout objects are defined here.
## Registered properties
| Property | Type | Possible values | Description |
| -------- | ------- | --------------- | --------------------------------------------------- |
| margins | margins | | Margins inside the container widget to the children |
| spacing | int | | Spacing around each widget in the layout |
## See also
- [HorizontalBoxLayout](help://man/5/GML/Layout-HorizontalBoxLayout)
- [VerticalBoxLayout](help://man/5/GML/Layout-VerticalBoxLayout)

232
Base/usr/share/man/man5/GML/Syntax.md Normal file
View file

@ -0,0 +1,232 @@
## 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.
```gml
// 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)](help://man/5/GML/Widget).
```gml
// 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.
```gml
// 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:
- `int`: Regular JSON integer, note that JSON floats are not currently used.
- `ui_dimension`: either positive integers, that work just like `int`, or special meaning values as JSON strings; see [UI Dimensions](help://man/5/GML/UI-Dimensions)
- `bool`: Regular JSON boolean, may be enclosed in quotes but this is discouraged.
- `string`: JSON string, also used as a basis for other types.
- `readonly_string`: String-valued property that cannot be changed from C++ later.
- `enum`: A JSON string with special semantics. This is always the value of some C++ enum, but it's enclosed in quotes.
- `font_weight`: Special case of `enum` for `Gfx::FontWeight`. One of `Thin`, `ExtraLight`, `Light`, `Regular`, `Medium`, `SemiBold`, `Bold`, `ExtraBold`, `Black`, `ExtraBlack`.
- `text_alignment`: Special case of `enum` for `Gfx::TextAlignment`. Supports values of the form `VerticalHorizontal`, where `Vertical` is the vertical alignment, one of `Center`, `Top`, `Bottom`, and `Horizontal` is the horizontal alignment, one of `Left`, `Right`, `Center`. The exception is the value `Center` (because `CenterCenter` is silly).
- `text_wrapping`: Special case of `enum` for `Gfx::TextWrapping`. One of `Wrap` or `DontWrap`.
- `rect`: A JSON object of four `int`s specifying a rectangle. The keys are `x`, `y`, `width`, `height`.
- `size`: A JSON array of two `int`s specifying two sizes in the format `[width, height]`.
- `ui_size`: A JSON array of two `ui_dimension`s specifying two sizes in the format `[width, height]`
- `margins`: A JSON array or object specifying four-directional margins as `int`s. If this is a JSON object, the four keys `top`, `right`, `bottom`, `left` are used. If this is a JSON array, there can be one to four integers. These have the following meaning (see also `GUI::Margins`):
- `[ all_four_margins ]`
- `[ top_and_bottom, right_and_left ]`
- `[ top, right_and_left, bottom ]`
- `[ top, right, bottom, left ]`
Properties are never ended with `;` or `,`, and the property key is never enclosed in quotes or double quotes.
## See also
- The SerenityOS source code is the best source of further information on GML. The GML parser and AST builder can be found in the `GML` subdirectory in the `LibGUI` library. The `AK` JSON parsers and data structures are used for all JSON values.
## Examples
GML files can be found in the SerenityOS source tree with the `*.gml` extension.
```gml
@GUI::Widget {
name: "my_first_widget"
}
```
```gml
// 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"
}
}
```
```gml
// 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"
}
}
```

29
Base/usr/share/man/man5/GML/UI-Dimensions.md Normal file
View file

@ -0,0 +1,29 @@
## Name
UI Dimensions
# Description
UI Dimension (or [GUI::UIDimension](file:///usr/src/serenity/Userland/Libraries/LibGUI/UIDimensions.h) in c++) is a special, union — of positive integer and enum — like, type that is used to represent dimensions in a user interface context.
It can either store positive integers ≥0 or special meaning values from a pre determined set.
## Basic Syntax
In GML UI Dimensions that are "regular" values (integer ≥0) are represented by JSON's int type,
while "special" values are represented by their name as a JSON string type.
# Special Values
Special Values carry size information that would otherwise not be intuitively possible to be transported by an integer (positive or negative) alone.
Importantly, while any "regular" (i.e. int ≥0) UI Dimension values might (by convention) be assigned to any UI Dimension property, many properties only allow a subset of the "special" values to be assigned to them.
| Name | c++ name | GML/JSON representation | General meaning |
|-------------------|--------------------------------------------|-------------------------|-------------------------------------------------|
| Regular | `GUI::SpecialDimension::Regular` (mock) | int ≥0 | This is a regular integer value specifying a specific size |
| Grow | `GUI::SpecialDimension::Grow` | `"grow"` | Grow to the maximum size the surrounding allows |
| OpportunisticGrow | `GUI::SpecialDimension::OpportunisticGrow` | `"opportunistic_grow"` | Grow when the opportunity arises, meaning — only when all other widgets have already grown to their maximum size, and only opportunistically growing widgets are left |
| Fit | `GUI::SpecialDimension::Fit` | `"fit"` | Grow exactly to the size of the surrounding as determined by other factors, but do not call for e.g. expansion of the parent container itself |
| Shrink | `GUI::SpecialDimension::Shrink` | `"shrink"` | Shrink to the smallest size possible |

48
Base/usr/share/man/man5/GML/Usage.md Normal file
View file

@ -0,0 +1,48 @@
## Name
GML Usage
## Description
How to use GML in SerenityOS C++ applications
## CMake
Include `compile_gml()` your applications CMake file. The header file name and GML string name are not fixed but must follow this convention.
```cmake
compile_gml(MyApp.gml MyAppGML.h my_app_gml)
```
Include the name of the header file that will be compiled from your GML file in your `SOURCES`.
```cmake
set(SOURCES
MyAppGML.h
)
```
## C++
You can then reference the variable you set (e.g. `my_app_gml`) in your main C++ file using `load_from_gml()`.
```cpp
load_from_gml(my_app_gml);
```
From there, you can use `find_descendant_of_type_named` to select widgets from your GML by their `name` property.
```gml
@GUI::Button {
name: "mem_add_button"
text: "M+"
fixed_width: 35
fixed_height: 28
foreground_color: "red"
}
```
Is referenced using...
```cpp
load_from_gml(calculator_gml);
m_mem_add_button = *find_descendant_of_type_named<GUI::Button>("mem_add_button");
```

19
Base/usr/share/man/man5/GML/Widget-Breadcrumbbar.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Breadcrumb Bar Widget
## Description
Defines a GUI bread crumb toolbar widget.
## Synopsis
`@GUI::Breadcrumbbar`
## Examples
```gml
@GUI::Breadcrumbbar {
name: "breadcrumbbar"
}
```

34
Base/usr/share/man/man5/GML/Widget-Button.md Normal file
View file

@ -0,0 +1,34 @@
## Name
## Description
Defines a GUI Button widget.
## Synopsis
`@GUI::Button`
## Examples
```gml
@GUI::Button {
name: "normal_button"
text: "Button"
}
@GUI::Button {
name: "disabled_normal_button"
text: "Disabled"
enabled: false
}
```
## Registered Properties
| Property | Type | Possible values | Description |
| ------------ | ------ | --------------- | ----------------------------------------------------------------------------------------------------- |
| button_style | enum | Normal, Coolbar | Sets the style of the button |
| text | string | Any string | Sets the label text |
| checked | bool | true or false | Whether the button is checked; this only applies to checkable subclasses |
| checkable | bool | true or false | Whether the button can be checked; this only applies to checkable subclasses |
| exclusive | bool | true or false | Whether the button's check state is exclusive to its group; this only applies to checkable subclasses |

19
Base/usr/share/man/man5/GML/Widget-Calendar.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Calendar Widget
## Description
Defines a GUI calendar widget.
## Synopsis
`@GUI::Calendar`
## Examples
```gml
@GUI::Calendar {
name: "calendar"
}
```

36
Base/usr/share/man/man5/GML/Widget-CheckBox.md Normal file
View file

@ -0,0 +1,36 @@
## Name
GML Checkbox Widget
## Description
Defines a GUI checkbox widget.
## Synopsis
`@GUI::CheckBox`
## Examples
```gml
@GUI::CheckBox {
name: "top_checkbox"
text: "Checkbox"
}
@GUI::CheckBox {
name: "bottom_checkbox"
text: "Disabled"
enabled: false
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------------|--------|-------------------|--------------------------------------------------------------------|
| autosize | bool | true or false | Determines if auto-sized |
| checkbox_position | String | "Left" or "Right" | Place the checkbox itself on either the left or right of its label |
## See also
- [GML Button](help://man/5/GML/Widget-Button)

32
Base/usr/share/man/man5/GML/Widget-ColorInput.md Normal file
View file

@ -0,0 +1,32 @@
## Name
GML Color Input Widget
## Description
Defines a GUI color input widget.
## Synopsis
`@GUI::ColorInput`
## Examples
```gml
@GUI::ColorInput {
name: "font_colorinput"
placeholder: "Color dialog"
}
@GUI::ColorInput {
placeholder: "Disabled"
enabled: false
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|--------------------|--------|-----------------|---------------------------------------------------------|
| color_picker_title | string | Any string | Sets the title of the input |
| has_alpha_channel | bool | true or false | Whether to include the alpha channel in color selection |

32
Base/usr/share/man/man5/GML/Widget-ComboBox.md Normal file
View file

@ -0,0 +1,32 @@
## Name
GML Combo Box Widget
## Description
Defines a GUI combo box widget. Another name for this would be a dropdown or select.
## Synopsis
`@GUI::ComboBox`
## Examples
```gml
@GUI::ComboBox {
name: "msgbox_icon_combobox"
model_only: true
}
@GUI::ComboBox {
name: "msgbox_buttons_combobox"
model_only: true
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------|--------|-----------------|------------------------------|
| placeholder | string | Any string | Editor placeholder |
| model_only | bool | true or false | Only allow values from model |

32
Base/usr/share/man/man5/GML/Widget-Frame.md Normal file
View file

@ -0,0 +1,32 @@
## Name
GML Frame Widget
## Description
Defines a GUI frame widget. Frames can contain other GUI widgets.
## Synopsis
`@GUI::Frame`
## Examples
```gml
@GUI::Frame {
name: "tip_frame"
min_width: 340
min_height: 160
layout: @GUI::HorizontalBoxLayout {
margins: [0, 16, 0, 0]
}
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-----------|---------|--------------------------------------------------------------|--------------------|
| thickness | integer | 64-bit integer | Sets the thickness |
| shadow | enum | Plain, Raised, Sunken | Sets the shadow |
| shape | enum | NoFrame, Box, Container, Panel, VerticalLine, HorizontalLine | Sets the shape |

25
Base/usr/share/man/man5/GML/Widget-GroupBox.md Normal file
View file

@ -0,0 +1,25 @@
## Name
GML Group Box Widget
## Description
Defines a GUI group box widget. Used to contain widgets in a border with a title.
## Synopsis
`@GUI::GroupBox`
## Examples
```gml
@GUI::GroupBox {
title: "Appearance"
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|----------|--------|-----------------|----------------|
| title | string | Any string | Sets the title |

20
Base/usr/share/man/man5/GML/Widget-HorizontalProgressbar.md Normal file
View file

@ -0,0 +1,20 @@
## Name
GML Horizontal Progress Bar Widget
## Description
Defines a GUI horizontal progress bar widget.
## Synopsis
`@GUI::HorizontalProgressbar`
## Examples
```gml
@GUI::HorizontalProgressbar {
name: "horizontal_progressbar"
fixed_height: 20
}
```

19
Base/usr/share/man/man5/GML/Widget-HorizontalSeparator.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Horizontal Separator Widget
## Description
Defines a horizontal separator widget. Creates a horizontal line separating elements.
## Synopsis
`@GUI::HorizontalSeparator`
## Examples
```gml
@GUI::HorizontalSeparator {
fixed_height: 2
}
```

19
Base/usr/share/man/man5/GML/Widget-HorizontalSlider.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Horizontal Slider Widget
## Description
Defines a GUI horizontal slider widget.
## Synopsis
`@GUI::HorizontalSlider`
## Examples
```gml
@GUI::HorizontalSlider {
}
```

19
Base/usr/share/man/man5/GML/Widget-HorizontalSplitter.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GUI Horizontal Splitter Widget
## Description
Defines a GUI horizontal splitter widget.
## Synopsis
`@GUI::HorizontalSplitter`
## Examples
```gml
@GUI::HorizontalSplitter {
}
```

19
Base/usr/share/man/man5/GML/Widget-IconView.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Icon View Widget
## Description
Defines a GUI icon view widget.
## Synopsis
`@GUI::IconView`
## Examples
```gml
@GUI::IconView {
}
```

26
Base/usr/share/man/man5/GML/Widget-ImageWidget.md Normal file
View file

@ -0,0 +1,26 @@
## Name
GML Image Widget
## Description
Defines a GUI image widget.
## Synopsis
`@GUI::ImageWidget`
## Examples
```gml
@GUI::ImageWidget {
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|----------------|------|-----------------|-------------------------------------|
| auto_resize | bool | true or false | Set if the image should auto-resize |
| should_stretch | bool | true or false | Set if the image should stretch |

30
Base/usr/share/man/man5/GML/Widget-Label.md Normal file
View file

@ -0,0 +1,30 @@
## Name
GML Label Widget
## Description
Defines a GUI label widget.
## Synopsis
`@GUI::Label`
## Examples
```
@GUI::Label {
text: "Copying files..."
text_alignment: "CenterLeft"
font_weight: "Bold"
fixed_height: 32
name: "files_copied_label"
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-----------------|----------------|-----------------------------------------------------------------------------|----------------------------|
| text_alignment | text_alignment | Center, CenterLeft, CenterRight, TopLeft, TopRight, BottomLeft, BottomRight | Sets alignment of the text |
| text_wrapping | text_wrapping | | | | |

19
Base/usr/share/man/man5/GML/Widget-LinkLabel.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Link Label Widget
## Description
Defines a GUI link label widget.
## Synopsis
`@GUI::LinkLabel`
## Examples
```gml
@GUI::LinkLabel {
}
```

19
Base/usr/share/man/man5/GML/Widget-ListView.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML List-view Widget
## Synopsis
`@GUI::ListView`
## Description
Defines a GUI list view widget.
## Examples
```gml
@GUI::ListView {
name: "list_view"
}
```

19
Base/usr/share/man/man5/GML/Widget-MultiView.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Multi-view Widget
## Description
Defines a GUI multi view widget.
## Synopsis
`@GUI::MultiView`
## Examples
```gml
@GUI::MultiView {
}
```

21
Base/usr/share/man/man5/GML/Widget-OpacitySlider.md Normal file
View file

@ -0,0 +1,21 @@
## Name
GML Opacity Slider Widget
## Description
Defines a GUI opacity slider widget.
## Synopsis
`@GUI::HorizontalOpacitySlider`
`@GUI::VerticalOpacitySlider`
## Examples
```gml
@GUI::HorizontalOpacitySlider {
name: "opacity_slider"
tooltip: "Opacity Slider"
}
```

21
Base/usr/share/man/man5/GML/Widget-PasswordBox.md Normal file
View file

@ -0,0 +1,21 @@
## Name
GML Password Box Widget
## Description
Defines a GUI password box widget.
## Synopsis
```gml
@GUI::PasswordBox
```
## Examples
```gml
@GUI::PasswordBox {
}
```

32
Base/usr/share/man/man5/GML/Widget-Progressbar.md Normal file
View file

@ -0,0 +1,32 @@
## Name
GML Progress Bar Widget
## Description
Defines a GUI progress bar widget.
## Synopsis
```gml
@GUI::Progressbar
```
## Examples
```gml
@GUI::Progressbar {
fixed_height: 22
name: "progressbar"
min: 0
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|----------|--------|-----------------------------------|--------------------------------------------|
| text | string | Any string | Sets progress text |
| format | enum | NoText, Percentage, ValueSlashMax | Sets the format of the progress indication |
| min | int | Any 64 bit integer | Sets the minimum progress value |
| max | int | Any 64 bit integer | Set the maximum progress value |

26
Base/usr/share/man/man5/GML/Widget-RadioButton.md Normal file
View file

@ -0,0 +1,26 @@
## Name
GML Radio Button Widget
## Description
Defines a GUI radio button widget.
## Synopsis
`@GUI::RadioButton`
## Examples
```gml
@GUI::RadioButton {
name: "top_radiobutton"
text: "Radio 1"
checked: true
}
@GUI::RadioButton {
name: "bottom_radiobutton"
text: "Radio 2"
}
```

34
Base/usr/share/man/man5/GML/Widget-ScrollableContainerWidget.md Normal file
View file

@ -0,0 +1,34 @@
## Name
GML Scrollable Container Widget
## Description
Defines a GUI scrollable container widget.
Unlike other container widgets, this one does not allow multiple child widgets to be added, and thus also does not support setting a layout.
## Synopsis
`@GUI::ScrollableContainerWidget`
Content declared as `content_widget` property.
## Examples
```gml
@GUI::ScrollableContainerWidget {
content_widget: @GUI::Widget {
[...]
}
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|------------------------------------|---------------|------------------------|---------------------------------------------|
| ~~layout~~ | | none | Does not take layout |
| scrollbars_enabled | bool | true or false | Status of scrollbar |
| should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary |
| content_widget | widget object | Any Subclass of Widget | The Widget to be displayed in the Container |

24
Base/usr/share/man/man5/GML/Widget-Scrollbar.md Normal file
View file

@ -0,0 +1,24 @@
## Name
GML Scrollbar Widget
## Description
Defines a GUI scrollbar widget.
## Synopsis
`@GUI::Scrollbar`
## Examples
```gml
@GUI::Scrollbar {
name: "enabled_scrollbar"
fixed_height: 16
fixed_width: -1
min: 0
max: 100
value: 50
}
```

25
Base/usr/share/man/man5/GML/Widget-Slider.md Normal file
View file

@ -0,0 +1,25 @@
## Name
GML Slider Widget
## Description
Defines a GUI slider widget.
## Synopsis
`@GUI::Slider`
## Examples
```gml
@GUI::Slider {
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|----------------|------|---------------------|---------------------------|
| knob_size_mode | enum | Fixed, Proportional | Sets the slider knob size |

28
Base/usr/share/man/man5/GML/Widget-SpinBox.md Normal file
View file

@ -0,0 +1,28 @@
## Name
GML Spin Box Widget
## Description
Defines a GUI spin box widget. This is a number input with buttons to increment and decrement the value.
## Synopsis
`@GUI::SpinBox`
## Examples
```gml
@GUI::SpinBox {
name: "thickness_spinbox"
min: 0
max: 2
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|----------|-------|--------------------|----------------------------------------------|
| min | int | Any 64 bit integer | Minimum number the spin box can increment to |
| max | int | Any 64 bit integer | Maximum number the spin box can increment to |

19
Base/usr/share/man/man5/GML/Widget-StackWidget.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Stack Widget
## Description
Defines a GUI stack widget.
## Synopsis
`@GUI::StackWidget`
## Examples
```gml
@GUI::StackWidget {
}
```

26
Base/usr/share/man/man5/GML/Widget-Statusbar.md Normal file
View file

@ -0,0 +1,26 @@
## Name
GML Status Bar Widget
## Description
Defines a GUI status bar widget.
## Synopsis
`@GUI::Statusbar`
## Examples
```gml
@GUI::Statusbar {
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------|--------|--------------------|---------------------------------|
| text | string | Any string | Sets the text of the status bar |
| label_count | int | Any 64 bit integer | Sets the label count |

38
Base/usr/share/man/man5/GML/Widget-TabWidget.md Normal file
View file

@ -0,0 +1,38 @@
## Name
GML Tab Widget
## Description
Defines a GUI tab widget.
## Synopsis
`@GUI::TabWidget`
## Examples
```gml
@GUI::TabWidget {
uniform_tabs: true
@GUI::Widget {
title: "First tab"
}
@GUI::Widget {
title: "Second tab"
}
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|--------------------|----------------|-----------------------------------------------------------------------------|--------------------------------------|
| container_margins | margins | | Margins for the tab content |
| reorder_allowed | bool | true or false | Allow changing the order of the tabs |
| show_close_buttons | bool | true or false | Show a close button on each tab |
| show_tab_bar | bool | true or false | Whether to display the tabs |
| text_alignment | text_alignment | Center, CenterLeft, CenterRight, TopLeft, TopRight, BottomLeft, BottomRight | Set the alignment of tab text |
| tab_position | tab_position | Top, Bottom, Left, Right | Set the tab position |
| uniform_tabs | bool | true or false | Give all tabs the same width |

20
Base/usr/share/man/man5/GML/Widget-TableView.md Normal file
View file

@ -0,0 +1,20 @@
## Name
GML Table View Widget
## Description
Defines a GUI table view widget.
## Synopsis
`@GUI::TableView`
## Examples
```gml
@GUI::TableView {
name: "cursors_tableview"
font_size: 12
}
```

25
Base/usr/share/man/man5/GML/Widget-TextBox.md Normal file
View file

@ -0,0 +1,25 @@
## Name
GML Text Box Widget
## Description
Defines a GUI text box widget.
## Synopsis
`@GUI::TextBox`
## Examples
```gml
@GUI::TextBox {
placeholder: "Text box"
mode: "Editable"
}
@GUI::TextBox {
text: "Disabled"
enabled: false
}
```

28
Base/usr/share/man/man5/GML/Widget-TextEditor.md Normal file
View file

@ -0,0 +1,28 @@
## Name
GML Text Editor Widget
## Description
Defines a GUI text editor widget.
## Synopsis
`@GUI::TextEditor`
## Examples
```gml
@GUI::TextEditor {
name: "text_editor"
placeholder: "Text editor"
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------|--------|---------------------------------|-----------------|
| text | string | Any string | Set text |
| placeholder | string | Any string | Set placeholder |
| mode | enum | Editable, ReadOnly, DisplayOnly | Set editor mode |

32
Base/usr/share/man/man5/GML/Widget-Toolbar.md Normal file
View file

@ -0,0 +1,32 @@
## Name
GML Toolbar Widget
## Description
Defines a GUI toolbar widget.
When `collapsible` is set to `true`, the toolbar can be resized below the size of its items.
Any items that do not fit the current size, will be placed in an overflow menu.
To keep groups (i.e. Buttons/items separated by Separators) together, and move them to the overflow menu as one, set the `gouped` property.
## Synopsis
`@GUI::Toolbar`
## Examples
```gml
@GUI::Toolbar {
name: "toolbar"
collapsible: true
grouped: true
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------|------|-----------------|---------------------------------------------------------------------------------------|
| collapsible | bool | true or false | If items that do not fit should be placed in an overflow menu |
| grouped | bool | true or false | If items should be moved to the overflow menu in groups, separated by Separator items |

23
Base/usr/share/man/man5/GML/Widget-ToolbarContainer.md Normal file
View file

@ -0,0 +1,23 @@
## Name
GML Toolbar Container Widget
## Description
Defines a GUI toolbar container widget.
## Synopsis
`@GUI::ToolbarContainer`
## Examples
```gml
@GUI::ToolbarContainer {
name: "toolbar_container"
@GUI::Toolbar {
name: "toolbar"
}
}
```

19
Base/usr/share/man/man5/GML/Widget-Tray.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Tray Widget
## Description
Defines a GUI tray widget.
## Synopsis
`@GUI::Tray`
## Examples
```gml
@GUI::Tray {
}
```

20
Base/usr/share/man/man5/GML/Widget-TreeView.md Normal file
View file

@ -0,0 +1,20 @@
## Name
GML Tree View Widget
## Description
Defines a GUI tree view widget.
## Synopsis
`@GUI::TreeView`
## Examples
```gml
@GUI::TreeView {
name: "tree_view"
fixed_width: 200
}
```

19
Base/usr/share/man/man5/GML/Widget-UrlBox.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML URL Box Widget
## Description
Defines a GUI url box widget.
## Synopsis
`@GUI::UrlBox`
## Examples
```gml
@GUI::UrlBox {
}
```

23
Base/usr/share/man/man5/GML/Widget-ValueSlider.md Normal file
View file

@ -0,0 +1,23 @@
## Name
GML Value Slider Widget
## Description
Defines a GUI value slider widget.
## Synopsis
`@GUI::ValueSlider`
## Examples
```gml
@GUI::ValueSlider {
name: "value_slider"
min: 0
max: 100
value: 100
tooltip: "Value Slider"
}
```

20
Base/usr/share/man/man5/GML/Widget-VerticalProgressbar.md Normal file
View file

@ -0,0 +1,20 @@
## Name
GML Vertical Progress Bar Widget
## Description
Defines a GUI vertical progress bar widget.
## Synopsis
`@GUI::VerticalProgressbar`
## Examples
```gml
@GUI::VerticalProgressbar {
name: "vertical_progressbar_left"
fixed_width: 36
}
```

19
Base/usr/share/man/man5/GML/Widget-VerticalSeparator.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Vertical Separator Widget
## Description
Defines a GUI vertical separator.
## Synopsis
`@GUI::VerticalSeparator`
## Examples
```gml
@GUI::VerticalSeparator {
}
```

19
Base/usr/share/man/man5/GML/Widget-VerticalSlider.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Vertical Slider Widget
## Description
Defines a GUI vertical slider widget.
## Synopsis
`@GUI::VerticalSlider`
## Examples
```gml
@GUI::VerticalSlider {
}
```

19
Base/usr/share/man/man5/GML/Widget-VerticalSplitter.md Normal file
View file

@ -0,0 +1,19 @@
## Name
GML Vertical Splitter Widget
## Description
Defines a GUI vertical splitter widget.
## Synopsis
`@GUI::VerticalSplitter`
## Examples
```gml
@GUI::VerticalSplitter {
}
```

54
Base/usr/share/man/man5/GML/Widget.md Normal file
View file

@ -0,0 +1,54 @@
# Widget
Defines a GUI widget.
```gml
@GUI::Widget {
min_width: 200
preferred_width: "opportunistic_grow"
fixed_height: 215
fill_with_background_color: true
layout: @GUI::VerticalBoxLayout {
}
}
```
## Registered Properties
| Property | Type | Possible values | Description |
| --------------------------- | ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| x | int | | x offset relative to parent |
| y | int | | y offset relative to parent |
| visible | bool | | Whether widget and children are drawn |
| focused | bool | | Whether widget should be tab-focused on start |
| focus_policy | enum | ClickFocus, NoFocus, TabFocus, StrongFocus | How the widget can receive focus |
| enabled | bool | | Whether this widget is enabled for interactive purposes, e.g. can be clicked |
| tooltip | string | | Mouse tooltip to show when hovering over this widget |
| min_size | ui_size | {Regular, Shrink}² | Minimum size this widget wants to occupy (Shrink is equivalent to 0) |
| max_size | ui_size | {Regular, Grow}² | Maximum size this widget wants to occupy |
| preferred_size | ui_size | {Regular, Shrink, Fit, OpportunisticGrow, Grow}² | Preferred size this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
| width | int | | Width of the widget, independent of its layout size calculation |
| height | int | | Height of the widget, independent of its layout size calculation |
| min_width | ui_dimension | Regular, Shrink | Minimum width this widget wants to occupy (Shrink is equivalent to 0) |
| min_height | ui_dimension | Regular, Shrink | Minimum height this widget wants to occupy (Shrink is equivalent to 0 |
| max_width | ui_dimension | Regular, Grow | Maximum width this widget wants to occupy |
| max_height | ui_dimension | Regular, Grow | Maximum height this widget wants to occupy |
| preferred_width | ui_dimension | Regular, Shrink, Fit, OpportunisticGrow, Grow | Preferred width this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
| preferred_height | ui_dimension | Regular, Shrink, Fit, OpportunisticGrow, Grow | Preferred height this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
| fixed_width | ui_dimension | Regular (currently only integer values ≥0 allowed) | Both maximum and minimum width; widget is fixed-width |
| fixed_height | ui_dimension | Regular (currently only integer values ≥0 allowed) | Both maximum and minimum height; widget is fixed-height |
| fixed_size | ui_size | {Regular}² | Both maximum and minimum size; widget is fixed-size |
| shrink_to_fit | bool | | Whether the widget shrinks as much as possible while still respecting its children's minimum sizes |
| font | string | Any system-known font | Font family |
| font_size | int | Font size that is available on this family | Font size |
| font_weight | font_weight | Font weight that is available on this family and size | Font weight |
| font_type | enum | FixedWidth, Normal | Font type |
| foreground_color | color | | Color of foreground elements such as text |
| foreground_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the foreground elements |
| background_color | color | | Color of the widget background |
| background_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the widget background |
| fill_width_background_color | bool | | Whether to fill the widget's background with the background color |
| layout | layout object | | Layout object for layouting this widget's children |
| relative_rect | rect | | Rectangle for relatively positioning the widget to the parent |