mirror of
https://github.com/LadybirdBrowser/ladybird.git
synced 2025-06-11 18:20:43 +09:00
Base: Add manpages for new layout system
This is far from explaining all implications of the new layout system, but it covers the basics.
This commit is contained in:
FrHun
Sam Atkins
parent
1d6d074536
commit
a78f84645c
Notes:
sideshowbarker
2024-07-18 08:59:31 +09:00
Author: https://github.com/frhun
Commit: a78f84645c
Pull-request: https://github.com/SerenityOS/serenity/pull/14261
Reviewed-by: https://github.com/AtkinsSJ ✅
Reviewed-by: https://github.com/MacDue
Reviewed-by: https://github.com/mjz19910
5 changed files with 85 additions and 38 deletions
|
|
@ -30,6 +30,7 @@ Or right clicking on a folder in the TreeView and using
|
|||
- [Define widgets](help://man/5/GML-Define-widget)
|
||||
- GML object and property reference
|
||||
- [Core::Object](help://man/5/GML-CoreObject)
|
||||
- [UI Dimensions](help://man/5/GML-UI-Dimensions)
|
||||
- Layouts
|
||||
- [HorizontalBoxLayout](help://man/5/GML-Layout-HorizontalBoxLayout)
|
||||
- [VerticalBoxLayout](help://man/5/GML-Layout-VerticalBoxLayout)
|
||||
|
|
@ -76,3 +77,4 @@ Or right clicking on a folder in the TreeView and using
|
|||
- [VerticalSlider](help://man/5/GML-Widget-VerticalSlider)
|
||||
- [VerticalSplitter](help://man/5/GML-Widget-VerticalSplitter)
|
||||
- [Widget](help://man/5/GML-Widget)
|
||||
|
||||
|
|
|
|||
|
|
@ -90,6 +90,7 @@ A property's `value` is required to be either a JSON value or another object. Ob
|
|||
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.
|
||||
|
|
@ -99,6 +100,7 @@ Among the supported JSON values, these types can be further distinguished:
|
|||
- `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 ]`
|
||||
|
|
@ -232,3 +234,4 @@ GML files can be found in the SerenityOS source tree with the `*.gml` extension.
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
29
Base/usr/share/man/man5/GML-UI-Dimensions.md
Normal file
29
Base/usr/share/man/man5/GML-UI-Dimensions.md
Normal 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 |
|
||||
|
||||
|
|
@ -6,21 +6,29 @@ GML Scrollable Container Widget
|
|||
|
||||
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 |
|
||||
|------------------------------------|------|-----------------|---------------------------------------------|
|
||||
| scrollbars_enabled | bool | true or false | Status of scrollbar |
|
||||
| should_hide_unnecessary_scrollbars | bool | true or false | Whether to hide scrollbars when unnecessary |
|
||||
| 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 |
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ Defines a GUI widget.
|
|||
|
||||
```gml
|
||||
@GUI::Widget {
|
||||
fixed_width: 250
|
||||
min_width: 200
|
||||
preferred_width: "opportunistic_grow"
|
||||
fixed_height: 215
|
||||
fill_with_background_color: true
|
||||
layout: @GUI::VerticalBoxLayout {
|
||||
|
|
@ -15,35 +16,39 @@ Defines a GUI widget.
|
|||
|
||||
## 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 | size | | Minimum size this widget wants to occupy |
|
||||
| max_size | size | | Maximum size this widget wants to occupy |
|
||||
| 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 | int | smaller than max_width | Minimum width this widget wants to occupy |
|
||||
| min_height | int | smaller than max_height | Minimum height this widget wants to occupy |
|
||||
| max_width | int | greater than min_width | Maximum width this widget wants to occupy |
|
||||
| max_height | int | greater than min_height | Maximum height this widget wants to occupy |
|
||||
| fixed_width | int | | Both maximum and minimum width; widget is fixed-width |
|
||||
| fixed_height | int | | Both maximum and minimum height; widget is fixed-height |
|
||||
| fixed_size | size | | 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 childrens 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 |
|
||||
| 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 childrens 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 |
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue