Docs: Improvements to description of using colored glyphes/emojis. (#4169, #3369) + Add Fonts to Metrics. Removed IMGUI_HAS_TABLE markers.
diff --git a/docs/CHANGELOG.txt b/docs/CHANGELOG.txt
index ef58aed..88d228f 100644
--- a/docs/CHANGELOG.txt
+++ b/docs/CHANGELOG.txt
@@ -83,6 +83,7 @@
par with original version. Now incorporating the correct revert.
- ImDrawList: Fixed PathArcTo() regression from 1.82 preventing use of counter-clockwise angles. (#4030, #3491) [@thedmd]
- Demo: Improved popups demo and comments.
+- Metrics: Added "Fonts" section with same information as available in "Style Editor">"Fonts".
- Backends: SDL: Rework global mouse pos availability check listing supported platforms explicitly,
effectively fixing mouse access on Raspberry Pi. (#2837, #3950) [@lethal-guitar, @hinxx]
- Backends: Win32: Clearing keyboard down array when losing focus (WM_KILLFOCUS). (#2062, #3532, #3961)
@@ -104,6 +105,7 @@
- Examples: Vulkan: Prefer using discrete GPU if there are more than one available. (#4012) [@rokups]
- Examples: SDL2: Link with shell32.lib required by SDL2main.lib since SDL 2.0.12. [#3988]
- Examples: Android: Make Android example build compatible with Gradle 7.0. (#3446)
+- Docs: Improvements to description of using colored glyphes/emojis. (#4169, #3369)
- Docs: Improvements to minor mistakes in documentation comments (#3923) [@ANF-Studios]
diff --git a/docs/FONTS.md b/docs/FONTS.md
index 2aa651d..760877e 100644
--- a/docs/FONTS.md
+++ b/docs/FONTS.md
@@ -5,7 +5,7 @@
The code in imgui.cpp embeds a copy of 'ProggyClean.ttf' (by Tristan Grimmer),
a 13 pixels high, pixel-perfect font used by default. We embed it in the source code so you can use Dear ImGui without any file system access. ProggyClean does not scale smoothly, therefore it is recommended that you load your own file when using Dear ImGui in an application aiming to look nice and wanting to support multiple resolutions.
-You may also load external .TTF/.OTF files.
+You may also load external .TTF/.OTF files.
In the [misc/fonts/](https://github.com/ocornut/imgui/tree/master/misc/fonts) folder you can find a few suggested fonts, provided as a convenience.
**Also read the FAQ:** https://www.dearimgui.org/faq (there is a Fonts section!)
@@ -14,8 +14,9 @@
- [Readme First](#readme-first)
- [How should I handle DPI in my application?](#how-should-i-handle-dpi-in-my-application)
- [Fonts Loading Instructions](#font-loading-instructions)
-- [Using Icons](#using-icons)
-- [Using FreeType Rasterizer](#using-freetype-rasterizer)
+- [Using Icon Fonts](#using-icon-fonts)
+- [Using FreeType Rasterizer (imgui_freetype)](#using-freetype-rasterizer-imgui_freetype)
+- [Using Colorful Glyphs/Emojis](#using-colorful-glyphsemojis)
- [Using Custom Glyph Ranges](#using-custom-glyph-ranges)
- [Using Custom Colorful Icons](#using-custom-colorful-icons)
- [Using Font Data Embedded In Source Code](#using-font-data-embedded-in-source-code)
@@ -26,7 +27,7 @@
---------------------------------------
## Readme First
-- All loaded fonts glyphs are rendered into a single texture atlas ahead of time. Calling either of `io.Fonts->GetTexDataAsAlpha8()`, `io.Fonts->GetTexDataAsRGBA32()` or `io.Fonts->Build()` will build the atlas.
+- All loaded fonts glyphs are rendered into a single texture atlas ahead of time. Calling either of `io.Fonts->GetTexDataAsAlpha8()`, `io.Fonts->GetTexDataAsRGBA32()` or `io.Fonts->Build()` will build the atlas.
- You can use the style editor `ImGui::ShowStyleEditor()` in the "Fonts" section to browse your fonts and understand what's going on if you have an issue. You can also reach it in `Demo->Tools->Style Editor->Fonts`:
@@ -160,13 +161,13 @@
##### [Return to Index](#index)
-## Using Icons
+## Using Icon Fonts
Using an icon font (such as [FontAwesome](http://fontawesome.io) or [OpenFontIcons](https://github.com/traverseda/OpenFontIcons)) is an easy and practical way to use icons in your Dear ImGui application.
A common pattern is to merge the icon font within your main font, so you can embed icons directly from your strings without having to change fonts back and forth.
To refer to the icon UTF-8 codepoints from your C++ code, you may use those headers files created by Juliette Foucaut: https://github.com/juliettef/IconFontCppHeaders.
-
+
So you can use `ICON_FA_SEARCH` as a string that will render as a "Search" icon.
Example Setup:
@@ -197,7 +198,7 @@
##### [Return to Index](#index)
-## Using FreeType Rasterizer
+## Using FreeType Rasterizer (imgui_freetype)
- Dear ImGui uses imstb\_truetype.h to rasterize fonts (with optional oversampling). This technique and its implementation are not ideal for fonts rendered at small sizes, which may appear a little blurry or hard to read.
- There is an implementation of the ImFontAtlas builder using FreeType that you can use in the [misc/freetype/](https://github.com/ocornut/imgui/tree/master/misc/freetype) folder.
@@ -207,6 +208,28 @@
##### [Return to Index](#index)
+## Using Colorful Glyphs/Emojis
+
+- Rendering of colored emojis is only supported by imgui_freetype with FreeType 2.10+.
+- You will need to load fonts with the `ImGuiFreeTypeBuilderFlags_LoadColor` flag.
+- Emojis are frequently encoded in upper Unicode layers (character codes >0x10000) and will need dear imgui compiled with `IMGUI_USE_WCHAR32`.
+- Not all types of color fonts are supported by FreeType at the moment.
+- Stateful Unicode features such as skin tone modifiers are not supported by the text renderer.
+
+
+
+```cpp
+io.Fonts->AddFontFromFileTTF("../../../imgui_dev/data/fonts/NotoSans-Regular.ttf", 16.0f);
+static ImWchar ranges[] = { 0x1, 0x1FFFF, 0 };
+static ImFontConfig cfg;
+cfg.OversampleH = cfg.OversampleV = 1;
+cfg.MergeMode = true;
+cfg.FontBuilderFlags |= ImGuiFreeTypeBuilderFlags_LoadColor;
+io.Fonts->AddFontFromFileTTF("C:\\Windows\\Fonts\\seguiemj.ttf", 16.0f, &cfg, ranges);
+```
+
+##### [Return to Index](#index)
+
## Using Custom Glyph Ranges
You can use the `ImFontGlyphRangesBuilder` helper to create glyph ranges based on text input. For example: for a game where your script is known, if you can feed your entire script to it and only build the characters the game needs.
@@ -226,7 +249,7 @@
## Using Custom Colorful Icons
-**(This is a BETA api, use if you are familiar with dear imgui and with your rendering backend)**
+As an alternative to rendering colorful glyphs using imgui_freetype with `ImGuiFreeTypeBuilderFlags_LoadColor`, you may allocate your own space in the texture atlas and write yourself into it. **(This is a BETA api, use if you are familiar with dear imgui and with your rendering backend)**
- You can use the `ImFontAtlas::AddCustomRect()` and `ImFontAtlas::AddCustomRectFontGlyph()` api to register rectangles that will be packed into the font atlas texture. Register them before building the atlas, then call Build()`.
- You can then use `ImFontAtlas::GetCustomRectByIndex(int)` to query the position/size of your rectangle within the texture, and blit/copy any graphics data of your choice into those rectangles.
@@ -315,7 +338,7 @@
<br>https://fonts.google.com/specimen/Roboto
**Cousine-Regular.ttf**, by Steve Matteson
-<br>Digitized data copyright (c) 2010 Google Corporation.
+<br>Digitized data copyright (c) 2010 Google Corporation.
<br>Licensed under the SIL Open Font License, Version 1.1
<br>https://fonts.google.com/specimen/Cousine
diff --git a/imgui.cpp b/imgui.cpp
index 44e7d28..4b204f9 100644
--- a/imgui.cpp
+++ b/imgui.cpp
@@ -4141,10 +4141,8 @@
g.SettingsHandlers.push_back(ini_handler);
}
-#ifdef IMGUI_HAS_TABLE
// Add .ini handle for ImGuiTable type
TableSettingsInstallHandler(context);
-#endif // #ifdef IMGUI_HAS_TABLE
// Create default viewport
ImGuiViewportP* viewport = IM_NEW(ImGuiViewportP)();
@@ -7215,13 +7213,11 @@
ImGuiContext& g = *GImGui;
while (g.CurrentWindowStack.Size > 0)
{
-#ifdef IMGUI_HAS_TABLE
while (g.CurrentTable && (g.CurrentTable->OuterWindow == g.CurrentWindow || g.CurrentTable->InnerWindow == g.CurrentWindow))
{
if (log_callback) log_callback(user_data, "Recovered from missing EndTable() in '%s'", g.CurrentTable->OuterWindow->Name);
EndTable();
}
-#endif
ImGuiWindow* window = g.CurrentWindow;
IM_ASSERT(window != NULL);
while (g.CurrentTabBar != NULL) //-V1044
@@ -10914,6 +10910,8 @@
}
}
+namespace ImGui { void ShowFontAtlas(ImFontAtlas* atlas); }
+
void ImGui::ShowMetricsWindow(bool* p_open)
{
if (!Begin("Dear ImGui Metrics/Debugger", p_open))
@@ -11109,14 +11107,20 @@
}
// Details for Tables
-#ifdef IMGUI_HAS_TABLE
if (TreeNode("Tables", "Tables (%d)", g.Tables.GetSize()))
{
for (int n = 0; n < g.Tables.GetSize(); n++)
DebugNodeTable(g.Tables.GetByIndex(n));
TreePop();
}
-#endif // #ifdef IMGUI_HAS_TABLE
+
+ // Details for Fonts
+ ImFontAtlas* atlas = g.IO.Fonts;
+ if (TreeNode("Fonts", "Fonts (%d)", atlas->Fonts.Size))
+ {
+ ShowFontAtlas(atlas);
+ TreePop();
+ }
// Details for Docking
#ifdef IMGUI_HAS_DOCK
@@ -11156,14 +11160,12 @@
TreePop();
}
-#ifdef IMGUI_HAS_TABLE
if (TreeNode("SettingsTables", "Settings packed data: Tables: %d bytes", g.SettingsTables.size()))
{
for (ImGuiTableSettings* settings = g.SettingsTables.begin(); settings != NULL; settings = g.SettingsTables.next_chunk(settings))
DebugNodeTableSettings(settings);
TreePop();
}
-#endif // #ifdef IMGUI_HAS_TABLE
#ifdef IMGUI_HAS_DOCK
#endif // #ifdef IMGUI_HAS_DOCK
@@ -11237,7 +11239,6 @@
}
}
-#ifdef IMGUI_HAS_TABLE
// Overlay: Display Tables Rectangles
if (cfg->ShowTablesRects)
{
@@ -11264,7 +11265,6 @@
}
}
}
-#endif // #ifdef IMGUI_HAS_TABLE
#ifdef IMGUI_HAS_DOCK
// Overlay: Display Docking info
diff --git a/imgui_demo.cpp b/imgui_demo.cpp
index 6e03b67..6ffb22f 100644
--- a/imgui_demo.cpp
+++ b/imgui_demo.cpp
@@ -54,6 +54,7 @@
// - sub section: ShowDemoWindowTables()
// - sub section: ShowDemoWindowMisc()
// [SECTION] About Window / ShowAboutWindow()
+// [SECTION] Font Viewer / ShowFontAtlas()
// [SECTION] Style Editor / ShowStyleEditor()
// [SECTION] Example App: Main Menu Bar / ShowExampleAppMainMenuBar()
// [SECTION] Example App: Debug Console / ShowExampleAppConsole()
@@ -1603,7 +1604,7 @@
};
static int func_type = 0, display_count = 70;
ImGui::Separator();
- ImGui::SetNextItemWidth(100);
+ ImGui::SetNextItemWidth(ImGui::GetFontSize() * 8);
ImGui::Combo("func", &func_type, "Sin\0Saw\0");
ImGui::SameLine();
ImGui::SliderInt("Sample count", &display_count, 1, 400);
@@ -2393,7 +2394,7 @@
// the POV of the parent window). See 'Demo->Querying Status (Active/Focused/Hovered etc.)' for details.
{
static int offset_x = 0;
- ImGui::SetNextItemWidth(100);
+ ImGui::SetNextItemWidth(ImGui::GetFontSize() * 8);
ImGui::DragInt("Offset X", &offset_x, 1.0f, -1000, 1000);
ImGui::SetCursorPosX(ImGui::GetCursorPosX() + (float)offset_x);
@@ -2415,15 +2416,15 @@
if (ImGui::TreeNode("Widgets Width"))
{
+ static float f = 0.0f;
+ static bool show_indented_items = true;
+ ImGui::Checkbox("Show indented items", &show_indented_items);
+
// Use SetNextItemWidth() to set the width of a single upcoming item.
// Use PushItemWidth()/PopItemWidth() to set the width of a group of items.
// In real code use you'll probably want to choose width values that are proportional to your font size
// e.g. Using '20.0f * GetFontSize()' as width instead of '200.0f', etc.
- static float f = 0.0f;
- static bool show_indented_items = true;
- ImGui::Checkbox("Show indented items", &show_indented_items);
-
ImGui::Text("SetNextItemWidth/PushItemWidth(100)");
ImGui::SameLine(); HelpMarker("Fixed width.");
ImGui::PushItemWidth(100);
@@ -5743,31 +5744,15 @@
}
//-----------------------------------------------------------------------------
-// [SECTION] Style Editor / ShowStyleEditor()
+// [SECTION] Font viewer / ShowFontAtlas()
//-----------------------------------------------------------------------------
-// - ShowStyleSelector()
// - ShowFontSelector()
-// - ShowStyleEditor()
+// - ShowFont()
+// - ShowFontAtlas()
//-----------------------------------------------------------------------------
-// Demo helper function to select among default colors. See ShowStyleEditor() for more advanced options.
-// Here we use the simplified Combo() api that packs items into a single literal string.
-// Useful for quick combo boxes where the choices are known locally.
-bool ImGui::ShowStyleSelector(const char* label)
-{
- static int style_idx = -1;
- if (ImGui::Combo(label, &style_idx, "Dark\0Light\0Classic\0"))
- {
- switch (style_idx)
- {
- case 0: ImGui::StyleColorsDark(); break;
- case 1: ImGui::StyleColorsLight(); break;
- case 2: ImGui::StyleColorsClassic(); break;
- }
- return true;
- }
- return false;
-}
+// This isn't worth putting in public API but we want Metrics to use it
+namespace ImGui { void ShowFontAtlas(ImFontAtlas* atlas); }
// Demo helper function to select among loaded fonts.
// Here we use the regular BeginCombo()/EndCombo() api which is more the more flexible one.
@@ -5796,7 +5781,7 @@
}
// [Internal] Display details for a single font, called by ShowStyleEditor().
-static void NodeFont(ImFont* font)
+static void ShowFont(ImFont* font)
{
ImGuiIO& io = ImGui::GetIO();
ImGuiStyle& style = ImGui::GetStyle();
@@ -5806,9 +5791,13 @@
if (!font_details_opened)
return;
+ // Display preview text
ImGui::PushFont(font);
ImGui::Text("The quick brown fox jumps over the lazy dog");
ImGui::PopFont();
+
+ // Display details
+ ImGui::SetNextItemWidth(ImGui::GetFontSize() * 8);
ImGui::DragFloat("Font scale", &font->Scale, 0.005f, 0.3f, 2.0f, "%.1f"); // Scale only this font
ImGui::SameLine(); HelpMarker(
"Note than the default embedded font is NOT meant to be scaled.\n\n"
@@ -5826,9 +5815,10 @@
if (const ImFontConfig* cfg = &font->ConfigData[config_i])
ImGui::BulletText("Input %d: \'%s\', Oversample: (%d,%d), PixelSnapH: %d, Offset: (%.1f,%.1f)",
config_i, cfg->Name, cfg->OversampleH, cfg->OversampleV, cfg->PixelSnapH, cfg->GlyphOffset.x, cfg->GlyphOffset.y);
+
+ // Display all glyphs of the fonts in separate pages of 256 characters
if (ImGui::TreeNode("Glyphs", "Glyphs (%d)", font->Glyphs.Size))
{
- // Display all glyphs of the fonts in separate pages of 256 characters
const ImU32 glyph_col = ImGui::GetColorU32(ImGuiCol_Text);
for (unsigned int base = 0; base <= IM_UNICODE_CODEPOINT_MAX; base += 256)
{
@@ -5883,6 +5873,50 @@
ImGui::TreePop();
}
+void ImGui::ShowFontAtlas(ImFontAtlas* atlas)
+{
+ for (int i = 0; i < atlas->Fonts.Size; i++)
+ {
+ ImFont* font = atlas->Fonts[i];
+ ImGui::PushID(font);
+ ShowFont(font);
+ ImGui::PopID();
+ }
+ if (ImGui::TreeNode("Atlas texture", "Atlas texture (%dx%d pixels)", atlas->TexWidth, atlas->TexHeight))
+ {
+ ImVec4 tint_col = ImVec4(1.0f, 1.0f, 1.0f, 1.0f);
+ ImVec4 border_col = ImVec4(1.0f, 1.0f, 1.0f, 0.5f);
+ ImGui::Image(atlas->TexID, ImVec2((float)atlas->TexWidth, (float)atlas->TexHeight), ImVec2(0, 0), ImVec2(1, 1), tint_col, border_col);
+ ImGui::TreePop();
+ }
+}
+
+//-----------------------------------------------------------------------------
+// [SECTION] Style Editor / ShowStyleEditor()
+//-----------------------------------------------------------------------------
+// - ShowStyleSelector()
+// - ShowStyleEditor()
+//-----------------------------------------------------------------------------
+
+// Demo helper function to select among default colors. See ShowStyleEditor() for more advanced options.
+// Here we use the simplified Combo() api that packs items into a single literal string.
+// Useful for quick combo boxes where the choices are known locally.
+bool ImGui::ShowStyleSelector(const char* label)
+{
+ static int style_idx = -1;
+ if (ImGui::Combo(label, &style_idx, "Dark\0Light\0Classic\0"))
+ {
+ switch (style_idx)
+ {
+ case 0: ImGui::StyleColorsDark(); break;
+ case 1: ImGui::StyleColorsLight(); break;
+ case 2: ImGui::StyleColorsClassic(); break;
+ }
+ return true;
+ }
+ return false;
+}
+
void ImGui::ShowStyleEditor(ImGuiStyle* ref)
{
// You can pass in a reference ImGuiStyle structure to compare to, revert to and save to
@@ -6039,21 +6073,7 @@
ImGuiIO& io = ImGui::GetIO();
ImFontAtlas* atlas = io.Fonts;
HelpMarker("Read FAQ and docs/FONTS.md for details on font loading.");
- ImGui::PushItemWidth(120);
- for (int i = 0; i < atlas->Fonts.Size; i++)
- {
- ImFont* font = atlas->Fonts[i];
- ImGui::PushID(font);
- NodeFont(font);
- ImGui::PopID();
- }
- if (ImGui::TreeNode("Atlas texture", "Atlas texture (%dx%d pixels)", atlas->TexWidth, atlas->TexHeight))
- {
- ImVec4 tint_col = ImVec4(1.0f, 1.0f, 1.0f, 1.0f);
- ImVec4 border_col = ImVec4(1.0f, 1.0f, 1.0f, 0.5f);
- ImGui::Image(atlas->TexID, ImVec2((float)atlas->TexWidth, (float)atlas->TexHeight), ImVec2(0, 0), ImVec2(1, 1), tint_col, border_col);
- ImGui::TreePop();
- }
+ ImGui::ShowFontAtlas(atlas);
// Post-baking font scaling. Note that this is NOT the nice way of scaling fonts, read below.
// (we enforce hard clamping manually as by default DragFloat/SliderFloat allows CTRL+Click text to get out of bounds).
@@ -6065,6 +6085,7 @@
"rebuild the font atlas, and call style.ScaleAllSizes() on a reference ImGuiStyle structure.\n"
"Using those settings here will give you poor quality results.");
static float window_scale = 1.0f;
+ ImGui::PushItemWidth(ImGui::GetFontSize() * 8);
if (ImGui::DragFloat("window scale", &window_scale, 0.005f, MIN_SCALE, MAX_SCALE, "%.2f", ImGuiSliderFlags_AlwaysClamp)) // Scale only this window
ImGui::SetWindowFontScale(window_scale);
ImGui::DragFloat("global scale", &io.FontGlobalScale, 0.005f, MIN_SCALE, MAX_SCALE, "%.2f", ImGuiSliderFlags_AlwaysClamp); // Scale everything
@@ -6084,7 +6105,7 @@
HelpMarker("Faster lines using texture data. Require backend to render with bilinear filtering (not point/nearest filtering).");
ImGui::Checkbox("Anti-aliased fill", &style.AntiAliasedFill);
- ImGui::PushItemWidth(100);
+ ImGui::PushItemWidth(ImGui::GetFontSize() * 8);
ImGui::DragFloat("Curve Tessellation Tolerance", &style.CurveTessellationTol, 0.02f, 0.10f, 10.0f, "%.2f");
if (style.CurveTessellationTol < 0.10f) style.CurveTessellationTol = 0.10f;
diff --git a/imgui_internal.h b/imgui_internal.h
index c190a63..3111933 100644
--- a/imgui_internal.h
+++ b/imgui_internal.h
@@ -2015,8 +2015,6 @@
// [SECTION] Table support
//-----------------------------------------------------------------------------
-#ifdef IMGUI_HAS_TABLE
-
#define IM_COL32_DISABLE IM_COL32(0,0,0,1) // Special sentinel code which cannot be used as a regular color.
#define IMGUI_TABLE_MAX_COLUMNS 64 // sizeof(ImU64) * 8. This is solely because we frequently encode columns set in a ImU64.
#define IMGUI_TABLE_MAX_DRAW_CHANNELS (4 + 64 * 2) // See TableSetupDrawChannels()
@@ -2266,8 +2264,6 @@
ImGuiTableColumnSettings* GetColumnSettings() { return (ImGuiTableColumnSettings*)(this + 1); }
};
-#endif // #ifdef IMGUI_HAS_TABLE
-
//-----------------------------------------------------------------------------
// [SECTION] ImGui internal API
// No guarantee of forward compatibility here!
diff --git a/misc/freetype/README.md b/misc/freetype/README.md
index a3db353..d54af19 100644
--- a/misc/freetype/README.md
+++ b/misc/freetype/README.md
@@ -28,3 +28,10 @@
Small, thin anti-aliased fonts are typically benefiting a lots from Freetype's hinting:
+
+### Colorful glyphs/emojis
+
+You can use the `ImGuiFreeTypeBuilderFlags_LoadColor` flag to load certain colorful glyphs. See
+["Using Colorful Glyphs/Emojis"](https://github.com/ocornut/imgui/edit/master/docs/FONTS.md#using-colorful-glyphsemojis) section of FONTS.md.
+
+
