Skip to content

Commit

Permalink
Update docs / 2024-07-06 / 22:52:53
Browse files Browse the repository at this point in the history
  • Loading branch information
@pthom
pthom committed Jul 6, 2024
1 parent b9410c8 commit 2bdd068
Show file tree
Hide file tree
Showing 5 changed files with 119 additions and 35 deletions.
23 changes: 20 additions & 3 deletions docs/book/_sources/doc_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,12 @@ See [hello_imgui_font.h](https://github.com/pthom/hello_imgui/blob/master/src/he
// Otherwise, it will be loaded from the filesystem
bool insideAssets = true;
// the ranges of glyphs to load:
// the ranges of glyphs to load, as a list of pairs of ImWchar
// - 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)
// Note: in order to use common ranges defined by ImGui (GetGlyphRangesJapanese, GetGlyphRangesChinese, ...)
// use TranslateCommonGlyphRanges (or translate_common_glyph_ranges in Python)
std::vector<ImWcharPair> glyphRanges = {};
// ImGui native font config to use
Expand Down Expand Up @@ -326,7 +327,7 @@ std::string CurrentLayoutName();
```cpp
// IniFolderType is an enum which describle where is the base path to store
// IniFolderType is an enum which describes where is the base path to store
// the ini file for the application settings.
//
// You can use IniFolderLocation(iniFolderType) to get the corresponding path.
Expand All @@ -348,6 +349,10 @@ enum class IniFolderType
// (convenient for development, but not recommended for production)
CurrentFolder,
// AbsolutePath: an absolute path
// (convenient, but not recommended if targeting multiple platforms)
AbsolutePath,
// AppUserConfigFolder:
// AppData under Windows (Example: C:\Users\[Username]\AppData\Roaming under windows)
// ~/.config under Linux
Expand Down Expand Up @@ -464,8 +469,20 @@ void ShowAppMenu(RunnerParams & runnerParams);
// ```
struct InputTextData
{
// The text edited in the input field
std::string Text;
// An optional hint displayed when the input field is empty
// (only works for single-line text input)
std::string Hint;
// If true, the input field is multi-line
bool Multiline = false;
// If true, the input field is resizable
bool Resizable = true;
// The size of the input field in em units
ImVec2 SizeEm = ImVec2(0, 0);
InputTextData(const std::string& text = "", bool multiline = false, ImVec2 size_em = ImVec2(0, 0)) : Text(text), Multiline(multiline), SizeEm(size_em) {}
Expand Down
53 changes: 39 additions & 14 deletions docs/book/_sources/doc_params.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,7 @@ struct RunnerCallbacks
// --------------- GUI Callbacks -------------------
// `ShowGui`: Fill it with a function that will add your widgets.
// (ShowGui will be called at each frame, before rendering the Dockable windows, if any)
VoidFunction ShowGui = EmptyVoidFunction();
// `ShowMenus`: Fill it with a function that will add ImGui menus by calling:
Expand Down Expand Up @@ -408,6 +409,10 @@ struct RunnerCallbacks
// on top of that content.
VoidFunction CustomBackground = EmptyVoidFunction();
// `PostRenderDockableWindows`: Fill it with a function that will be called
// after the dockable windows are rendered.
VoidFunction PostRenderDockableWindows = EmptyVoidFunction();
// `AnyBackendEventCallback`:
// Callbacks for events from a specific backend. _Only implemented for SDL.
// where the event will be of type 'SDL_Event *'_
Expand Down Expand Up @@ -594,6 +599,13 @@ struct AppWindowParams
// `handleEdgeInsets`: _bool, default = true_. iOS only.
// If true, HelloImGui will handle the edgeInsets on iOS.
bool handleEdgeInsets = true;

// ----------------- repaint the window during resize -----------------
// Very advanced and reserved for advanced C++ users.
// If you set this to true, the window will be repainted during resize.
// Do read https://github.com/pthom/hello_imgui/issues/112 for info about the possible gotchas
// (This API is not stable, as the name suggests, and this is not supported)
bool repaintDuringResize_GotchaReentrantRepaint = false;
};
```

Expand Down Expand Up @@ -861,8 +873,9 @@ Source: [dpi_aware.h](https://github.com/pthom/hello_imgui/blob/master/src/hello

//
// Hello ImGui will try its best to automatically handle DPI scaling for you.
// It does this by setting two values:
//
// Parameters to change the scaling behavior:
// ------------------------------------------
// - `dpiWindowSizeFactor`:
// factor by which window size should be multiplied
//
Expand All @@ -873,22 +886,22 @@ Source: [dpi_aware.h](https://github.com/pthom/hello_imgui/blob/master/src/hello
// By default, Hello ImGui will compute them automatically,
// when dpiWindowSizeFactor and fontRenderingScale are set to 0.
//
// Parameters to improve font rendering quality:
// ---------------------------------------------
// - `fontOversampleH` and `fontOversampleV` : Font oversampling parameters
// Rasterize at higher quality for sub-pixel positioning. Probably unused if freeType is used.
// If not zero, these values will be used to set the oversampling factor when loading fonts.
//
//
// How to set those values manually:
// ---------------------------------
// If it fails (i.e. your window and/or fonts are too big or too small),
// you may set them manually:
// (1) Either by setting them programmatically in your application
// (set their values in `runnerParams.dpiAwareParams`)
// (2) Either by setting them in a `hello_imgui.ini` file in the current folder, or any of its parent folders.
// (this is useful when you want to set them for a specific app or set of apps, without modifying the app code)
// (2) Either by setting them in a `hello_imgui.ini` file. See hello_imgui/hello_imgui_example.ini for more info
// Note: if several methods are used, the order of priority is (1) > (2)
//
// Example content of a ini file:
// ------------------------------
// [DpiAwareParams]
// dpiWindowSizeFactor=2
// fontRenderingScale=0.5
//
// For more information, see the documentation on DPI handling, here: https://pthom.github.io/hello_imgui/book/doc_api.html#handling-screens-with-high-dpi
//
struct DpiAwareParams
Expand Down Expand Up @@ -922,10 +935,22 @@ struct DpiAwareParams
// (This parameter will be used to set ImGui::GetIO().FontGlobalScale at startup)
float fontRenderingScale = 0.0f;

// `onlyUseFontDpiResponsive`
// If true, guarantees that only HelloImGui::LoadDpiResponsiveFont will be used to load fonts.
// (also for the default font)
bool onlyUseFontDpiResponsive = false;
// `onlyUseFontDpiResponsive`
// If true, guarantees that only HelloImGui::LoadDpiResponsiveFont will be used to load fonts.
// (also for the default font)
bool onlyUseFontDpiResponsive = false;

// `fontOversampleH` and `fontOversampleV` : Font oversampling parameters
// Rasterize at higher quality for sub-pixel positioning. Probably unused if freeType is used.
// If not zero, these values will be used to set the oversampling factor when loading fonts.
// (i.e. they will be set in ImFontConfig::OversampleH and ImFontConfig::OversampleV)
// OversampleH: The difference between 2 and 3 for OversampleH is minimal.
// You can reduce this to 1 for large glyphs save memory.
// OversampleV: This is not really useful as we don't use sub-pixel positions on the Y axis.
// Read https://github.com/nothings/stb/blob/master/tests/oversample/README.md for details.
int fontOversampleH = 0; // Default is 2 in ImFontConfig
int fontOversampleV = 0; // Default is 1 in ImFontConfig


// `dpiFontLoadingFactor`
// factor by which font size should be multiplied at loading time to get a similar
Expand Down Expand Up @@ -1356,7 +1381,7 @@ struct RendererBackendOptions

// `openGlOptions`:
// Advanced options for OpenGL. Use at your own risk.
std::optional<OpenGlOptions> openGlOptions = std::nullopt;
OpenGlOptions openGlOptions;
};


Expand Down
23 changes: 20 additions & 3 deletions docs/book/doc_api.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -530,11 +530,12 @@ <h1>Load fonts<a class="headerlink" href="#load-fonts" title="Permalink to this
<span class="w"> </span><span class="c1">// Otherwise, it will be loaded from the filesystem</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">insideAssets</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">true</span><span class="p">;</span>

<span class="w"> </span><span class="c1">// the ranges of glyphs to load:</span>
<span class="w"> </span><span class="c1">// the ranges of glyphs to load, as a list of pairs of ImWchar</span>
<span class="w"> </span><span class="c1">// - if empty, the default glyph range will be used</span>
<span class="w"> </span><span class="c1">// - you can specify several ranges</span>
<span class="w"> </span><span class="c1">// - intervals bounds are inclusive</span>
<span class="w"> </span><span class="c1">// (will be translated and stored as a static ImWChar* inside fontConfig)</span>
<span class="w"> </span><span class="c1">// Note: in order to use common ranges defined by ImGui (GetGlyphRangesJapanese, GetGlyphRangesChinese, ...)</span>
<span class="w"> </span><span class="c1">// use TranslateCommonGlyphRanges (or translate_common_glyph_ranges in Python)</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span><span class="n">ImWcharPair</span><span class="o">&gt;</span><span class="w"> </span><span class="n">glyphRanges</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{};</span>

<span class="w"> </span><span class="c1">// ImGui native font config to use</span>
Expand Down Expand Up @@ -751,7 +752,7 @@ <h1>Switch between several layouts<a class="headerlink" href="#switch-between-se
<h1>Ini settings<a class="headerlink" href="#ini-settings" title="Permalink to this heading">#</a></h1>
<section id="ini-settings-location">
<h2>Ini settings location<a class="headerlink" href="#ini-settings-location" title="Permalink to this heading">#</a></h2>
<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>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// IniFolderType is an enum which describes 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>
Expand All @@ -773,6 +774,10 @@ <h2>Ini settings location<a class="headerlink" href="#ini-settings-location" tit
<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">// AbsolutePath: an absolute path</span>
<span class="w"> </span><span class="c1">// (convenient, but not recommended if targeting multiple platforms)</span>
<span class="w"> </span><span class="n">AbsolutePath</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>
Expand Down Expand Up @@ -878,8 +883,20 @@ <h2>InputTextResizable<a class="headerlink" href="#inputtextresizable" title="Pe
<span class="w"> </span><span class="c1">// ```</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">InputTextData</span>
<span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="c1">// The text edited in the input field</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="n">Text</span><span class="p">;</span>

<span class="w"> </span><span class="c1">// An optional hint displayed when the input field is empty</span>
<span class="w"> </span><span class="c1">// (only works for single-line text input)</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="w"> </span><span class="n">Hint</span><span class="p">;</span>

<span class="w"> </span><span class="c1">// If true, the input field is multi-line</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">Multiline</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">;</span>

<span class="w"> </span><span class="c1">// If true, the input field is resizable</span>
<span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">Resizable</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">true</span><span class="p">;</span>

<span class="w"> </span><span class="c1">// The size of the input field in em units</span>
<span class="w"> </span><span class="n">ImVec2</span><span class="w"> </span><span class="n">SizeEm</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ImVec2</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">);</span>

<span class="w"> </span><span class="n">InputTextData</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">&amp;</span><span class="w"> </span><span class="n">text</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">,</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">multiline</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">false</span><span class="p">,</span><span class="w"> </span><span class="n">ImVec2</span><span class="w"> </span><span class="n">size_em</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ImVec2</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">))</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">Text</span><span class="p">(</span><span class="n">text</span><span class="p">),</span><span class="w"> </span><span class="n">Multiline</span><span class="p">(</span><span class="n">multiline</span><span class="p">),</span><span class="w"> </span><span class="n">SizeEm</span><span class="p">(</span><span class="n">size_em</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span>
Expand Down
Loading

0 comments on commit 2bdd068

Please sign in to comment.