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

Base: Document new GML usage method

This is now preferred over the old one.
This commit is contained in:
kleines Filmröllchen 2023-08-11 15:18:36 +02:00 committed by Jelle Raaijmakers
parent 8ec9b26bba
commit 54eab251f6

View file

@ -6,33 +6,36 @@ GML Usage
How to use GML in SerenityOS C++ applications How to use GML in SerenityOS C++ applications
## Note
This manpage describes the new method of loading GML files via generated C++ code. There also is the runtime `load_from_gml` function which has the same behavior. The runtime method should not be used except for specific use cases such as [GMLPlayground](help://man/1/Applications/GMLPlayground).
## CMake ## CMake
Include `stringify_gml()` your applications CMake file. The header file name and GML string name are not fixed but must follow this convention. Include `compile_gml()` your application's CMake file. The generated source file name is not fixed, but should follow this convention.
```cmake ```cmake
stringify_gml(MyApp.gml MyAppGML.h my_app_gml) compile_gml(MyApp.gml MyAppGML.cpp)
``` ```
Include the name of the header file that will be compiled from your GML file in your `SOURCES`. Include the name of the source file that will be compiled from your GML file in your `SOURCES`.
```cmake ```cmake
set(SOURCES set(SOURCES
MyAppGML.h MyAppGML.cpp
) )
``` ```
## C++ ## C++
You can then reference the variable you set (e.g. `my_app_gml`) in your main C++ file using `load_from_gml()`. The C++ source file that is generated will provide an implementation for the `ErrorOr<NonnullRefPtr<MyApp::Widget>> MyApp::Widget::try_create()` function, given that the root widget of the GML file is `MyApp::Widget`. For this to work, you have to add a declaration for this function in the header of the `MyApp::Widget` class. (The function will not collide with functions provided by `Core::Object`, do not worry.) Additionally, there must be a no-argument constructor in `MyApp::Widget`, which is used by the `try_create` implementation.
```cpp Calling the `try_create` function directly or indirectly (e.g. `Window::try_set_main_widget`) will now automatically load the structure defined in GML.
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. From there, you can use `find_descendant_of_type_named` to select widgets from your GML by their `name` property.
```gml ```gml
@MyApp::Widget {
@GUI::Button { @GUI::Button {
name: "mem_add_button" name: "mem_add_button"
text: "M+" text: "M+"
@ -40,9 +43,10 @@ From there, you can use `find_descendant_of_type_named` to select widgets from y
fixed_height: 28 fixed_height: 28
foreground_color: "red" foreground_color: "red"
} }
}
``` ```
Is referenced using...
```cpp ```cpp
load_from_gml(calculator_gml); // MyApp::Widget::foo_bar
m_mem_add_button = *find_descendant_of_type_named<GUI::Button>("mem_add_button"); m_mem_add_button = *find_descendant_of_type_named<GUI::Button>("mem_add_button");
``` ```