diff options
Diffstat (limited to 'Base/usr/share/man/man5/GML-Define-property.md')
| -rw-r--r-- | Base/usr/share/man/man5/GML-Define-property.md | 24 |
1 files changed, 22 insertions, 2 deletions
diff --git a/Base/usr/share/man/man5/GML-Define-property.md b/Base/usr/share/man/man5/GML-Define-property.md index 5dcc3d17bc..de0869cc36 100644 --- a/Base/usr/share/man/man5/GML-Define-property.md +++ b/Base/usr/share/man/man5/GML-Define-property.md @@ -6,15 +6,35 @@ GML Property Definition How to register property to a widget. -**LIbGUI** widget definitions contain macros that define the properties that can be used for a given 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. -However, widgets also understand properties defined by their parents. Such as `x`, `y`, `name`, etc. +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) |