update hello_imgui (added doc book)

bindings/imgui_bundle/doc/doc_parts/manual_himgui.adoc

@@ -4,24 +4,40 @@ include::_utils.adoc[]
 
 Dear ImGui Bundle includes https://github.com/pthom/hello_imgui[Hello ImGui], which is itself based on ImGui. "Hello ImGui" can be compared to a starter pack that enables to easily write cross-platform Gui apps for Windows, macOS, Linux,  iOS,  and https://en.wikipedia.org/wiki/Emscripten[emscripten].
 
-==== API
+==== API & Usage
 
-See the "Hello ImGui" https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/hello_imgui_api.md[API doc]. Also consult the doc on how to build {url-himgui-master-tree}/src/hello_imgui/dpi_aware.h[DPI aware] applications.
+See the "Hello ImGui" https://pthom.github.io/hello_imgui/book/doc_api.html[API doc] and https://pthom.github.io/hello_imgui/book/doc_params.html[Application parameter doc].
 
 ==== Features
 
-* Full multiplatform support: Windows, Linux, OSX, iOS, Emscripten, Android (poorly supported). See demo https://traineq.org/HelloImGui_6_Platforms.mp4[video]
-* Advanced layout handling
-* Power Save mode: reduce FPS when application is idle (see https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h[RunnerParams.fpsIdle])
-* {url-himgui-master-tree}/src/hello_imgui/dpi_aware.h[DPI aware] applications (widget placement, window size, font loading and scaling)
-* Theme tweaking (see https://www.youtube.com/watch?v=4f_-3DDcAZk[demo video], and https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/imgui_theme.h[API] )
-* Window geometry utilities: autosize, restore window position, full screen, etc. (see https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/app_window_params.h[WindowGeometry])
-* Multiplatform https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/hello_imgui_assets.h[assets embedding]
-* Switch between Glfw or Sdl backend (see https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h[RunnerParams.backendType])
+**Multiplatform utilities**
+
+* Truly multiplatform: Linux, Windows, macOS, iOS, Android, emscripten (with 4 lines of CMake code)
+* Easily embed assets on all platforms (no code required)
+* Customize app settings (icon and app name for mobile platforms, etc.- no code required)
+* Customize application icon on all platforms (including mobile and macOS - no code required)
+
+**Dear ImGui Tweaks**
+
+* Power Save mode: reduce FPS when idling
+* High DPI support: scale UI according to DPI, whatever the platform
+* Advanced layout handling: dockable windows, multiple layouts
+* Window geometry utilities: autosize application window, restore app window position
+* Theme tweaking: extensive list of additional themes
+* Support for movable and resizable borderless windows
+* Advanced font support: icons, emojis and colored fonts
+* Integration with ImGui Test Engine: automate and test your apps
+* Save user settings: window position, layout, opened windows, theme, user defined custom settings
+* Easily add a custom 3D background to your app
+
+**Backends**
+
+* Available platform backends: SDL2, Glfw3
+* Available rendering backends: OpenGL3, Metal, Vulkan, DirectX
 
 NOTE: The usage of `Hello ImGui` is optional. You can also build an imgui application from scratch, in {cpp} or in python (see link:{url-bindings-bundle}/demos_python/demos_immapp/imgui_example_glfw_opengl3.py[python example])
 
-TIP: HelloImGui is fully configurable by POD (plain old data) structures. See link:https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/hello_imgui_api.md[their description]
+TIP: HelloImGui is fully configurable by POD (plain old data) structures. See link:https://pthom.github.io/hello_imgui/book/doc_params.html[their description]
 
 ==== Advanced layout and theming with Hello ImGui:
 

bindings/imgui_bundle/hello_imgui.pyi

@@ -70,91 +70,47 @@ def EmptyEventCallback() -> AnyEventCallback:
 # //////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 # *
-# @@md#Dpi
+# @@md#DocEmToVec2
 #
 # Special care must be taken in order to correctly handle screen with high DPI (for example, almost all recent laptops screens).
-# Otherwise, widgets might be misplaced or too small, and font rendering might be blurry or too small.
 #
-#### How to position widgets on a window in a Dpi independent way
+# Using ImVec2 with fixed values is *almost always a bad idea* if you intend your application to be used on high DPI screens!
+# Otherwise, widgets might be misplaced or too small on different screens and/or OSes.
 #
-# Using ImVec2 with fixed values is *almost always a bad idea* if you intend your application to be used on high DPI screens.
-# Instead you can:
-# * either multiply those values by ImGui::GetFontSize()
-# * or use `HelloImGui::EmToVec2(x, y)` which will do this multiplication for you. Em stand for the `em` measurements,
-#   as used in CSS: 1em simply correspond to the current font height.
+# Instead you should use scale your widgets and windows relatively to the font size, as is done
+# with the [em CSS Unit](https://lyty.dev/css/css-unit.html).
 #
-#
-#### How to load fonts for a crisp font rendering and a correct size
-#
-# HelloImGui provides `HelloImGui::DpiFontLoadingFactor()` which corresponds to:
-#    `DpiWindowSizeFactor() * 1. / ImGui::GetIO().FontGlobalScale`
-#              where DpiWindowSizeFactor() is equal to `CurrentScreenPixelPerInch / 96` under windows and linux, 1 under macOS
-#
-# ==> When loading fonts, multiply their size by this factor!
-#
-#### More details on DPI handling with different OS and backends
-#
-# Let's consider screen whose physical pixel resolution is 3600x2000, but which will displayed with a scaling factor of 200%,
-# so that widgets do not look too small on it.
-#
-# The way it is handled depends on the OS:
-# - On MacOS, the screen will be seen as having a resolution of 1800x1000, and the OS handles the resizing by itself.
-# - On Linux, and on Windows if the application is DPI aware, the screen will be seen as having a resolution of 3600x2000.
-# - On Windows if the application is not DPI aware, the screen will be seen as having a resolution of 1800x1000
-#
-# By default, if using the glfw backend, applications will be Dpi aware under windows.
-# Sdl applications are normally not Dpi aware. However HelloImGui makes them Dpi aware when using the sdl backend.
-#
-#
-#### HelloImGui Dpi aware C++ API
-#
-# `HelloImGui::EmSize()` (C++) and `hello_imgui.em_size()` (Python) return the visible font size on the screen.
-# For reproducible results, even on HighDPI screens, always scale your widgets and windows relatively to this size.
-# It is somewhat comparable to the [em CSS Unit](https://lyty.dev/css/css-unit.html).
-#
-# `HelloImGui::EmToVec2(x, y)` (C++) and `hello_imgui.em_to_vec2(x,y)` (Python) return an ImVec2 that you can use
-# to size or place your widgets in a DPI independent way.
-#
-# `HelloImGui::EmSize(nbLines)` (C++) and `hello_imgui.em_size(nb_lines)` (Python) return a size corresponding to nbLines text lines
-#
-# `HelloImGui::DpiFontLoadingFactor()` (C++) and `hello_imgui.dpi_font_loading_factor()` (Python) return a factor by
-# which you shall multiply your font sizes when loading fonts manually with _ImGui::GetIO().Fonts->AddFont..._
-# HelloImGui::LoadFontTTF does this by default.
-#
-# `HelloImGui::ImGuiDefaultFontGlobalScale()` (C++) and `hello_imgui.imgui_default_font_global_scale()` (Python) returns the
-# default value that should be stored inside `ImGui::GetIO().FontGlobalScale`.
-# Under windows and linux, this is always 1: no rescaling should be done by ImGui. Under macOS and emscripten,
-# this can be < 1 (for example it will be 0.5 if the dpi scaling is 200%)
 # @@md
-#
+# *
 
-# float EmSize();    /* original C++ signature */
+# @@md#EmToVec2
+#  __HelloImGui::EmToVec2()__ returns an ImVec2 that you can use to size
+#  or place your widgets in a DPI independent way.
+#  Values are in multiples of the font size (i.e. as in the em CSS unit).
+# ImVec2 EmToVec2(float x, float y);    /* original C++ signature */
 @overload
-def em_size() -> float:
-    """__HelloImGui::EmSize()__ returns the visible font size on the screen. For good results on HighDPI screens, always scale your
-    widgets and windows relatively to this size.
-    It is somewhat comparable to the [em CSS Unit](https://lyty.dev/css/css-unit.html).
-    EmSize() = ImGui::GetFontSize()
-    """
+def em_to_vec2(x: float, y: float) -> ImVec2:
     pass
 
-# float EmSize(float nbLines);    /* original C++ signature */
+# ImVec2 EmToVec2(ImVec2 v);    /* original C++ signature */
 @overload
-def em_size(nb_lines: float) -> float:
-    """__HelloImGui::EmSize(nbLines)__ returns a size corresponding to nbLines text lines"""
+def em_to_vec2(v: ImVec2) -> ImVec2:
     pass
 
-# __HelloImGui::EmToVec2()__ returns an ImVec2 that you can use to size or place your widgets in a DPI independent way
-# ImVec2 EmToVec2(float x, float y);    /* original C++ signature */
+# float EmSize();    /* original C++ signature */
 @overload
-def em_to_vec2(x: float, y: float) -> ImVec2:
+def em_size() -> float:
+    """__HelloImGui::EmSize()__ returns the visible font size on the screen."""
     pass
 
-# ImVec2 EmToVec2(ImVec2 v);    /* original C++ signature */
+# float EmSize(float nbLines);    /* original C++ signature */
 @overload
-def em_to_vec2(v: ImVec2) -> ImVec2:
+def em_size(nb_lines: float) -> float:
+    """__HelloImGui::EmSize(nbLines)__ returns a size corresponding to nbLines text lines"""
     pass
 
+# @@md
+
 # float DpiFontLoadingFactor();    /* original C++ signature */
 def dpi_font_loading_factor() -> float:
     """Multiply font sizes by this factor when loading fonts manually with ImGui::GetIO().Fonts->AddFont...
@@ -175,6 +131,8 @@ def imgui_default_font_global_scale() -> float:
     """returns the default value that should be stored inside `ImGui::GetIO().FontGlobalScale`"""
     pass
 
+# namespace HelloImGui
+
 # *
 # @@md#AssetsStructure
 #
@@ -567,7 +525,12 @@ def darcula(
 # //////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 class FontLoadingParams:
-    """Font loading parameters: several options are available (color, merging, range, ...)"""
+    """@@md#Fonts
+
+    When loading fonts, use HelloImGui::LoadFont(fontFilename, fontSize, fontLoadingParams)
+
+    Font loading parameters: several options are available (color, merging, range, ...)
+    """
 
     # bool adjustSizeToDpi = true;    /* original C++ signature */
     # if True, the font size will be adjusted automatically to account for HighDPI
@@ -577,26 +540,30 @@ class FontLoadingParams:
     # if True, the font will be loaded with the full glyph range
     use_full_glyph_range: bool = False
     # bool reduceMemoryUsageIfFullGlyphRange = true;    /* original C++ signature */
-    # if set, fontConfig.GlyphRanges, and fontConfig.OversampleH / fontConfig.OversampleV will be set to 1
-    # when useFullGlyphRange is True (this is useful to save memory)
+    # if set, fontConfig.GlyphRanges, and
+    #   fontConfig.OversampleH / fontConfig.OversampleV will be set to 1
+    #   when useFullGlyphRange is True (this is useful to save memory)
     reduce_memory_usage_if_full_glyph_range: bool = True
 
     # bool mergeToLastFont = false;    /* original C++ signature */
     # if True, the font will be merged to the last font
     merge_to_last_font: bool = False
 
     # bool loadColor = false;    /* original C++ signature */
-    # if True, the font will be loaded using colors (requires freetype, enabled by IMGUI_ENABLE_FREETYPE)
+    # if True, the font will be loaded using colors
+    # (requires freetype, enabled by IMGUI_ENABLE_FREETYPE)
     load_color: bool = False
 
     # bool insideAssets = true;    /* original C++ signature */
-    # if True, the font will be loaded using HelloImGui asset system. Otherwise, it will be loaded from the filesystem
+    # if True, the font will be loaded using HelloImGui asset system.
+    # Otherwise, it will be loaded from the filesystem
     inside_assets: bool = True
 
     # std::vector<ImWcharPair> glyphRanges = {};    /* original C++ signature */
     # the ranges of glyphs to load:
     #    - if empty, the default glyph range will be used
     #    - you can specify several ranges
+    #    - intervals bounds are inclusive
     # (will be translated and stored as a static ImWChar* inside fontConfig)
     glyph_ranges: List[ImWcharPair] = List[ImWcharPair]()
 
@@ -627,14 +594,17 @@ class FontLoadingParams:
         """Auto-generated default constructor with named params"""
         pass
 
-# ImFont* LoadFont(const std::string & fontFilename, float fontSize, const FontLoadingParams & params = __srcmlcpp_brace_init__());    /* original C++ signature */
+# ImFont* LoadFont(const std::string & fontFilename, float fontSize,    /* original C++ signature */
+#                      const FontLoadingParams & params = __srcmlcpp_brace_init__());
 def load_font(
     font_filename: str,
     font_size: float,
     params: FontLoadingParams = FontLoadingParams(),
 ) -> ImFont:
     pass
 
+# @@md
+
 #
 # Deprecated API below, kept for compatibility (uses LoadFont internally)
 #
@@ -855,8 +825,7 @@ class WindowGeometry:
       // Will resize the app window at next displayed frame
       HelloImGui::GetRunnerParams()->appWindowParams.windowGeometry.resizeAppWindowAtNextFrame = True;
       ```
-
-      :::Note: this flag is intended to be used during execution, not at startup (use sizeAuto at startup):::
+      Note: this flag is intended to be used during execution, not at startup (use sizeAuto at startup).
     @@md
     *
     """
@@ -1438,7 +1407,7 @@ class RunnerCallbacks:
 #
 #![demo docking](https://traineq.org/ImGuiBundle/HelloImGuiLayout.gif)
 #
-# * Source for this example: [src/hello_imgui_demos/hello_imgui_demodocking](../../src/hello_imgui_demos/hello_imgui_demodocking)
+# * Source for this example: [src/hello_imgui_demos/hello_imgui_demodocking](https://github.com/pthom/hello_imgui/tree/master/src/hello_imgui_demos/hello_imgui_demodocking)
 # * [Video explanation on YouTube](https://www.youtube.com/watch?v=XKxmz__F4ow) (5 minutes)
 #
 #
@@ -1930,19 +1899,19 @@ class RunnerParams:
     **RunnerParams** is a struct that contains all the settings and callbacks needed to run an application.
 
      Members:
-    * `callbacks`: _see [runner_callbacks.h](runner_callbacks.h)_.
+    * `callbacks`: _see runner_callbacks.h_
        callbacks.ShowGui() will render the gui, ShowMenus() will show the menus, etc.
-    * `appWindowParams`: _see [app_window_params.h](app_window_params.h)_.
+    * `appWindowParams`: _see app_window_params.h_
        application Window Params (position, size, title)
-    * `imGuiWindowParams`: _see [imgui_window_params.h](imgui_window_params.h)_.
+    * `imGuiWindowParams`: _see imgui_window_params.h_
        imgui window params (use docking, showMenuBar, ProvideFullScreenWindow, etc)
-    * `dockingParams`: _see [docking_params.h](docking_params.h)_.
+    * `dockingParams`: _see docking_params.h_
        dockable windows content and layout
     * `alternativeDockingLayouts`: _vector<DockingParams>, default=empty_
        List of possible additional layout for the applications. Only used in advanced cases when several layouts are available.
     * `rememberSelectedAlternativeLayout`: _bool, default=true_
        Shall the application remember the last selected layout. Only used in advanced cases when several layouts are available.
-    * `backendPointers`: _see [backend_pointers.h](backend_pointers.h)_.
+    * `backendPointers`: _see backend_pointers.h_
        A struct that contains optional pointers to the backend implementations. These pointers will be filled
        when the application starts
     * `backendType`: _enum BackendType, default=BackendType::FirstAvailable_
@@ -2148,18 +2117,6 @@ def run(runner_params: RunnerParams) -> None:
       Runs an application, using simpler params.
 
     * `HelloImGui::Run(guiFunction, windowTitle, windowSize, windowSizeAuto=False, restoreLastWindowGeometry=False, fpsIdle=10)`
-
-
-    __Other utilities:__
-
-    * `HelloImGui::GetRunnerParams()`:
-      a convenience function that will return the runnerParams of the current application
-
-    * `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.
-      May differ from ImGui::GetIO().FrameRate, since one can choose the duration for the calculation of the mean value of the fps
-
-    * `ImGuiTestEngine* GetImGuiTestEngine()`: returns a pointer to the global instance of ImGuiTestEngine that was
-      initialized by HelloImGui (iif ImGui Test Engine is active).
     @@md
 
     """
@@ -2191,6 +2148,20 @@ def run(
 
 # RunnerParams *GetRunnerParams();    /* original C++ signature */
 def get_runner_params() -> RunnerParams:
+    """*
+    @@md#GetRunnerParams
+
+    * `HelloImGui::GetRunnerParams()`:
+      a convenience function that will return the runnerParams of the current application
+
+    * `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.
+      May differ from ImGui::GetIO().FrameRate, since one can choose the duration for the calculation of the mean value of the fps
+
+    * `ImGuiTestEngine* GetImGuiTestEngine()`: returns a pointer to the global instance of ImGuiTestEngine that was
+      initialized by HelloImGui (iif ImGui Test Engine is active).
+    @@md
+    *
+    """
     pass
 
 # float FrameRate(float durationForMean = 0.5f);    /* original C++ signature */
@@ -2209,7 +2180,7 @@ def get_imgui_test_engine() -> ImGuiTestEngine:
 # @@md#HelloImGui::Layouts
 #
 # In advanced cases when several layouts are available, you can switch between layouts.
-# (see demo inside [hello_imgui_demodocking.main.cpp](../hello_imgui_demos/hello_imgui_demodocking/hello_imgui_demodocking.main.cpp))
+# (see demo inside [hello_imgui_demodocking.main.cpp](https://github.com/pthom/hello_imgui/tree/master/src/hello_imgui_demos/hello_imgui_demodocking/hello_imgui_demodocking.main.cpp))
 #
 # * `SwitchLayout(layoutName)`
 #  Changes the application current layout. Only used in advanced cases when several layouts are available,

docs/devel_docs.html

@@ -484,7 +484,7 @@ <h2 id="devel_docs">Developer docs</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>

docs/faq.html

@@ -813,7 +813,7 @@ <h4 id="_windows_linux_adapting_windows_and_font_size_when_application_is_moved_
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>

docs/folders.html

@@ -653,7 +653,7 @@ <h2 id="folders">Repository folders structure</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>

docs/index.html

@@ -536,7 +536,7 @@ <h1>Dear ImGui Bundle documentation</h1>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>

docs/install-instructions.html

@@ -698,7 +698,7 @@ <h4 id="_run_the_c_demo">Run the C&#43;&#43; demo</h4>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>

docs/introduction.html

@@ -812,7 +812,7 @@ <h3 id="_easily_port_your_code_between_python_and_c">Easily port your code betwe
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2023-12-31 14:04:27 +0100
+Last updated 2024-01-08 08:03:24 +0100
 </div>
 </div>
 </body>