Important internal classes

Here, we will document important internal classes.

Core/Defines.hpp

The Defines.hpp header contains the following definitions:

1. Defines __declspec(dllimport)/__declspec(dllexport) when compiling for Windows
2. Defines the std_filesystem macro, to make working with older compilers that support std::filesystem as part of std::experimental::filesystem possible
3. Defines the IMGUI_START macro that is called as the first thing in the entry point.

It also defines the following strings that can be used to set the semantic type of a window in X11(more info on the Window Interface page). They look like this:

#define X11_WINDOW_TYPE_DESKTOP "_NET_WM_WINDOW_TYPE_DESKTOP"
#define X11_WINDOW_TYPE_DOCK "_NET_WM_WINDOW_TYPE_DOCK"
#define X11_WINDOW_TYPE_TOOLBAR "_NET_WM_WINDOW_TYPE_TOOLBAR"
#define X11_WINDOW_TYPE_MENU "_NET_WM_WINDOW_TYPE_MENU"
#define X11_WINDOW_TYPE_UTILITY "_NET_WM_WINDOW_TYPE_UTILITY"
#define X11_WINDOW_TYPE_SPLASH "_NET_WM_WINDOW_TYPE_SPLASH"
#define X11_WINDOW_TYPE_DIALOG "_NET_WM_WINDOW_TYPE_DIALOG"
#define X11_WINDOW_TYPE_NORMAL "_NET_WM_WINDOW_TYPE_NORMAL"

Additionally, it defines the ComponentState enum:

/**
 * @brief The ComponentState enum defines 3 fields that represent the event state of the given component, the given
 * component can then check its own state(if in PAUSED or RUNNING state) and call specific components of its event
 * functions. The OFF state is there to make it easy to fully shut down a component until the program closes
 */
enum ComponentState
{
    // The component is not running but its events are still running
    UIMGUI_COMPONENT_STATE_PAUSED,
    // The component is running
    UIMGUI_COMPONENT_STATE_RUNNING,
    // The component is not running and its events are not running, only the constructor and destructor are called
    UIMGUI_COMPONENT_STATE_OFF,
};

And the ComponentType enum:

/**
 * @brief An enum that defines component types to be used by various functions
 * @var UIMGUI_COMPONENT_TYPE_INLINE - Defines an inline component
 * @var UIMGUI_COMPONENT_TYPE_TITLEBAR - Defines a titlebar component
 * @var UIMGUI_COMPONENT_PYE_WINDOW - Defines a window component
 */
enum [[maybe_unused]] ComponentType
{
    UIMGUI_COMPONENT_TYPE_INLINE,
    UIMGUI_COMPONENT_TYPE_TITLEBAR,
    UIMGUI_COMPONENT_TYPE_WINDOW
};

Core/Global

This class defines the Global class, which stores global data used internally, such as pointers to the Instance and RendererInternal classes and the single instances of the WindowInternal and ModulesManager classes.

It also has the init member function, which is equivalent to the Begin event listed on the Internal Event Safety page.

Core/Types.hpp

It defines the following types:

// Redefine for C++
typedef UImGui_FVector2 FVector2;
typedef UImGui_FVector FVector;
typedef UImGui_FVector4 FVector4;
typedef UImGui_String String;
typedef std::string FString;

YAML::Emitter& operator<<(YAML::Emitter& out, const FVector4& vect) noexcept;
YAML::Emitter& operator<<(YAML::Emitter& out, const FVector& vect) noexcept;
YAML::Emitter& operator<<(YAML::Emitter& out, const FVector2& vect) noexcept;

and also calls using namespace UVKLog; to remove the UVKLog namespace when logging.

The above type definitions are imported from the C API at CTypes.h, which looks like this:

struct UIMGUI_PUBLIC_API UImGui_FVector2_I
{
    float x;
    float y;
};

struct UIMGUI_PUBLIC_API UImGui_FVector_I
{
    float x;
    float y;
    float z;
};

struct UIMGUI_PUBLIC_API UImGui_FVector4_I
{
    float x;
    float y;
    float z;
    float w;
};

typedef const char* UImGui_String;

typedef struct UImGui_FVector2_I UImGui_FVector2;
typedef struct UImGui_FVector_I UImGui_FVector;
typedef struct UImGui_FVector4_I UImGui_FVector4;

The 3 operator<< overrides allow our vector types to easily be output to YAML. Additionally, the following class definitions allow us to easily load YAML into those types:

namespace YAML
{
    template<>
    struct convert<UImGui::FVector4>
    {
        static Node encode(const UImGui::FVector4& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.push_back(rhs.z);
            node.push_back(rhs.w);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector4& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 4)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            rhs.z = node[2].as<float>();
            rhs.w = node[3].as<float>();
            return true;
        }
    };

    template<>
    struct convert<UImGui::FVector>
    {
        static Node encode(const UImGui::FVector& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.push_back(rhs.z);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 3)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            rhs.z = node[2].as<float>();
            return true;
        }
    };

    template<>
    struct convert<UImGui::FVector2>
    {
        static Node encode(const UImGui::FVector2& rhs) noexcept
        {
            Node node;
            node.push_back(rhs.x);
            node.push_back(rhs.y);
            node.SetStyle(EmitterStyle::Flow);
            return node;
        }

        static bool decode(const Node& node, UImGui::FVector2& rhs) noexcept
        {
            if (!node.IsSequence() || node.size() != 2)
                return false;

            rhs.x = node[0].as<float>();
            rhs.y = node[1].as<float>();
            return true;
        }
    };
}

Modules/Manager/ModulesManager

This file defines the internal ModulesManager class, the Modules interface and the ModuleSettings struct.

The ModulesManager class manages module settings, which module is enabled at runtime and at compile time, and managing the modules' lifetime.

It looks like this:

class ModulesManager
{
private:
    ModuleSettings settings;
#ifdef UIMGUI_LOCALE_MODULE_ENABLED
    LocaleManager localeManager{};
#endif

#ifdef UIMGUI_UNDO_MODULE_ENABLED
    StateTracker stateTracker{};
#endif

    void init();
    void initModules();
    void save() const noexcept;
};

Reference:

1. init - Loads module settings
2. initModules - Initializes modules with the settings
3. save - saves settings to Modules.yaml

Renderer/Renderer

The internal Renderer class looks like this:

class UIMGUI_PUBLIC_API RendererInternal
{
public:
    void start() noexcept;
    void stop() noexcept;
private:
    FString vendorString;
    FString apiVersion;
    FString driverVersion;
    FString gpuName;

    void loadConfig();
    void saveConfig() const noexcept;

    RendererData data{};
};

Reference:

1. start - Initializes and starts the renderer
2. stop - Destroys the renderer and deallocates all renderer data
3. The 4 strings - GPU information that can be fetched using the renderer interface
4. loadConfig - Loads the renderer config file, Renderer.yaml
5. saveConfig - Saves the renderer data stored in the data field to Renderer.yaml

Renderer/ImGui/ImGui

The GUIRenderer class contains internal functions that set up dear imgui through the different stages of the render loop. It looks like this:

class GUIRenderer
{
public:
    static void init(GLFWwindow* glfwwindow, const FString& ini);
    static void beginUI(float deltaTime);
    static void beginFrame();
    static void shutdown(const FString& ini);
};

Reference:

1. init - Creates an imgui context, sets up themes and style, calls the begin events of the components and the instance
2. beginUI - Called at the beginning of every render loop iteration
3. beginFrame - Starts a new imgui frame
4. shutdown - Cleans up imgui resources + save the layout to the specified location in the Window.yaml config file

Renderer/Utils/Window

The internal Window class looks like this:

class WindowInternal
{
public:
    [[nodiscard]] GLFWwindow* data() const noexcept;
    bool& resized() noexcept;
    void close() noexcept;
private:
    void updateKeyState() noexcept;

    FVector2 windowSize = { 800.0f, 600.0f };
    FVector2 windowSizeInScreenCoords;

    std::array<uint16_t, 350> keys{};
    std::vector<InputAction> inputActionList{};

    void saveConfig(bool bSaveKeybindings) noexcept;
    void openConfig();

    void setTitle(String title) noexcept;
    void setIcon(String name) noexcept;

    FVector2 getMousePositionChange() noexcept;
    FVector2 getScroll() noexcept;

    void createWindow() noexcept;
    void destroyWindow() noexcept;

    void configureCallbacks() noexcept;
    static void framebufferSizeCallback(GLFWwindow* window, int width, int height) noexcept;
    static void keyboardInputCallback(GLFWwindow* window, int key, int scanCode, int action, int mods) noexcept;
    static void mouseKeyInputCallback(GLFWwindow* window, int button, int action, int mods) noexcept;
    static void mouseCursorPositionCallback(GLFWwindow* window, double xpos, double ypos) noexcept;
    static void scrollInputCallback(GLFWwindow* window, double xoffset, double yoffset) noexcept;
    static void windowPositionCallback(GLFWwindow* window, int xpos, int ypos) noexcept;

    static void windowSizeCallback(GLFWwindow* window, int width, int height) noexcept;
    static void windowCloseCallback(GLFWwindow* window) noexcept;
    static void windowFocusCallback(GLFWwindow* window, int focused) noexcept;
    static void windowIconifyCallback(GLFWwindow* window, int iconified) noexcept;
    static void windowContentScaleCallback(GLFWwindow* window, float x, float y) noexcept;
    static void windowRefreshCallback(GLFWwindow* window) noexcept;
    static void windowMaximisedCallback(GLFWwindow* window, int maximised) noexcept;

    static void monitorCallback(GLFWmonitor* monitor, int event) noexcept;

    static void windowOSDragDropCallback(GLFWwindow* window, int count, const char** paths) noexcept;

    static void windowErrorCallback(int code, const char* description) noexcept;

    void setWindowAlwaysOnTop() noexcept;
    void setWindowAlwaysBelow() noexcept;
    void disableWindowMoving() noexcept;

    void setShowWindowInPager(bool bShowInPagerr) noexcept;
    void setShowWindowOnTaskbar(bool bShowOnTaskbarr) noexcept;

    void setWindowType(const char* type) noexcept;
    
    bool bShowOnPager = true;
    bool bShowOnTaskbar = true;

    std::vector<std::function<void(int, int)>> windowResizeCallbackList;
    std::vector<std::function<void(int, int)>> windowResizeInScreenCoordCallbackList;
    std::vector<std::function<void(void)>> windowCloseCallbackList;
    std::vector<std::function<void(bool)>> windowFocusCallbackList;
    std::vector<std::function<void(bool)>> windowIconifiedCallbackList;
    std::vector<std::function<void(FVector2)>> windowPositionChangeCallbackList;
    std::vector<std::function<void(FVector2)>> windowContentScaleChangeCallbackList;
    std::vector<std::function<void(void)>> windowRefreshCallbackList;
    std::vector<std::function<void(bool)>> windowMaximisedCallbackList;
    std::vector<std::function<void(Monitor&, MonitorState)>> windowMonitorCallbackList;
    std::vector<std::function<void(std::vector<FString>&)>> dragDropPathCallbackList;
    
    std::vector<std::function<void(int, const char*)>> windowErrorCallbackList;

    std::vector<FString> dragDropPaths;

    std::vector<Monitor> monitors;

    GLFWwindow* windowMain = nullptr;
    WindowData windowData;

    bool bFirstMove = true;
    bool bResized = false;

    FVector2 mousePos = { 0.0f, 0.0f };
    FVector2 mouseLastPos = { 0.0f, 0.0f };
    FVector2 mouseOffset = { 0.0f, 0.0f };

    FVector2 scroll;

    FVector2 windowLastPos = { 0.0f, 0.0f };
    FVector2 windowCurrentPos = { 0.0f, 0.0f };
};

Functions:

1. data - Returns the internal GLFW window context
2. resized - Resized a boolean reference to check if the window was resized
3. close - Close the window
4. updateKeyState - Updates the state of InputActions after all keys' state is known, i.e. after glfwPollEvents
5. saveConfig - Saves window settings
6. openConfig - Loads window settings
7. setTitle - Sets the title of the window
8. setIcon - Sets the window icon
9. getMousePositionChange - Returns the difference between the last and current mouse position
10. getScroll - Returns the current scroll value as a FVector2
11. createWindow, destroyWindow - Creates/destroys the window context
12. configureCallbacks - Sets up the callbacks
13. setWindowAlwaysOnTop - Backend version of the same function in the Window interface. Makes the window appear as the top most window.
14. setWindowAlwaysBelow - Backend version of the same function in the Window interface. Makes the window appear as the root or bottom-most window.
15. disableWindowMoving - Backend version of the same function in the Window interface. Completely disable movement of the window by the user
16. setShowWindowInPager - Backend version of the same function in the Window interface. Toggles display of the window in the pager
17. setShowWindowOnTaskbar - Backend version of the same function in the Window interface. Toggles display of the window in the taskbar
18. setWindowType - Backend version of the same function in the Window interface. Given a C string, sets the given X11 semantic window type as defined by the X11 documentation.
19. The rest - Callbacks for window events.

Variables:

1. windowSize - The size of the window as a FVector2
2. windowSizeInScreenCoords - The size of the window in screen coordinates as an FVector2
3. keys - An array of events on a given key code
4. inputActionList - The internal list of input actions
5. dragDropPaths - A list of all paths that were acquired by the window on OS file drag and drop into it
6. bShowOnPager - The internal bool that is used to check whether the window is shown on the pager
7. bShowOnTaskbar - The internal bool that is used to check whether the window is shown on the taskbar
8. monitors - The internal monitors array
9. windowMain - The internal GLFW window context
10. windowData - The internal instance of the WindowData struct
11. bResized - To check whether the window was resized
12. mousePos, mouseLastPos, mouseOffset - Mouse positions as FVector2
13. scroll - Current scroll value
14. windowCurrentPos, windowLastPos - Window positions as FVector2
15. The rest - std::vector<std::function<void(T)>> style variables which store the callbacks pushed by the Window interface by pushWindow*Callback functions