windowpp 0.1.1

package/framework/include/windowpp/windowpp.h

@@ -0,0 +1,704 @@
+#pragma once
+
+// ============================================================================
+//  WindowPP — Cross-Platform Native Window Library
+//  
+//  One header. Two config structs. Zero boilerplate.
+//
+//  Supports: Windows (Win32), macOS (Cocoa), Linux (X11 + XCB)
+//  Features: Frameless/transparent windows with proper resize handles,
+//            system tray, startup registration, file drop, multi-window.
+// ============================================================================
+
+#include <string>
+#include <functional>
+#include <vector>
+#include <cstdint>
+#include <memory>
+#include <unordered_map>
+
+namespace wpp {
+
+// ─── Forward Declarations ────────────────────────────────────────────────────
+
+class Application;
+class Window;
+class AppDataManager;
+struct KeyEvent;
+
+namespace input {
+
+enum class Key {
+    Unknown,
+    A, B, C, D, E, F, G, H, I, J, K, L, M,
+    N, O, P, Q, R, S, T, U, V, W, X, Y, Z,
+    Digit0, Digit1, Digit2, Digit3, Digit4,
+    Digit5, Digit6, Digit7, Digit8, Digit9,
+    Space,
+    Enter,
+    Escape,
+    Tab,
+    Backspace,
+    Delete,
+    Insert,
+    Home,
+    End,
+    PageUp,
+    PageDown,
+    Left,
+    Right,
+    Up,
+    Down,
+    CapsLock,
+    Shift,
+    Control,
+    Alt,
+    Meta,
+    F1,
+    F2,
+    F3,
+    F4,
+    F5,
+    F6,
+    F7,
+    F8,
+    F9,
+    F10,
+    F11,
+    F12
+};
+
+enum class KeyEventType {
+    KeyDown,
+    KeyUp
+};
+
+struct Shortcut {
+    Key         key = Key::Unknown;
+    bool        ctrl = false;
+    bool        shift = false;
+    bool        alt = false;
+    bool        meta = false;
+    std::string text;
+};
+
+struct ShortcutOptions {
+    bool        global = false;
+    bool        trigger_on_key_up = false;
+    bool        allow_repeat = false;
+    std::string window_id;
+};
+
+class Service {
+public:
+    using ListenerId = uint64_t;
+    using KeyListener = std::function<void(const KeyEvent& event)>;
+    using ShortcutHandler = std::function<void(const KeyEvent& event)>;
+
+    static Service& instance();
+
+    ListenerId add_key_listener(KeyListener listener);
+    void remove_key_listener(ListenerId id);
+
+    Shortcut parse_shortcut(const std::string& text) const;
+    std::string format_shortcut(const Shortcut& shortcut) const;
+
+    void register_shortcut(const std::string& id,
+                           const std::string& shortcut,
+                           ShortcutHandler handler,
+                           ShortcutOptions options = {});
+    void register_app_shortcut(const std::string& id,
+                               const std::string& shortcut,
+                               ShortcutHandler handler,
+                               const std::string& window_id = "") {
+        register_shortcut(id, shortcut, std::move(handler), ShortcutOptions{false, false, false, window_id});
+    }
+    void register_global_shortcut(const std::string& id,
+                                  const std::string& shortcut,
+                                  ShortcutHandler handler) {
+        register_shortcut(id, shortcut, std::move(handler), ShortcutOptions{true, false, false, {}});
+    }
+    void unregister_shortcut(const std::string& id);
+    void clear_shortcuts();
+
+    bool is_pressed(Key key) const;
+    std::vector<Key> pressed_keys() const;
+
+private:
+    Service() = default;
+};
+
+Service& service();
+std::string key_to_string(Key key);
+
+} // namespace input
+
+struct AppDataEntry {
+    std::string name;
+    std::string path;
+    bool        is_dir = false;
+    bool        is_symlink = false;
+};
+
+// ─── AppData Types ───────────────────────────────────────────────────────────
+
+struct SeedEntry {
+    std::string relative_path;
+    std::string content;
+    bool overwrite = false;
+};
+
+class AppDataManager {
+public:
+    explicit AppDataManager(const std::string& app_name);
+
+    const std::string& root() const;
+    std::string path(const std::string& relative = "") const;
+
+    bool exists(const std::string& relative = "") const;
+    std::string read_text(const std::string& relative) const;
+    void write_text(const std::string& relative, const std::string& content);
+    void append_text(const std::string& relative, const std::string& content);
+    void delete_file(const std::string& relative);
+    void create_dir(const std::string& relative, bool recursive = true);
+    void remove_dir(const std::string& relative, bool recursive = false);
+    std::vector<AppDataEntry> read_dir(const std::string& relative = "") const;
+
+    void ensure_dirs(const std::vector<std::string>& dirs);
+    void seed_file(const std::string& relative_path,
+                   const std::string& content,
+                   bool overwrite = false);
+    void seed_files(const std::vector<SeedEntry>& entries);
+
+private:
+    std::string root_;
+};
+
+// ─── Enums ───────────────────────────────────────────────────────────────────
+
+enum class WindowState {
+    Normal,
+    Minimized,
+    Maximized,
+    Fullscreen,
+    Hidden
+};
+
+enum class CursorType {
+    Arrow,
+    Hand,
+    IBeam,
+    Crosshair,
+    ResizeNS,
+    ResizeEW,
+    ResizeNWSE,
+    ResizeNESW,
+    Move,
+    NotAllowed,
+    Wait
+};
+
+enum class HitTestRegion {
+    Client,         // Normal content area
+    Caption,        // Draggable titlebar region
+    ResizeTop,
+    ResizeBottom,
+    ResizeLeft,
+    ResizeRight,
+    ResizeTopLeft,
+    ResizeTopRight,
+    ResizeBottomLeft,
+    ResizeBottomRight,
+    Close,
+    Minimize,
+    Maximize
+};
+
+enum class TrayClickType {
+    Left,
+    Right,
+    Double
+};
+
+// ─── Data Types ──────────────────────────────────────────────────────────────
+
+struct Point {
+    int x = 0;
+    int y = 0;
+};
+
+struct Size {
+    int width  = 0;
+    int height = 0;
+};
+
+struct Rect {
+    int x      = 0;
+    int y      = 0;
+    int width  = 0;
+    int height = 0;
+};
+
+struct Color {
+    uint8_t r = 0;
+    uint8_t g = 0;
+    uint8_t b = 0;
+    uint8_t a = 255;
+};
+
+struct MonitorInfo {
+    std::string name;
+    Rect        bounds;        // Full monitor area
+    Rect        work_area;     // Excluding taskbar/dock
+    float       scale_factor;  // DPI scaling (1.0 = 96dpi)
+    bool        is_primary;
+};
+
+// ─── Event Types ─────────────────────────────────────────────────────────────
+
+struct MouseEvent {
+    Point position;       // Relative to window
+    Point global_position;
+    int   button;         // 0=left, 1=right, 2=middle
+    int   clicks;         // 1=single, 2=double
+    int   scroll_delta_x;
+    int   scroll_delta_y;
+    bool  ctrl;
+    bool  shift;
+    bool  alt;
+    bool  meta;
+};
+
+struct KeyEvent {
+    input::Key  key = input::Key::Unknown;
+    input::KeyEventType type = input::KeyEventType::KeyDown;
+    int         keycode;      // Platform virtual keycode
+    uint32_t    scancode;
+    std::string key_name;     // "A", "Enter", "Escape", etc.
+    bool        ctrl;
+    bool        shift;
+    bool        alt;
+    bool        meta;
+    bool        is_repeat;
+    bool        is_global = false;
+    std::string window_id;
+    std::vector<input::Key> pressed_keys;
+};
+
+struct DropEvent {
+    std::vector<std::string> paths;  // File/folder paths
+    Point                    position;
+};
+
+struct ResizeEvent {
+    Size old_size;
+    Size new_size;
+};
+
+struct MoveEvent {
+    Point old_position;
+    Point new_position;
+};
+
+// ─── WebView ─────────────────────────────────────────────────────────────────
+
+// Response returned by a custom scheme handler (see WebViewConfig::scheme_handler).
+struct SchemeResponse {
+    std::vector<uint8_t> body;
+    std::string          content_type;
+    int                  status = 200;
+};
+
+struct WebViewConfig {
+    bool        enabled     = false;
+    bool        frameless   = false;
+    bool        scrollbars  = false;
+    bool        file_drop   = false;
+    std::string initial_url;
+    std::string initial_html;
+    bool        devtools    = false;
+    std::function<void(std::string)> on_load_finished;
+    std::function<void(std::string)> on_message;
+
+    // Optional: register a custom URI scheme (e.g. "app") so the WebView can
+    // serve embedded assets without an external server.  When set, the WebView
+    // intercepts every request whose scheme matches `custom_scheme` and calls
+    // `scheme_handler` with the URL path (e.g. "/index.html").  Return a
+    // SchemeResponse with the body and MIME type.  For SPA routing, return
+    // index.html for any path that isn't a known asset.
+    //
+    // Usage in main.cpp:
+    //   config.custom_scheme  = "app";
+    //   config.scheme_handler = [](const std::string& path) { ... };
+    //   config.initial_url    = "app://localhost/index.html";
+    std::string custom_scheme;
+    std::function<SchemeResponse(const std::string& path)> scheme_handler;
+
+    // Optional: directory for WebView2/WKWebView/WebKitGTK profile data
+    // (cookies, cache, localStorage, IndexedDB, etc.).
+    // Defaults to empty — WebView2 creates a folder next to the exe;
+    // set to wpp::paths::app_data_dir(app_name) + "/WebView" to keep
+    // all profile data in the OS-standard application data location.
+    std::string user_data_dir;
+};
+
+class WebView {
+public:
+    virtual ~WebView() = default;
+    virtual void load_url(const std::string& url) = 0;
+    virtual void load_html(const std::string& html) = 0;
+    virtual void execute_script(const std::string& script) = 0;
+    virtual void send_message(const std::string& message) = 0;
+    virtual void go_back() = 0;
+    virtual void go_forward() = 0;
+    virtual void reload() = 0;
+    virtual void close() = 0;
+    virtual void resize(int width, int height) = 0;
+    virtual void set_drag_drop_enabled(bool enabled) = 0;
+};
+
+// ─── Menu ────────────────────────────────────────────────────────────────────
+
+struct MenuItem {
+    std::string                    label;
+    std::string                    shortcut;    // e.g. "Ctrl+Q"
+    std::function<void()>          on_click;
+    bool                           enabled    = true;
+    bool                           checked    = false;
+    bool                           is_separator = false;
+    std::vector<MenuItem>          submenu;
+
+    static MenuItem Separator() {
+        MenuItem m;
+        m.is_separator = true;
+        return m;
+    }
+};
+
+// ─── Tray Config ─────────────────────────────────────────────────────────────
+
+struct TrayConfig {
+    std::string           icon_path;     // Path to tray icon (PNG, ICO)
+    std::string           tooltip;
+    std::vector<MenuItem> menu;
+    std::function<void(TrayClickType)> on_click;
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  STRUCT 1: APP_CONFIG — Application-level settings
+// ═════════════════════════════════════════════════════════════════════════════
+
+struct AppConfig {
+    // ── Identity ──
+    std::string name          = "WindowPP App";
+    std::string version       = "1.0.0";
+    std::string identifier    = "com.app.windowpp"; // Reverse domain (macOS bundle ID, Linux .desktop)
+
+    // ── App Icon ──
+    std::string icon_path     = "";   // Path to app icon (PNG/ICO) — embedded into binary on build
+
+    // ── System Tray ──
+    bool        tray_enabled  = false;
+    TrayConfig  tray;
+
+    // ── Behavior ──
+    bool        single_instance    = false;  // Only allow one running instance
+    bool        run_on_startup     = false;  // Register with OS auto-start
+    bool        quit_on_last_close = true;   // Exit app when all windows closed
+    bool        hide_on_close      = false;  // Hide to tray instead of quitting
+
+    // ── Appearance ──
+    bool        dark_mode          = false;  // Prefer dark theme (where supported)
+    bool        high_dpi_aware     = true;   // Enable DPI scaling
+
+    // ── Lifecycle Callbacks ──
+    std::function<void()>                    on_ready;          // App initialized
+    std::function<void()>                    on_quit;           // About to quit
+    std::function<bool()>                    on_quit_requested; // Return false to cancel
+    std::function<void(const std::string&)>  on_open_file;      // OS asked us to open a file
+    std::function<void(const std::string&)>  on_open_url;       // OS asked us to open a URL (custom protocol)
+
+    // ── Custom Protocol ──
+    std::string protocol_scheme = "";  // e.g. "myapp" → handles "myapp://..."
+
+    // ── Logging ──
+    bool        verbose_logging = false;
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  STRUCT 2: WINDOW_CONFIG — Per-window settings
+// ═════════════════════════════════════════════════════════════════════════════
+
+struct WindowConfig {
+    // ── Identity ──
+    std::string id            = "main";     // Unique window ID: "main", "settings", "child", etc.
+    std::string title         = "Window";
+
+    // ── Geometry ──
+    int         width         = 800;
+    int         height        = 600;
+    int         x             = -1;         // -1 = center on screen
+    int         y             = -1;
+    int         min_width     = 0;          // 0 = no minimum
+    int         min_height    = 0;
+    int         max_width     = 0;          // 0 = no maximum
+    int         max_height    = 0;
+
+    // ── Chrome ──
+    bool        frameless     = false;      // No OS-provided window frame
+    bool        titlebar      = true;       // Show native titlebar (ignored if frameless)
+    bool        resizable     = true;
+    bool        closable      = true;
+    bool        minimizable   = true;
+    bool        maximizable   = true;
+
+    // ── Transparency ──
+    bool        transparent   = false;      // Allow per-pixel alpha (requires frameless on some platforms)
+    float       opacity       = 1.0f;       // Window-level opacity [0.0–1.0]
+    Color       background    = {255, 255, 255, 255};
+
+    // ── Behavior ──
+    bool        always_on_top = false;
+    bool        skip_taskbar  = false;      // Don't show in taskbar/dock
+    bool        modal         = false;      // Block parent window
+    std::string parent_id     = "";         // Parent window ID for child/modal
+    bool        center        = true;       // Center on screen (overrides x/y if true)
+
+    // ── Scrolling ──
+    bool        scrollbars    = true;
+
+    // ── File Drop ──
+    bool        file_drop     = true;
+
+    // ── Initial State ──
+    WindowState initial_state = WindowState::Normal;
+
+    // ── WebView ──
+    WebViewConfig webview;
+
+    // ── Frameless Window: Custom Hit-Test ──
+    //    When frameless=true, you must define where the user can drag/resize.
+    //    The library provides a default 8px resize border + top 32px caption.
+    //    Override for custom layouts:
+    int         resize_border_width = 8;    // Pixels from edge that trigger resize
+    int         caption_height      = 32;   // Top region height that acts as draggable titlebar
+
+    //    For full control, supply a hit-test callback:
+    std::function<HitTestRegion(Point)>      on_hit_test;
+
+    // ── Event Callbacks ──
+    std::function<void()>                    on_created;
+    std::function<void()>                    on_shown;
+    std::function<void()>                    on_hidden;
+    std::function<void()>                    on_focused;
+    std::function<void()>                    on_blurred;
+    std::function<void(ResizeEvent)>         on_resize;
+    std::function<void(MoveEvent)>           on_move;
+    std::function<bool()>                    on_close_requested;  // Return false to cancel
+    std::function<void()>                    on_closed;
+    std::function<void(WindowState)>         on_state_changed;
+    std::function<void(float)>               on_scale_changed;    // DPI change
+
+    // ── Input Callbacks ──
+    std::function<void(MouseEvent)>          on_mouse_down;
+    std::function<void(MouseEvent)>          on_mouse_up;
+    std::function<void(MouseEvent)>          on_mouse_move;
+    std::function<void(MouseEvent)>          on_mouse_scroll;
+    std::function<void(MouseEvent)>          on_mouse_enter;
+    std::function<void(MouseEvent)>          on_mouse_leave;
+    std::function<void(KeyEvent)>            on_key_down;
+    std::function<void(KeyEvent)>            on_key_up;
+    std::function<void(DropEvent)>           on_file_drop;
+
+    // ── Paint Callback ──
+    //    Called when the window needs repainting. Use with raw pixel buffer
+    //    or integrate your own renderer (OpenGL, Vulkan, Metal, etc.)
+    std::function<void(void* native_handle)> on_paint;
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  Window — Handle to a created window
+// ═════════════════════════════════════════════════════════════════════════════
+
+class Window {
+public:
+    virtual ~Window() = default;
+
+    // ── Getters ──
+    virtual std::string id() const = 0;
+    virtual std::string title() const = 0;
+    virtual Size        size() const = 0;
+    virtual Point       position() const = 0;
+    virtual WindowState state() const = 0;
+    virtual bool        is_visible() const = 0;
+    virtual bool        is_focused() const = 0;
+    virtual float       scale_factor() const = 0;
+    virtual void*       native_handle() const = 0;  // HWND, NSWindow*, X11 Window
+
+    // ── Setters ──
+    virtual void set_title(const std::string& title) = 0;
+    virtual void set_size(int w, int h) = 0;
+    virtual void set_position(int x, int y) = 0;
+    virtual void set_min_size(int w, int h) = 0;
+    virtual void set_max_size(int w, int h) = 0;
+    virtual void set_resizable(bool v) = 0;
+    virtual void set_always_on_top(bool v) = 0;
+    virtual void set_opacity(float v) = 0;
+    virtual void set_background(Color c) = 0;
+    virtual void set_cursor(CursorType c) = 0;
+
+    // ── Actions ──
+    virtual void show() = 0;
+    virtual void hide() = 0;
+    virtual void close() = 0;
+    virtual void focus() = 0;
+    virtual void minimize() = 0;
+    virtual void maximize() = 0;
+    virtual void restore() = 0;
+    virtual void fullscreen() = 0;
+    virtual void center() = 0;
+    virtual void request_repaint() = 0;
+
+    // ── Drag (for frameless windows) ──
+    virtual void start_drag() = 0;           // Begin window drag from current mouse pos
+    virtual void start_resize(HitTestRegion edge) = 0;
+
+    virtual WebView* webview() = 0;
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  Application — The singleton app controller
+// ═════════════════════════════════════════════════════════════════════════════
+
+class Application {
+public:
+    virtual ~Application() = default;
+
+    // ── Create / Access Windows ──
+    virtual Window* create_window(const WindowConfig& config) = 0;
+    virtual Window* get_window(const std::string& id) = 0;
+    virtual std::vector<Window*> all_windows() = 0;
+
+    // ── App Actions ──
+    virtual void run() = 0;                   // Enter main event loop (blocking)
+    virtual void quit() = 0;
+    virtual void set_tray(const TrayConfig& config) = 0;
+    virtual void remove_tray() = 0;
+
+    // ── System Info ──
+    virtual std::vector<MonitorInfo> monitors() = 0;
+    virtual MonitorInfo primary_monitor() = 0;
+
+    // ── Clipboard ──
+    virtual std::string clipboard_text() = 0;
+    virtual void set_clipboard_text(const std::string& text) = 0;
+
+    // ── Inter-Window Messaging ──
+    virtual void send_message(const std::string& window_id,
+                              const std::string& event,
+                              const std::string& payload = "") = 0;
+
+    using MessageHandler = std::function<void(const std::string& event,
+                                              const std::string& payload)>;
+    virtual void on_message(const std::string& window_id, MessageHandler handler) = 0;
+
+    // ── Timers ──
+    using TimerId = uint64_t;
+    virtual TimerId set_timeout(uint32_t ms, std::function<void()> callback) = 0;
+    virtual TimerId set_interval(uint32_t ms, std::function<void()> callback) = 0;
+    virtual void    clear_timer(TimerId id) = 0;
+
+    // ── Run on Main Thread (thread-safe) ──
+    virtual void dispatch(std::function<void()> fn) = 0;
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  Entry Point — The only function you call
+// ═════════════════════════════════════════════════════════════════════════════
+
+/// Creates the application singleton. Call once.
+std::unique_ptr<Application> create_app(const AppConfig& config);
+
+// ─── Path Utilities ──────────────────────────────────────────────────────────
+
+namespace paths {
+
+/// Returns the OS-standard application data directory for the given app name,
+/// creating it if it does not already exist.
+///
+///   Windows : %%APPDATA%%\\<app_name>       (C:\Users\...\AppData\Roaming\<app_name>)
+///   macOS   : ~/Library/Application Support/<app_name>
+///   Linux   : $XDG_DATA_HOME/<app_name>  or  ~/.local/share/<app_name>
+///
+/// Use this for config files, SQLite databases, and the WebView user data dir.
+std::string app_data_dir(const std::string& app_name);
+
+} // namespace paths
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  API Helpers — Convenience structs and free functions
+// ═════════════════════════════════════════════════════════════════════════════
+
+namespace api {
+
+struct AppInfo {
+    std::string name;
+    std::string version;
+    std::string identifier;
+};
+
+struct WindowInfo {
+    std::string id;
+    std::string title;
+    Size        size;
+    Point       position;
+    WindowState state;
+    bool        visible;
+    bool        focused;
+    float       scale_factor;
+};
+
+inline AppInfo app_info(const AppConfig& config) {
+    return AppInfo{config.name, config.version, config.identifier};
+}
+
+inline std::vector<MonitorInfo> monitors(Application& app) {
+    return app.monitors();
+}
+
+inline MonitorInfo primary_monitor(Application& app) {
+    return app.primary_monitor();
+}
+
+inline std::string clipboard_text(Application& app) {
+    return app.clipboard_text();
+}
+
+inline void set_clipboard_text(Application& app, const std::string& text) {
+    app.set_clipboard_text(text);
+}
+
+inline WindowInfo window_info(Window& window) {
+    return WindowInfo{
+        window.id(),
+        window.title(),
+        window.size(),
+        window.position(),
+        window.state(),
+        window.is_visible(),
+        window.is_focused(),
+        window.scale_factor(),
+    };
+}
+
+inline std::vector<WindowInfo> window_infos(Application& app) {
+    std::vector<WindowInfo> result;
+    for (auto* window : app.all_windows()) {
+        if (window) result.push_back(window_info(*window));
+    }
+    return result;
+}
+
+} // namespace api
+
+} // namespace wpp