Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "app/UserGuide.h"
#include "app/App.h"
#include "app/I18n.h"
#include "app/Theme.h"
#include "app/Ui.h"
#include "core/Image.h"
#include "core/LegacyNames.h"
#include "render/GL.h"
#include <IconsLucide.h>
#include <SDL3/SDL.h>
#include <imgui_internal.h>
#include <algorithm>
#include <cfloat>
#include <cmath>
#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <utility>
namespace sf {
namespace assets {
extern const unsigned char fontSemiBold[];
extern const unsigned long long fontSemiBold_size;
extern const unsigned char fontRegular[];
extern const unsigned long long fontRegular_size;
} // namespace assets
namespace guide_data {
struct File {
const char* path;
const unsigned char* data;
unsigned long long size;
};
extern const File kFiles[];
extern const int kFileCount;
} // namespace guide_data
namespace {
using guide::Block;
using guide::BlockKind;
using guide::Span;
using guide::Spans;
constexpr const char* kWebsite = "https://sculptforge.app/guide/";
// Colours of the page (on the panel background).
constexpr ImU32 kText = IM_COL32(0xd2, 0xd2, 0xd4, 0xff);
constexpr ImU32 kStrong = IM_COL32(0xf0, 0xf0, 0xf0, 0xff);
constexpr ImU32 kHeading = IM_COL32(0xf4, 0xf4, 0xf4, 0xff);
constexpr ImU32 kDim = IM_COL32(0x8c, 0x8c, 0x90, 0xff);
constexpr ImU32 kLink = IM_COL32(0xff, 0xa2, 0x55, 0xff);
constexpr ImU32 kCode = IM_COL32(0xe9, 0xc0, 0x8f, 0xff);
constexpr ImU32 kCodeBg = IM_COL32(0x1b, 0x1b, 0x1e, 0xff);
constexpr ImU32 kInlineCodeBg = IM_COL32(0x33, 0x33, 0x38, 0xff);
constexpr ImU32 kRule = IM_COL32(0x3a, 0x3a, 0x3f, 0xff);
constexpr ImU32 kHighlight = IM_COL32(0xf0, 0x88, 0x2e, 0x5a);
// --- Where the guide's files come from: embedded, or SCULPTFORGE_GUIDE_DIR while writing it ---
std::filesystem::path fsPath(const std::string& utf8) { return std::filesystem::path(std::u8string(utf8.begin(), utf8.end())); }
std::string guideDir() {
const char* dir = std::getenv("SCULPTFORGE_GUIDE_DIR");
return dir && *dir ? std::string(dir) : std::string();
}
bool readGuideFile(const std::string& name, std::string& out) {
if (name.find("..") != std::string::npos) return false;
if (const std::string dir = guideDir(); !dir.empty()) {
std::ifstream f(fsPath(dir) / fsPath(name), std::ios::binary);
if (!f) return false;
out.assign(std::istreambuf_iterator<char>(f), {});
return true;
}
for (int i = 0; i < guide_data::kFileCount; ++i)
if (name == guide_data::kFiles[i].path) {
out.assign(reinterpret_cast<const char*>(guide_data::kFiles[i].data), size_t(guide_data::kFiles[i].size));
return true;
}
return false;
}
bool loadPage(const std::string& file, std::string& text, void*) { return readGuideFile(file, text); }
std::string lower(std::string s) {
for (auto& c : s) c = char(std::tolower(static_cast<unsigned char>(c)));
return s;
}
float textWidth(ImFont* f, const std::string& s) { return f->CalcTextSizeA(f->FontSize, FLT_MAX, 0.0f, s.c_str()).x; }
// Draws TEXT and slants it (Inter has no italic in the atlas: shear the glyph quads instead).
void drawText(ImDrawList* dl, ImFont* f, ImVec2 p, ImU32 col, const std::string& s, bool italic) {
const int start = dl->VtxBuffer.Size;
dl->AddText(f, f->FontSize, p, col, s.c_str());
if (!italic) return;
const float base = p.y + f->FontSize * 0.8f;
for (int i = start; i < dl->VtxBuffer.Size; ++i) dl->VtxBuffer[i].pos.x += (base - dl->VtxBuffer[i].pos.y) * 0.2f;
}
// ---------------------------------------------------------------------------
// Rich text: spans laid out in lines, wrapped at word boundaries
// ---------------------------------------------------------------------------
struct FlowStyle {
ImFont* regular = nullptr;
ImFont* bold = nullptr;
ImFont* mono = nullptr;
ImFont* heading = nullptr; // headings: every non-code word in this font
ImU32 color = kText;
ImU32 labelColor = 0; // callouts: colour of the leading bold label
float lineHeight = 20.0f;
};
struct Piece {
const Span* span = nullptr;
std::string text;
ImFont* font = nullptr;
float width = 0.0f;
std::string linkText; // the whole link's text (button label for UI tests)
};
struct Word {
std::vector<Piece> pieces;
float width = 0.0f;
bool spaceBefore = false;
};
struct LinkClick {
std::string target;
};
class Flow {
public:
Flow(const FlowStyle& st, float scale) : st_(st), s_(scale) {}
// Lays SPANS out from ORIGIN in WIDTH; draws when DL is set. Returns the height.
float run(const Spans& spans, ImVec2 origin, float width, ImDrawList* dl, const std::vector<std::string>* highlight,
LinkClick* click, int& linkCounter) {
build(spans);
const float space = textWidth(st_.heading ? st_.heading : st_.regular, " ");
float x = 0.0f, y = 0.0f;
bool any = false;
for (const Word& w : words_) {
float sw = w.spaceBefore && x > 0.0f ? space : 0.0f;
if (x > 0.0f && x + sw + w.width > width) {
x = 0.0f;
y += st_.lineHeight;
sw = 0.0f;
}
x += sw;
any = true;
if (dl) {
float px = origin.x + x;
for (const Piece& p : w.pieces) {
drawPiece(dl, p, ImVec2(px, origin.y + y), highlight, click, linkCounter);
px += p.width;
}
}
x += w.width;
}
return any ? y + st_.lineHeight : 0.0f;
}
private:
ImFont* fontFor(const Span& sp) const {
if (sp.code) return st_.heading ? st_.heading : st_.regular; // inline code: the text font on a chip
if (st_.heading) return st_.heading;
return sp.bold ? st_.bold : st_.regular;
}
float pieceWidth(const Span& sp, const std::string& text, ImFont* f) const {
if (sp.kbd) return textWidth(st_.regular, text) + 10.0f * s_ + 4.0f * s_;
const float w = textWidth(f, text);
return sp.code ? w + 6.0f * s_ : w;
}
void build(const Spans& spans) {
words_.clear();
// The text of each link (consecutive spans with the same target).
std::vector<std::string> linkText(spans.size());
for (size_t i = 0; i < spans.size();) {
size_t j = i;
std::string text;
while (j < spans.size() && !spans[i].link.empty() && spans[j].link == spans[i].link) text += spans[j++].text;
if (j == i) {
++i;
continue;
}
for (size_t k = i; k < j; ++k) linkText[k] = text;
i = j;
}
Word cur;
bool pendingSpace = false;
auto endWord = [&] {
if (!cur.pieces.empty()) words_.push_back(std::move(cur));
cur = Word{};
};
for (size_t si = 0; si < spans.size(); ++si) {
const Span& sp = spans[si];
ImFont* f = fontFor(sp);
auto addPiece = [&](std::string text) {
if (text.empty()) return;
if (cur.pieces.empty()) cur.spaceBefore = pendingSpace;
pendingSpace = false;
Piece p;
p.span = &sp;
p.font = f;
p.width = pieceWidth(sp, text, f);
p.text = std::move(text);
p.linkText = linkText[si];
cur.width += p.width;
cur.pieces.push_back(std::move(p));
};
if (sp.kbd) {
addPiece(sp.text);
continue;
}
std::string run;
for (char c : sp.text) {
if (c == ' ' || c == '\n' || c == '\t') {
addPiece(std::move(run));
run.clear();
endWord();
pendingSpace = true;
} else {
run += c;
}
}
addPiece(std::move(run));
}
endWord();
}
void drawPiece(ImDrawList* dl, const Piece& p, ImVec2 at, const std::vector<std::string>* highlight, LinkClick* click,
int& linkCounter) {
const Span& sp = *p.span;
const float lh = st_.lineHeight;
ImFont* f = p.font;
const ImVec2 r0(at.x, at.y), r1(at.x + p.width, at.y + lh);
bool hovered = false;
if (!sp.link.empty() && click) {
ImGui::SetCursorScreenPos(r0);
const std::string label = (p.linkText.empty() ? p.text : p.linkText) + "##guidelink" + std::to_string(linkCounter++);
if (ImGui::InvisibleButton(label.c_str(), ImVec2(std::max(1.0f, p.width), lh))) click->target = sp.link;
hovered = ImGui::IsItemHovered();
if (hovered) {
ImGui::SetMouseCursor(ImGuiMouseCursor_Hand);
const guide::Target t = guide::splitTarget(sp.link);
if (t.external) ImGui::SetTooltip("%s", sp.link.c_str());
}
}
if (sp.kbd) {
ImFont* kf = st_.regular;
const float h = kf->FontSize + 4.0f * s_;
const ImVec2 a(at.x + 2.0f * s_, at.y + (lh - h) * 0.5f), b(at.x + p.width - 2.0f * s_, a.y + h);
dl->AddRectFilled(a, b, IM_COL32(0x2c, 0x2c, 0x30, 0xff), 3.0f * s_);
dl->AddRect(a, b, IM_COL32(0x4a, 0x4a, 0x50, 0xff), 3.0f * s_);
dl->AddText(kf, kf->FontSize, ImVec2(a.x + 5.0f * s_, a.y + 2.0f * s_), ui::color::accent, p.text.c_str());
return;
}
float tx = at.x;
const float ty = at.y + (lh - f->FontSize) * 0.5f;
if (sp.code) {
dl->AddRectFilled(ImVec2(at.x, ty - 1.0f * s_), ImVec2(at.x + p.width, ty + f->FontSize + 1.0f * s_), kInlineCodeBg,
3.0f * s_);
tx += 3.0f * s_;
}
if (highlight && !highlight->empty()) {
const std::string low = lower(p.text);
for (const auto& w : *highlight)
for (size_t at2 = low.find(w); at2 != std::string::npos; at2 = low.find(w, at2 + w.size())) {
const float x0 = tx + textWidth(f, p.text.substr(0, at2));
const float x1 = tx + textWidth(f, p.text.substr(0, at2 + w.size()));
dl->AddRectFilled(ImVec2(x0 - 1.0f * s_, ty - 1.0f * s_), ImVec2(x1 + 1.0f * s_, ty + f->FontSize + 1.0f * s_),
kHighlight, 2.0f * s_);
}
}
ImU32 col = st_.color;
if (sp.code) col = kCode;
else if (!sp.link.empty()) col = kLink;
else if (sp.bold && st_.labelColor && &sp == firstSpan_) col = st_.labelColor;
else if (sp.bold && !st_.heading) col = kStrong;
drawText(dl, f, ImVec2(tx, ty), col, p.text, sp.italic);
if (hovered) dl->AddLine(ImVec2(r0.x, ty + f->FontSize), ImVec2(r1.x, ty + f->FontSize), kLink, 1.0f * s_);
}
public:
const Span* firstSpan_ = nullptr; // callouts colour their label (the first bold span)
private:
FlowStyle st_;
float s_;
std::vector<Word> words_;
};
struct CalloutLook {
const char* label;
ImU32 color;
};
constexpr CalloutLook kCallouts[] = {
{"Tip", IM_COL32(0x62, 0xc0, 0x7e, 0xff)}, {"Note", IM_COL32(0x6f, 0xa8, 0xe6, 0xff)},
{"Experienced sculptor?", IM_COL32(0xf0, 0x88, 0x2e, 0xff)}, {"Not yet", IM_COL32(0xa9, 0x90, 0xdc, 0xff)},
{"Warning", IM_COL32(0xe5, 0x60, 0x4a, 0xff)}, {"Important", IM_COL32(0xe5, 0x60, 0x4a, 0xff)},
};
ImU32 calloutColor(const Block& b) {
if (b.spans.empty() || !b.spans[0].bold) return kRule;
std::string label = b.spans[0].text;
while (!label.empty() && (label.back() == ':' || label.back() == ' ')) label.pop_back();
for (const auto& c : kCallouts)
if (label == c.label) return c.color;
return IM_COL32(0x8c, 0x8c, 0x90, 0xff);
}
} // namespace
// ---------------------------------------------------------------------------
// Set-up and navigation
// ---------------------------------------------------------------------------
void UserGuide::addFonts(float scale) {
ImGuiIO& io = ImGui::GetIO();
ImFontConfig cfg;
cfg.FontDataOwnedByAtlas = false;
cfg.OversampleH = 2;
auto add = [&](float size, bool bold = true) {
return bold ? io.Fonts->AddFontFromMemoryTTF(const_cast<unsigned char*>(assets::fontSemiBold),
int(assets::fontSemiBold_size), size * scale, &cfg)
: io.Fonts->AddFontFromMemoryTTF(const_cast<unsigned char*>(assets::fontRegular),
int(assets::fontRegular_size), size * scale, &cfg);
};
// Reading text a step above the 15 px UI font (the guide, What's New, the update banner).
body_ = add(kReadingSize, false);
bodyBold_ = add(kReadingSize);
h1_ = add(30.0f);
h2_ = add(23.0f);
h3_ = add(19.0f);
}
bool UserGuide::ensureLoaded() {
if (loaded_) return loadError_.empty();
loaded_ = true;
if (!book_.load(loadPage, nullptr, loadError_) && loadError_.empty()) loadError_ = "The user guide could not be loaded.";
prepareWhatsNew();
return loadError_.empty();
}
void UserGuide::open(const std::string& target) {
open_ = true;
if (!target.empty()) navigate(target);
}
void UserGuide::toggle() { open_ = !open_; }
std::string UserGuide::currentFile() const {
if (place_.chapter < 0 || place_.chapter >= int(book_.chapters().size())) return "index.md";
return book_.chapters()[size_t(place_.chapter)].file;
}
std::string UserGuide::chapterTitle(const std::string& file) {
if (!ensureLoaded()) return {};
const int i = book_.find(file);
return i >= 0 ? book_.chapters()[size_t(i)].title : std::string();
}
const guide::Document* UserGuide::document(const std::string& file) {
if (!ensureLoaded()) return nullptr;
const int i = book_.find(file);
return i >= 0 ? &book_.chapters()[size_t(i)].doc : nullptr;
}
ImTextureID UserGuide::image(const std::string& path, ImVec2* size) {
const Texture* t = texture(path);
if (!t) return ImTextureID(0);
if (size) *size = ImVec2(float(t->width), float(t->height));
return ImTextureID(uintptr_t(t->tex));
}
const guide::Document& UserGuide::page() const {
if (place_.chapter >= 0 && place_.chapter < int(book_.chapters().size())) return book_.chapters()[size_t(place_.chapter)].doc;
return book_.index();
}
void UserGuide::go(Place place, const std::string& anchor, bool record) {
if (record) {
back_.push_back({place_.chapter, scroll_});
if (back_.size() > 100) back_.erase(back_.begin());
forward_.clear();
}
const bool samePage = place.chapter == place_.chapter;
place_ = place;
pendingAnchor_ = anchor;
pendingBlock_ = -1;
pendingScroll_ = -1.0f;
pendingTop_ = anchor.empty() && !samePage;
if (!samePage) highlight_.clear();
}
void UserGuide::navigate(const std::string& target, bool record) {
if (!ensureLoaded()) return;
const guide::Target t = guide::splitTarget(target);
if (t.external) {
SDL_OpenURL(t.file.c_str());
return;
}
if (t.file.empty()) { // an anchor on this page
go(place_, t.anchor, record);
return;
}
std::string file = t.file;
if (const size_t slash = file.rfind('/'); slash != std::string::npos) file = file.substr(slash + 1);
// Chapters renamed to SculptForge's own names: old links still find them.
file = legacy::modernize(file);
static const std::pair<const char*, const char*> kRenamed[] = {{"forgespheres.md", "forge-spheres.md"},
{"vertexpaint.md", "vertex-paint.md"},
{"facegroups.md", "face-groups.md"}};
for (const auto& [from, to] : kRenamed)
if (file == from) file = to;
if (file == "index.md") {
go({-1, 0.0f}, t.anchor, record);
return;
}
const int chapter = book_.find(file);
if (chapter < 0) return;
go({chapter, 0.0f}, t.anchor, record);
}
std::string UserGuide::websiteUrl() const {
std::string file = currentFile();
file = file.substr(0, file.size() - 3) + ".html";
return std::string(kWebsite) + file;
}
std::string UserGuide::chapterFor(const std::string& palette, const std::string& actionId) {
auto starts = [&](const char* p) { return palette.rfind(p, 0) == 0; };
auto idStarts = [&](const char* p) { return actionId.rfind(p, 0) == 0; };
// Palette paths by SculptForge's names, and the older classic ones (stored layouts, scripts).
if (starts("Tool > Geometry > Quad Remesh") || starts("Tool > Geometry > QRemesh") || starts("Tool > Parts > Project") ||
starts("Tool > Part > Project"))
return "retopology.md";
if (starts("Brush packs")) return "brush-packs.md";
if (starts("Tool > Parts") || starts("Tool > Part")) return "parts.md";
if (starts("Tool > Forge Spheres") || starts("Tool > Forge Spheres")) return "forge-spheres.md";
if (starts("Tool > Layers")) return "layers.md";
if (starts("Tool > Facial Shapes")) return "facial-shapes.md";
if (starts("Tool > Geometry") || starts("Tool > Remesh")) return "geometry.md";
if (starts("Tool > Masking")) return "masking.md";
if (starts("Tool > Face Groups") || starts("Tool > Face groups") || starts("Tool > Visibility")) return "face-groups.md";
if (starts("Tool > Selection Sets")) return "selection-sets.md";
if (starts("Tool > Export")) return "exporting.md";
if (starts("Tool > Display")) return "interface.md";
if (starts("Tool")) return "parts.md";
if (starts("Brush"))
return actionId == "ui.brush_lab" || actionId == "ui.brush_gallery" || actionId == "brush.paste" ? "brush-lab.md"
: "sculpting.md";
if (starts("Draw") || starts("Stroke") || starts("Alpha")) return "sculpting.md";
if (starts("Color") || starts("Material")) return "vertex-paint.md";
if (starts("File > Blender")) return "blender.md";
if (starts("File > Maya")) return "maya.md";
if (starts("File > Capture from phone") || actionId == "file.capture_phone") return "phone-capture.md";
if (starts("File > Export") || idStarts("file.export") || actionId == "file.send_unreal" || actionId == "file.save_splats" ||
starts("File > Bridge") || starts("File > Bridge files"))
return "exporting.md";
if (starts("File")) return "projects.md";
if (starts("Generate")) return "generate-3d.md";
if (starts("Splats > Make sculptable")) return "scan-to-sculptable.md";
if (starts("Splats")) return "splats.md";
if (starts("Script")) return "scripting.md";
if (starts("Library > Packs") || starts("Macros") || idStarts("pack.") || idStarts("macro.")) return "packs-and-macros.md";
if (starts("Transform > Gizmo") || idStarts("gizmo.") || actionId == "tool.draw" || actionId == "tool.move" ||
actionId == "tool.scale" || actionId == "tool.rotate" || actionId == "tool.gizmo_all")
return "gizmo.md";
if (starts("Transform")) return idStarts("transform.symmetry") ? "sculpting.md" : "navigation.md";
if (starts("Preferences > Integrations")) return "discord.md";
if (starts("Render") || starts("Edit") || starts("Help") || starts("Palettes") || starts("Preferences") ||
starts("Library"))
return "interface.md";
return {};
}
// ---------------------------------------------------------------------------
// Images
// ---------------------------------------------------------------------------
const UserGuide::Texture* UserGuide::texture(const std::string& path) {
auto it = textures_.find(path);
if (it != textures_.end()) return it->second.failed ? nullptr : &it->second;
Texture& t = textures_[path];
std::string bytes;
Image image;
std::string err;
if (!readGuideFile(path, bytes) ||
!Image::decode(reinterpret_cast<const unsigned char*>(bytes.data()), bytes.size(), image, err)) {
t.failed = true;
return nullptr;
}
gl::GenTextures(1, &t.tex);
gl::BindTexture(GL_TEXTURE_2D, t.tex);
gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
gl::TexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
gl::PixelStorei(GL_UNPACK_ALIGNMENT, 1);
gl::TexImage2D(GL_TEXTURE_2D, 0, GLint(GL_RGBA8), image.width, image.height, 0, GL_RGBA, GL_UNSIGNED_BYTE,
image.rgba.data());
gl::BindTexture(GL_TEXTURE_2D, 0);
t.width = image.width;
t.height = image.height;
return &t;
}
// ---------------------------------------------------------------------------
// Drawing
// ---------------------------------------------------------------------------
void UserGuide::draw(App& app) {
if (!open_) return;
const float s = app.uiScale_;
const CanvasRect c = app.canvasRect();
const ImVec2 size(std::min(1180.0f * s, c.w * 0.94f), std::min(800.0f * s, c.h * 0.94f));
ImGui::SetNextWindowSize(size, ImGuiCond_FirstUseEver);
ImGui::SetNextWindowPos(ImVec2(c.x + c.w * 0.5f, c.y + c.h * 0.5f), ImGuiCond_FirstUseEver, ImVec2(0.5f, 0.5f));
ImGui::SetNextWindowSizeConstraints(ImVec2(520.0f * s, 320.0f * s), ImVec2(FLT_MAX, FLT_MAX));
ImGui::PushStyleVar(ImGuiStyleVar_WindowPadding, ImVec2(8.0f * s, 8.0f * s));
const bool visible = ImGui::Begin(tr("User Guide"), &open_, ImGuiWindowFlags_NoCollapse);
ImGui::PopStyleVar();
if (!visible) {
ImGui::End();
return;
}
if (!ensureLoaded()) {
ImGui::TextColored(ImGui::ColorConvertU32ToFloat4(ui::color::danger), "%s", loadError_.c_str());
ImGui::End();
return;
}
// Keys while the guide has focus: Alt+Left / Alt+Right, Ctrl+F; mouse back / forward buttons.
if (ImGui::IsWindowFocused(ImGuiFocusedFlags_RootAndChildWindows)) {
const ImGuiIO& io = ImGui::GetIO();
if (io.KeyAlt && ImGui::IsKeyPressed(ImGuiKey_LeftArrow, false) && !back_.empty()) {
forward_.push_back({place_.chapter, scroll_});
const Place p = back_.back();
back_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
} else if (io.KeyAlt && ImGui::IsKeyPressed(ImGuiKey_RightArrow, false) && !forward_.empty()) {
back_.push_back({place_.chapter, scroll_});
const Place p = forward_.back();
forward_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
}
if ((io.KeyCtrl || io.KeySuper) && ImGui::IsKeyPressed(ImGuiKey_F, false)) focusSearch_ = true;
}
if (ImGui::IsWindowHovered(ImGuiHoveredFlags_RootAndChildWindows)) {
if (ImGui::IsMouseClicked(3) && !back_.empty()) {
forward_.push_back({place_.chapter, scroll_});
const Place p = back_.back();
back_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
} else if (ImGui::IsMouseClicked(4) && !forward_.empty()) {
back_.push_back({place_.chapter, scroll_});
const Place p = forward_.back();
forward_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
}
}
drawToolbar(app);
const float sideW = 262.0f * s;
ImGui::PushStyleColor(ImGuiCol_ChildBg, theme::shellBg);
ImGui::BeginChild("##guide_side", ImVec2(sideW, 0), ImGuiChildFlags_None, ImGuiWindowFlags_None);
if (query_[0]) drawSearchResults(app);
else drawContents(app);
ImGui::EndChild();
ImGui::PopStyleColor();
ImGui::SameLine(0, 1.0f * s);
drawPage(app);
ImGui::End();
}
void UserGuide::drawToolbar(App& app) {
const float s = app.uiScale_;
const ImVec2 btn(ImGui::GetFrameHeight() * 1.2f, 0);
ImGui::BeginDisabled(back_.empty());
if (ImGui::Button(ICON_LC_ARROW_LEFT "##guide_back", btn)) {
forward_.push_back({place_.chapter, scroll_});
const Place p = back_.back();
back_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
}
ImGui::EndDisabled();
ui::HelpText("Back", "Alt+Left", "Go back to the page you were reading.", "Help > User Guide");
ui::DelayedTooltip("Back (Alt+Left)");
ImGui::SameLine();
ImGui::BeginDisabled(forward_.empty());
if (ImGui::Button(ICON_LC_ARROW_RIGHT "##guide_forward", btn)) {
back_.push_back({place_.chapter, scroll_});
const Place p = forward_.back();
forward_.pop_back();
go(p, "", false);
pendingScroll_ = p.scroll;
pendingTop_ = false;
}
ImGui::EndDisabled();
ui::HelpText("Forward", "Alt+Right", "Go forward again.", "Help > User Guide");
ui::DelayedTooltip("Forward (Alt+Right)");
ImGui::SameLine();
if (ImGui::Button(ICON_LC_HOUSE "##guide_home", btn)) {
query_[0] = '\0';
navigate("index.md");
}
ui::HelpText("Contents", nullptr, "The guide's first page: every chapter.", "Help > User Guide");
ui::DelayedTooltip("Contents");
ImGui::SameLine();
const float webW = ImGui::CalcTextSize(ICON_LC_GLOBE " Open in browser").x + ImGui::GetStyle().FramePadding.x * 2.0f;
ImGui::SetNextItemWidth(std::min(340.0f * s, ImGui::GetContentRegionAvail().x - webW - 12.0f * s));
if (focusSearch_) {
ImGui::SetKeyboardFocusHere();
focusSearch_ = false;
}
ImGui::InputTextWithHint("##guide_search", tr(ICON_LC_SEARCH " Search the guide (Ctrl+F)"), query_, sizeof query_,
ImGuiInputTextFlags_EscapeClearsAll);
ui::HelpText("Search", "Ctrl+F", "Find every place in the guide that mentions all of these words.", "Help > User Guide");
if (query_[0]) {
ImGui::SameLine(0, 2.0f * s);
if (ui::GlyphButton("##guide_clear", ICON_LC_X, ImVec2(ImGui::GetFrameHeight(), 0))) query_[0] = '\0';
ui::DelayedTooltip("Clear the search");
}
if (lastQuery_ != query_) {
lastQuery_ = query_;
hits_ = book_.search(query_);
}
ImGui::SameLine(ImGui::GetWindowContentRegionMax().x - webW);
if (ImGui::Button(tr(ICON_LC_GLOBE " Open in browser##guide_web"))) SDL_OpenURL(websiteUrl().c_str());
ui::HelpText("Open in browser", nullptr, "Read this page on the SculptForge website.", "Help > User Guide");
ImGui::Dummy(ImVec2(0, 2.0f * s));
}
void UserGuide::drawContents(App& app) {
const float s = app.uiScale_;
ImGui::Dummy(ImVec2(0, 4.0f * s));
ImGui::Indent(6.0f * s);
const float w = ImGui::GetContentRegionAvail().x - 6.0f * s;
if (ImGui::Selectable(tr("Contents##guide.toc.index"), place_.chapter < 0, 0, ImVec2(w, 0))) {
if (place_.chapter >= 0) navigate("index.md");
}
std::string group;
const auto& chapters = book_.chapters();
for (size_t i = 0; i < chapters.size(); ++i) {
const auto& ch = chapters[i];
if (ch.group != group) {
group = ch.group;
ImGui::Dummy(ImVec2(0, 6.0f * s));
if (app.smallFont()) ImGui::PushFont(app.smallFont());
ImGui::TextColored(ImGui::ColorConvertU32ToFloat4(kDim), "%s", group.c_str());
if (app.smallFont()) ImGui::PopFont();
}
const bool current = int(i) == place_.chapter;
if (current) ImGui::PushStyleColor(ImGuiCol_Text, theme::accent);
if (ImGui::Selectable((ch.title + "##guide.toc." + ch.file).c_str(), current, 0, ImVec2(w, 0)) && !current)
navigate(ch.file);
if (current) ImGui::PopStyleColor();
if (!current) continue;
// The open chapter's sections.
if (app.smallFont()) ImGui::PushFont(app.smallFont());
ImGui::Indent(12.0f * s);
if (ch.file == "whats-new.md") { // the versions in full, then the groups (core/WhatsNew.h)
for (int v = 0; v < whatsNew_.detailed; ++v) {
const auto& ver = whatsNew_.versions[size_t(v)];
if (ImGui::Selectable(("Version " + ver.version + "##guide.sec." + ver.anchor).c_str(), false, 0, ImVec2(w - 12.0f * s, 0)))
navigate("#" + ver.anchor);
}
for (const auto& g : whatsNew_.groups)
if (ImGui::Selectable((g.label + "##guide.sec." + g.anchor).c_str(), false, 0, ImVec2(w - 12.0f * s, 0)))
navigate("#" + g.anchor);
} else {
for (const auto& b : ch.doc.blocks) {
if (b.kind != BlockKind::Heading || b.level != 2) continue;
const std::string title = guide::plainText(b.spans);
if (ImGui::Selectable((title + "##guide.sec." + b.anchor).c_str(), false, 0, ImVec2(w - 12.0f * s, 0)))
navigate("#" + b.anchor);
}
}
ImGui::Unindent(12.0f * s);
if (app.smallFont()) ImGui::PopFont();
}
ImGui::Unindent(6.0f * s);
ImGui::Dummy(ImVec2(0, 6.0f * s));
}
void UserGuide::drawSearchResults(App& app) {
const float s = app.uiScale_;
ImGui::Dummy(ImVec2(0, 4.0f * s));
ImGui::Indent(6.0f * s);
const float w = ImGui::GetContentRegionAvail().x - 6.0f * s;
if (hits_.empty()) {
ImGui::PushTextWrapPos(ImGui::GetCursorPosX() + w);
ImGui::TextColored(ImGui::ColorConvertU32ToFloat4(kDim), tr("Nothing in the guide matches \"%s\"."), query_);
ImGui::PopTextWrapPos();
} else {
ImGui::TextColored(ImGui::ColorConvertU32ToFloat4(kDim), tr(hits_.size() >= 50 ? "%zu results (best 50)" : hits_.size() == 1 ? "%zu result" : "%zu results"),
hits_.size());
}
ImFont* small = app.smallFont() ? app.smallFont() : ImGui::GetFont();
ImFont* bold = app.boldFont() ? app.boldFont() : ImGui::GetFont();
for (size_t i = 0; i < hits_.size(); ++i) {
const auto& h = hits_[i];
const auto& ch = book_.chapters()[size_t(h.chapter)];
// Chapter (small), section (bold, wrapped), then up to three lines of snippet.
const float textW = w - 12.0f * s;
const std::string where = h.section.empty() ? ch.title : h.section;
const ImVec2 whereSize = bold->CalcTextSizeA(bold->FontSize, FLT_MAX, textW, where.c_str());
const ImVec2 snipSize = small->CalcTextSizeA(small->FontSize, FLT_MAX, textW, h.snippet.c_str());
const float snipH = std::min(snipSize.y, small->FontSize * 3.0f);
const float rowH = small->FontSize + 2.0f * s + whereSize.y + 3.0f * s + snipH + 12.0f * s;
const ImVec2 p = ImGui::GetCursorScreenPos();
const bool selected = h.chapter == place_.chapter && h.block == pendingBlock_;
if (ImGui::Selectable(("##guide.hit." + std::to_string(i)).c_str(), selected, 0, ImVec2(w, rowH))) {
navigate(ch.file + (h.anchor.empty() ? std::string() : "#" + h.anchor));
pendingAnchor_.clear();
pendingBlock_ = h.block;
pendingTop_ = false;
highlight_.clear();
std::string q = lower(query_), word;
for (char c : q + " ") {
if (c == ' ') {
if (!word.empty()) highlight_.push_back(word);
word.clear();
} else {
word += c;
}
}
}
ImGui::LogText("%s %s %s", ch.title.c_str(), where.c_str(), h.snippet.c_str());
ImDrawList* dl = ImGui::GetWindowDrawList();
dl->PushClipRect(p, ImVec2(p.x + w, p.y + rowH - 4.0f * s), true);
const float x = p.x + 6.0f * s;
float ty = p.y + 5.0f * s;
dl->AddText(small, small->FontSize, ImVec2(x, ty), theme::u32(theme::accent, 0.85f), ch.title.c_str());
ty += small->FontSize + 2.0f * s;
dl->AddText(bold, bold->FontSize, ImVec2(x, ty), kStrong, where.c_str(), nullptr, textW);
ty += whereSize.y + 3.0f * s;
// Snippet with the match marked: the highlight goes on the wrapped line the match falls on.
const float sy = ty;
dl->AddText(small, small->FontSize, ImVec2(x, sy), kDim, h.snippet.c_str(), nullptr, textW);
if (h.matchLength && h.matchStart + h.matchLength <= h.snippet.size()) {
// Find the wrapped line and x of the match by measuring the snippet prefix with wrapping.
const char* begin = h.snippet.c_str();
const char* lineStart = begin;
float ly = sy;
while (lineStart < begin + h.matchStart) {
const char* wrap = small->CalcWordWrapPositionA(1.0f, lineStart, begin + h.snippet.size(), textW);
if (wrap == lineStart) wrap = lineStart + 1;
if (wrap > begin + h.matchStart) break;
lineStart = wrap;
while (lineStart < begin + h.snippet.size() && *lineStart == ' ') ++lineStart;
ly += small->FontSize;
}
const float mx0 = x + small->CalcTextSizeA(small->FontSize, FLT_MAX, 0, lineStart, begin + h.matchStart).x;
const float mx1 = mx0 + small->CalcTextSizeA(small->FontSize, FLT_MAX, 0, begin + h.matchStart,
begin + h.matchStart + h.matchLength)
.x;
dl->AddRectFilled(ImVec2(mx0 - 1, ly), ImVec2(mx1 + 1, ly + small->FontSize), kHighlight, 2.0f * s);
dl->AddText(small, small->FontSize, ImVec2(mx0, ly), kStrong, begin + h.matchStart,
begin + h.matchStart + h.matchLength);
}
dl->PopClipRect();
}
ImGui::Unindent(6.0f * s);
}
float UserGuide::drawBlock(App& app, const Block& b, int index, ImVec2 o, float width, bool draw) {
const float s = app.uiScale_;
ImDrawList* dl = draw ? ImGui::GetWindowDrawList() : nullptr;
ImFont* regular = body_ ? body_ : ImGui::GetFont();
FlowStyle st;
st.regular = regular;
st.bold = bodyBold_ ? bodyBold_ : app.boldFont() ? app.boldFont() : regular;
st.mono = app.consoleFont();
st.lineHeight = std::round(regular->FontSize * 1.55f);
LinkClick click;
const std::vector<std::string>* hl = highlight_.empty() ? nullptr : &highlight_;
auto flow = [&](const Spans& spans, ImVec2 at, float w, const FlowStyle& style, const Span* label = nullptr) {
Flow f(style, s);
f.firstSpan_ = label;
return f.run(spans, at, w, dl, hl, draw ? &click : nullptr, linkCounter_);
};
float h = 0.0f;
if (draw) ImGui::LogText("%s\n", guide::plainText(b).c_str());
switch (b.kind) {
case BlockKind::Heading: {
FlowStyle hs = st;
hs.heading = b.level == 1 ? h1_ : b.level == 2 ? h2_ : demoteHeadings_ ? bodyBold_ : h3_; // (What's New's groups)
if (!hs.heading) hs.heading = st.bold;
hs.color = kHeading;
hs.lineHeight = std::round(hs.heading->FontSize * 1.3f);
const float top = index == 0 ? 0.0f : (b.level == 1 ? 8.0f : b.level == 2 ? 22.0f : 14.0f) * s;
h = top + flow(b.spans, ImVec2(o.x, o.y + top), width, hs);
if (b.level <= 2) {
if (dl) dl->AddLine(ImVec2(o.x, o.y + h + 3.0f * s), ImVec2(o.x + width, o.y + h + 3.0f * s), kRule, 1.0f);
h += 8.0f * s;
}
break;
}
case BlockKind::Paragraph: h = flow(b.spans, o, width, st); break;
case BlockKind::Bullet:
case BlockKind::Numbered: {
const float indent = (22.0f + float(b.level) * 22.0f) * s;
if (dl) {
if (b.kind == BlockKind::Bullet) {
const float r = (b.level ? 2.2f : 2.6f) * s;
const ImVec2 c(o.x + indent - 11.0f * s, o.y + st.lineHeight * 0.5f + 0.5f * s);
if (b.level) dl->AddCircle(c, r, kDim, 12, 1.2f * s);
else dl->AddCircleFilled(c, r, kDim, 12);
} else {
const std::string n = std::to_string(b.number) + ".";
const float nw = textWidth(regular, n);
dl->AddText(regular, regular->FontSize,
ImVec2(o.x + indent - 7.0f * s - nw, o.y + (st.lineHeight - regular->FontSize) * 0.5f), kDim,
n.c_str());
}
}
h = flow(b.spans, ImVec2(o.x + indent, o.y), width - indent, st);
break;
}
case BlockKind::Callout: {
const float pad = 10.0f * s, bar = 3.0f * s;
const ImU32 col = calloutColor(b);
FlowStyle cs = st;
cs.labelColor = col;
const Span* label = !b.spans.empty() && b.spans[0].bold ? &b.spans[0] : nullptr;
const float textW = width - pad * 2.0f - bar;
const float th = Flow(cs, s).run(b.spans, o, textW, nullptr, nullptr, nullptr, linkCounter_);
h = th + pad * 1.6f;
if (dl) {
dl->AddRectFilled(o, ImVec2(o.x + width, o.y + h), IM_COL32(0x2d, 0x2d, 0x31, 0xff), 4.0f * s);
dl->AddRectFilled(o, ImVec2(o.x + bar, o.y + h), col, 4.0f * s, ImDrawFlags_RoundCornersLeft);
flow(b.spans, ImVec2(o.x + bar + pad, o.y + pad * 0.8f), textW, cs, label);
}
break;
}
case BlockKind::Code: {
ImFont* mono = st.mono;
const float pad = 10.0f * s;
const float lh = std::round(mono->FontSize * 1.4f);
const float cw = std::max(1.0f, textWidth(mono, "M"));
const size_t cols = size_t(std::max(8.0f, (width - pad * 2.0f) / cw));
std::vector<std::string> lines;
size_t start = 0;
while (start <= b.text.size()) {
size_t end = b.text.find('\n', start);
if (end == std::string::npos) end = b.text.size();
std::string line = b.text.substr(start, end - start);
do { // long lines wrap at the column limit
lines.push_back(line.substr(0, cols));
line = line.size() > cols ? " " + line.substr(cols) : std::string();
} while (!line.empty());
start = end + 1;
}
h = float(lines.size()) * lh + pad * 2.0f;
if (dl) {
const ImVec2 b1(o.x + width, o.y + h);
dl->AddRectFilled(o, b1, kCodeBg, 4.0f * s);
dl->AddRect(o, b1, IM_COL32(0x34, 0x34, 0x38, 0xff), 4.0f * s);
for (size_t i = 0; i < lines.size(); ++i)
dl->AddText(mono, mono->FontSize, ImVec2(o.x + pad, o.y + pad + float(i) * lh + (lh - mono->FontSize) * 0.5f),
IM_COL32(0xd8, 0xd8, 0xd0, 0xff), lines[i].c_str());
// A Copy button while the pointer is over the block.
if (ImGui::IsMouseHoveringRect(o, b1) && ImGui::IsWindowHovered()) {
const char* label = ICON_LC_COPY " Copy";
const ImVec2 bs(ImGui::CalcTextSize(label).x + 12.0f * s, ImGui::GetFrameHeight());
ImGui::SetCursorScreenPos(ImVec2(b1.x - bs.x - 4.0f * s, o.y + 4.0f * s));
if (ImGui::Button((std::string(label) + "##guidecode" + std::to_string(index)).c_str(), bs)) {
SDL_SetClipboardText(b.text.c_str());
app.status_ = "Copied to the clipboard";
}
}
}
break;
}
case BlockKind::Table: {
const size_t cols = b.rows.empty() ? 0 : b.rows[0].size();
if (!cols) break;
const float padX = 8.0f * s, padY = 5.0f * s;
FlowStyle header = st;
header.regular = st.bold;
header.color = kStrong;
// Natural (one line) and minimum (longest word) width of each column, then share the width.
std::vector<float> natural(cols, 0.0f), minimum(cols, 0.0f);
for (size_t r = 0; r < b.rows.size(); ++r)
for (size_t c = 0; c < cols; ++c) {
const Spans& cell = b.rows[r][c];
float lineW = 0.0f;
for (const auto& sp : cell) {
ImFont* f = (sp.bold || r == 0) && !sp.code ? st.bold : regular;
lineW += textWidth(f, sp.text) + (sp.code ? 6.0f * s : sp.kbd ? 14.0f * s : 0.0f);
std::string word;
for (char ch : sp.text + " ") {
if (ch == ' ') {
minimum[c] = std::max(minimum[c], textWidth(f, word) + (sp.code ? 6.0f * s : 0.0f));
word.clear();
} else {
word += ch;
}
}
}
natural[c] = std::max(natural[c], lineW + padX * 2.0f);
minimum[c] = std::max(minimum[c] + padX * 2.0f, 40.0f * s);
}
std::vector<float> colW(cols);
float sumNat = 0.0f, sumMin = 0.0f;
for (size_t c = 0; c < cols; ++c) sumNat += natural[c], sumMin += minimum[c];
if (sumNat <= width) {
colW = natural;
const float extra = (width - sumNat) / float(cols);
for (auto& w : colW) w += sumNat > width * 0.6f ? extra : 0.0f; // short tables stay compact
} else {
const float spare = std::max(0.0f, width - sumMin);
const float want = std::max(1.0f, sumNat - sumMin);
for (size_t c = 0; c < cols; ++c) colW[c] = minimum[c] + spare * (natural[c] - minimum[c]) / want;
}
float tableW = 0.0f;
for (float w : colW) tableW += w;
float y = 0.0f;
for (size_t r = 0; r < b.rows.size(); ++r) {
const FlowStyle& cs = r == 0 ? header : st;
float rowH = 0.0f;
for (size_t c = 0; c < cols; ++c)
rowH = std::max(rowH, Flow(cs, s).run(b.rows[r][c], o, colW[c] - padX * 2.0f, nullptr, nullptr, nullptr,
linkCounter_));
rowH = std::max(rowH, st.lineHeight) + padY * 2.0f;
if (dl) {
const ImVec2 a(o.x, o.y + y), z(o.x + tableW, o.y + y + rowH);
dl->AddRectFilled(a, z, r == 0 ? IM_COL32(0x33, 0x33, 0x37, 0xff)
: r % 2 ? IM_COL32(0x29, 0x29, 0x2c, 0xff) : IM_COL32(0x25, 0x25, 0x28, 0xff));
float x = o.x;
for (size_t c = 0; c < cols; ++c) {
flow(b.rows[r][c], ImVec2(x + padX, o.y + y + padY), colW[c] - padX * 2.0f, cs);
x += colW[c];
}
}
y += rowH;
}
if (dl) dl->AddRect(o, ImVec2(o.x + tableW, o.y + y), IM_COL32(0x3a, 0x3a, 0x3f, 0xff), 2.0f * s);
h = y;
break;
}
case BlockKind::Image: {
const Texture* t = texture(b.text);
ImFont* small = app.smallFont() ? app.smallFont() : regular;
if (!t) {
h = st.lineHeight;
if (dl) dl->AddText(o, ui::color::danger, ("[missing image " + b.text + "]").c_str());
break;
}
const float w = std::min(width, float(t->width) * s);
const float ih = w * float(t->height) / float(std::max(1, t->width));
const float x = o.x + (width - w) * 0.5f;
const ImVec2 capSize = small->CalcTextSizeA(small->FontSize, FLT_MAX, width * 0.9f, b.alt.c_str());
h = ih + (b.alt.empty() ? 0.0f : capSize.y + 8.0f * s);
if (dl) {
dl->AddImageRounded(ImTextureID(uintptr_t(t->tex)), ImVec2(x, o.y), ImVec2(x + w, o.y + ih), ImVec2(0, 0),
ImVec2(1, 1), IM_COL32_WHITE, 4.0f * s);
dl->AddRect(ImVec2(x, o.y), ImVec2(x + w, o.y + ih), IM_COL32(0x3a, 0x3a, 0x3f, 0xff), 4.0f * s);
if (!b.alt.empty())
drawText(dl, small, ImVec2(o.x + (width - capSize.x) * 0.5f, o.y + ih + 6.0f * s), kDim, b.alt, false);
}
break;
}
case BlockKind::Rule:
h = 14.0f * s;
if (dl) dl->AddLine(ImVec2(o.x, o.y + h * 0.5f), ImVec2(o.x + width, o.y + h * 0.5f), kRule, 1.0f);
break;
}
if (!click.target.empty()) navigate(click.target);
return h;
}
float UserGuide::layoutBlocks(App& app, int first, int end, ImVec2 origin, float width, float y) {
const float s = app.uiScale_;
const guide::Document& doc = page();
const int page = place_.chapter;
for (int i = first; i < end; ++i) {
const Block& b = doc.blocks[size_t(i)];
blockY_[size_t(i)] = y;
if (b.kind == BlockKind::Heading) anchorY_[b.anchor] = y;
const ImVec2 at(origin.x, origin.y + y);
float h = blockH_[size_t(i)];
const bool visible = h < 0.0f || ImGui::IsRectVisible(at, ImVec2(at.x + width, at.y + h));
if (visible) h = drawBlock(app, b, i, at, width, true);
if (place_.chapter != page) return y; // a link was followed: the rest is the next page's
blockH_[size_t(i)] = h;
// Spacing after the block: list items sit close together, the last one of a list leaves a gap.
const bool listItem = b.kind == BlockKind::Bullet || b.kind == BlockKind::Numbered;
const bool nextList = i + 1 < end && (doc.blocks[size_t(i) + 1].kind == BlockKind::Bullet ||
doc.blocks[size_t(i) + 1].kind == BlockKind::Numbered);
float gap = 12.0f * s;
if (b.kind == BlockKind::Heading) gap = b.level == 3 ? 4.0f * s : 8.0f * s;
else if (listItem && nextList) gap = 3.0f * s;
else if (b.kind == BlockKind::Image || b.kind == BlockKind::Table || b.kind == BlockKind::Code) gap = 16.0f * s;
y += h + gap;
}
return y;
}
// ---------------------------------------------------------------------------
// What's New (whats-new.md): the newest versions in full (a band, the feature cards, "All changes"), then the older
// ones folded into groups with their highlights (core/WhatsNew.h; the website does the same in build_site.py).
// ---------------------------------------------------------------------------
void UserGuide::prepareWhatsNew() {
const int i = book_.find("whats-new.md");
if (i < 0) return;
// SF_GUIDE_VERSION shows the chapter as of another version (ui_whats_new pins the newest section it checks).
const char* as = std::getenv("SF_GUIDE_VERSION");
whatsNew_ = whatsnew::build(book_.chapters()[size_t(i)].doc, as && *as ? as : SCULPTFORGE_VERSION);
expanded_.clear();
if (!whatsNew_.versions.empty()) expanded_[whatsNew_.versions[0].anchor] = true; // the newest one is open
}
std::vector<std::string> UserGuide::whatsNewContents() const {
std::vector<std::string> out;
for (int v = 0; v < whatsNew_.detailed; ++v) out.push_back("Version " + whatsNew_.versions[size_t(v)].version);
for (const auto& g : whatsNew_.groups) out.push_back(g.label);
return out;
}
int UserGuide::whatsNewExpanded() const {
return int(std::count_if(expanded_.begin(), expanded_.end(), [](const auto& e) { return e.second; }));
}
float UserGuide::drawWhatsNewBand(App& app, ImVec2 at, float width, const std::string& title, const std::string& right,
const std::string& line, bool large) {
const float s = app.uiScale_;
ImDrawList* dl = ImGui::GetWindowDrawList();
ImFont* head = (large ? h2_ : h3_) ? (large ? h2_ : h3_) : ImGui::GetFont();
ImFont* small = app.smallFont() ? app.smallFont() : ImGui::GetFont();
ImFont* regular = body_ ? body_ : ImGui::GetFont();
// A short accent rule, the title with the date on the right, and one line under it.
dl->AddRectFilled(at, ImVec2(at.x + 40.0f * s, at.y + 3.0f * s), theme::u32(theme::accent), 1.5f * s);
float y = at.y + 14.0f * s;
dl->AddText(head, head->FontSize, ImVec2(at.x, y), theme::u32(theme::textBright), title.c_str());
ImGui::LogText("%s\n", title.c_str());
if (!right.empty()) {
const float rw = small->CalcTextSizeA(small->FontSize, FLT_MAX, 0.0f, right.c_str()).x;
dl->AddText(small, small->FontSize, ImVec2(at.x + width - rw, y + head->FontSize - small->FontSize - 2.0f * s),
theme::u32(theme::textDim), right.c_str());
}
y += std::round(head->FontSize * 1.3f);
if (!line.empty()) {
const float lw = std::min(width, 680.0f * s);
const ImVec2 ls = regular->CalcTextSizeA(regular->FontSize, FLT_MAX, lw, line.c_str());
dl->AddText(regular, regular->FontSize, ImVec2(at.x, y + 2.0f * s), theme::u32(theme::textDim), line.c_str(), nullptr, lw);
ImGui::LogText("%s\n", line.c_str());
y += ls.y + 4.0f * s;
}
return y - at.y;
}
float UserGuide::drawWhatsNewCards(App& app, const whatsnew::Version& v, ImVec2 at, float width) {
const float s = app.uiScale_;
ImDrawList* dl = ImGui::GetWindowDrawList();
ImFont* bold = bodyBold_ ? bodyBold_ : ImGui::GetFont();
ImFont* regular = app.fontCardBody_ ? app.fontCardBody_ : body_ ? body_ : ImGui::GetFont();
const float lineSize = std::round(15.0f * s);
const float gap = 14.0f * s, pad = 14.0f * s;
const int n = int(v.cards.size());
const int cols = std::clamp(int((width + gap) / (230.0f * s + gap)), 1, std::min(3, n));
const float cw = (width - gap * float(cols - 1)) / float(cols), ph = std::round(cw * 340.0f / 600.0f);
float y = 0.0f;
for (int row = 0; row * cols < n; ++row) {
float rowH = 0.0f;
for (int c = 0; c < cols && row * cols + c < n; ++c) { // the row's height: its tallest words
const auto& card = v.cards[size_t(row * cols + c)];
rowH = std::max(rowH, ph + pad + bold->CalcTextSizeA(bold->FontSize, FLT_MAX, cw - pad * 2.0f, card.title.c_str()).y +
4.0f * s + regular->CalcTextSizeA(lineSize, FLT_MAX, cw - pad * 2.0f, card.line.c_str()).y +
12.0f * s + ImGui::GetFrameHeight() + pad);
}
for (int c = 0; c < cols && row * cols + c < n; ++c) {
const int i = row * cols + c;
const auto& card = v.cards[size_t(i)];
const ImVec2 p0(at.x + float(c) * (cw + gap), at.y + y), p1(p0.x + cw, p0.y + rowH);
if (!ImGui::IsRectVisible(p0, p1)) continue;
const float r = 10.0f * s;
const bool hot = ImGui::IsMouseHoveringRect(p0, p1) && ImGui::IsWindowHovered();
dl->AddRectFilled(p0, p1, theme::u32(theme::header), r);
if (const Texture* tex = card.image.empty() ? nullptr : texture(card.image)) {
// Covers the top of the card (centred crop to 600 x 340).
const float ia = float(tex->width) / float(std::max(1, tex->height)), ba = cw / ph;
ImVec2 uv0(0, 0), uv1(1, 1);
if (ia > ba) uv0.x = 0.5f - ba / ia * 0.5f, uv1.x = 0.5f + ba / ia * 0.5f;
else uv0.y = 0.5f - ia / ba * 0.5f, uv1.y = 0.5f + ia / ba * 0.5f;
dl->AddImageRounded(ImTextureID(uintptr_t(tex->tex)), p0, ImVec2(p1.x, p0.y + ph), uv0, uv1, IM_COL32_WHITE, r,
ImDrawFlags_RoundCornersTop);
}
dl->AddRect(p0, p1, theme::u32(hot ? theme::accent : theme::text, hot ? 0.55f : 0.10f), r, 0, 1.0f);
float ty = p0.y + ph + pad;
const float tw = cw - pad * 2.0f;
dl->AddText(bold, bold->FontSize, ImVec2(p0.x + pad, ty), theme::u32(theme::textBright), card.title.c_str(), nullptr, tw);
ImGui::LogText("%s\n", card.title.c_str());
ty += bold->CalcTextSizeA(bold->FontSize, FLT_MAX, tw, card.title.c_str()).y + 4.0f * s;
dl->AddText(regular, lineSize, ImVec2(p0.x + pad, ty), theme::u32(theme::textDim), card.line.c_str(), nullptr, tw);
ImGui::LogText("%s\n", card.line.c_str());
const bool guideLink = card.action.rfind("guide:", 0) == 0;
ImGui::SetCursorScreenPos(ImVec2(p0.x + pad, p1.y - pad - ImGui::GetFrameHeight()));
const std::string label = std::string(guideLink ? "Read more " : "Try it ") + ICON_LC_ARROW_RIGHT + "##wn." + v.anchor + "." +
std::to_string(i);
if (ImGui::Button(label.c_str())) app.runWhatsNewAction(card.action);
}
y += rowH + gap;
}
return y - gap;
}
bool UserGuide::drawWhatsNewToggle(App& app, ImVec2 at, float width, const std::string& id, bool open, float& h) {
const float s = app.uiScale_;
ImFont* bold = bodyBold_ ? bodyBold_ : ImGui::GetFont();
h = bold->FontSize + 14.0f * s;
ImGui::SetCursorScreenPos(at);
const bool clicked = ImGui::InvisibleButton(("All changes##wn." + id).c_str(), ImVec2(width, h));
const bool hot = ImGui::IsItemHovered();
ImDrawList* dl = ImGui::GetWindowDrawList();
const ImU32 c = theme::u32(hot ? theme::accent : theme::text);
dl->AddLine(ImVec2(at.x, at.y), ImVec2(at.x + width, at.y), theme::u32(theme::sectionRule));
// A chevron (drawn: the reading font has no icons), right when folded, down when open.
const ImVec2 m(at.x + 6.0f * s, at.y + 7.0f * s + bold->FontSize * 0.5f);
const float r = 4.0f * s;
const ImVec2 pts[3] = {open ? ImVec2(m.x - r, m.y - r * 0.5f) : ImVec2(m.x - r * 0.5f, m.y - r),
open ? ImVec2(m.x, m.y + r * 0.5f) : ImVec2(m.x + r * 0.5f, m.y),
open ? ImVec2(m.x + r, m.y - r * 0.5f) : ImVec2(m.x - r * 0.5f, m.y + r)};
dl->AddPolyline(pts, 3, theme::u32(theme::accent), 0, 1.8f * s);
dl->AddText(bold, bold->FontSize, ImVec2(at.x + 20.0f * s, at.y + 7.0f * s), c, "All changes");
ImGui::LogText("All changes\n");
return clicked;
}
float UserGuide::drawWhatsNew(App& app, ImVec2 origin, float width) {
const float s = app.uiScale_;
const guide::Document& doc = page();
const whatsnew::Page& wn = whatsNew_;
const float prose = std::min(width, 680.0f * s); // about 70 characters a line
// Going to a heading or a search hit inside a folded section opens it.
int target = pendingBlock_ >= 0 ? pendingBlock_ : -1;
if (!pendingAnchor_.empty())
for (size_t i = 0; i < doc.blocks.size(); ++i)
if (doc.blocks[i].kind == BlockKind::Heading && doc.blocks[i].anchor == pendingAnchor_) target = int(i);
if (target >= 0) {
for (int v = 0; v < int(wn.versions.size()); ++v) {
const auto& ver = wn.versions[size_t(v)];
if (target < ver.first || target >= ver.end) continue;
if (v < wn.detailed) expanded_[ver.anchor] = true;
for (const auto& g : wn.groups)
if (std::find(g.versions.begin(), g.versions.end(), v) != g.versions.end()) expanded_[g.anchor] = true;
}
}
float y = layoutBlocks(app, 0, wn.introEnd, origin, prose, 0.0f) + 18.0f * s;
const int page = place_.chapter;
ImDrawList* dl = ImGui::GetWindowDrawList();
for (int vi = 0; vi < wn.detailed && place_.chapter == page; ++vi) {
const whatsnew::Version& v = wn.versions[size_t(vi)];
anchorY_[v.anchor] = y;
blockY_[size_t(v.heading)] = y;
const std::string date = v.date == "unreleased" ? std::string("Not released yet") : v.date;
y += drawWhatsNewBand(app, ImVec2(origin.x, origin.y + y), width, "Version " + v.version, date, v.tagline, true) + 16.0f * s;
if (!v.cards.empty()) y += drawWhatsNewCards(app, v, ImVec2(origin.x, origin.y + y), width) + 16.0f * s;
const bool open = expanded_[v.anchor];
float th = 0.0f;
if (drawWhatsNewToggle(app, ImVec2(origin.x, origin.y + y), width, v.anchor, open, th)) expanded_[v.anchor] = !open;
y += th;
if (open) y = layoutBlocks(app, v.first, v.end, origin, prose, y + 8.0f * s);
y += 40.0f * s;
}
if (!wn.groups.empty() && place_.chapter == page) {
ImFont* small = app.boldFont() ? app.boldFont() : ImGui::GetFont();
dl->AddText(small, small->FontSize, ImVec2(origin.x, origin.y + y), theme::u32(theme::textDim), "EARLIER VERSIONS");
y += small->FontSize + 18.0f * s;
}
for (const whatsnew::Group& g : wn.groups) {
if (place_.chapter != page) break;
anchorY_[g.anchor] = y;
y += drawWhatsNewBand(app, ImVec2(origin.x, origin.y + y), width, g.label, "", "", true) + 4.0f * s;
// The highlights, as a list ("Title: line" with the title in bold).
for (const std::string& h : g.highlights) {
const auto [title, rest] = whatsnew::splitHighlight(h);
Block b;
b.kind = BlockKind::Bullet;
if (!title.empty()) b.spans.push_back({title, true});
b.spans.push_back({title.empty() ? rest : ": " + rest});
y += drawBlock(app, b, -1, ImVec2(origin.x, origin.y + y), prose, true) + 3.0f * s;
}
y += 10.0f * s;
const bool open = expanded_[g.anchor];
float th = 0.0f;
if (drawWhatsNewToggle(app, ImVec2(origin.x, origin.y + y), width, g.anchor, open, th)) expanded_[g.anchor] = !open;
y += th;
if (open) {
for (int vi : g.versions) {
const whatsnew::Version& v = wn.versions[size_t(vi)];
y += 14.0f * s;
anchorY_[v.anchor] = y;
blockY_[size_t(v.heading)] = y;
ImFont* head = h3_ ? h3_ : ImGui::GetFont();
const std::string title = "Version " + v.version;
dl->AddText(head, head->FontSize, ImVec2(origin.x, origin.y + y), theme::u32(theme::accent), title.c_str());
ImGui::LogText("%s\n", title.c_str());
y += std::round(head->FontSize * 1.4f);
demoteHeadings_ = true; // its "###" sit under the version's title
y = layoutBlocks(app, v.first, v.end, origin, prose, y);
demoteHeadings_ = false;
if (place_.chapter != page) break;
}
}
y += 34.0f * s;
}
return y;
}
void UserGuide::drawPage(App& app) {
const float s = app.uiScale_;
ImGui::PushStyleColor(ImGuiCol_ChildBg, theme::panelBg);
ImGui::BeginChild("##guide_page", ImVec2(0, 0), ImGuiChildFlags_None, ImGuiWindowFlags_None);
const guide::Document& doc = page();
const float avail = ImGui::GetContentRegionAvail().x;
const float pad = 24.0f * s;
const float width = std::max(200.0f * s, std::min(avail - pad * 2.0f, 820.0f * s));
const ImVec2 start = ImGui::GetCursorScreenPos();
const ImVec2 origin(start.x + std::max(pad, (avail - width) * 0.5f), start.y + pad * 0.8f);
const size_t n = doc.blocks.size();
const bool cached = layoutPage_ == place_.chapter && std::abs(layoutWidth_ - width) < 0.5f && blockH_.size() == n;
if (!cached) {
blockH_.assign(n, -1.0f);
layoutWidth_ = width;
layoutPage_ = place_.chapter;
}
blockY_.assign(n, 0.0f);
anchorY_.clear();
linkCounter_ = 0;
const int page = place_.chapter;
const bool whatsNew = currentFile() == "whats-new.md";
float y = whatsNew ? drawWhatsNew(app, origin, width) : layoutBlocks(app, 0, int(n), origin, width, 0.0f);
if (place_.chapter == page && whatsNew) {
// The end of What's New: a quiet line about supporting SculptForge (it only opens the website's page).
const float y0 = origin.y + y + 8.0f * s;
ImDrawList* dl = ImGui::GetWindowDrawList();
dl->AddLine(ImVec2(origin.x, y0), ImVec2(origin.x + width, y0), theme::u32(theme::sectionRule));
ImGui::SetCursorScreenPos(ImVec2(origin.x, y0 + 14.0f * s));
if (bodyFont()) ImGui::PushFont(bodyFont());
ImGui::PushTextWrapPos(origin.x + width);
ImGui::TextUnformatted(tr("SculptForge is free and open source, and stays that way. If it helps your work, "
"you can support its development."));
ImGui::PopTextWrapPos();
if (bodyFont()) ImGui::PopFont();
ImGui::Spacing();
ImGui::SetCursorScreenPos(ImVec2(origin.x, ImGui::GetCursorScreenPos().y));
if (ImGui::Button(tr("Support SculptForge##whats_new"))) app.openSupportPage();
y = ImGui::GetCursorScreenPos().y - origin.y;
}
ImGui::SetCursorScreenPos(start);
ImGui::Dummy(ImVec2(avail, y + pad * 2.0f));
// Scroll to where navigation asked (positions are known now).
const float top = pad * 0.8f;
if (place_.chapter == page) {
if (!pendingAnchor_.empty()) {
if (auto it = anchorY_.find(pendingAnchor_); it != anchorY_.end()) ImGui::SetScrollY(std::max(0.0f, top + it->second - 6.0f * s));
pendingAnchor_.clear();
} else if (pendingBlock_ >= 0 && pendingBlock_ < int(n)) {
ImGui::SetScrollY(std::max(0.0f, top + blockY_[size_t(pendingBlock_)] - 60.0f * s));
pendingBlock_ = -pendingBlock_ - 2; // done, but remembered (search result stays selected)
} else if (pendingScroll_ >= 0.0f) {
ImGui::SetScrollY(pendingScroll_);
pendingScroll_ = -1.0f;
} else if (pendingTop_) {
ImGui::SetScrollY(0.0f);
pendingTop_ = false;
}
}
scroll_ = ImGui::GetScrollY();
ImGui::EndChild();
ImGui::PopStyleColor();
}
} // namespace sf