Update docs / 2024-01-08 / 20:03:36

docs/book/00_00_intro.html

@@ -187,6 +187,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>
 
 

docs/book/05_05_get_started.html

@@ -188,6 +188,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>
 
 

docs/book/60_05_build.html

@@ -187,6 +187,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>
 
 

docs/book/_sources/doc_api.md

@@ -227,7 +227,76 @@ ImVec2 ImageProportionalSize(const ImVec2& askedSize, const ImVec2& imageSize);
 
 ----
 
-## Utility functions
+# Ini settings location
+
+```cpp
+
+// IniFolderType is an enum which describle where is the base path to store
+// the ini file for the application settings.
+//
+// You can use IniFolderLocation(iniFolderType) to get the corresponding path.
+//
+// RunnerParams contains the following members, which are used to compute
+// the ini file location:
+//     iniFolderType           (IniFolderType::CurrentFolder by default)
+//     iniFilename             (empty string by default)
+//     iniFilename_useAppWindowTitle
+//         (true by default: iniFilename is derived from
+//          appWindowParams.windowTitle)
+//
+// iniFilename may contain a subfolder
+// (which will be created inside the iniFolderType folder if needed)
+//
+enum class IniFolderType
+{
+    // CurrentFolder: the folder where the application is executed
+    // (convenient for development, but not recommended for production)
+    CurrentFolder,
+
+    // AppUserConfigFolder:
+    //      AppData under Windows (Example: C:\Users\[Username]\AppData\Roaming under windows)
+    //      ~/.config under Linux
+    //      "~/Library/Application Support" under macOS
+    // (recommended for production, if settings do not need to be easily accessible by the user)
+    AppUserConfigFolder,
+
+    // AppExecutableFolder: the folder where the application executable is located
+    // (this may be different from CurrentFolder if the application is launched from a shortcut)
+    // (convenient for development, but not recommended for production)
+    AppExecutableFolder,
+
+    // HomeFolder: the user home folder
+    // (recommended for production, if settings need to be easily accessible by the user)
+    HomeFolder,
+
+    // DocumentsFolder: the user documents folder
+    DocumentsFolder,
+
+    // TempFolder: the system temp folder
+    TempFolder
+};
+
+// Returns the path corresponding to the given IniFolderType
+std::string IniFolderLocation(IniFolderType iniFolderType);
+
+```
+
+```cpp
+
+// IniSettingsLocation returns the path to the ini file for the application settings.
+std::string IniSettingsLocation(const RunnerParams& runnerParams);
+
+// HasIniSettings returns true if the ini file for the application settings exists.
+bool HasIniSettings(const RunnerParams& runnerParams);
+
+// DeleteIniSettings deletes the ini file for the application settings.
+void DeleteIniSettings(const RunnerParams& runnerParams);
+
+```
+
+----
+
+# Utility functions
 
 ```cpp
 

docs/book/_sources/doc_params.md

@@ -176,6 +176,7 @@ struct RunnerParams
 };
 ```
 
+
 # Fps Idling
 
 See [runner_params.h](https://github.com/pthom/hello_imgui/blob/master/src/hello_imgui/runner_params.h).

docs/book/doc_api.html

@@ -188,6 +188,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>
 
 
@@ -400,9 +402,10 @@ <h2> Contents </h2>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#load-assets-as-data-buffer">Load Assets as data buffer</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#get-assets-path">Get assets path</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#display-images-from-assets">Display images from assets</a></li>
-<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#utility-functions">Utility functions</a></li>
 </ul>
 </li>
+<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#ini-settings-location">Ini settings location</a></li>
+<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#utility-functions">Utility functions</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#switch-between-several-layouts">Switch between several layouts</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#store-user-settings-in-the-ini-file">Store user settings in the ini file</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#customize-hello-imgui-menus">Customize Hello ImGui Menus</a></li>
@@ -631,9 +634,73 @@ <h2>Display images from assets<a class="headerlink" href="#display-images-from-a
 </pre></div>
 </div>
 </section>
+</section>
 <hr class="docutils" />
-<section id="utility-functions">
-<h2>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this heading">#</a></h2>
+<section class="tex2jax_ignore mathjax_ignore" id="ini-settings-location">
+<h1>Ini settings location<a class="headerlink" href="#ini-settings-location" title="Permalink to this heading">#</a></h1>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// IniFolderType is an enum which describle where is the base path to store</span>
+<span class="c1">// the ini file for the application settings.</span>
+<span class="c1">//</span>
+<span class="c1">// You can use IniFolderLocation(iniFolderType) to get the corresponding path.</span>
+<span class="c1">//</span>
+<span class="c1">// RunnerParams contains the following members, which are used to compute</span>
+<span class="c1">// the ini file location:</span>
+<span class="c1">//     iniFolderType           (IniFolderType::CurrentFolder by default)</span>
+<span class="c1">//     iniFilename             (empty string by default)</span>
+<span class="c1">//     iniFilename_useAppWindowTitle</span>
+<span class="c1">//         (true by default: iniFilename is derived from</span>
+<span class="c1">//          appWindowParams.windowTitle)</span>
+<span class="c1">//</span>
+<span class="c1">// iniFilename may contain a subfolder</span>
+<span class="c1">// (which will be created inside the iniFolderType folder if needed)</span>
+<span class="c1">//</span>
+<span class="k">enum</span><span class="w"> </span><span class="k">class</span><span class="w"> </span><span class="nc">IniFolderType</span>
+<span class="p">{</span>
+<span class="w">    </span><span class="c1">// CurrentFolder: the folder where the application is executed</span>
+<span class="w">    </span><span class="c1">// (convenient for development, but not recommended for production)</span>
+<span class="w">    </span><span class="n">CurrentFolder</span><span class="p">,</span>
+
+<span class="w">    </span><span class="c1">// AppUserConfigFolder:</span>
+<span class="w">    </span><span class="c1">//      AppData under Windows (Example: C:\Users\[Username]\AppData\Roaming under windows)</span>
+<span class="w">    </span><span class="c1">//      ~/.config under Linux</span>
+<span class="w">    </span><span class="c1">//      &quot;~/Library/Application Support&quot; under macOS</span>
+<span class="w">    </span><span class="c1">// (recommended for production, if settings do not need to be easily accessible by the user)</span>
+<span class="w">    </span><span class="n">AppUserConfigFolder</span><span class="p">,</span>
+
+<span class="w">    </span><span class="c1">// AppExecutableFolder: the folder where the application executable is located</span>
+<span class="w">    </span><span class="c1">// (this may be different from CurrentFolder if the application is launched from a shortcut)</span>
+<span class="w">    </span><span class="c1">// (convenient for development, but not recommended for production)</span>
+<span class="w">    </span><span class="n">AppExecutableFolder</span><span class="p">,</span>
+
+<span class="w">    </span><span class="c1">// HomeFolder: the user home folder</span>
+<span class="w">    </span><span class="c1">// (recommended for production, if settings need to be easily accessible by the user)</span>
+<span class="w">    </span><span class="n">HomeFolder</span><span class="p">,</span>
+
+<span class="w">    </span><span class="c1">// DocumentsFolder: the user documents folder</span>
+<span class="w">    </span><span class="n">DocumentsFolder</span><span class="p">,</span>
+
+<span class="w">    </span><span class="c1">// TempFolder: the system temp folder</span>
+<span class="w">    </span><span class="n">TempFolder</span>
+<span class="p">};</span>
+
+<span class="c1">// Returns the path corresponding to the given IniFolderType</span>
+<span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="nf">IniFolderLocation</span><span class="p">(</span><span class="n">IniFolderType</span><span class="w"> </span><span class="n">iniFolderType</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// IniSettingsLocation returns the path to the ini file for the application settings.</span>
+<span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="nf">IniSettingsLocation</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">RunnerParams</span><span class="o">&amp;</span><span class="w"> </span><span class="n">runnerParams</span><span class="p">);</span>
+
+<span class="c1">// HasIniSettings returns true if the ini file for the application settings exists.</span>
+<span class="kt">bool</span><span class="w"> </span><span class="nf">HasIniSettings</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">RunnerParams</span><span class="o">&amp;</span><span class="w"> </span><span class="n">runnerParams</span><span class="p">);</span>
+
+<span class="c1">// DeleteIniSettings deletes the ini file for the application settings.</span>
+<span class="kt">void</span><span class="w"> </span><span class="nf">DeleteIniSettings</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">RunnerParams</span><span class="o">&amp;</span><span class="w"> </span><span class="n">runnerParams</span><span class="p">);</span>
+</pre></div>
+</div>
+</section>
+<hr class="docutils" />
+<section class="tex2jax_ignore mathjax_ignore" id="utility-functions">
+<h1>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this heading">#</a></h1>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// `FrameRate(durationForMean = 0.5)`: Returns the current FrameRate.</span>
 <span class="c1">//  May differ from ImGui::GetIO().FrameRate, since one can choose the duration</span>
 <span class="c1">//  for the calculation of the mean value of the fps</span>
@@ -649,7 +716,6 @@ <h2>Utility functions<a class="headerlink" href="#utility-functions" title="Perm
 </pre></div>
 </div>
 </section>
-</section>
 <hr class="docutils" />
 <section class="tex2jax_ignore mathjax_ignore" id="switch-between-several-layouts">
 <h1>Switch between several layouts<a class="headerlink" href="#switch-between-several-layouts" title="Permalink to this heading">#</a></h1>
@@ -818,9 +884,10 @@ <h2>Dpi aware Font scaling<a class="headerlink" href="#dpi-aware-font-scaling" t
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#load-assets-as-data-buffer">Load Assets as data buffer</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#get-assets-path">Get assets path</a></li>
 <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#display-images-from-assets">Display images from assets</a></li>
-<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#utility-functions">Utility functions</a></li>
 </ul>
 </li>
+<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#ini-settings-location">Ini settings location</a></li>
+<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#utility-functions">Utility functions</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#switch-between-several-layouts">Switch between several layouts</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#store-user-settings-in-the-ini-file">Store user settings in the ini file</a></li>
 <li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#customize-hello-imgui-menus">Customize Hello ImGui Menus</a></li>

docs/book/doc_params.html

@@ -188,6 +188,8 @@
 
 
 
+
+
 <li class="toctree-l1 current active"><a class="current reference internal" href="#">Application parameters</a></li>
 
 

docs/book/genindex.html

@@ -185,6 +185,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>
 
 

docs/book/search.html

@@ -187,6 +187,8 @@
 
 
 
+
+
 <li class="toctree-l1"><a class="reference internal" href="doc_params.html">Application parameters</a></li>