1
Fork 0
mirror of https://github.com/RGBCube/serenity synced 2025-07-25 06:27:45 +00:00

Base+Manpages: Add basic GML documentation

First draft of GML documentation, just to get things started.
This commit is contained in:
electrikmilk 2022-02-09 18:11:07 -05:00 committed by Brian Gianforcaro
parent d01d754b83
commit 58a865f349
51 changed files with 1242 additions and 0 deletions

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 |

View file

@ -0,0 +1,20 @@
## 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.
However, widgets also understand properties defined by their parents. Such as `x`, `y`, `name`, etc.
## Examples
```cpp
REGISTER_ENUM_PROPERTY(
"button_style", button_style, set_button_style, Gfx::ButtonStyle,
{ Gfx::ButtonStyle::Normal, "Normal" },
{ Gfx::ButtonStyle::Coolbar, "Coolbar" });
```

View file

@ -0,0 +1,36 @@
## Name
Library or Application Defined Widgets
## Description
Some applications and libraries find it useful to define their own **LibGUI** widgets.
## Examples
```gml
@Web::OutOfProcessWebView {
name: "web_view"
min_width: 340
min_height: 160
visible: false
}
```
They are defined using `REGISTER_WIDGET()`, just as they are in **LIbGUI**.
```cpp
REGISTER_WIDGET(Web, OutOfProcessWebView)
...
OutOfProcessWebView::OutOfProcessWebView()
{
set_should_hide_unnecessary_scrollbars(true);
set_focus_policy(GUI::FocusPolicy::StrongFocus);
create_client();
}
...
```

View file

@ -0,0 +1,17 @@
## Name
GUI Markup Language (GML)
## Description
GML is Serenity's graphic user interface markup language. GML files are human-readable and have no easily detectable filemagic. The format is strongly influenced by QML, the Qt Modeling Language.
It allows you to easily define GUI interfaces for your applications. It is easy to learn and link to your C++ code.
You can easily add GML files to your project in Hack Studio either using
`Project > New > GML File`
Or right clicking on a folder in the TreeView and using
`New > GML File`

View file

@ -0,0 +1,48 @@
## Name
Linking to GML widgets
## Description
How to link to your GML widgets in C++
## CMake
Include `compile_gml()` your applications CMake file.
```cmake
compile_gml(YourGMLFile.gml MyGML.h my_gml)
```
Include the name of the header file that will be compiled from your GML file in your `SOURCES`.
```cmake
set(SOURCES
MyGML.h
)
```
## C++
You can then reference the variable you set (e.g. `calculator_gml`) in your main C++ file using `load_from_gml()`.
```cpp
load_from_gml(my_gml);
```
From there, you can use `find_descendant_of_type_named` to select widgets from your GML from 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");
```

View file

@ -0,0 +1,39 @@
## Name
GML Basic Syntax
# Description
How to write GML using proper syntax.
## Basic Syntax
Each widget begins with `@GUI::`, with the name of the widget following. To define the properties of this widget, we follow with curly brackets and a list of properties.
## Properties
A property's `value` is required to be in the property's set `type`:
- `int`
- `bool`
- `string`
- `readonly_string`
- `enum`
- `font_weight`
- `text_alignment`
- `text_wrapping`
- `rect`
- `size`
- `margins`
Properties are never ended with `;` or `,`, and the property name is never enclosed in quotes or double quotes.
Properties are always surrounded by curly brackets (e.g. `{}`). If no properties are set however, no brackets are required.
## Examples
```gml
@GUI::Widget {
name: "my_first_widget"
}
```

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"
}
```

View file

@ -0,0 +1,33 @@
## 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 | |
| checkable | bool | true or false | |

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"
}
```

View file

@ -0,0 +1,32 @@
## 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 |

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 |

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 |

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 |

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 |

View file

@ -0,0 +1,19 @@
## Name
GML Horizontal Box Layout Widget
## Description
Defines a horizontal GUI box layout widget.
## Synopsis
`@GUI::HorizontalBoxLayout`
## Examples
```gml
@GUI::HorizontalBoxLayout {
spacing: 2
}
```

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
}
```

View file

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

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 {
}
```

View file

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

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 {
}
```

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 |

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 | | | | |

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 {
}
```

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"
}
```

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 {
}
```

View file

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

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 {
}
```

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 |

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"
}
```

View file

@ -0,0 +1,26 @@
## Name
GML Scrollable Container Widget
## Description
Defines a GUI scrollable container widget.
## Synopsis
`@GUI::ScrollableContainerWidget`
## Examples
```gml
@GUI::ScrollableContainerWidget {
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|------------------------------------|------|-----------------|---------------------------------------------|
| scrollbars_enabled | bool | true or false | Status of scrollbar |
| should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary |

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
}
```

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 |

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 |

View file

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

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 |

View file

@ -0,0 +1,27 @@
## Name
GML Tab Widget
## Description
Defines a GUI tab widget.
## Synopsis
`@GUI::TabWidget`
## Examples
```gml
@GUI::TabWidget {
uniform_tabs: true
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-------------------|----------------|-----------------------------------------------------------------------------|-------------------------------|
| container_margins | margins | | Set container margins |
| uniform_tabs | bool | true or false | Set uniform tabs |
| text_alignment | text_alignment | Center, CenterLeft, CenterRight, TopLeft, TopRight, BottomLeft, BottomRight | Set the alignment of tab text |

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
}
```

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
}
```

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 |

View file

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

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"
}
}
```

View file

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

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
}
```

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 {
}
```

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"
}
```

View file

@ -0,0 +1,19 @@
## Name
GML Vertical Box Layout Widget
## Description
Defines a vertical GUI box layout.
## Synopsis
`@GUI::VerticalBoxLayout`
## Examples
```gml
@GUI::VerticalBoxLayout {
spacing: 2
}
```

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
}
```

View file

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

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 {
}
```

View file

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

View file

@ -0,0 +1,50 @@
# Widget
Defines a GUI widget.
```gml
@GUI::Widget {
fixed_width: 250
fixed_height: 215
fill_with_background_color: true
layout: @GUI::VerticalBoxLayout {
}
}
```
## Registered Properties
| Property | Type | Possible values | Description |
|-----------------------------|-------------|----------------------------------------------------|------------------------------------------------|
| x | int | | |
| y | int | | |
| visible | bool | | |
| focused | bool | | |
| enabled | bool | | |
| tooltip | string | | |
| min_size | size | | |
| max_size | size | | |
| width | int | | |
| height | int | | |
| min_width | int | | |
| min_height | int | | |
| max_width | int | | |
| max_height | int | | |
| fixed_width | int | | |
| fixed_height | int | | |
| fixed_size | size | | |
| shrink_to_fit | bool | | |
| font | string | | |
| font_size | int | | |
| font_weight | font_weight | | |
| font_type | enum | FixedWidth, Normal | |
| foreground_color | color | | |
| foreground_role | string | | |
| background_color | color | | |
| background_role | string | | |
| fill_width_background_color | bool | | |
| layout | widget | @GUI::VerticalBoxLayout, @GUI::HorizontalBoxLayout | |
| relative_rect | rect | | |
| focus_policy | enum | ClickFocus, NoFocus, TabFocus, StrongFocus | |
| margins | | | |