Skip to content

Commit a78f846

Browse files
frhunAtkinsSJ
frhun
authored and
AtkinsSJ
committed
Base: Add manpages for new layout system
This is far from explaining all implications of the new layout system, but it covers the basics.
1 parent 1d6d074 commit a78f846

File tree

5 files changed

+85
-38
lines changed

5 files changed

+85
-38
lines changed

‎Base/usr/share/man/man5/GML-Introduction.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Or right clicking on a folder in the TreeView and using
3030
- [Define widgets](help://man/5/GML-Define-widget)
3131
- GML object and property reference
3232
- [Core::Object](help://man/5/GML-CoreObject)
33+
- [UI Dimensions](help://man/5/GML-UI-Dimensions)
3334
- Layouts
3435
- [HorizontalBoxLayout](help://man/5/GML-Layout-HorizontalBoxLayout)
3536
- [VerticalBoxLayout](help://man/5/GML-Layout-VerticalBoxLayout)
@@ -76,3 +77,4 @@ Or right clicking on a folder in the TreeView and using
7677
- [VerticalSlider](help://man/5/GML-Widget-VerticalSlider)
7778
- [VerticalSplitter](help://man/5/GML-Widget-VerticalSplitter)
7879
- [Widget](help://man/5/GML-Widget)
80+

‎Base/usr/share/man/man5/GML-Syntax.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ A property's `value` is required to be either a JSON value or another object. Ob
9090
Among the supported JSON values, these types can be further distinguished:
9191

9292
- `int`: Regular JSON integer, note that JSON floats are not currently used.
93+
- `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)
9394
- `bool`: Regular JSON boolean, may be enclosed in quotes but this is discouraged.
9495
- `string`: JSON string, also used as a basis for other types.
9596
- `readonly_string`: String-valued property that cannot be changed from C++ later.
@@ -99,6 +100,7 @@ Among the supported JSON values, these types can be further distinguished:
99100
- `text_wrapping`: Special case of `enum` for `Gfx::TextWrapping`. One of `Wrap` or `DontWrap`.
100101
- `rect`: A JSON object of four `int`s specifying a rectangle. The keys are `x`, `y`, `width`, `height`.
101102
- `size`: A JSON array of two `int`s specifying two sizes in the format `[width, height]`.
103+
- `ui_size`: A JSON array of two `ui_dimension`s specifying two sizes in the format `[width, height]`
102104
- `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`):
103105
- `[ all_four_margins ]`
104106
- `[ top_and_bottom, right_and_left ]`
@@ -232,3 +234,4 @@ GML files can be found in the SerenityOS source tree with the `*.gml` extension.
232234
}
233235
}
234236
```
237+

‎Base/usr/share/man/man5/GML-UI-Dimensions.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Name
2+
3+
UI Dimensions
4+
5+
# Description
6+
7+
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.
8+
9+
It can either store positive integers ≥0 or special meaning values from a pre determined set.
10+
11+
## Basic Syntax
12+
13+
In GML UI Dimensions that are "regular" values (integer ≥0) are represented by JSON's int type,
14+
while "special" values are represented by their name as a JSON string type.
15+
16+
# Special Values
17+
18+
Special Values carry size information that would otherwise not be intuitively possible to be transported by an integer (positive or negative) alone.
19+
20+
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.
21+
22+
| Name | c++ name | GML/JSON representation | General meaning |
23+
|-------------------|--------------------------------------------|-------------------------|-------------------------------------------------|
24+
| Regular | `GUI::SpecialDimension::Regular` (mock) | int ≥0 | This is a regular integer value specifying a specific size |
25+
| Grow | `GUI::SpecialDimension::Grow` | `"grow"` | Grow to the maximum size the surrounding allows |
26+
| 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 |
27+
| 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 |
28+
| Shrink | `GUI::SpecialDimension::Shrink` | `"shrink"` | Shrink to the smallest size possible |
29+

‎Base/usr/share/man/man5/GML-Widget-ScrollableContainerWidget.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,29 @@ GML Scrollable Container Widget
66

77
Defines a GUI scrollable container widget.
88

9+
Unlike other container widgets, this one does not allow multiple child widgets to be added, and thus also does not support setting a layout.
10+
911
## Synopsis
1012

1113
`@GUI::ScrollableContainerWidget`
1214

15+
Content declared as `content_widget` property.
16+
1317
## Examples
1418

1519
```gml
1620
@GUI::ScrollableContainerWidget {
17-
21+
content_widget: @GUI::Widget {
22+
[...]
23+
}
1824
}
1925
```
2026

2127
## Registered Properties
2228

23-
| Property | Type | Possible values | Description |
24-
|------------------------------------|------|-----------------|---------------------------------------------|
25-
| scrollbars_enabled | bool | true or false | Status of scrollbar |
26-
| should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary |
29+
| Property | Type | Possible values | Description |
30+
|------------------------------------|---------------|------------------------|---------------------------------------------|
31+
| ~~layout~~ | | none | Does not take layout |
32+
| scrollbars_enabled | bool | true or false | Status of scrollbar |
33+
| should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary |
34+
| content_widget | widget object | Any Subclass of Widget | The Widget to be displayed in the Container |

‎Base/usr/share/man/man5/GML-Widget.md‎

Lines changed: 38 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ Defines a GUI widget.
44

55
```gml
66
@GUI::Widget {
7-
fixed_width: 250
7+
min_width: 200
8+
preferred_width: "opportunistic_grow"
89
fixed_height: 215
910
fill_with_background_color: true
1011
layout: @GUI::VerticalBoxLayout {
@@ -15,35 +16,39 @@ Defines a GUI widget.
1516

1617
## Registered Properties
1718

18-
| Property | Type | Possible values | Description |
19-
| --------------------------- | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
20-
| x | int | | x offset relative to parent |
21-
| y | int | | y offset relative to parent |
22-
| visible | bool | | Whether widget and children are drawn |
23-
| focused | bool | | Whether widget should be tab-focused on start |
24-
| focus_policy | enum | ClickFocus, NoFocus, TabFocus, StrongFocus | How the widget can receive focus |
25-
| enabled | bool | | Whether this widget is enabled for interactive purposes, e.g. can be clicked |
26-
| tooltip | string | | Mouse tooltip to show when hovering over this widget |
27-
| min_size | size | | Minimum size this widget wants to occupy |
28-
| max_size | size | | Maximum size this widget wants to occupy |
29-
| width | int | | Width of the widget, independent of its layout size calculation |
30-
| height | int | | Height of the widget, independent of its layout size calculation |
31-
| min_width | int | smaller than max_width | Minimum width this widget wants to occupy |
32-
| min_height | int | smaller than max_height | Minimum height this widget wants to occupy |
33-
| max_width | int | greater than min_width | Maximum width this widget wants to occupy |
34-
| max_height | int | greater than min_height | Maximum height this widget wants to occupy |
35-
| fixed_width | int | | Both maximum and minimum width; widget is fixed-width |
36-
| fixed_height | int | | Both maximum and minimum height; widget is fixed-height |
37-
| fixed_size | size | | Both maximum and minimum size; widget is fixed-size |
38-
| shrink_to_fit | bool | | Whether the widget shrinks as much as possible while still respecting its childrens minimum sizes |
39-
| font | string | Any system-known font | Font family |
40-
| font_size | int | Font size that is available on this family | Font size |
41-
| font_weight | font_weight | Font weight that is available on this family and size | Font weight |
42-
| font_type | enum | FixedWidth, Normal | Font type |
43-
| foreground_color | color | | Color of foreground elements such as text |
44-
| foreground_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the foreground elements |
45-
| background_color | color | | Color of the widget background |
46-
| background_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the widget background |
47-
| fill_width_background_color | bool | | Whether to fill the widget's background with the background color |
48-
| layout | layout object | | Layout object for layouting this widget's children |
49-
| relative_rect | rect | | Rectangle for relatively positioning the widget to the parent |
19+
| Property | Type | Possible values | Description |
20+
| --------------------------- | ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
21+
| x | int | | x offset relative to parent |
22+
| y | int | | y offset relative to parent |
23+
| visible | bool | | Whether widget and children are drawn |
24+
| focused | bool | | Whether widget should be tab-focused on start |
25+
| focus_policy | enum | ClickFocus, NoFocus, TabFocus, StrongFocus | How the widget can receive focus |
26+
| enabled | bool | | Whether this widget is enabled for interactive purposes, e.g. can be clicked |
27+
| tooltip | string | | Mouse tooltip to show when hovering over this widget |
28+
| min_size | ui_size | {Regular, Shrink}² | Minimum size this widget wants to occupy (Shrink is equivalent to 0) |
29+
| max_size | ui_size | {Regular, Grow}² | Maximum size this widget wants to occupy |
30+
| preferred_size | ui_size | {Regular, Shrink, Fit, OpportunisticGrow, Grow}² | Preferred size this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
31+
| width | int | | Width of the widget, independent of its layout size calculation |
32+
| height | int | | Height of the widget, independent of its layout size calculation |
33+
| min_width | ui_dimension | Regular, Shrink | Minimum width this widget wants to occupy (Shrink is equivalent to 0) |
34+
| min_height | ui_dimension | Regular, Shrink | Minimum height this widget wants to occupy (Shrink is equivalent to 0 |
35+
| max_width | ui_dimension | Regular, Grow | Maximum width this widget wants to occupy |
36+
| max_height | ui_dimension | Regular, Grow | Maximum height this widget wants to occupy |
37+
| preferred_width | ui_dimension | Regular, Shrink, Fit, OpportunisticGrow, Grow | Preferred width this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
38+
| preferred_height | ui_dimension | Regular, Shrink, Fit, OpportunisticGrow, Grow | Preferred height this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
39+
| fixed_width | ui_dimension | Regular (currently only integer values ≥0 allowed) | Both maximum and minimum width; widget is fixed-width |
40+
| fixed_height | ui_dimension | Regular (currently only integer values ≥0 allowed) | Both maximum and minimum height; widget is fixed-height |
41+
| fixed_size | ui_size | {Regular}² | Both maximum and minimum size; widget is fixed-size |
42+
| shrink_to_fit | bool | | Whether the widget shrinks as much as possible while still respecting its childrens minimum sizes |
43+
| font | string | Any system-known font | Font family |
44+
| font_size | int | Font size that is available on this family | Font size |
45+
| font_weight | font_weight | Font weight that is available on this family and size | Font weight |
46+
| font_type | enum | FixedWidth, Normal | Font type |
47+
| foreground_color | color | | Color of foreground elements such as text |
48+
| foreground_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the foreground elements |
49+
| background_color | color | | Color of the widget background |
50+
| background_role | string | Any theme palette color role name | Palette color role (depends on system theme) for the widget background |
51+
| fill_width_background_color | bool | | Whether to fill the widget's background with the background color |
52+
| layout | layout object | | Layout object for layouting this widget's children |
53+
| relative_rect | rect | | Rectangle for relatively positioning the widget to the parent |
54+

0 commit comments

Comments
 (0)