Update docs / 2024-09-30 / 15:15:13

docs/book/_sources/doc_api.md

@@ -24,6 +24,67 @@ the elements in the `RunnerParams` struct, or in the simpler  `SimpleRunnerParam
 __HelloImGui::GetRunnerParams()__  will return the runnerParams of the current application.
 
 
+# Run Application while handling the rendering loop
+If you want to be in control of the rendering loop, you may use the class `HelloImGui::Renderer` (available since September 2024)
+
+```cpp
+
+// HelloImGui::Renderer is an alternative to HelloImGui::Run, allowing fine-grained control over the rendering process.
+// - It is customizable like HelloImGui::Run: construct it with `RunnerParams` or `SimpleRunnerParams`
+// - `Render()` will render the application for one frame:
+//   Ensure that `Render()` is triggered regularly (e.g., through a loop or other mechanism) to maintain responsiveness.
+//   This method must be called on the main thread.
+//
+// A typical use case is:
+//    ```cpp
+//    HelloImGui::RunnerParams runnerParams;
+//    runnerParams.callbacks.ShowGui = ...; // your GUI function
+//    // Optionally, choose between Sleep, EarlyReturn, or Auto for fps idling mode:
+//    // runnerParams.fpsIdling.fpsIdlingMode = HelloImGui::FpsIdlingMode::Sleep; // or EarlyReturn, Auto
+//    Renderer renderer(runnerParams); // note: a distinct copy of the `RunnerParams` will be stored inside the HelloImGui::GetRunnerParams()
+//    while (! HelloImGui::GetRunnerParams()->appShallExit)
+//    {
+//        renderer.Render();
+//    }
+//   ```
+//
+// **Notes:**
+//  1. Depending on the configuration (`runnerParams.fpsIdling.fpsIdlingMode`), `HelloImGui` may enter an idle state to
+//     reduce CPU usage, if no events are received (e.g., no input or interaction).
+//     In this case, `Render()` will either sleep or return immediately.
+//     By default,
+//       - On Emscripten, `Render()` will return immediately to avoid blocking the main thread.
+//       - On other platforms, it will sleep
+//  2. Only one instance of `Renderer` can exist at a time.
+//  3. If constructed with `RunnerParams`, a copy of the `RunnerParams` will be made (which you can access with `GetRunnerParams())`.
+class Renderer
+{
+public:
+    // Initializes with the full customizable `RunnerParams` to set up the application.
+    // Nb: a distinct copy of the `RunnerParams` will be made, and you can access it with `GetRunnerParams()`.
+    Renderer(const RunnerParams& runnerParams);
+
+    // Initializes with SimpleRunnerParams.
+    Renderer(const SimpleRunnerParams& simpleParams);
+
+    // Initializes with a simple GUI function and additional parameters.
+    Renderer(
+        const VoidFunction &guiFunction,
+        const std::string &windowTitle = "",
+        bool windowSizeAuto = false,
+        bool windowRestorePreviousGeometry = false,
+        const ScreenSize &windowSize = DefaultWindowSize,
+        float fpsIdle = 10.f
+    );
+
+    // Render the current frame (or return immediately if in idle state).
+    void Render();
+
+    // Destructor (automatically tears down HelloImGui).
+    ~Renderer();
+};
+```
+
 ----
 
 # Place widgets in a DPI-aware way
@@ -51,6 +112,13 @@ ImVec2 EmToVec2(ImVec2 v);
 float EmSize();
 // __HelloImGui::EmSize(nbLines)__ returns a size corresponding to nbLines text lines
 float EmSize(float nbLines);
+
+// __HelloImGui::PixelToEm()__ converts a Vec2 in pixels coord to a Vec2 in em units
+ImVec2 PixelsToEm(ImVec2 pixels);
+
+// __HelloImGui::PixelSizeToEm()__ converts a size in pixels coord to a size in em units
+float  PixelSizeToEm(float pixelSize);
+
 ```
 
 ----
@@ -272,6 +340,12 @@ ImVec2 ImageProportionalSize(const ImVec2& askedSize, const ImVec2& imageSize);
 
 ```cpp
 
+// `GetRunnerParams()`:  a convenience function that will return the runnerParams
+// of the current application
+    RunnerParams* GetRunnerParams();
+
+// `IsUsingHelloImGui()`: returns true if the application is using HelloImGui
+    bool IsUsingHelloImGui();
 
 // `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.
 //  May differ from ImGui::GetIO().FrameRate, since one can choose the duration
@@ -317,6 +391,16 @@ void           SwitchLayout(const std::string& layoutName);
 
 // `CurrentLayoutName()`: returns the name of the current layout
 std::string    CurrentLayoutName();
+
+// `AddDockableWindow()`: will add a dockable window to the current layout.
+// Will dock the window to the dockspace it belongs to if forceDockspace is true,
+// otherwise will dock it to the last space it was docked to (using saved settings)
+void AddDockableWindow(const DockableWindow& dockableWindow, bool forceDockspace = false);
+
+// `RemoveDockableWindow()`: will remove a dockable window from the current layout.
+// (dockableWindowName is the label of the window, as provided in the DockableWindow struct)
+void RemoveDockableWindow(const std::string& dockableWindowName);
+
 ```
 
 ----

docs/book/_sources/doc_params.md

@@ -830,6 +830,22 @@ See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello
 
 ```cpp
 
+// FpsIdlingMode is an enum that describes the different modes of idling when rendering the GUI.
+// - Sleep: the application will sleep when idling to reduce CPU usage.
+// - EarlyReturn: rendering will return immediately when idling.
+//   This is specifically designed for event-driven, and real-time applications.
+//   Avoid using it in a tight loop without pauses, as it may cause excessive CPU consumption.
+// - Auto: use platform-specific default behavior.
+//    On most platforms, it will sleep. On Emscripten, `Render()` will return immediately
+//    to avoid blocking the main thread.
+// Note: you can override the default behavior by explicitly setting Sleep or EarlyReturn.
+enum class FpsIdlingMode
+{
+    Sleep,
+    EarlyReturn,
+    Auto,
+};
+
 // FpsIdling is a struct that contains Fps Idling parameters
 struct FpsIdling
 {
@@ -861,6 +877,10 @@ struct FpsIdling
     // `rememberEnableIdling`: _bool, default=true_.
     //  If true, the last value of enableIdling is restored from the settings at startup.
     bool  rememberEnableIdling = false;
+
+    // `fpsIdlingMode`: _FpsIdlingMode, default=FpsIdlingMode::Automatic_.
+    // Sets the mode of idling when rendering the GUI (Sleep, EarlyReturn, Automatic)
+    FpsIdlingMode fpsIdlingMode = FpsIdlingMode::Auto;
 };
 ```
 
@@ -1135,7 +1155,7 @@ struct DockingSplit
     // `direction`: *ImGuiDir_* 
     //  (enum with ImGuiDir_Down, ImGuiDir_Down, ImGuiDir_Left, ImGuiDir_Right)*
     //  Direction where this dock space should be created.
-    ImGuiDir_ direction;
+    ImGuiDir direction;
 
     // `ratio`: _float, default=0.25f_. 
     //  Ratio of the initialDock size that should be used by the new dock space.
@@ -1148,7 +1168,7 @@ struct DockingSplit
 
     // Constructor
     DockingSplit(const DockSpaceName& initialDock_ = "", const DockSpaceName& newDock_ = "",
-                 ImGuiDir_ direction_ = ImGuiDir_Down, float ratio_ = 0.25f,
+                 ImGuiDir direction_ = ImGuiDir_Down, float ratio_ = 0.25f,
                  ImGuiDockNodeFlags nodeFlags_ = ImGuiDockNodeFlags_None)
         : initialDock(initialDock_), newDock(newDock_), direction(direction_), ratio(ratio_), nodeFlags(nodeFlags_) {}
 };
@@ -1163,7 +1183,7 @@ struct DockableWindow
 {
     // --------------- Main params -------------------
 
-    // `label`: _string_. Title of the window.
+    // `label`: _string_. Title of the window. It should be unique! Use "##" to add a unique suffix if needed.
     std::string label;
 
     // `dockSpaceName`: _DockSpaceName (aka string)_.
@@ -1310,11 +1330,7 @@ struct DockingParams
     bool focusDockableWindow(const std::string& windowName);
 
     // `optional<ImGuiID> dockSpaceIdFromName(const std::string& dockSpaceName)`:
-    // may return the ImGuiID corresponding to the dockspace with this name.
-    // **Warning**: this will work reliably only if
-    //     layoutCondition = DockingLayoutCondition::ApplicationStart.
-    // In other cases, the ID may be cached by ImGui himself at the first run,
-    // and HelloImGui will *not* know it on subsequent runs!
+    // returns the ImGuiID corresponding to the dockspace with this name
     std::optional<ImGuiID> dockSpaceIdFromName(const std::string& dockSpaceName);
 };
 ```

docs/book/build.html

@@ -199,6 +199,7 @@
 
 
 
+
 <li class="toctree-l1 current active"><a class="current reference internal" href="#">Build instructions</a></li>
 </ul>
 
@@ -542,7 +543,7 @@ <h2>Hello ImGui dependencies<a class="headerlink" href="#hello-imgui-dependencie
 <span class="w">    </span><span class="nb">set</span><span class="p">(</span><span class="s">autodownload_default</span><span class="w"> </span><span class="s">ON</span><span class="p">)</span>
 <span class="nb">endif</span><span class="p">()</span>
 <span class="nb">option</span><span class="p">(</span><span class="s">HELLOIMGUI_DOWNLOAD_GLFW_IF_NEEDED</span><span class="w"> </span><span class="s2">&quot;Download and build GLFW if needed&quot;</span><span class="w"> </span><span class="o">${</span><span class="nv">autodownload_default</span><span class="o">}</span><span class="p">)</span>
-<span class="nb">option</span><span class="p">(</span><span class="s">HELLOIMGUI_DOWNLOAD_SDL_IF_NEEDED</span><span class="w"> </span><span class="s2">&quot;Download and build GLFW if needed&quot;</span><span class="w"> </span><span class="o">${</span><span class="nv">autodownload_default</span><span class="o">}</span><span class="p">)</span>
+<span class="nb">option</span><span class="p">(</span><span class="s">HELLOIMGUI_DOWNLOAD_SDL_IF_NEEDED</span><span class="w"> </span><span class="s2">&quot;Download and build SDL2 if needed&quot;</span><span class="w"> </span><span class="o">${</span><span class="nv">autodownload_default</span><span class="o">}</span><span class="p">)</span>
 <span class="nb">option</span><span class="p">(</span><span class="s">HELLOIMGUI_DOWNLOAD_FREETYPE_IF_NEEDED</span><span class="w"> </span><span class="s2">&quot;Download and build Freetype if needed&quot;</span><span class="w"> </span><span class="o">${</span><span class="nv">autodownload_default</span><span class="o">}</span><span class="p">)</span>
 <span class="nb">option</span><span class="p">(</span><span class="s">HELLOIMGUI_FREETYPE_STATIC</span><span class="w"> </span><span class="s2">&quot;Force static linking of freetype (only used for python bindings)&quot;</span><span class="w"> </span><span class="s">OFF</span><span class="p">)</span>
 </pre></div>