From 54eab251f62b45509ccb6fdc5512a2d8b1816573 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?kleines=20Filmr=C3=B6llchen?= Date: Fri, 11 Aug 2023 15:18:36 +0200 Subject: [PATCH] Base: Document new GML usage method This is now preferred over the old one. --- Base/usr/share/man/man5/GML/Usage.md | 36 +++++++++++++++------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/Base/usr/share/man/man5/GML/Usage.md b/Base/usr/share/man/man5/GML/Usage.md index 70e2280bfb6..d9d176b6bfa 100644 --- a/Base/usr/share/man/man5/GML/Usage.md +++ b/Base/usr/share/man/man5/GML/Usage.md @@ -6,43 +6,47 @@ GML Usage 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 -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 -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 set(SOURCES - MyAppGML.h + MyAppGML.cpp ) ``` ## 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> 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 -load_from_gml(my_app_gml); -``` +Calling the `try_create` function directly or indirectly (e.g. `Window::try_set_main_widget`) will now automatically load the structure defined in GML. From there, you can use `find_descendant_of_type_named` to select widgets from your GML by their `name` property. ```gml -@GUI::Button { - name: "mem_add_button" - text: "M+" - fixed_width: 35 - fixed_height: 28 - foreground_color: "red" +@MyApp::Widget { + @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); +// MyApp::Widget::foo_bar m_mem_add_button = *find_descendant_of_type_named("mem_add_button"); ```