diff --git a/core/include/cubos/core/ui/ecs.hpp b/core/include/cubos/core/ui/ecs.hpp index af5799a93c..4d95aa434e 100644 --- a/core/include/cubos/core/ui/ecs.hpp +++ b/core/include/cubos/core/ui/ecs.hpp @@ -1,17 +1,25 @@ +/// @file +/// @brief Functions @ref cubos::core::ui::showWorld and @ref cubos::core::ui::editWorld. +/// @ingroup core-ui + #pragma once #include namespace cubos::core::ui { - /// ECS system which allows the user to inspect the entities and components in an ECS world. + /// @brief Adds a ImGui window which allows the user to inspect the entities and components in + /// a @ref ecs::World. /// @param world World to show. /// @param context Optional context for serializing the world. + /// @ingroup core-ui void showWorld(const ecs::World& world, data::Context* context = nullptr); - /// ECS system which allows the user to inspect and edit the entities and components in an ECS world. + /// @brief Adds a ImGui window which allows the user to edit the entities and components in a + /// @ref ecs::World. /// @param world World to edit. /// @param serContext Optional context for serializing the world. /// @param desContext Optional context for deserializing the world. + /// @ingroup core-ui void editWorld(ecs::World& world, data::Context* serContext = nullptr, data::Context* desContext = nullptr); } // namespace cubos::core::ui diff --git a/core/include/cubos/core/ui/imgui.hpp b/core/include/cubos/core/ui/imgui.hpp index 7182ebe08b..b732922cc5 100644 --- a/core/include/cubos/core/ui/imgui.hpp +++ b/core/include/cubos/core/ui/imgui.hpp @@ -1,3 +1,7 @@ +/// @file +/// @brief Functions for initializing and using ImGui. +/// @ingroup core-ui + #pragma once #include @@ -5,23 +9,31 @@ namespace cubos::core::ui { - /// Initializes ImGui for use with the given window. - /// Should only be called once and no ImGui calls should be made before this is called. + /// @brief Initializes ImGui for use with the given window. + /// @note Should only be called once and no ImGui calls should be made before this is called. /// @param window The window to use. + /// @ingroup core-ui void initialize(io::Window window); - /// Shuts down ImGui. - /// Should only be called once, after @ref initialize, and no ImGui calls should be made after this is called. + /// @brief Shuts down ImGui. + /// @note Should only be called once, after @ref initialize(), and no ImGui calls should be + /// made after this is called. + /// @ingroup core-ui void terminate(); - /// Begins a new ImGui frame. + /// @brief Begins a new ImGui frame. + /// @ingroup core-ui void beginFrame(); - /// Ends the current ImGui frame, and renders the ImGui draw data to the window. + /// @brief Ends the current ImGui frame, and renders the ImGui draw data to the @p target + /// framebuffer, or the default framebuffer if @p target is null. + /// @param target Framebuffer to render to. + /// @ingroup core-ui void endFrame(const gl::Framebuffer& target = nullptr); - /// Passes a window event to ImGui. - /// @param event The event to pass. - /// @return True if the event was consumed by ImGui, false otherwise. + /// @brief Passes a window event to ImGui. + /// @param event Event to pass. + /// @return True if the event was handled by ImGui, false otherwise. + /// @ingroup core-ui bool handleEvent(const io::WindowEvent& event); } // namespace cubos::core::ui diff --git a/core/include/cubos/core/ui/module.dox b/core/include/cubos/core/ui/module.dox new file mode 100644 index 0000000000..9ac851450c --- /dev/null +++ b/core/include/cubos/core/ui/module.dox @@ -0,0 +1,15 @@ +/// @dir +/// @brief @ref core-ui module. + +#pragma once + +/// @namespace cubos::core::ui +/// @brief @ref core-ui module. +/// @ingroup core-ui + +namespace cubos::core::ui +{ + /// @defgroup core-ui User Interface + /// @ingroup core + /// @brief Provides `ImGui` integration and general UI utilities. +} // namespace cubos::core::ui diff --git a/core/include/cubos/core/ui/serialization.hpp b/core/include/cubos/core/ui/serialization.hpp index c80f0335bb..da99eb707d 100644 --- a/core/include/cubos/core/ui/serialization.hpp +++ b/core/include/cubos/core/ui/serialization.hpp @@ -1,33 +1,46 @@ +/// @file +/// @brief Functions for showing and editing serializable objects in the UI. +/// @ingroup core-ui + #pragma once #include namespace cubos::core::ui { - /// Shows a packaged object's properties in the UI. Should be called - /// inside a ImGui::BeginTable(2)/ImGui::EndTable() block. + /// @brief Shows a packaged object's properties in the UI. Should be called inside a + /// `ImGui::BeginTable(2)` and `ImGui::EndTable()` block. + /// + /// The first column displays the name of the package and the second column displays the value + /// of the package. /// - /// The first column displays the name of the package and the second column displays the value of the package - /// @param pkg The packaged object to show. - /// @param name The name of the object. + /// @param pkg Packaged object to show. + /// @param name Name of the object. + /// @ingroup core-ui void showPackage(const data::Package& pkg, const std::string& name); - /// Shows a packaged object's properties in the UI, allowing the user to - /// edit the object. Should be called inside a - /// ImGui::BeginTable(3)/ImGui::EndTable() block. - /// - /// The first column displays the name of the package, the second column displays the value of the package, and the - /// third column is used for remove buttons in the case of arrays and dictionaries. - /// @param pkg The packaged object to edit. - /// @param name The name of the object. - /// @returns True if the object was edited, false otherwise. + /// @brief Shows a packaged object's properties in the UI, allowing the user to edit the + /// object. Should be called inside a `ImGui::BeginTable(3)` and `ImGui::EndTable()` block. + /// + /// The first column displays the name of the package, the second column displays the value + /// of the package and the third column is used for remove buttons in the case of arrays and + /// dictionaries. + /// + /// @param pkg Packaged object to edit. + /// @param name Name of the object. + /// @return True if the object was modified, false otherwise. + /// @ingroup core-ui bool editPackage(data::Package& pkg, const std::string& name); - /// Shows a serializable object's properties in the UI. Should be called - /// inside a ImGui::BeginTable(2)/ImGui::EndTable() block. - /// @tparam T The type of the serializable object. - /// @param object The object to show. - /// @param name The name of the object. + /// @brief Shows a serializable object's properties in the UI. Should be called inside a + /// `ImGui::BeginTable(2)` and `ImGui::EndTable()` block. + /// + /// Internally packages the object and calls @ref showPackage(). + /// + /// @tparam T Type of the serializable object. + /// @param object Object to show. + /// @param name Name of the object. + /// @ingroup core-ui template inline void show(const T& object, const std::string& name) { @@ -35,14 +48,17 @@ namespace cubos::core::ui showPackage(pkg, name); } - /// Shows a serializable and deserializable object's properties in the UI, - /// allowing the user to edit the object. If any of the properties is - /// edited, the object's deserialize() method is called. Should be called - /// inside a ImGui::BeginTable(3)/ImGui::EndTable() block. - /// @tparam T The type of the serializable object. - /// @param object The object to edit. - /// @param name The name of the object. - /// @returns True if the object was edited, false otherwise. + /// @brief Shows a serializable object's properties in the UI. Should be called inside a + /// `ImGui::BeginTable(3)` and `ImGui::EndTable()` block. + /// + /// Internally packages the object, calls @ref editPackage() and then unpackages the object, if + /// it was modified. + /// + /// @tparam T Type of the serializable object. + /// @param object Object to edit. + /// @param name Name of the object. + /// @return True if the object was edited, false otherwise. + /// @ingroup core-ui template inline bool edit(T& object, const std::string& name) {