|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Abstraction Layer - DWN Documentation</title>
|
|
<link rel="stylesheet" href="css/style.css">
|
|
</head>
|
|
<body>
|
|
<button class="mobile-menu-btn">Menu</button>
|
|
|
|
<div class="layout">
|
|
<aside class="sidebar">
|
|
<div class="sidebar-header">
|
|
<h1>DWN</h1>
|
|
<span class="version">v2.0.0</span>
|
|
</div>
|
|
|
|
<div class="search-box">
|
|
<input type="text" class="search-input" placeholder="Search docs...">
|
|
</div>
|
|
|
|
<nav class="sidebar-nav">
|
|
<div class="nav-section">
|
|
<div class="nav-section-title">Getting Started</div>
|
|
<a href="index.html" class="nav-link">Introduction</a>
|
|
<a href="installation.html" class="nav-link">Installation</a>
|
|
<a href="quickstart.html" class="nav-link">Quick Start</a>
|
|
</div>
|
|
|
|
<div class="nav-section">
|
|
<div class="nav-section-title">User Guide</div>
|
|
<a href="features.html" class="nav-link">Features</a>
|
|
<a href="shortcuts.html" class="nav-link">Keyboard Shortcuts</a>
|
|
<a href="configuration.html" class="nav-link">Configuration</a>
|
|
<a href="layouts.html" class="nav-link">Layouts</a>
|
|
<a href="ai-features.html" class="nav-link">AI Integration</a>
|
|
</div>
|
|
|
|
<div class="nav-section">
|
|
<div class="nav-section-title">API Reference</div>
|
|
<a href="api-overview.html" class="nav-link">API Overview</a>
|
|
<a href="api-reference.html" class="nav-link">API Reference</a>
|
|
<a href="api-examples.html" class="nav-link">API Examples</a>
|
|
</div>
|
|
|
|
<div class="nav-section">
|
|
<div class="nav-section-title">Advanced</div>
|
|
<a href="architecture.html" class="nav-link">Architecture</a>
|
|
<a href="abstraction-layer.html" class="nav-link active">Abstraction Layer</a>
|
|
<a href="plugin-development.html" class="nav-link">Plugin Development</a>
|
|
<a href="building.html" class="nav-link">Building from Source</a>
|
|
</div>
|
|
</nav>
|
|
</aside>
|
|
|
|
<main class="main-content">
|
|
<div class="content">
|
|
<div class="page-header">
|
|
<h1>Abstraction Layer</h1>
|
|
<p class="lead">Backend-agnostic architecture for future extensibility</p>
|
|
</div>
|
|
|
|
<div class="toc">
|
|
<div class="toc-title">On this page</div>
|
|
<ul class="toc-list">
|
|
<li><a href="#overview">Overview</a></li>
|
|
<li><a href="#core-types">Core Types</a></li>
|
|
<li><a href="#backend-interface">Backend Interface</a></li>
|
|
<li><a href="#client-abstraction">Client Abstraction</a></li>
|
|
<li><a href="#containers">Container Types</a></li>
|
|
<li><a href="#migration">Migration Strategy</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<h2 id="overview">Overview</h2>
|
|
<p>DWN v2.0 introduces a comprehensive abstraction layer that separates the window manager logic from backend-specific implementations. This architecture enables:</p>
|
|
|
|
<ul>
|
|
<li><strong>Backend Portability</strong> - Clean migration path from X11 to Wayland</li>
|
|
<li><strong>Type Safety</strong> - Strongly typed handles eliminate void* casting</li>
|
|
<li><strong>Memory Safety</strong> - Abstract strings and containers prevent buffer overflows</li>
|
|
<li><strong>Plugin Extensibility</strong> - Dynamic loading of layouts and widgets</li>
|
|
<li><strong>100% Compatibility</strong> - Existing code continues to work unchanged</li>
|
|
</ul>
|
|
|
|
<h2 id="core-types">Core Types</h2>
|
|
<p>The abstraction layer provides type-safe replacements for backend-specific types:</p>
|
|
|
|
<div class="table-container">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Abstract Type</th>
|
|
<th>X11 Equivalent</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>WmWindowHandle</code></td>
|
|
<td><code>Window</code></td>
|
|
<td>Opaque window reference</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>WmClientId</code></td>
|
|
<td>-</td>
|
|
<td>Unique client identifier</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>WmWorkspaceId</code></td>
|
|
<td><code>int</code></td>
|
|
<td>Workspace identifier</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>WmRect</code></td>
|
|
<td>-</td>
|
|
<td>Rectangle geometry (x, y, w, h)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>WmColor</code></td>
|
|
<td><code>unsigned long</code></td>
|
|
<td>RGBA color value</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h3>Geometry Operations</h3>
|
|
<p>Inline functions for rectangle operations:</p>
|
|
<div class="code-block">
|
|
<pre><code>WmRect rect = wm_rect_make(0, 0, 1920, 1080);
|
|
bool contains = wm_rect_contains_point(&rect, 100, 100);
|
|
bool intersects = wm_rect_intersects(&rect1, &rect2);
|
|
WmRect intersection = wm_rect_intersection(&rect1, &rect2);</code></pre>
|
|
</div>
|
|
|
|
<h3>Color Operations</h3>
|
|
<div class="code-block">
|
|
<pre><code>WmColor color = wm_color_rgb(255, 0, 128); // RGB
|
|
WmColor color = wm_color_rgba(255, 0, 128, 200); // RGBA
|
|
uint8_t r = wm_color_get_red(color);
|
|
uint8_t a = wm_color_get_alpha(color);</code></pre>
|
|
</div>
|
|
|
|
<h2 id="backend-interface">Backend Interface</h2>
|
|
<p>The backend interface defines a vtable of operations that any backend must implement:</p>
|
|
|
|
<div class="code-block">
|
|
<pre><code>typedef struct BackendInterface {
|
|
/* Identification */
|
|
const char *name;
|
|
WmBackendInfo (*get_info)(void);
|
|
|
|
/* Lifecycle */
|
|
bool (*init)(void *config);
|
|
void (*shutdown)(void);
|
|
|
|
/* Window Management */
|
|
void (*window_move)(WmWindowHandle window, int x, int y);
|
|
void (*window_resize)(WmWindowHandle window, int width, int height);
|
|
void (*window_focus)(WmWindowHandle window);
|
|
|
|
/* Events */
|
|
bool (*poll_event)(WmBackendEvent *event_out);
|
|
|
|
/* ... 80+ operations */
|
|
} BackendInterface;</code></pre>
|
|
</div>
|
|
|
|
<h3>X11 Backend</h3>
|
|
<p>The X11 backend is the reference implementation, translating abstract operations to X11 calls:</p>
|
|
<ul>
|
|
<li>Event translation (X11 → abstract events)</li>
|
|
<li>Protocol support (ICCCM, EWMH)</li>
|
|
<li>Property management with atom caching</li>
|
|
<li>Error handling with custom handlers</li>
|
|
</ul>
|
|
|
|
<h3>Future Backends</h3>
|
|
<p>The architecture supports multiple backends:</p>
|
|
<ul>
|
|
<li><strong>X11</strong> - Current, fully implemented</li>
|
|
<li><strong>Wayland</strong> - Planned for future</li>
|
|
<li><strong>Headless</strong> - For testing and CI</li>
|
|
</ul>
|
|
|
|
<h2 id="client-abstraction">Client Abstraction</h2>
|
|
<p>The <code>AbstractClient</code> type provides a backend-agnostic representation of a managed window:</p>
|
|
|
|
<div class="code-block">
|
|
<pre><code>/* Create from native window */
|
|
AbstractClient* client = wm_client_create(window, WM_CLIENT_TYPE_NORMAL);
|
|
|
|
/* State management */
|
|
wm_client_set_state(client, WM_CLIENT_STATE_FULLSCREEN);
|
|
wm_client_add_state(client, WM_CLIENT_STATE_FLOATING);
|
|
bool is_floating = wm_client_is_floating(client);
|
|
|
|
/* Geometry */
|
|
WmRect geom = wm_client_get_geometry(client);
|
|
wm_client_set_geometry(client, &new_geom);
|
|
wm_client_move_resize(client, x, y, width, height);
|
|
|
|
/* Properties */
|
|
wm_client_set_title(client, "New Title");
|
|
const char* title = wm_client_get_title(client);</code></pre>
|
|
</div>
|
|
|
|
<h3>Legacy Compatibility</h3>
|
|
<p>Abstract clients maintain bidirectional synchronization with legacy <code>Client</code> structures:</p>
|
|
<div class="code-block">
|
|
<pre><code>/* Wrap existing legacy client */
|
|
AbstractClient* abs_client = wm_client_from_legacy(legacy_client);
|
|
|
|
/* Access legacy client when needed */
|
|
Client* legacy = wm_client_get_legacy(abs_client);</code></pre>
|
|
</div>
|
|
|
|
<h2 id="containers">Container Types</h2>
|
|
<p>Safe, dynamic container implementations:</p>
|
|
|
|
<h3>WmString (Dynamic Strings)</h3>
|
|
<div class="code-block">
|
|
<pre><code>WmString* str = wm_string_new("Hello");
|
|
wm_string_append(str, " World");
|
|
wm_string_append_printf(str, " %d", 42);
|
|
|
|
const char* cstr = wm_string_cstr(str);
|
|
bool empty = wm_string_is_empty(str);
|
|
|
|
wm_string_destroy(str);</code></pre>
|
|
</div>
|
|
|
|
<h3>WmList (Dynamic Arrays)</h3>
|
|
<div class="code-block">
|
|
<pre><code>WmList* list = wm_list_new();
|
|
wm_list_append(list, item1);
|
|
wm_list_prepend(list, item2);
|
|
|
|
void* item = wm_list_get(list, 0);
|
|
wm_list_foreach(list, my_callback, user_data);
|
|
|
|
wm_list_destroy(list);</code></pre>
|
|
</div>
|
|
|
|
<h3>WmHashMap</h3>
|
|
<div class="code-block">
|
|
<pre><code>WmHashMap* map = wm_hashmap_new_string_key();
|
|
wm_hashmap_insert_string(map, "key", value);
|
|
|
|
void* value = wm_hashmap_get_string(map, "key");
|
|
bool exists = wm_hashmap_contains_string(map, "key");
|
|
|
|
wm_hashmap_destroy(map);</code></pre>
|
|
</div>
|
|
|
|
<h2 id="migration">Migration Strategy</h2>
|
|
<p>The abstraction layer uses an incremental migration approach:</p>
|
|
|
|
<ol>
|
|
<li><strong>Phase 1: Infrastructure</strong> (Complete)
|
|
<ul>
|
|
<li>Core types defined</li>
|
|
<li>Backend interface specified</li>
|
|
<li>X11 backend implemented</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Phase 2: Client Migration</strong> (Complete)
|
|
<ul>
|
|
<li>AbstractClient type created</li>
|
|
<li>Bidirectional sync with legacy Client</li>
|
|
<li>Client manager with MRU tracking</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Phase 3: Plugin System</strong> (Complete)
|
|
<ul>
|
|
<li>Layout plugin API</li>
|
|
<li>Widget plugin API</li>
|
|
<li>4 built-in layout plugins</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Phase 4: Future</strong>
|
|
<ul>
|
|
<li>Gradual migration of existing code</li>
|
|
<li>Wayland backend implementation</li>
|
|
<li>Legacy code deprecation (long-term)</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
|
|
<div class="alert alert-info">
|
|
<strong>Note:</strong> The abstraction layer is fully backward compatible. Existing code using X11 types continues to work unchanged.
|
|
</div>
|
|
|
|
<footer>
|
|
<p>DWN Window Manager - retoor <retoor@molodetz.nl></p>
|
|
</footer>
|
|
</div>
|
|
</main>
|
|
</div>
|
|
|
|
<script src="js/main.js"></script>
|
|
</body>
|
|
</html>
|