class EE::UI::UISystemIconTheme¶

Overview¶

Icons provided by the platform, loaded asynchronously. More…

#include <uisystemicontheme.hpp>

class UISystemIconTheme: public std::enable_shared_from_this< UISystemIconTheme > {
public:
    // structs

    struct Request;

    // construction

    ~UISystemIconTheme();

    // methods

    static std::shared_ptr<UISystemIconTheme> New(Executor& worker, Executor& ui, const std::string& themeName = {});
    UIIcon* getIcon(const std::vector<std::string>& names, UIIcon* fallback = nullptr);
    UIIcon* getFileIcon(const std::string& fileName, bool isDirectory, const std::vector<std::string>& names, UIIcon* fallback = nullptr);
    UIIcon* getPathIcon(const std::string& path, const std::vector<std::string>& names, UIIcon* fallback = nullptr);
    const std::string& getThemeName() const;
    void setOnIconsLoaded(std::function<void()> callback);
};

Detailed Documentation¶

Icons provided by the platform, loaded asynchronously.

Linux and BSD: the user’s freedesktop.org icon theme (Icon Theme Specification).
Windows: the shell’s icons (file types, special folders and stock icons).
macOS: NSWorkspace icons.

Icons are returned immediately. Finding, reading and rasterizing them happens on the worker executor; until an icon’s image is ready it shows its fallback icon (or nothing). Textures are created on the UI executor, which then calls the icons-loaded callback so views can redraw. Loaded icons are cached for the life of the theme.

Both executors must outlive the work they were given (shut the worker down first, as a ThreadPool member declared after the UI executor does). Methods are UI thread only.

Methods¶

static std::shared_ptr<UISystemIconTheme> New(Executor& worker, Executor& ui, const std::string& themeName = {})

Parameters:

worker	Where lookups, file reads and rasterization run (e.g. a ThreadPool).
ui	The thread that owns the graphics context (e.g. a MainThreadExecutor).
themeName	Freedesktop theme to use; empty detects the user’s (Linux and BSD only). Detection and indexing start right away on the worker.

UIIcon* getIcon(const std::vector<std::string>& names, UIIcon* fallback = nullptr)

Icon for standard (freedesktop) icon names, tried in order: “folder”, “user-home”, “folder-documents”, “user-trash”, “drive-harddisk”, “drive-removable-media”, “network-server”, “text-x-generic”… Windows and macOS map these names to their own special folder and stock icons. The returned icon is owned by the theme.

UIIcon* getFileIcon(const std::string& fileName, bool isDirectory, const std::vector<std::string>& names, UIIcon* fallback = nullptr)

Icon for a file or folder type. On Linux and BSD names are the freedesktop names of its MIME type (most specific first); Windows and macOS use the type of the file name’s extension.

UIIcon* getPathIcon(const std::string& path, const std::vector<std::string>& names, UIIcon* fallback = nullptr)

Icon of a local path as the platform shows it (special folders, drives): Windows and macOS ask the shell for that path; Linux and BSD use names.

const std::string& getThemeName() const

The freedesktop theme in use, once detected (empty before, and on Windows and macOS).

void setOnIconsLoaded(std::function<void()> callback)

Called on the UI thread after icons received images (coalesced): redraw the views that show them.