PlexyDesk - Display Server for GNU/Linux - User contributions [en-gb]

Main Page

2026-03-22T06:11:21Z

Plexydesk: Replace hero figcaption with full-width caption block

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">System overview</div>

== PlexyDesk technical documentation ==

<div class="pp-frontpage__hero">
[[File:Screenshot 2026-03-03 10-32-43.png|alt=shows plexydesk in use|900px|none]]
<div class="pp-frontpage__hero-caption">PlexyDesk screenshot</div>
</div>

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit. The project combines surface composition, shell-owned desktop components, rendering infrastructure, and client-side UI libraries in one integrated system.</p>

This wiki is the technical reference for PlexyDesk. It describes the compositor architecture, desktop shell behaviour, public toolkit APIs, source layout, and current implementation status. Use the section index below to navigate the main documentation areas.
</div>

<div class="pp-frontpage__story pp-frontpage__story--wide">
<div class="pp-frontpage__label">Section index</div>

== Main sections ==

<div class="pp-frontpage__section-grid">

<div>
=== Primary sections ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Documentation]]''' - top-level map of architecture notes, references, examples, and project pages.</li>
<li>'''[[Architecture]]''' - compositor, shell, client, and rendering model.</li>
<li>'''[[Development]]''' - engineering focus areas and implementation-oriented documentation hubs.</li>
<li>'''[[Components]]''' - subsystem survey and source tree structure.</li>
<li>'''[[News]]''' - project chronicle and milestone summaries.</li>
<li>'''[[Gallery]]''' - screenshots and short demo captures of PlexyDesk sessions.</li>
<li>'''[[Community]]''' - contribution and wiki participation guidance.</li>
</ul>
</div>

<div>
=== Reference pages ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Developer Guide]]''' - source orientation and implementation landmarks.</li>
<li>'''[[PlexyUI API]]''' - generated reference for the current UI toolkit headers.</li>
<li>'''[[Examples]]''' - sample programs and UI usage patterns.</li>
<li>'''[[Development Status]]''' - current implementation notes and subsystem coverage.</li>
<li>'''[[Getting Started]]''' - local runtime and setup notes.</li>
<li>'''[[Desktop Submissions]]''' - public procedure for uploading screenshots and listing desktops.</li>
</ul>
</div>

</div>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">What PlexyDesk is</div>

== System model ==

PlexyDesk combines several layers that are often documented separately: a compositor responsible for final output composition, a desktop shell responsible for system UI such as the dock and menubar, and client libraries that let applications render native interface surfaces.

Applications can render their own content and submit finished surfaces to the compositor. The shell composes those surfaces with desktop-owned elements, manages input routing, and applies the presentation rules that define the environment.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Feature areas</div>

== Implemented feature areas ==

<ul class="pp-frontpage__brief-list">
<li>GPU-accelerated composition of windows and desktop surfaces.</li>
<li>Shell-owned dock, menubar, wallpaper, and window framing.</li>
<li>Window movement, resizing, focus handling, transitions, and presentation effects.</li>
<li>Client-side UI toolkit components exposed through PlexyUI and related libraries.</li>
<li>Theme, scale, wallpaper, and appearance configuration.</li>
<li>Multi-display layout and desktop-space positioning support.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Technical entry points</div>

== Key references ==

<ul class="pp-frontpage__brief-list">
<li>Start with [[Architecture]] for the runtime model.</li>
<li>Use [[Components]] and [[Developer Guide]] for source orientation.</li>
<li>Use [[PlexyUI API]] for the current public UI interface surface.</li>
<li>Use [[Examples]] to inspect small application patterns.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Wiki interaction</div>

== Using this wiki ==

<ul class="pp-frontpage__brief-list">
<li>[[Special:AllPages]] provides the complete page index.</li>
<li>[[Special:RecentChanges]] shows the latest documentation edits.</li>
<li>[[Special:Upload]] accepts images and video for diagrams, screenshots, and demonstrations.</li>
<li>[[Gallery]] collects submitted screenshots and short demo captures.</li>
<li>[[Desktop Submissions]] explains how public users can contribute desktops.</li>
<li>Talk pages remain available for technical discussion and page review.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Current scope</div>

== Current documentation scope ==

The current wiki covers architecture, source structure, generated API reference, example programs, implementation status, and project record pages. It will continue to expand as more subsystem documentation is extracted directly from the codebase.
</div>

</div>

Main Page

2026-03-22T05:15:38Z

Plexydesk: Render front-page screenshot as an inline lead image

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">System overview</div>

== PlexyDesk technical documentation ==

<div class="pp-frontpage__hero">
[[File:Screenshot 2026-03-03 10-32-43.png|alt=shows plexydesk in use|900px|none|thumb|PlexyDesk screenshot]]
</div>

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit. The project combines surface composition, shell-owned desktop components, rendering infrastructure, and client-side UI libraries in one integrated system.</p>

This wiki is the technical reference for PlexyDesk. It describes the compositor architecture, desktop shell behaviour, public toolkit APIs, source layout, and current implementation status. Use the section index below to navigate the main documentation areas.
</div>

<div class="pp-frontpage__story pp-frontpage__story--wide">
<div class="pp-frontpage__label">Section index</div>

== Main sections ==

<div class="pp-frontpage__section-grid">

<div>
=== Primary sections ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Documentation]]''' - top-level map of architecture notes, references, examples, and project pages.</li>
<li>'''[[Architecture]]''' - compositor, shell, client, and rendering model.</li>
<li>'''[[Development]]''' - engineering focus areas and implementation-oriented documentation hubs.</li>
<li>'''[[Components]]''' - subsystem survey and source tree structure.</li>
<li>'''[[News]]''' - project chronicle and milestone summaries.</li>
<li>'''[[Gallery]]''' - screenshots and short demo captures of PlexyDesk sessions.</li>
<li>'''[[Community]]''' - contribution and wiki participation guidance.</li>
</ul>
</div>

<div>
=== Reference pages ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Developer Guide]]''' - source orientation and implementation landmarks.</li>
<li>'''[[PlexyUI API]]''' - generated reference for the current UI toolkit headers.</li>
<li>'''[[Examples]]''' - sample programs and UI usage patterns.</li>
<li>'''[[Development Status]]''' - current implementation notes and subsystem coverage.</li>
<li>'''[[Getting Started]]''' - local runtime and setup notes.</li>
<li>'''[[Desktop Submissions]]''' - public procedure for uploading screenshots and listing desktops.</li>
</ul>
</div>

</div>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">What PlexyDesk is</div>

== System model ==

PlexyDesk combines several layers that are often documented separately: a compositor responsible for final output composition, a desktop shell responsible for system UI such as the dock and menubar, and client libraries that let applications render native interface surfaces.

Applications can render their own content and submit finished surfaces to the compositor. The shell composes those surfaces with desktop-owned elements, manages input routing, and applies the presentation rules that define the environment.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Feature areas</div>

== Implemented feature areas ==

<ul class="pp-frontpage__brief-list">
<li>GPU-accelerated composition of windows and desktop surfaces.</li>
<li>Shell-owned dock, menubar, wallpaper, and window framing.</li>
<li>Window movement, resizing, focus handling, transitions, and presentation effects.</li>
<li>Client-side UI toolkit components exposed through PlexyUI and related libraries.</li>
<li>Theme, scale, wallpaper, and appearance configuration.</li>
<li>Multi-display layout and desktop-space positioning support.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Technical entry points</div>

== Key references ==

<ul class="pp-frontpage__brief-list">
<li>Start with [[Architecture]] for the runtime model.</li>
<li>Use [[Components]] and [[Developer Guide]] for source orientation.</li>
<li>Use [[PlexyUI API]] for the current public UI interface surface.</li>
<li>Use [[Examples]] to inspect small application patterns.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Wiki interaction</div>

== Using this wiki ==

<ul class="pp-frontpage__brief-list">
<li>[[Special:AllPages]] provides the complete page index.</li>
<li>[[Special:RecentChanges]] shows the latest documentation edits.</li>
<li>[[Special:Upload]] accepts images and video for diagrams, screenshots, and demonstrations.</li>
<li>[[Gallery]] collects submitted screenshots and short demo captures.</li>
<li>[[Desktop Submissions]] explains how public users can contribute desktops.</li>
<li>Talk pages remain available for technical discussion and page review.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Current scope</div>

== Current documentation scope ==

The current wiki covers architecture, source structure, generated API reference, example programs, implementation status, and project record pages. It will continue to expand as more subsystem documentation is extracted directly from the codebase.
</div>

</div>

Main Page

2026-03-22T05:14:38Z

Plexydesk: Place front-page screenshot inline beneath the title

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">System overview</div>

== PlexyDesk technical documentation ==

<div class="pp-frontpage__hero">
[[File:Screenshot 2026-03-03 10-32-43.png|alt=shows plexydesk in use|none|thumb|PlexyDesk screenshot]]
</div>

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit. The project combines surface composition, shell-owned desktop components, rendering infrastructure, and client-side UI libraries in one integrated system.</p>

This wiki is the technical reference for PlexyDesk. It describes the compositor architecture, desktop shell behaviour, public toolkit APIs, source layout, and current implementation status. Use the section index below to navigate the main documentation areas.
</div>

<div class="pp-frontpage__story pp-frontpage__story--wide">
<div class="pp-frontpage__label">Section index</div>

== Main sections ==

<div class="pp-frontpage__section-grid">

<div>
=== Primary sections ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Documentation]]''' - top-level map of architecture notes, references, examples, and project pages.</li>
<li>'''[[Architecture]]''' - compositor, shell, client, and rendering model.</li>
<li>'''[[Development]]''' - engineering focus areas and implementation-oriented documentation hubs.</li>
<li>'''[[Components]]''' - subsystem survey and source tree structure.</li>
<li>'''[[News]]''' - project chronicle and milestone summaries.</li>
<li>'''[[Gallery]]''' - screenshots and short demo captures of PlexyDesk sessions.</li>
<li>'''[[Community]]''' - contribution and wiki participation guidance.</li>
</ul>
</div>

<div>
=== Reference pages ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Developer Guide]]''' - source orientation and implementation landmarks.</li>
<li>'''[[PlexyUI API]]''' - generated reference for the current UI toolkit headers.</li>
<li>'''[[Examples]]''' - sample programs and UI usage patterns.</li>
<li>'''[[Development Status]]''' - current implementation notes and subsystem coverage.</li>
<li>'''[[Getting Started]]''' - local runtime and setup notes.</li>
<li>'''[[Desktop Submissions]]''' - public procedure for uploading screenshots and listing desktops.</li>
</ul>
</div>

</div>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">What PlexyDesk is</div>

== System model ==

PlexyDesk combines several layers that are often documented separately: a compositor responsible for final output composition, a desktop shell responsible for system UI such as the dock and menubar, and client libraries that let applications render native interface surfaces.

Applications can render their own content and submit finished surfaces to the compositor. The shell composes those surfaces with desktop-owned elements, manages input routing, and applies the presentation rules that define the environment.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Feature areas</div>

== Implemented feature areas ==

<ul class="pp-frontpage__brief-list">
<li>GPU-accelerated composition of windows and desktop surfaces.</li>
<li>Shell-owned dock, menubar, wallpaper, and window framing.</li>
<li>Window movement, resizing, focus handling, transitions, and presentation effects.</li>
<li>Client-side UI toolkit components exposed through PlexyUI and related libraries.</li>
<li>Theme, scale, wallpaper, and appearance configuration.</li>
<li>Multi-display layout and desktop-space positioning support.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Technical entry points</div>

== Key references ==

<ul class="pp-frontpage__brief-list">
<li>Start with [[Architecture]] for the runtime model.</li>
<li>Use [[Components]] and [[Developer Guide]] for source orientation.</li>
<li>Use [[PlexyUI API]] for the current public UI interface surface.</li>
<li>Use [[Examples]] to inspect small application patterns.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Wiki interaction</div>

== Using this wiki ==

<ul class="pp-frontpage__brief-list">
<li>[[Special:AllPages]] provides the complete page index.</li>
<li>[[Special:RecentChanges]] shows the latest documentation edits.</li>
<li>[[Special:Upload]] accepts images and video for diagrams, screenshots, and demonstrations.</li>
<li>[[Gallery]] collects submitted screenshots and short demo captures.</li>
<li>[[Desktop Submissions]] explains how public users can contribute desktops.</li>
<li>Talk pages remain available for technical discussion and page review.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Current scope</div>

== Current documentation scope ==

The current wiki covers architecture, source structure, generated API reference, example programs, implementation status, and project record pages. It will continue to expand as more subsystem documentation is extracted directly from the codebase.
</div>

</div>

Main Page

2026-03-22T04:53:49Z

Plexydesk: Add gallery and submission links to main page

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">System overview</div>

== PlexyDesk technical documentation ==

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit. The project combines surface composition, shell-owned desktop components, rendering infrastructure, and client-side UI libraries in one integrated system.</p>

This wiki is the technical reference for PlexyDesk. It describes the compositor architecture, desktop shell behaviour, public toolkit APIs, source layout, and current implementation status. Use the section index below to navigate the main documentation areas.
</div>

<div class="pp-frontpage__story pp-frontpage__story--wide">
<div class="pp-frontpage__label">Section index</div>

== Main sections ==

<div class="pp-frontpage__section-grid">

<div>
=== Primary sections ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Documentation]]''' - top-level map of architecture notes, references, examples, and project pages.</li>
<li>'''[[Architecture]]''' - compositor, shell, client, and rendering model.</li>
<li>'''[[Development]]''' - engineering focus areas and implementation-oriented documentation hubs.</li>
<li>'''[[Components]]''' - subsystem survey and source tree structure.</li>
<li>'''[[News]]''' - project chronicle and milestone summaries.</li>
<li>'''[[Gallery]]''' - screenshots and short demo captures of PlexyDesk sessions.</li>
<li>'''[[Community]]''' - contribution and wiki participation guidance.</li>
</ul>
</div>

<div>
=== Reference pages ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Developer Guide]]''' - source orientation and implementation landmarks.</li>
<li>'''[[PlexyUI API]]''' - generated reference for the current UI toolkit headers.</li>
<li>'''[[Examples]]''' - sample programs and UI usage patterns.</li>
<li>'''[[Development Status]]''' - current implementation notes and subsystem coverage.</li>
<li>'''[[Getting Started]]''' - local runtime and setup notes.</li>
<li>'''[[Desktop Submissions]]''' - public procedure for uploading screenshots and listing desktops.</li>
</ul>
</div>

</div>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">What PlexyDesk is</div>

== System model ==

PlexyDesk combines several layers that are often documented separately: a compositor responsible for final output composition, a desktop shell responsible for system UI such as the dock and menubar, and client libraries that let applications render native interface surfaces.

Applications can render their own content and submit finished surfaces to the compositor. The shell composes those surfaces with desktop-owned elements, manages input routing, and applies the presentation rules that define the environment.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Feature areas</div>

== Implemented feature areas ==

<ul class="pp-frontpage__brief-list">
<li>GPU-accelerated composition of windows and desktop surfaces.</li>
<li>Shell-owned dock, menubar, wallpaper, and window framing.</li>
<li>Window movement, resizing, focus handling, transitions, and presentation effects.</li>
<li>Client-side UI toolkit components exposed through PlexyUI and related libraries.</li>
<li>Theme, scale, wallpaper, and appearance configuration.</li>
<li>Multi-display layout and desktop-space positioning support.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Technical entry points</div>

== Key references ==

<ul class="pp-frontpage__brief-list">
<li>Start with [[Architecture]] for the runtime model.</li>
<li>Use [[Components]] and [[Developer Guide]] for source orientation.</li>
<li>Use [[PlexyUI API]] for the current public UI interface surface.</li>
<li>Use [[Examples]] to inspect small application patterns.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Wiki interaction</div>

== Using this wiki ==

<ul class="pp-frontpage__brief-list">
<li>[[Special:AllPages]] provides the complete page index.</li>
<li>[[Special:RecentChanges]] shows the latest documentation edits.</li>
<li>[[Special:Upload]] accepts images and video for diagrams, screenshots, and demonstrations.</li>
<li>[[Gallery]] collects submitted screenshots and short demo captures.</li>
<li>[[Desktop Submissions]] explains how public users can contribute desktops.</li>
<li>Talk pages remain available for technical discussion and page review.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Current scope</div>

== Current documentation scope ==

The current wiki covers architecture, source structure, generated API reference, example programs, implementation status, and project record pages. It will continue to expand as more subsystem documentation is extracted directly from the codebase.
</div>

</div>

Desktop Submissions

2026-03-22T04:53:48Z

Plexydesk: Add public desktop submission guide

= Desktop Submissions =

'''Desktop Submissions''' explains how public contributors can add screenshots or short demo captures of PlexyDesk to the wiki gallery.

== 1. Sign in ==
Create or sign in to a wiki account before uploading files or editing gallery pages.

== 2. Capture the desktop ==
Prepare a screenshot or short video that clearly shows PlexyDesk in use.

Preferred media:
* PNG or JPEG for still images
* WebM or MP4 for short demo captures

Before uploading, remove private data such as personal files, tokens, chat windows, or unrelated desktop content.

== 3. Upload the file ==
Open [[Special:Upload]] and provide:
* the media file
* a clear filename, preferably in a form such as <code>PlexyDesk-username-topic.png</code>
* a summary describing what the capture shows

If the file represents a specific branch, build, or experiment, include that in the upload summary.

== 4. Add the file to [[Gallery]] ==
After the upload finishes, edit [[Gallery]] and add one line inside the <code><gallery></code> block:

<pre>
File:PlexyDesk-username-topic.png|Short technical caption — branch or build; scale factor; visible shell components
</pre>

== 5. Write a useful caption ==
A good caption should include:
* branch, version, or build context when known
* what part of PlexyDesk is being shown
* whether the capture highlights shell layout, compositor behaviour, toolkit widgets, or an application
* any display-scale or multi-monitor detail that matters to interpretation

== Submission rules ==
* submit only media directly related to PlexyDesk
* use technical wording rather than promotional wording
* keep video clips short and focused on one visible behaviour
* do not upload copyrighted material you do not have the right to share
* do not upload media containing credentials, personal information, or unrelated private content

== Related pages ==
* [[Gallery]]
* [[Special:Upload]]
* [[Community]]

Gallery

2026-03-22T04:53:47Z

Plexydesk: Add screenshot gallery page

= Gallery =

'''Gallery''' indexes screenshots and short demo captures of PlexyDesk sessions. Use it to document compositor behaviour, shell layout, visual changes, and application integration with the desktop.

== Scope ==
This page is intended for:
* full desktop screenshots
* focused captures of the dock, menubar, windows, or toolkit behaviour
* short demo videos that show visible runtime behaviour

== Community submissions ==
No desktop captures have been listed yet.

After uploading media through [[Special:Upload]], add it to the gallery block below by following [[Desktop Submissions]].

<gallery mode="packed" heights="220">

</gallery>

== Caption guidance ==
Each gallery entry should describe:
* the branch, build, or relevant code state if known
* the visible shell or toolkit features shown in the capture
* display scale, monitor layout, or theme details when they matter
* the specific behaviour the screenshot or video is meant to document

== Related pages ==
* [[Desktop Submissions]]
* [[Special:Upload]]
* [[Community]]

Community

2026-03-22T04:53:47Z

Plexydesk: Rewrite community hub in technical style

= Community =

'''Community''' describes how contributors can use this wiki as a shared technical record for PlexyDesk.

== Contribution paths ==
* improve architecture, component, and API reference pages when behaviour becomes clearer
* add diagrams, screenshots, and short demo media that document actual runtime behaviour
* correct source-oriented pages when code structure or exposed interfaces change
* use article talk pages to discuss wording, missing details, or technical accuracy

== Media contributions ==
* [[Gallery]] is the public index for screenshots and short demo captures
* [[Desktop Submissions]] explains how to prepare, upload, and list desktop screenshots
* [[Special:Upload]] is the upload entry point for image and video files

== Useful pages ==
* [[Documentation]] for the main documentation map
* [[Special:RecentChanges]] for a live view of current edits
* [[Special:AllPages]] for the full page index
* [[News]] for milestone summaries and documentation updates

== Content conventions ==
Pages should use technical language, avoid marketing claims, and stay close to what the codebase and runtime actually support. Captions, summaries, and page text should explain behaviour precisely enough to be useful to both contributors and readers.

News

2026-03-22T04:53:46Z

Plexydesk: Rewrite news hub in technical style

= News =

'''News''' records high-level project changes that affect how PlexyDesk is understood, evaluated, or documented. It should summarize milestones, visible feature additions, and major documentation changes in concise technical terms.

== Current status summary ==
* PlexyDesk includes a functioning compositor shell with integrated dock and menubar components.
* The runtime supports shell-owned composition, visual presentation, and client-submitted surfaces.
* Public toolkit headers are documented through the generated [[PlexyUI API]] reference.
* The wiki now includes architectural, subsystem, example, gallery, and contribution pages intended to track the codebase.

== Tracking pages ==
* [[Development Status]] for implementation notes and subsystem coverage
* [[Development]] for engineering-facing references
* [[Special:RecentChanges]] for the latest wiki edits
* [[Gallery]] for visual captures of running PlexyDesk sessions
* [[PlexyUI API]] for source-backed toolkit reference

== Intended use ==
This page should be used for milestone summaries, major visible changes, documentation expansions, and other high-level updates that are useful to readers who need a compact view of project progress.

Components

2026-03-22T04:53:45Z

Plexydesk: Rewrite components hub in technical style

= Components =

'''Components''' maps the major building blocks of PlexyDesk and the role each one plays in the runtime.

== System layers ==
{| class="wikitable"
|-
! Layer
! Role in the desktop
|-
| Applications
| Create windows, controls, text, panels, lists, and other interface content
|-
| PlexyDesk client libraries
| Help applications describe UI, render it locally, and submit finished surfaces
|-
| PlexyDesk compositor and shell
| Combine application surfaces with shell elements such as the dock, menubar, wallpaper, chrome, and transitions
|}

== Source tree map ==
{| class="wikitable"
|-
! Path
! Component area
! Responsibility
|-
| <code>src/</code>
| Compositor and shell runtime
| Output composition, window presentation, backend integration, input routing, and shell-owned desktop behaviour
|-
| <code>lib/</code>
| Client support libraries
| Application-facing runtime helpers, event loop code, and support functionality used by PlexyDesk clients
|-
| <code>include/plexy/</code>
| Public headers
| Exposed interface definitions for client code, including the current PlexyUI surface
|-
| <code>examples/</code>
| Reference examples
| Small programs that demonstrate application patterns and toolkit usage
|-
| <code>apps/</code>
| Application experiments
| Larger programs used to exercise the desktop, shell integration, and UI stack
|-
| <code>tasks/</code>
| Engineering notes
| Design notes, implementation summaries, and optimisation work
|}

== Related pages ==
* [[Architecture]]
* [[Developer Guide]]
* [[PlexyUI API]]
* [[Development]]

Development

2026-03-22T04:53:45Z

Plexydesk: Rewrite development hub in technical style

= Development =

'''Development''' indexes the engineering-facing material for PlexyDesk. Use this page to identify active work areas, the source directories that implement them, and the reference pages that should be consulted during development.

== Current engineering themes ==
Current work is centred on making the compositor, shell, and client toolkit operate as one coherent runtime. The main areas are:

* compositor and surface management behaviour
* shell-owned desktop UI such as the dock, menubar, wallpaper, and chrome
* renderer behaviour, materials, and presentation consistency
* client toolkit growth and public API clarity
* source-backed documentation and examples that track the codebase closely

== Source map ==
{| class="wikitable"
|-
! Area
! Why it matters
|-
| <code>src/</code>
| Core compositor, backend, renderer, protocol, input, and shell implementation
|-
| <code>lib/</code>
| Client-side support libraries and event loop code used by applications
|-
| <code>include/plexy/</code>
| Public API headers, including the current PlexyUI interface surface
|-
| <code>examples/</code>
| Small reference programs that demonstrate application patterns
|-
| <code>apps/</code>
| Application experiments that exercise the runtime and UI toolkit
|-
| <code>tasks/</code>
| Engineering notes, implementation summaries, and optimisation work
|}

== Working references ==
* [[Architecture]] for the runtime model and subsystem responsibilities
* [[Developer Guide]] for a guided source-tree tour
* [[PlexyUI API]] for the current toolkit interface surface
* [[Examples]] for small application patterns
* [[Development Status]] for implementation notes and current project state

Documentation

2026-03-22T04:53:44Z

Plexydesk: Rewrite documentation hub in technical style

= Documentation =

'''Documentation''' is the top-level index for PlexyDesk technical material. It links to the pages that describe runtime architecture, subsystem boundaries, source layout, public APIs, and reference media.

== System documentation ==
* [[Architecture]] - compositor, shell, client-surface, and rendering model
* [[Components]] - subsystem survey and source tree map
* [[Developer Guide]] - implementation landmarks and source orientation
* [[Development]] - current engineering areas and working references
* [[Development Status]] - implementation coverage and subsystem notes

== API and reference material ==
* [[PlexyUI API]] - generated reference derived from the current UI toolkit headers
* [[Examples]] - sample programs and UI usage patterns
* [[Getting Started]] - local runtime and setup notes

== Media and community resources ==
* [[Gallery]] - screenshots and short demo captures of PlexyDesk sessions
* [[Desktop Submissions]] - public procedure for uploading and listing desktop captures
* [[Community]] - contribution workflow and content conventions
* [[News]] - milestone and documentation record

MediaWiki:Sidebar

2026-03-22T04:53:42Z

Plexydesk: Add gallery and submission links to sidebar

Main Page

2026-03-22T04:46:12Z

Plexydesk: Rework main page into technical section index

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">System overview</div>

== PlexyDesk technical documentation ==

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit. The project combines surface composition, shell-owned desktop components, rendering infrastructure, and client-side UI libraries in one integrated system.</p>

This wiki is the technical reference for PlexyDesk. It describes the compositor architecture, desktop shell behaviour, public toolkit APIs, source layout, and current implementation status. Use the section index below to navigate the main documentation areas.
</div>

<div class="pp-frontpage__story pp-frontpage__story--wide">
<div class="pp-frontpage__label">Section index</div>

== Main sections ==

<div class="pp-frontpage__section-grid">

<div>
=== Primary sections ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Documentation]]''' - top-level map of architecture notes, references, examples, and project pages.</li>
<li>'''[[Architecture]]''' - compositor, shell, client, and rendering model.</li>
<li>'''[[Development]]''' - engineering focus areas and implementation-oriented documentation hubs.</li>
<li>'''[[Components]]''' - subsystem survey and source tree structure.</li>
<li>'''[[News]]''' - project chronicle and milestone summaries.</li>
<li>'''[[Community]]''' - contribution and wiki participation guidance.</li>
</ul>
</div>

<div>
=== Reference pages ===
<ul class="pp-frontpage__brief-list">
<li>'''[[Developer Guide]]''' - source orientation and implementation landmarks.</li>
<li>'''[[PlexyUI API]]''' - generated reference for the current UI toolkit headers.</li>
<li>'''[[Examples]]''' - sample programs and UI usage patterns.</li>
<li>'''[[Development Status]]''' - current implementation notes and subsystem coverage.</li>
<li>'''[[Getting Started]]''' - local runtime and setup notes.</li>
</ul>
</div>

</div>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">What PlexyDesk is</div>

== System model ==

PlexyDesk combines several layers that are often documented separately: a compositor responsible for final output composition, a desktop shell responsible for system UI such as the dock and menubar, and client libraries that let applications render native interface surfaces.

Applications can render their own content and submit finished surfaces to the compositor. The shell composes those surfaces with desktop-owned elements, manages input routing, and applies the presentation rules that define the environment.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Feature areas</div>

== Implemented feature areas ==

<ul class="pp-frontpage__brief-list">
<li>GPU-accelerated composition of windows and desktop surfaces.</li>
<li>Shell-owned dock, menubar, wallpaper, and window framing.</li>
<li>Window movement, resizing, focus handling, transitions, and presentation effects.</li>
<li>Client-side UI toolkit components exposed through PlexyUI and related libraries.</li>
<li>Theme, scale, wallpaper, and appearance configuration.</li>
<li>Multi-display layout and desktop-space positioning support.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Technical entry points</div>

== Key references ==

<ul class="pp-frontpage__brief-list">
<li>Start with [[Architecture]] for the runtime model.</li>
<li>Use [[Components]] and [[Developer Guide]] for source orientation.</li>
<li>Use [[PlexyUI API]] for the current public UI interface surface.</li>
<li>Use [[Examples]] to inspect small application patterns.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Wiki interaction</div>

== Using this wiki ==

<ul class="pp-frontpage__brief-list">
<li>[[Special:AllPages]] provides the complete page index.</li>
<li>[[Special:RecentChanges]] shows the latest documentation edits.</li>
<li>[[Special:Upload]] accepts images and video for diagrams, screenshots, and demonstrations.</li>
<li>Talk pages remain available for technical discussion and page review.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Current scope</div>

== Current documentation scope ==

The current wiki covers architecture, source structure, generated API reference, example programs, implementation status, and project record pages. It will continue to expand as more subsystem documentation is extracted directly from the codebase.
</div>

</div>

Community

2026-03-21T21:36:33Z

Plexydesk: Add community and editorial guidance page

= Community =

'''Community''' describes how people can use this wiki as a shared editorial and technical record for PlexyDesk.

== Ways to contribute ==
* improve explanatory pages when architecture or behaviour becomes clearer
* upload screenshots, diagrams, icons, and short videos that help explain the desktop
* use article talk pages to discuss wording, structure, and missing references
* keep source-backed technical pages aligned with the code and the generated API reference

== Useful places around the site ==
* [[Special:Upload]] for images and video
* [[Special:RecentChanges]] for a live view of ongoing edits
* [[Special:AllPages]] for the full page index
* [[Documentation]] for the main reading map
* [[News]] for the current project chronicle

== Editorial direction ==
This wiki is meant to feel like a serious technical publication. Pages should explain the system clearly, avoid inflated claims, and stay close to what the source tree and runtime actually support. The goal is a record that is readable to newcomers and still useful to engineers.

News

2026-03-21T21:36:33Z

Plexydesk: Add project chronicle page

= News =

'''News''' is the public chronicle for the PlexyDesk project. It is less about marketing announcements and more about keeping a readable record of what the system already is, what areas are actively being refined, and where readers should look next.

== Current headlines ==
* PlexyDesk already presents a functioning compositor shell with its own dock and menubar.
* The rendering path supports a visually rich desktop with shell-owned presentation and effects.
* The project includes a native application toolkit so programs can look and behave like part of the same environment.
* Documentation is being expanded into a permanent project publication, with architecture notes, component surveys, and generated API reference pages.

== Where to follow the project ==
* [[Development Status]] for implementation notes and current subsystem coverage
* [[Development]] for the engineering hub
* [[Special:RecentChanges]] for the latest edits on this wiki
* [[PlexyUI API]] for source-backed toolkit reference

== Why this page exists ==
The purpose of this page is to give PlexyDesk a chronicle that reads clearly to new visitors while staying grounded in the work already represented elsewhere in the wiki. As the publication grows, this page can carry milestone summaries, notable additions, and high-level editorial notes.

Components

2026-03-21T21:36:32Z

Plexydesk: Add component survey page

= Components =

'''Components''' surveys the major building blocks of PlexyDesk and the role each one plays in the overall desktop.

== System layers ==
{| class="wikitable"
|-
! Layer
! Role in the desktop
|-
| Applications
| Create windows, controls, text, panels, lists, and other interface content
|-
| PlexyDesk client libraries
| Help applications describe UI, render it locally, and submit finished surfaces
|-
| PlexyDesk compositor and shell
| Combine application surfaces with shell elements such as the dock, menubar, wallpaper, chrome, and transitions
|}

== Source tree components ==
=== Compositor and shell runtime ===
The runtime lives primarily under <code>src/</code>. This is where window presentation, rendering, shell behaviour, backend integration, and input flow are managed.

=== Client libraries ===
The supporting libraries under <code>lib/</code> provide application-facing helpers so client programs can participate in the PlexyDesk environment without duplicating shell responsibilities.

=== Public interface headers ===
The public headers under <code>include/plexy/</code> define the interface surface exposed to clients. The most visible reference is [[PlexyUI API]].

=== Examples and applications ===
The <code>examples/</code> and <code>apps/</code> directories show how the runtime and toolkit are exercised in practice, from small UI samples to larger application experiments.

== Further reading ==
* [[Architecture]]
* [[Developer Guide]]
* [[Examples]]
* [[Development]]

MediaWiki:Wiki-tools

2026-03-21T21:36:32Z

Plexydesk: Rename editorial site tools section

Site Tools

Development

2026-03-21T21:36:31Z

Plexydesk: Add development hub page

= Development =

'''Development''' collects the engineering view of PlexyDesk: what areas are active, where the important subsystems live, and which reference pages should be consulted while the project evolves.

== Current engineering themes ==
PlexyDesk development is focused on making the compositor, shell, and toolkit behave like one deliberate desktop environment. That means work tends to concentrate on:

* compositor and surface management behaviour
* shell-owned UI such as the dock, menubar, and window framing
* renderer and visual effect consistency
* growth and clarification of the PlexyUI toolkit
* source-backed documentation that stays close to the code

== Source map ==
{| class="wikitable"
|-
! Area
! Why it matters
|-
| <code>src/</code>
| Core compositor, backend, renderer, protocol, input, and shell implementation
|-
| <code>lib/</code>
| Client-side support libraries and event loop code used by applications
|-
| <code>include/plexy/</code>
| Public API headers, including the current PlexyUI interface surface
|-
| <code>examples/</code>
| Small reference programs that demonstrate application patterns
|-
| <code>apps/</code>
| Application experiments that exercise the runtime and UI toolkit
|-
| <code>tasks/</code>
| Engineering notes, implementation summaries, and optimisation work
|}

== Development references ==
* [[Development Status]] for the current implementation record
* [[Developer Guide]] for a guided source-tree tour
* [[PlexyUI API]] for the toolkit API reference
* [[Architecture]] for the system-level design picture
* [[News]] for the public-facing chronicle of progress

MediaWiki:Plexydesk-nav

2026-03-21T21:36:31Z

Plexydesk: Rename editorial reference section

Reference Desk

Documentation

2026-03-21T21:36:31Z

Plexydesk: Add editorial documentation hub

= Documentation =

'''Documentation''' is the central index for the PlexyDesk publication. It points to the pages that explain how the desktop is structured, how the source tree is arranged, and where the current API reference lives.

== Core reading ==
* [[Architecture]] - a technical explanation of how the compositor, shell, and client stack fit together
* [[Components]] - a survey of the major subsystems and directories that make up the project
* [[Developer Guide]] - a guide to the main source areas and implementation landmarks

== Practical references ==
* [[PlexyUI API]] - generated reference for the current PlexyUI surface
* [[Examples]] - small programs and UI samples that show how PlexyDesk applications are assembled
* [[Getting Started]] - current environment and setup notes for running or exploring the project locally

== Project record ==
* [[Development]] - the working hub for engineering direction and subsystem notes
* [[Development Status]] - implementation coverage and current project shape
* [[News]] - the project chronicle and headline summary
* [[Community]] - editorial, contribution, and wiki participation pointers

Main Page

2026-03-21T21:36:30Z

Plexydesk: Refresh main page for PlexyPress editorial layout

__NOTOC__
__NOEDITSECTION__

<div class="pp-frontpage">

<div class="pp-frontpage__lead">
<div class="pp-frontpage__label">Lead article</div>

== The PlexyDesk desktop as one coherent system ==

<p class="pp-frontpage__deck">PlexyDesk is a Linux display server, compositor, desktop shell, and application toolkit built to present the desktop as one connected system. It is concerned with how windows move, how the dock and menubar behave, how widgets are drawn, and how applications participate in the same visual language.</p>

PlexyDesk does not stop at arranging windows on screen. It draws the shell itself, manages presentation and effects, and offers native client libraries so applications can feel like part of the environment rather than separate guests inside it.

* [[Architecture|Read the architecture briefing]]
* [[Documentation|Open the documentation desk]]
* [[Components|Browse the component index]]
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Architecture spotlight</div>

== Compositor, shell, and toolkit ==

The system is organised around a compositor that combines application surfaces with desktop-owned elements such as the dock, the menubar, wallpaper, window frames, and transitions. Client libraries help applications render their own interface and submit finished surfaces to the shell, keeping responsibilities clear while preserving a consistent desktop identity.

See [[Architecture]] for the full technical model, or jump to [[PlexyUI API]] for the current toolkit surface.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Project features</div>

== What the desktop already supports ==

<ul class="pp-frontpage__brief-list">
<li>GPU-driven window composition and desktop rendering.</li>
<li>Integrated dock and menubar owned by the shell.</li>
<li>Window movement, resize handling, depth styling, and smooth surface presentation.</li>
<li>Native UI controls through PlexyUI, including text, panels, lists, sliders, and drawers.</li>
<li>Wallpaper, theme, scale, and appearance configuration.</li>
<li>Multi-display layout awareness and desktop-space positioning.</li>
</ul>
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Reference desk</div>

== Essential reading ==

* [[Documentation]] for the main documentation map
* [[Developer Guide]] for source tree orientation
* [[Examples]] for small application and UI samples
* [[Development Status]] for engineering notes and implementation coverage
* [[Getting Started]] for the current environment and setup notes
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Shell components</div>

== Major building blocks ==

PlexyDesk is made up of several layers that cooperate closely: compositor and backend code in <code>src/</code>, client-facing libraries in <code>lib/</code>, public headers in <code>include/plexy/</code>, example programs in <code>examples/</code>, and application experiments in <code>apps/</code>. Each layer exists to explain one part of the system rather than hide it.

The [[Components]] page gives a structured survey of the main areas and why they matter.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Development notes</div>

== What the project is refining ==

Current work is centred on stabilising compositor behaviour, expanding the UI toolkit, clarifying subsystem boundaries, and documenting APIs in a way that stays close to the source tree. The generated [[PlexyUI API]] reference and the living [[Development]] hub are intended to keep the publication aligned with the code.
</div>

<div class="pp-frontpage__story">
<div class="pp-frontpage__label">Community and record</div>

== A working journal for the project ==

This wiki is meant to read like a publication, but it also acts as the project record: pages can be edited collaboratively, images and videos can be uploaded to illustrate work, and talk pages remain available for discussion. Visit [[Community]] for editorial and collaboration pointers, or [[News]] for the project chronicle.
</div>

</div>

MediaWiki:Sidebar

2026-03-21T21:36:29Z

Plexydesk: Update PlexyPress navigation

Developer Guide

2026-03-21T19:54:03Z

Plexydesk: Link generated PlexyUI API reference

= Developer Guide =

This page is a practical map for engineers who want to read or modify the PlexyDesk source tree.

== Read these first ==
* <code>tasks/README.md</code> - current work areas and implementation notes
* <code>install-deps.sh</code> - the fastest view of build and system dependencies
* <code>Makefile</code> - build modes, active runtime entry points, and source grouping
* <code>include/plexy/plexy_ui.h</code> - public client API
* [[PlexyUI API]] - generated reference page built directly from <code>include/plexy/plexy_ui.h</code>
* <code>examples/hello_uikit.c</code> - smallest useful UI example
* <code>docker/README.md</code> - package build workflow
* <code>plexyshell.conf.example</code> - runtime configuration surface

== Key source areas ==
{| class="wikitable"
|-
! Path
! What you will find there
|-
| <code>src/renderer/</code>
| Compositing, window effects, dock, menubar, shaders, async renderer, and GPU configuration
|-
| <code>src/backend/</code>
| DRM, X11-related display backend code, session management, and display backend selection
|-
| <code>src/input/</code>
| libinput integration, focus policy, and input coordination
|-
| <code>src/core/</code>
| Shell runtime, event loop, dock manager, drag/resize state, and display layout state
|-
| <code>src/server/</code>
| Compositor-side protocol server
|-
| <code>src/wayland/</code>
| Wayland bridge and XWM interoperability work
|-
| <code>src/canvas/</code>
| Canvas rendering, text, layout, styling, and animation support
|-
| <code>lib/</code>
| Client-side event loop and protocol support
|}

== Build workflow ==
Standard release build:

<pre>
make
</pre>

Verbose debug build:

<pre>
BUILD_MODE=debug make
</pre>

The Makefile groups sources by subsystem and applies different compiler and logging flags for debug versus release mode. Release builds enable aggressive optimization and link-time optimization.

== Public client API ==
The main client-facing API lives in <code>include/plexy/plexy_ui.h</code>. It covers:
* application and window lifecycle
* widget creation
* layout primitives such as row, column, justify, align, padding, and gap
* state changes such as visibility, text, value, and enabled state
* styling helpers such as corner radius, fill color, elevation, and glass material
* event hooks for clicks, values, text changes, keys, and menus

== Example-driven learning ==
The best small files to read early are:
* <code>examples/hello_uikit.c</code>
* <code>examples/canvas_demo.c</code>
* <code>examples/drawer_demo.c</code>
* <code>examples/settings_panel.c</code>
* <code>examples/showcase_demo.c</code>

== Applications and experiments ==
The <code>apps/</code> directory includes larger experiments such as:
* <code>plexy_term</code>
* <code>plexy_browser</code>
* <code>plexy_clock</code>
* <code>fileman</code>
* <code>pcalc</code>
* <code>vim</code>

== Packaging and service helpers ==
* <code>docker/README.md</code> explains the Ubuntu Docker package flow
* <code>scripts/systemd/</code> contains the user slice, service, installer, starter, and status helpers

== Good follow-up pages ==
* [[Architecture]]
* [[Getting Started]]
* [[Examples]]
* [[Development Status]]

Main Page

2026-03-21T19:54:03Z

Plexydesk: Link PlexyUI API reference from front page

__NOTOC__
= PlexyDesk =

'''PlexyDesk''' is a display server and desktop shell for Linux built around a modern, GPU-driven user interface. It is responsible for drawing the desktop itself, placing application windows on screen, rendering the dock and the menubar, handling animation and visual effects, and presenting a consistent UI toolkit for PlexyDesk applications.

{| class="wikitable"
|+ PlexyDesk at a glance
|-
! Focus
| GPU-accelerated compositor and desktop shell for Linux
|-
! Runtime
| <code>plexyshell</code>
|-
! Client stack
| <code>libplexy</code>, <code>libplexycanvas</code>, <code>libplexyui</code>
|-
! License
| AGPL-3.0-only
|}

== What PlexyDesk does ==
PlexyDesk combines three responsibilities into one system:
* it acts as the display server that decides what appears on screen
* it acts as the desktop shell that draws the dock, menubar, background, and window chrome
* it provides application-facing libraries so apps can create native PlexyDesk windows and controls

In practical terms, PlexyDesk is the part of the desktop that gives applications a place to live, gives windows their shape and motion, and gives the overall environment its visual identity.

== Architecture in plain language ==
PlexyDesk is organised around three main layers:

{| class="wikitable"
|-
! Layer
! What it is responsible for
|-
| Applications
| Programs create windows, text, buttons, panels, lists, drawers, and other interface elements
|-
| PlexyDesk client libraries
| The libraries help apps describe their UI, render it locally, and send finished frames to the display server
|-
| PlexyDesk compositor and shell
| The compositor places windows on screen, draws the desktop shell, applies visual effects, handles input routing, and presents the final image
|}

Instead of asking the shell to draw every application widget for them, PlexyDesk applications can render their own interface locally and then hand the finished frame to the compositor. The compositor then combines those application surfaces with system elements such as the dock, menubar, background, window chrome, and transitions. This keeps the shell visually consistent while still allowing applications to manage their own content.

== Supported desktop features ==
=== Window presentation and motion ===
PlexyDesk provides its own window chrome and visual framing. Windows are not treated as plain rectangles with static borders; they are part of the shell experience. The compositor supports:
* animated window movement
* resize handling
* window shadows and depth styling
* rounded corners and smooth surface edges
* minimise and transition effects
* focus-aware rendering and presentation

=== Dock and menubar ===
PlexyDesk includes built-in desktop shell components instead of leaving those responsibilities to separate tools. Supported shell features include:
* a dock with launch feedback and running indicators
* icon magnification behaviour as the pointer moves across the dock
* a menubar that can show application menus, titles, and status information
* a desktop-level clock and shell-facing window metadata

=== Visual materials and effects ===
The rendering system supports a polished visual layer throughout the shell and the UI toolkit. This includes:
* glass-style surfaces
* blur-based materials
* shader-driven lighting and depth cues
* smooth rounded geometry
* scalable vector-style shape rendering for interface elements
* consistent text and surface styling across windows and widgets

These effects are part of the compositor and UI stack itself, so they can be used across the desktop rather than being isolated to one application.

=== Application UI toolkit ===
PlexyDesk includes a UI layer for building applications that look and behave like part of the environment. Supported interface building blocks include:
* labels and buttons
* text input and text areas
* sliders, switches, checkboxes, and progress controls
* separators, panels, rows, and columns
* list views and icon views
* sidebars, toolbars, breadcrumbs, status bars, and drawers
* menu integration for desktop menubars

The toolkit also supports layout controls such as padding, spacing, alignment, flexible sizing, and batched updates for responsive interfaces.

=== Multi-display and layout awareness ===
PlexyDesk is built with display layout awareness in mind. The configuration and compositor layout model support:
* more than one monitor
* explicit placement of outputs in desktop space
* per-layout presets
* desktop-space positioning that keeps pointer movement and window placement coherent across screens

=== Backgrounds and appearance ===
The shell supports desktop appearance controls such as:
* theme selection
* UI scale factor control
* wallpaper backgrounds
* animated background modes
* compositor tuning for chrome, blur, and window presentation
* dock and terminal appearance settings through configuration

=== Stability through application isolation ===
PlexyDesk applications can render their own content locally and then submit frames to the compositor. In simple terms, that means the shell manages the desktop while applications manage their own drawing. This separation helps keep the shell in control of composition and reduces the amount of direct rendering work the shell has to do for every application surface.

== Internal building blocks ==
{| class="wikitable"
|-
! Area
! Purpose
|-
| <code>src/</code>
| Compositor, backend, renderer, input, protocol, and shell code
|-
| <code>lib/</code>
| Client-side support libraries and event loop code
|-
| <code>include/plexy/</code>
| Public API headers such as <code>plexy_ui.h</code>
|-
| <code>examples/</code>
| Small client and UI examples
|-
| <code>apps/</code>
| Application experiments such as terminal, browser, clock, calculator, and file manager
|-
| <code>tasks/</code>
| Engineering notes, implementation summaries, and optimization work
|}

== Explore the project ==
* [[Architecture]] - a deeper technical explanation of how the compositor and client stack fit together
* [[PlexyUI API]] - generated reference for the UIKit application API
* [[Developer Guide]] - where the important source files and subsystems live
* [[Examples]] - small programs that show what PlexyDesk applications can look like
* [[Development Status]] - implementation notes and the current shape of the project

== Current state ==
PlexyDesk already includes a functioning compositor shell, a built-in dock and menubar, a GPU-driven rendering path, and a native application UI toolkit. Work is ongoing across performance, compatibility, and broader desktop behaviour, but the front-page story of the project is already clear: PlexyDesk is a complete graphical shell with its own rendering model, desktop components, and application framework.

PlexyUI API

2026-03-21T19:54:02Z

Plexydesk: Publish generated PlexyUI API reference

__NOTOC__
= PlexyUI API Reference =

''Generated from <code>include/plexy/plexy_ui.h</code> by <code>scripts/generate_plexy_uikit_docs.py</code>. Do not edit this page by hand; regenerate it from the header instead.''

PlexyUI — Client Library for PlexyDesk GPU-Accelerated Widgets
Renders widgets locally using libplexycanvas (SDF shaders, FreeType text,
flexbox layout) and submits DMA-BUF frames via the standard plexy protocol.
Client crash does not affect the compositor (plexyshell).

== Opaque types ==

=== PlexyApp ===
<pre>typedef struct PlexyApp PlexyApp;</pre>
Opaque handle for the lifetime of a PlexyDesk application.

=== PlexyWindow ===
<pre>typedef struct PlexyWindow PlexyWindow;</pre>
Opaque handle for a PlexyDesk window and its widget tree.

== Callback types ==

=== PlexyClickCallback ===
<pre>typedef void (*PlexyClickCallback)(uint32_t widget_id, void* userdata);</pre>
Called when a widget reports a click-style activation.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== PlexyValueCallback ===
<pre>typedef void (*PlexyValueCallback)(uint32_t widget_id, float value, void* userdata);</pre>
Called when a widget emits a numeric value change.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>value</code> || <code>float</code> || Numeric value to apply or report.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== PlexyTextCallback ===
<pre>typedef void (*PlexyTextCallback)(uint32_t widget_id, const char* text, void* userdata);</pre>
Called when widget text content changes.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>text</code> || <code>const char*</code> || Text content to display or apply.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== PlexyKeyCallback ===
<pre>typedef void (*PlexyKeyCallback)(uint32_t widget_id, uint32_t keycode, uint32_t mods, void* userdata);</pre>
Called when a widget receives keyboard input.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>keycode</code> || <code>uint32_t</code> || Key code supplied with a key event.
|-
| <code>mods</code> || <code>uint32_t</code> || Modifier state supplied with a key event.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== PlexyMenuCallback ===
<pre>typedef void (*PlexyMenuCallback)(uint32_t item_id, void* userdata);</pre>
Called when an application menubar item is chosen.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>item_id</code> || <code>uint32_t</code> || Identifier of a menu item.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

== App lifecycle ==

These functions manage the lifetime of a PlexyDesk application object and its main loop.

=== <code>plexy_app_create</code> ===
<pre>PlexyApp* plexy_app_create(const char* name);</pre>
Create a top-level PlexyDesk application object.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>name</code> || <code>const char*</code> || Human-readable name used to identify the application.
|}

* '''Returns:''' A new <code>PlexyApp</code> handle.

=== <code>plexy_app_run</code> ===
<pre>void plexy_app_run(PlexyApp* app);</pre>
Enter the application event loop and keep the UI running until it exits.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>app</code> || <code>PlexyApp*</code> || Application handle that owns the operation.
|}

=== <code>plexy_app_quit</code> ===
<pre>void plexy_app_quit(PlexyApp* app);</pre>
Request that the application event loop stops.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>app</code> || <code>PlexyApp*</code> || Application handle that owns the operation.
|}

=== <code>plexy_app_destroy</code> ===
<pre>void plexy_app_destroy(PlexyApp* app);</pre>
Release the application object and its remaining resources.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>app</code> || <code>PlexyApp*</code> || Application handle that owns the operation.
|}

== Window ==

These functions create, inspect, and destroy PlexyDesk windows.

=== <code>plexy_window_create</code> ===
<pre>PlexyWindow* plexy_window_create(PlexyApp* app, uint32_t width, uint32_t height, const char* title);</pre>
Create a new window for an application.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>app</code> || <code>PlexyApp*</code> || Application handle that owns the operation.
|-
| <code>width</code> || <code>uint32_t</code> || Requested width in pixels.
|-
| <code>height</code> || <code>uint32_t</code> || Requested height in pixels.
|-
| <code>title</code> || <code>const char*</code> || Human-readable label, title, or heading text.
|}

* '''Returns:''' A new <code>PlexyWindow</code> handle.

=== <code>plexy_window_root</code> ===
<pre>uint32_t plexy_window_root(PlexyWindow* win);</pre>
Return the root widget ID for the window's layout tree.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

* '''Returns:''' The root widget ID for the window.

=== <code>plexy_window_destroy</code> ===
<pre>void plexy_window_destroy(PlexyWindow* win);</pre>
Destroy a window and release its widget tree.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

== Widget creation ==

These functions create widgets and containers inside an existing window.

=== <code>plexy_label</code> ===
<pre>uint32_t plexy_label(PlexyWindow* win, uint32_t parent, const char* text);</pre>
Create a label and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>text</code> || <code>const char*</code> || Text content to display or apply.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_button</code> ===
<pre>uint32_t plexy_button(PlexyWindow* win, uint32_t parent, const char* text);</pre>
Create a button and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>text</code> || <code>const char*</code> || Text content to display or apply.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_text_input</code> ===
<pre>uint32_t plexy_text_input(PlexyWindow* win, uint32_t parent, const char* placeholder);</pre>
Create a text input and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>placeholder</code> || <code>const char*</code> || Placeholder text shown before the user enters content.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_text_area</code> ===
<pre>uint32_t plexy_text_area(PlexyWindow* win, uint32_t parent, const char* initial_text);</pre>
Create a text area and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>initial_text</code> || <code>const char*</code> || Initial text content for the widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_checkbox</code> ===
<pre>uint32_t plexy_checkbox(PlexyWindow* win, uint32_t parent, const char* label);</pre>
Create a checkbox and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_switch_widget</code> ===
<pre>uint32_t plexy_switch_widget(PlexyWindow* win, uint32_t parent, const char* label);</pre>
Create a switch widget and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_slider</code> ===
<pre>uint32_t plexy_slider(PlexyWindow* win, uint32_t parent, float min, float max, float initial);</pre>
Create a slider and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>min</code> || <code>float</code> || Minimum allowed value for the control.
|-
| <code>max</code> || <code>float</code> || Maximum allowed value for the control.
|-
| <code>initial</code> || <code>float</code> || Initial numeric value for the control.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_progress</code> ===
<pre>uint32_t plexy_progress(PlexyWindow* win, uint32_t parent, float value);</pre>
Create a progress and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>value</code> || <code>float</code> || Numeric value to apply or report.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_separator</code> ===
<pre>uint32_t plexy_separator(PlexyWindow* win, uint32_t parent);</pre>
Create a separator and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_spacer</code> ===
<pre>uint32_t plexy_spacer(PlexyWindow* win, uint32_t parent);</pre>
Create a spacer and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_panel</code> ===
<pre>uint32_t plexy_panel(PlexyWindow* win, uint32_t parent);</pre>
Create a panel and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_scroll_view</code> ===
<pre>uint32_t plexy_scroll_view(PlexyWindow* win, uint32_t parent);</pre>
Create a scroll view and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_list_view</code> ===
<pre>uint32_t plexy_list_view(PlexyWindow* win, uint32_t parent, const char* items_text);</pre>
Create a list view and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>items_text</code> || <code>const char*</code> || Text payload describing the initial items for the view.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_icon_view</code> ===
<pre>uint32_t plexy_icon_view(PlexyWindow* win, uint32_t parent, const char* items_text);</pre>
Create a icon view and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>items_text</code> || <code>const char*</code> || Text payload describing the initial items for the view.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_list_clear</code> ===
<pre>void plexy_list_clear(PlexyWindow* win, uint32_t list_view_id);</pre>
Remove all items from a list view.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>list_view_id</code> || <code>uint32_t</code> || Widget ID of the target list view.
|}

=== <code>plexy_list_append</code> ===
<pre>uint32_t plexy_list_append(PlexyWindow* win, uint32_t list_view_id, const char* item_text);</pre>
Append a new item to a list view and return the new child widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>list_view_id</code> || <code>uint32_t</code> || Widget ID of the target list view.
|-
| <code>item_text</code> || <code>const char*</code> || Text content for an inserted list or icon item.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_list_select</code> ===
<pre>void plexy_list_select(PlexyWindow* win, uint32_t list_view_id, int index);</pre>
Select an item in a list view by index.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>list_view_id</code> || <code>uint32_t</code> || Widget ID of the target list view.
|-
| <code>index</code> || <code>int</code> || Zero-based item index.
|}

=== <code>plexy_icon_clear</code> ===
<pre>void plexy_icon_clear(PlexyWindow* win, uint32_t icon_view_id);</pre>
Remove all items from an icon view.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>icon_view_id</code> || <code>uint32_t</code> || Widget ID of the target icon view.
|}

=== <code>plexy_icon_append</code> ===
<pre>uint32_t plexy_icon_append(PlexyWindow* win, uint32_t icon_view_id, const char* item_text);</pre>
Append a new item to an icon view and return the new child widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>icon_view_id</code> || <code>uint32_t</code> || Widget ID of the target icon view.
|-
| <code>item_text</code> || <code>const char*</code> || Text content for an inserted list or icon item.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_icon_select</code> ===
<pre>void plexy_icon_select(PlexyWindow* win, uint32_t icon_view_id, int index);</pre>
Select an item in an icon view by index.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>icon_view_id</code> || <code>uint32_t</code> || Widget ID of the target icon view.
|-
| <code>index</code> || <code>int</code> || Zero-based item index.
|}

=== <code>plexy_destroy_widget</code> ===
<pre>void plexy_destroy_widget(PlexyWindow* win, uint32_t widget_id);</pre>
Remove a widget from the window and destroy it.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|}

== Layout containers (convenience) ==

These helpers create common container shapes for arranging child widgets.

=== <code>plexy_row</code> ===
<pre>uint32_t plexy_row(PlexyWindow* win, uint32_t parent);</pre>
Create a row and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_column</code> ===
<pre>uint32_t plexy_column(PlexyWindow* win, uint32_t parent);</pre>
Create a column and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

== macOS-style widgets ==

These widgets model shell-like controls, navigation elements, and drawers.

=== <code>plexy_toolbar</code> ===
<pre>uint32_t plexy_toolbar(PlexyWindow* win, uint32_t parent);</pre>
Create a toolbar and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_toolbar_item</code> ===
<pre>uint32_t plexy_toolbar_item(PlexyWindow* win, uint32_t parent, const char* label);</pre>
Create a toolbar item and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_sidebar</code> ===
<pre>uint32_t plexy_sidebar(PlexyWindow* win, uint32_t parent);</pre>
Create a sidebar and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_sidebar_item</code> ===
<pre>uint32_t plexy_sidebar_item(PlexyWindow* win, uint32_t parent, const char* label);</pre>
Create a sidebar item and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_sidebar_item_with_icon</code> ===
<pre>uint32_t plexy_sidebar_item_with_icon(PlexyWindow* win, uint32_t parent, const char* label, const char* icon_name);</pre>
Create a sidebar item with icon and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|-
| <code>icon_name</code> || <code>const char*</code> || Icon name value.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_sidebar_section</code> ===
<pre>uint32_t plexy_sidebar_section(PlexyWindow* win, uint32_t parent, const char* title);</pre>
Create a sidebar section and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>title</code> || <code>const char*</code> || Human-readable label, title, or heading text.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_search_field</code> ===
<pre>uint32_t plexy_search_field(PlexyWindow* win, uint32_t parent, const char* placeholder);</pre>
Create a search field and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>placeholder</code> || <code>const char*</code> || Placeholder text shown before the user enters content.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_breadcrumb</code> ===
<pre>uint32_t plexy_breadcrumb(PlexyWindow* win, uint32_t parent, const char* path);</pre>
Create a breadcrumb and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>path</code> || <code>const char*</code> || Path text or breadcrumb string.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_split_view</code> ===
<pre>uint32_t plexy_split_view(PlexyWindow* win, uint32_t parent);</pre>
Create a split view and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_status_bar</code> ===
<pre>uint32_t plexy_status_bar(PlexyWindow* win, uint32_t parent, const char* text);</pre>
Create a status bar and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>text</code> || <code>const char*</code> || Text content to display or apply.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_drawer</code> ===
<pre>uint32_t plexy_drawer(PlexyWindow* win, uint32_t parent, int edge, float size);</pre>
Create a drawer and return its widget ID.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>parent</code> || <code>uint32_t</code> || Parent widget ID that will contain the new child widget.
|-
| <code>edge</code> || <code>int</code> || Drawer edge constant indicating which side the drawer attaches to.
|-
| <code>size</code> || <code>float</code> || Generic size value or drawer size.
|}

* '''Returns:''' A widget ID for the created or referenced widget.

=== <code>plexy_drawer_set_open</code> ===
<pre>void plexy_drawer_set_open(PlexyWindow* win, uint32_t drawer_id, int open, int animated);</pre>
Open or close a drawer and optionally animate the change.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>drawer_id</code> || <code>uint32_t</code> || Drawer id value.
|-
| <code>open</code> || <code>int</code> || Whether the drawer should be open.
|-
| <code>animated</code> || <code>int</code> || Whether the state change should be animated.
|}

=== <code>plexy_drawer_toggle</code> ===
<pre>void plexy_drawer_toggle(PlexyWindow* win, uint32_t drawer_id, int animated);</pre>
Toggle a drawer between open and closed states.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>drawer_id</code> || <code>uint32_t</code> || Drawer id value.
|-
| <code>animated</code> || <code>int</code> || Whether the state change should be animated.
|}

=== <code>plexy_drawer_is_open</code> ===
<pre>int plexy_drawer_is_open(PlexyWindow* win, uint32_t drawer_id);</pre>
Report whether a drawer is currently open.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>drawer_id</code> || <code>uint32_t</code> || Drawer id value.
|}

* '''Returns:''' A non-zero value when the drawer is open, otherwise zero.

== Layout properties ==

These functions change how a widget is positioned, aligned, or sized inside its parent layout.

=== <code>plexy_flex_direction</code> ===
<pre>void plexy_flex_direction(PlexyWindow* win, uint32_t widget_id, int direction);</pre>
Set the flex direction property on an existing widget.

'''Note:''' 0=row, 1=column

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>direction</code> || <code>int</code> || Layout direction constant, such as row or column.
|}

=== <code>plexy_justify</code> ===
<pre>void plexy_justify(PlexyWindow* win, uint32_t widget_id, int justify);</pre>
Set the justify property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>justify</code> || <code>int</code> || Main-axis justification constant.
|}

=== <code>plexy_align</code> ===
<pre>void plexy_align(PlexyWindow* win, uint32_t widget_id, int align);</pre>
Set the align property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>align</code> || <code>int</code> || Cross-axis alignment constant.
|}

=== <code>plexy_flex_grow</code> ===
<pre>void plexy_flex_grow(PlexyWindow* win, uint32_t widget_id, float grow);</pre>
Set the flex grow property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>grow</code> || <code>float</code> || Flex growth factor used during layout.
|}

=== <code>plexy_size</code> ===
<pre>void plexy_size(PlexyWindow* win, uint32_t widget_id, float width, float height);</pre>
Set the size property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>width</code> || <code>float</code> || Requested width in pixels.
|-
| <code>height</code> || <code>float</code> || Requested height in pixels.
|}

=== <code>plexy_margin</code> ===
<pre>void plexy_margin(PlexyWindow* win, uint32_t widget_id, float top, float right, float bottom, float left);</pre>
Set the margin property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>top</code> || <code>float</code> || Top edge distance or coordinate.
|-
| <code>right</code> || <code>float</code> || Right edge distance.
|-
| <code>bottom</code> || <code>float</code> || Bottom edge distance.
|-
| <code>left</code> || <code>float</code> || Left edge distance.
|}

=== <code>plexy_padding</code> ===
<pre>void plexy_padding(PlexyWindow* win, uint32_t widget_id, float top, float right, float bottom, float left);</pre>
Set the padding property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>top</code> || <code>float</code> || Top edge distance or coordinate.
|-
| <code>right</code> || <code>float</code> || Right edge distance.
|-
| <code>bottom</code> || <code>float</code> || Bottom edge distance.
|-
| <code>left</code> || <code>float</code> || Left edge distance.
|}

=== <code>plexy_gap</code> ===
<pre>void plexy_gap(PlexyWindow* win, uint32_t widget_id, float gap);</pre>
Set the gap property on an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>gap</code> || <code>float</code> || Spacing inserted between child items.
|}

== Widget state ==

These functions update widget content or toggle widget state after creation.

=== <code>plexy_set_text</code> ===
<pre>void plexy_set_text(PlexyWindow* win, uint32_t widget_id, const char* text);</pre>
Replace the text content of an existing widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>text</code> || <code>const char*</code> || Text content to display or apply.
|}

=== <code>plexy_set_value</code> ===
<pre>void plexy_set_value(PlexyWindow* win, uint32_t widget_id, float value);</pre>
Set the numeric value of a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>value</code> || <code>float</code> || Numeric value to apply or report.
|}

=== <code>plexy_set_visible</code> ===
<pre>void plexy_set_visible(PlexyWindow* win, uint32_t widget_id, int visible);</pre>
Show or hide a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>visible</code> || <code>int</code> || Visibility flag, typically non-zero for visible.
|}

=== <code>plexy_set_enabled</code> ===
<pre>void plexy_set_enabled(PlexyWindow* win, uint32_t widget_id, int enabled);</pre>
Enable or disable user interaction for a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>enabled</code> || <code>int</code> || Enabled flag, typically non-zero for enabled.
|}

=== <code>plexy_set_readonly</code> ===
<pre>void plexy_set_readonly(PlexyWindow* win, uint32_t widget_id, int readonly);</pre>
Toggle whether a text-capable widget is read-only.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>readonly</code> || <code>int</code> || Read-only flag, typically non-zero to prevent editing.
|}

== Style ==

These functions control visual appearance such as color, corner radius, and surface material.

=== <code>plexy_set_corner_radius</code> ===
<pre>void plexy_set_corner_radius(PlexyWindow* win, uint32_t widget_id, float radius);</pre>
Set the widget corner radius.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>radius</code> || <code>float</code> || Corner radius value.
|}

=== <code>plexy_set_elevation</code> ===
<pre>void plexy_set_elevation(PlexyWindow* win, uint32_t widget_id, float level);</pre>
Set the widget elevation or depth styling level.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>level</code> || <code>float</code> || Elevation level used to influence depth styling.
|}

=== <code>plexy_set_fill_color</code> ===
<pre>void plexy_set_fill_color(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a);</pre>
Apply a fill color using RGBA components.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>r</code> || <code>float</code> || Red color component.
|-
| <code>g</code> || <code>float</code> || Green color component.
|-
| <code>b</code> || <code>float</code> || Blue color component.
|-
| <code>a</code> || <code>float</code> || Alpha or opacity component.
|}

=== <code>plexy_set_fill_color_hex</code> ===
<pre>void plexy_set_fill_color_hex(PlexyWindow* win, uint32_t widget_id, const char* hex);</pre>
Apply a fill color using a hex color string.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>hex</code> || <code>const char*</code> || Hexadecimal color string.
|}

=== <code>plexy_set_text_color</code> ===
<pre>void plexy_set_text_color(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a);</pre>
Apply a text color using RGBA components.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>r</code> || <code>float</code> || Red color component.
|-
| <code>g</code> || <code>float</code> || Green color component.
|-
| <code>b</code> || <code>float</code> || Blue color component.
|-
| <code>a</code> || <code>float</code> || Alpha or opacity component.
|}

=== <code>plexy_set_text_color_hex</code> ===
<pre>void plexy_set_text_color_hex(PlexyWindow* win, uint32_t widget_id, const char* hex);</pre>
Apply a text color using a hex color string.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>hex</code> || <code>const char*</code> || Hexadecimal color string.
|}

=== <code>plexy_set_font_size</code> ===
<pre>void plexy_set_font_size(PlexyWindow* win, uint32_t widget_id, float size);</pre>
Set the rendered font size for the widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>size</code> || <code>float</code> || Generic size value or drawer size.
|}

=== <code>plexy_set_border</code> ===
<pre>void plexy_set_border(PlexyWindow* win, uint32_t widget_id, float r, float g, float b, float a, float width);</pre>
Set border color and width for a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>r</code> || <code>float</code> || Red color component.
|-
| <code>g</code> || <code>float</code> || Green color component.
|-
| <code>b</code> || <code>float</code> || Blue color component.
|-
| <code>a</code> || <code>float</code> || Alpha or opacity component.
|-
| <code>width</code> || <code>float</code> || Requested width in pixels.
|}

=== <code>plexy_set_glass</code> ===
<pre>void plexy_set_glass(PlexyWindow* win, uint32_t widget_id, float opacity);</pre>
Apply a glass-style material effect with the given opacity.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>opacity</code> || <code>float</code> || Opacity amount for the material effect.
|}

=== <code>plexy_set_glass_material</code> ===
<pre>void plexy_set_glass_material(PlexyWindow* win, uint32_t widget_id, float opacity);</pre>
Apply the full glass material treatment with the given opacity.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>opacity</code> || <code>float</code> || Opacity amount for the material effect.
|}

=== <code>plexy_set_surface_material</code> ===
<pre>void plexy_set_surface_material(PlexyWindow* win, uint32_t widget_id);</pre>
Switch the widget back to an opaque surface-style material.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|}

== Events ==

These functions register callbacks and direct focus for interactive widgets.

=== <code>plexy_on_click</code> ===
<pre>void plexy_on_click(PlexyWindow* win, uint32_t widget_id, PlexyClickCallback cb, void* userdata);</pre>
Register a click callback for a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>cb</code> || <code>PlexyClickCallback</code> || Callback function invoked when the event fires.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== <code>plexy_on_value_changed</code> ===
<pre>void plexy_on_value_changed(PlexyWindow* win, uint32_t widget_id, PlexyValueCallback cb, void* userdata);</pre>
Register a callback for value changes.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>cb</code> || <code>PlexyValueCallback</code> || Callback function invoked when the event fires.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== <code>plexy_on_text_changed</code> ===
<pre>void plexy_on_text_changed(PlexyWindow* win, uint32_t widget_id, PlexyTextCallback cb, void* userdata);</pre>
Register a callback for text changes.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>cb</code> || <code>PlexyTextCallback</code> || Callback function invoked when the event fires.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== <code>plexy_on_key</code> ===
<pre>void plexy_on_key(PlexyWindow* win, uint32_t widget_id, PlexyKeyCallback cb, void* userdata);</pre>
Register a callback for widget key events.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>cb</code> || <code>PlexyKeyCallback</code> || Callback function invoked when the event fires.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

=== <code>plexy_set_focus</code> ===
<pre>void plexy_set_focus(PlexyWindow* win, uint32_t widget_id);</pre>
Move keyboard focus to the specified widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|}

=== <code>plexy_on_menu</code> ===
<pre>void plexy_on_menu(PlexyWindow* win, PlexyMenuCallback cb, void* userdata);</pre>
Register a callback for desktop menubar item selections.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>cb</code> || <code>PlexyMenuCallback</code> || Callback function invoked when the event fires.
|-
| <code>userdata</code> || <code>void*</code> || Caller-provided context passed back into the callback.
|}

== App menubar model (desktop menubar integration) ==

These functions describe an application menu structure for the desktop menubar.

=== <code>plexy_menu_begin</code> ===
<pre>int plexy_menu_begin(PlexyWindow* win, int supported, const char* app_title);</pre>
Begin describing an application menu model for the desktop menubar.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>supported</code> || <code>int</code> || Flag indicating whether desktop menubar support is available.
|-
| <code>app_title</code> || <code>const char*</code> || Application title to expose through the menubar model.
|}

* '''Returns:''' An integer status or result code.

=== <code>plexy_menu_add</code> ===
<pre>int plexy_menu_add(PlexyWindow* win, uint32_t menu_id, const char* title);</pre>
Create a new menu within the current menubar model.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>menu_id</code> || <code>uint32_t</code> || Identifier of the target menu.
|-
| <code>title</code> || <code>const char*</code> || Human-readable label, title, or heading text.
|}

* '''Returns:''' An integer status or result code.

=== <code>plexy_menu_add_item</code> ===
<pre>int plexy_menu_add_item(PlexyWindow* win, uint32_t menu_id, uint32_t item_id, const char* label, int enabled);</pre>
Add a menu item to an existing menu.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>menu_id</code> || <code>uint32_t</code> || Identifier of the target menu.
|-
| <code>item_id</code> || <code>uint32_t</code> || Identifier of a menu item.
|-
| <code>label</code> || <code>const char*</code> || Display label shown with the widget.
|-
| <code>enabled</code> || <code>int</code> || Enabled flag, typically non-zero for enabled.
|}

* '''Returns:''' An integer status or result code.

=== <code>plexy_menu_commit</code> ===
<pre>int plexy_menu_commit(PlexyWindow* win);</pre>
Submit the completed menubar model to the shell.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

* '''Returns:''' An integer status or result code.

== Batch updates (reduces IPC round-trips) ==

These functions group a series of widget updates so they can be applied together.

=== <code>plexy_batch_begin</code> ===
<pre>void plexy_batch_begin(PlexyWindow* win);</pre>
Begin a batch of widget changes.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

=== <code>plexy_batch_end</code> ===
<pre>void plexy_batch_end(PlexyWindow* win);</pre>
End a batch of widget changes and flush the grouped update.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

== Retained Path Drawing (Bezier) ==

These functions build retained vector paths and query rendered widget bounds.

=== <code>plexy_path_clear</code> ===
<pre>void plexy_path_clear(PlexyWindow* win);</pre>
Clear any retained path drawing commands.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

=== <code>plexy_path_begin</code> ===
<pre>void plexy_path_begin(PlexyWindow* win);</pre>
Start defining a new retained path.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

=== <code>plexy_path_move_to</code> ===
<pre>void plexy_path_move_to(PlexyWindow* win, float x, float y);</pre>
Move the current drawing cursor to a new position.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>x</code> || <code>float</code> || X coordinate or output storage for the X position.
|-
| <code>y</code> || <code>float</code> || Y coordinate or output storage for the Y position.
|}

=== <code>plexy_path_line_to</code> ===
<pre>void plexy_path_line_to(PlexyWindow* win, float x, float y);</pre>
Append a straight line segment to the current path.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>x</code> || <code>float</code> || X coordinate or output storage for the X position.
|-
| <code>y</code> || <code>float</code> || Y coordinate or output storage for the Y position.
|}

=== <code>plexy_path_bezier_to</code> ===
<pre>void plexy_path_bezier_to(PlexyWindow* win, float cp1x, float cp1y, float cp2x, float cp2y, float x, float y);</pre>
Append a cubic Bezier curve to the current path.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>cp1x</code> || <code>float</code> || First Bezier control point X coordinate.
|-
| <code>cp1y</code> || <code>float</code> || First Bezier control point Y coordinate.
|-
| <code>cp2x</code> || <code>float</code> || Second Bezier control point X coordinate.
|-
| <code>cp2y</code> || <code>float</code> || Second Bezier control point Y coordinate.
|-
| <code>x</code> || <code>float</code> || X coordinate or output storage for the X position.
|-
| <code>y</code> || <code>float</code> || Y coordinate or output storage for the Y position.
|}

=== <code>plexy_path_set_stroke</code> ===
<pre>void plexy_path_set_stroke(PlexyWindow* win, float r, float g, float b, float a, float width);</pre>
Set stroke color and width for retained path drawing.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>r</code> || <code>float</code> || Red color component.
|-
| <code>g</code> || <code>float</code> || Green color component.
|-
| <code>b</code> || <code>float</code> || Blue color component.
|-
| <code>a</code> || <code>float</code> || Alpha or opacity component.
|-
| <code>width</code> || <code>float</code> || Requested width in pixels.
|}

=== <code>plexy_path_stroke</code> ===
<pre>void plexy_path_stroke(PlexyWindow* win);</pre>
Render the current retained path as a stroke.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|}

=== <code>plexy_widget_bounds</code> ===
<pre>int plexy_widget_bounds(PlexyWindow* win, uint32_t widget_id, float* x, float* y, float* width, float* height);</pre>
Query the current bounds of a widget.

==== Parameters ====
{| class="wikitable"
|-
! Parameter !! Type !! Description
|-
| <code>win</code> || <code>PlexyWindow*</code> || Window handle that owns or contains the widget tree.
|-
| <code>widget_id</code> || <code>uint32_t</code> || Widget ID of the target control or container.
|-
| <code>x</code> || <code>float*</code> || X coordinate or output storage for the X position.
|-
| <code>y</code> || <code>float*</code> || Y coordinate or output storage for the Y position.
|-
| <code>width</code> || <code>float*</code> || Requested width in pixels.
|-
| <code>height</code> || <code>float*</code> || Requested height in pixels.
|}

* '''Returns:''' An integer status or result code.

== Constants ==

=== Justify content ===
Constants used to choose how child widgets are distributed on the main layout axis.

{| class="wikitable"
|-
! Constant !! Value !! Description
|-
| <code>PLEXY_JUSTIFY_START</code> || <code>0</code> || Pack items toward the start of the main axis.
|-
| <code>PLEXY_JUSTIFY_END</code> || <code>1</code> || Pack items toward the end of the main axis.
|-
| <code>PLEXY_JUSTIFY_CENTER</code> || <code>2</code> || Center items along the main axis.
|-
| <code>PLEXY_JUSTIFY_SPACE_BETWEEN</code> || <code>3</code> || Distribute free space between items.
|-
| <code>PLEXY_JUSTIFY_SPACE_AROUND</code> || <code>4</code> || Distribute free space around items.
|-
| <code>PLEXY_JUSTIFY_SPACE_EVENLY</code> || <code>5</code> || Distribute free space evenly before, between, and after items.
|}

=== Align items ===
Constants used to choose how child widgets align on the cross axis.

{| class="wikitable"
|-
! Constant !! Value !! Description
|-
| <code>PLEXY_ALIGN_START</code> || <code>0</code> || Align items at the start of the cross axis.
|-
| <code>PLEXY_ALIGN_END</code> || <code>1</code> || Align items at the end of the cross axis.
|-
| <code>PLEXY_ALIGN_CENTER</code> || <code>2</code> || Center items on the cross axis.
|-
| <code>PLEXY_ALIGN_STRETCH</code> || <code>3</code> || Stretch items to fill the cross axis.
|}

=== Flex direction ===
Constants used to choose whether a layout flows as a row or a column.

{| class="wikitable"
|-
! Constant !! Value !! Description
|-
| <code>PLEXY_FLEX_ROW</code> || <code>0</code> || Lay out children horizontally.
|-
| <code>PLEXY_FLEX_COLUMN</code> || <code>1</code> || Lay out children vertically.
|}

=== Drawer edges ===
Constants used to attach a drawer to a specific edge of its parent window.

{| class="wikitable"
|-
! Constant !! Value !! Description
|-
| <code>PLEXY_DRAWER_LEFT</code> || <code>0</code> || Attach the drawer to the left edge.
|-
| <code>PLEXY_DRAWER_RIGHT</code> || <code>1</code> || Attach the drawer to the right edge.
|-
| <code>PLEXY_DRAWER_TOP</code> || <code>2</code> || Attach the drawer to the top edge.
|-
| <code>PLEXY_DRAWER_BOTTOM</code> || <code>3</code> || Attach the drawer to the bottom edge.
|}

Main Page

2026-03-21T19:39:40Z

Plexydesk: Rewrite front page to focus on architecture and supported features

__NOTOC__
= PlexyDesk =

'''PlexyDesk''' is a display server and desktop shell for Linux built around a modern, GPU-driven user interface. It is responsible for drawing the desktop itself, placing application windows on screen, rendering the dock and the menubar, handling animation and visual effects, and presenting a consistent UI toolkit for PlexyDesk applications.

{| class="wikitable"
|+ PlexyDesk at a glance
|-
! Focus
| GPU-accelerated compositor and desktop shell for Linux
|-
! Runtime
| <code>plexyshell</code>
|-
! Client stack
| <code>libplexy</code>, <code>libplexycanvas</code>, <code>libplexyui</code>
|-
! License
| AGPL-3.0-only
|}

== What PlexyDesk does ==
PlexyDesk combines three responsibilities into one system:
* it acts as the display server that decides what appears on screen
* it acts as the desktop shell that draws the dock, menubar, background, and window chrome
* it provides application-facing libraries so apps can create native PlexyDesk windows and controls

In practical terms, PlexyDesk is the part of the desktop that gives applications a place to live, gives windows their shape and motion, and gives the overall environment its visual identity.

== Architecture in plain language ==
PlexyDesk is organised around three main layers:

{| class="wikitable"
|-
! Layer
! What it is responsible for
|-
| Applications
| Programs create windows, text, buttons, panels, lists, drawers, and other interface elements
|-
| PlexyDesk client libraries
| The libraries help apps describe their UI, render it locally, and send finished frames to the display server
|-
| PlexyDesk compositor and shell
| The compositor places windows on screen, draws the desktop shell, applies visual effects, handles input routing, and presents the final image
|}

Instead of asking the shell to draw every application widget for them, PlexyDesk applications can render their own interface locally and then hand the finished frame to the compositor. The compositor then combines those application surfaces with system elements such as the dock, menubar, background, window chrome, and transitions. This keeps the shell visually consistent while still allowing applications to manage their own content.

== Supported desktop features ==
=== Window presentation and motion ===
PlexyDesk provides its own window chrome and visual framing. Windows are not treated as plain rectangles with static borders; they are part of the shell experience. The compositor supports:
* animated window movement
* resize handling
* window shadows and depth styling
* rounded corners and smooth surface edges
* minimise and transition effects
* focus-aware rendering and presentation

=== Dock and menubar ===
PlexyDesk includes built-in desktop shell components instead of leaving those responsibilities to separate tools. Supported shell features include:
* a dock with launch feedback and running indicators
* icon magnification behaviour as the pointer moves across the dock
* a menubar that can show application menus, titles, and status information
* a desktop-level clock and shell-facing window metadata

=== Visual materials and effects ===
The rendering system supports a polished visual layer throughout the shell and the UI toolkit. This includes:
* glass-style surfaces
* blur-based materials
* shader-driven lighting and depth cues
* smooth rounded geometry
* scalable vector-style shape rendering for interface elements
* consistent text and surface styling across windows and widgets

These effects are part of the compositor and UI stack itself, so they can be used across the desktop rather than being isolated to one application.

=== Application UI toolkit ===
PlexyDesk includes a UI layer for building applications that look and behave like part of the environment. Supported interface building blocks include:
* labels and buttons
* text input and text areas
* sliders, switches, checkboxes, and progress controls
* separators, panels, rows, and columns
* list views and icon views
* sidebars, toolbars, breadcrumbs, status bars, and drawers
* menu integration for desktop menubars

The toolkit also supports layout controls such as padding, spacing, alignment, flexible sizing, and batched updates for responsive interfaces.

=== Multi-display and layout awareness ===
PlexyDesk is built with display layout awareness in mind. The configuration and compositor layout model support:
* more than one monitor
* explicit placement of outputs in desktop space
* per-layout presets
* desktop-space positioning that keeps pointer movement and window placement coherent across screens

=== Backgrounds and appearance ===
The shell supports desktop appearance controls such as:
* theme selection
* UI scale factor control
* wallpaper backgrounds
* animated background modes
* compositor tuning for chrome, blur, and window presentation
* dock and terminal appearance settings through configuration

=== Stability through application isolation ===
PlexyDesk applications can render their own content locally and then submit frames to the compositor. In simple terms, that means the shell manages the desktop while applications manage their own drawing. This separation helps keep the shell in control of composition and reduces the amount of direct rendering work the shell has to do for every application surface.

== Internal building blocks ==
{| class="wikitable"
|-
! Area
! Purpose
|-
| <code>src/</code>
| Compositor, backend, renderer, input, protocol, and shell code
|-
| <code>lib/</code>
| Client-side support libraries and event loop code
|-
| <code>include/plexy/</code>
| Public API headers such as <code>plexy_ui.h</code>
|-
| <code>examples/</code>
| Small client and UI examples
|-
| <code>apps/</code>
| Application experiments such as terminal, browser, clock, calculator, and file manager
|-
| <code>tasks/</code>
| Engineering notes, implementation summaries, and optimization work
|}

== Explore the project ==
* [[Architecture]] - a deeper technical explanation of how the compositor and client stack fit together
* [[Developer Guide]] - where the important source files and subsystems live
* [[Examples]] - small programs that show what PlexyDesk applications can look like
* [[Development Status]] - implementation notes and the current shape of the project

== Current state ==
PlexyDesk already includes a functioning compositor shell, a built-in dock and menubar, a GPU-driven rendering path, and a native application UI toolkit. Work is ongoing across performance, compatibility, and broader desktop behaviour, but the front-page story of the project is already clear: PlexyDesk is a complete graphical shell with its own rendering model, desktop components, and application framework.

Main Page

2026-03-21T19:32:57Z

Plexydesk: Set up PlexyDesk wiki landing page

__NOTOC__
= PlexyDesk =

'''PlexyDesk''' is a GPU-accelerated display server and desktop shell for Linux. It renders window chrome, the dock, the menubar, and client widgets with OpenGL, signed distance field rendering, blur, and glass-style materials. Client applications render locally with <code>libplexycanvas</code> and submit frames to the compositor using DMA-BUF-backed buffers.

{| class="wikitable"
|+ PlexyDesk at a glance
|-
! Focus
| GPU-accelerated compositor and desktop shell for Linux
|-
! Runtime
| <code>plexyshell</code>
|-
! Client stack
| <code>libplexy</code>, <code>libplexycanvas</code>, <code>libplexyui</code>
|-
! Build system
| GNU Make with C11 and C++20
|-
! License
| AGPL-3.0-only
|}

== What makes it interesting ==
* GPU-first desktop shell with compositor effects built into the core runtime
* Custom display protocol optimized for local client rendering and DMA-BUF frame handoff
* macOS-inspired polish including blur, glass materials, dock magnification, and animated window effects
* Multi-monitor oriented architecture with a built-in shell instead of a separate panel-and-window-manager stack

== Core features ==
* Glass materials with blur, refraction, and shader-based visual effects
* Resolution-independent SDF rendering for chrome and widgets
* Built-in dock with hover magnification, launch animation, and running indicators
* Menubar integration with application title, menus, and clock
* PlexyUI widget toolkit with buttons, sliders, text input, sidebars, drawers, list views, and more
* Client isolation: applications render locally and submit frames to the compositor instead of drawing directly into the shell
* Native compositor work plus active bridge work around Wayland and X11 compatibility

== Quick start ==
<pre>
# Install dependencies on Debian/Ubuntu
./install-deps.sh

# Build the compositor
make

# Run PlexyDesk
./plexyshell
</pre>

For debug builds:

<pre>
BUILD_MODE=debug make
</pre>

== Documentation guide ==
* [[Getting Started]] - dependencies, build, run, systemd service, and package workflow
* [[Architecture]] - compositor model, client libraries, protocol flow, and repository layout
* [[Developer Guide]] - what to read first and where to work in the source tree
* [[Examples]] - minimal PlexyUI code plus example programs worth studying
* [[Development Status]] - current shape of the project and useful implementation notes

== Repository map ==
{| class="wikitable"
|-
! Area
! Purpose
|-
| <code>src/</code>
| Compositor, backend, renderer, input, protocol, and shell code
|-
| <code>lib/</code>
| Client-side support libraries and event loop code
|-
| <code>include/plexy/</code>
| Public API headers such as <code>plexy_ui.h</code>
|-
| <code>examples/</code>
| Small client and UI examples
|-
| <code>apps/</code>
| Application experiments such as terminal, browser, clock, calculator, and file manager
|-
| <code>scripts/</code>
| Packaging, systemd, and development helpers
|-
| <code>docker/</code>
| Ubuntu container workflow for building <code>.deb</code> packages
|-
| <code>tasks/</code>
| Engineering notes, implementation summaries, and optimization work
|}

== Project status ==
PlexyDesk is under active development. The rendering pipeline, compositor shell, dock, menubar, and widget toolkit are all present, but the project should still be treated as a developer-facing system rather than a finished general-purpose desktop environment.

== Suggested next pages ==
If you are starting from source, begin with [[Getting Started]]. If you want to understand the shape of the codebase before building, start with [[Architecture]] and [[Developer Guide]].

Development Status

2026-03-21T19:32:57Z

Plexydesk: Add development status page

= Development Status =

PlexyDesk is an active engineering project. It already contains a working compositor shell, rendering pipeline, widget toolkit, and supporting examples, but it should still be treated as a development platform rather than a finished consumer desktop.

== Working areas already visible in the tree ==
* compositor runtime and shell rendering
* dock and menubar
* widget toolkit and retained layout API
* example applications and experiments
* packaging and systemd helpers
* bridge and compatibility work around Wayland and X11

== Areas that still read as active work ==
* broader application compatibility
* input and clipboard edge cases
* bridge robustness and performance tuning
* memory, damage tracking, and async rendering refinement

== Useful engineering notes in the repository ==
The <code>tasks/</code> directory contains implementation notes and change summaries including:
* <code>ASYNC_RENDERING_COMPLETE.md</code>
* <code>DAMAGE_TRACKING_IMPLEMENTATION.md</code>
* <code>IMPLEMENTATION_COMPLETE.md</code>
* <code>VRAM_LEAK_ANALYSIS.md</code>
* <code>VRAM_LEAK_FIXES_APPLIED.md</code>
* <code>X11_FLUSH_FIX_SUMMARY.md</code>
* <code>WORLD_CLASS_OPTIMIZATION_STRATEGY.md</code>

== Suggested workflow for contributors ==
# Read [[Getting Started]]
# Build a debug tree
# Run and inspect the smallest examples
# Read [[Architecture]] and [[Developer Guide]]
# Use the task documents to understand current priorities before making larger changes

== Related pages ==
* [[Main Page]]
* [[Getting Started]]
* [[Architecture]]
* [[Developer Guide]]
* [[Examples]]

Examples

2026-03-21T19:32:56Z

Plexydesk: Add examples reference

= Examples =

The repository includes a small collection of examples that are useful both as smoke tests and as reference code for application authors.

== Minimal PlexyUI example ==
The following example is based on <code>examples/hello_uikit.c</code>:

<pre>
#include <plexy_ui.h>
#include <stdio.h>

static void on_click(uint32_t widget_id, void* userdata) {
printf("Button clicked! (widget %u)\n", widget_id);
}

int main(void) {
PlexyApp* app = plexy_app_create("Hello UIKit");
PlexyWindow* win = plexy_window_create(app, 400, 300, "Hello PlexyDesk");
uint32_t root = plexy_window_root(win);

plexy_padding(win, root, 24, 24, 24, 24);
plexy_gap(win, root, 16);
plexy_justify(win, root, PLEXY_JUSTIFY_CENTER);
plexy_align(win, root, PLEXY_ALIGN_CENTER);

uint32_t title = plexy_label(win, root, "Welcome to PlexyDesk UIKit");
plexy_set_text_color_hex(win, title, "#1f2937");

uint32_t btn = plexy_button(win, root, "Click Me");
plexy_set_fill_color_hex(win, btn, "#3b82f6");
plexy_set_text_color_hex(win, btn, "#ffffff");
plexy_on_click(win, btn, on_click, NULL);

plexy_app_run(app);
plexy_app_destroy(app);
return 0;
}
</pre>

Build and run:

<pre>
gcc -o hello_uikit hello_uikit.c -L../lib -lplexyui
./hello_uikit
</pre>

== Useful example files ==
{| class="wikitable"
|-
! File
! Why it is useful
|-
| <code>examples/hello_uikit.c</code>
| Smallest usable PlexyUI program
|-
| <code>examples/hello_client.c</code>
| Lightweight client-side entry point
|-
| <code>examples/canvas_demo.c</code>
| Canvas and rendering-oriented example
|-
| <code>examples/drawer_demo.c</code>
| Drawer and interaction example
|-
| <code>examples/plexy_dock.c</code>
| Dock-related shell UI ideas
|-
| <code>examples/settings_panel.c</code>
| Structured settings-style interface
|-
| <code>examples/showcase_demo.c</code>
| Broader demonstration page for the toolkit
|-
| <code>examples/widget_demo.c</code>
| Widget coverage and visual output
|}

== What to learn from the examples ==
* how to create an application and a root window
* how layout is controlled with padding, gap, justify, align, and rows or columns
* how to style widgets with color, radius, elevation, and glass-related helpers
* how to bind click and value callbacks
* how client programs fit into the compositor model

== Next step ==
After reading the examples, continue with [[Developer Guide]] and [[Architecture]].

Developer Guide

2026-03-21T19:32:55Z

Plexydesk: Add developer guide

= Developer Guide =

This page is a practical map for engineers who want to read or modify the PlexyDesk source tree.

== Read these first ==
* <code>tasks/README.md</code> - current work areas and implementation notes
* <code>install-deps.sh</code> - the fastest view of build and system dependencies
* <code>Makefile</code> - build modes, active runtime entry points, and source grouping
* <code>include/plexy/plexy_ui.h</code> - public client API
* <code>examples/hello_uikit.c</code> - smallest useful UI example
* <code>docker/README.md</code> - package build workflow
* <code>plexyshell.conf.example</code> - runtime configuration surface

== Key source areas ==
{| class="wikitable"
|-
! Path
! What you will find there
|-
| <code>src/renderer/</code>
| Compositing, window effects, dock, menubar, shaders, async renderer, and GPU configuration
|-
| <code>src/backend/</code>
| DRM, X11-related display backend code, session management, and display backend selection
|-
| <code>src/input/</code>
| libinput integration, focus policy, and input coordination
|-
| <code>src/core/</code>
| Shell runtime, event loop, dock manager, drag/resize state, and display layout state
|-
| <code>src/server/</code>
| Compositor-side protocol server
|-
| <code>src/wayland/</code>
| Wayland bridge and XWM interoperability work
|-
| <code>src/canvas/</code>
| Canvas rendering, text, layout, styling, and animation support
|-
| <code>lib/</code>
| Client-side event loop and protocol support
|}

== Build workflow ==
Standard release build:

<pre>
make
</pre>

Verbose debug build:

<pre>
BUILD_MODE=debug make
</pre>

The Makefile groups sources by subsystem and applies different compiler and logging flags for debug versus release mode. Release builds enable aggressive optimization and link-time optimization.

== Public client API ==
The main client-facing API lives in <code>include/plexy/plexy_ui.h</code>. It covers:
* application and window lifecycle
* widget creation
* layout primitives such as row, column, justify, align, padding, and gap
* state changes such as visibility, text, value, and enabled state
* styling helpers such as corner radius, fill color, elevation, and glass material
* event hooks for clicks, values, text changes, keys, and menus

== Example-driven learning ==
The best small files to read early are:
* <code>examples/hello_uikit.c</code>
* <code>examples/canvas_demo.c</code>
* <code>examples/drawer_demo.c</code>
* <code>examples/settings_panel.c</code>
* <code>examples/showcase_demo.c</code>

== Applications and experiments ==
The <code>apps/</code> directory includes larger experiments such as:
* <code>plexy_term</code>
* <code>plexy_browser</code>
* <code>plexy_clock</code>
* <code>fileman</code>
* <code>pcalc</code>
* <code>vim</code>

== Packaging and service helpers ==
* <code>docker/README.md</code> explains the Ubuntu Docker package flow
* <code>scripts/systemd/</code> contains the user slice, service, installer, starter, and status helpers

== Good follow-up pages ==
* [[Architecture]]
* [[Getting Started]]
* [[Examples]]
* [[Development Status]]

Architecture

2026-03-21T19:32:55Z

Plexydesk: Add architecture overview

= Architecture =

PlexyDesk combines a compositor, desktop shell, client libraries, and a custom display protocol into one system.

== High-level model ==
{| class="wikitable"
|-
! Layer
! Role
|-
| Client application
| Creates windows and widgets through PlexyDesk APIs
|-
| <code>libplexyui</code>
| High-level C API for widgets, layout, events, and styling
|-
| <code>libplexycanvas</code>
| Local rendering of widgets, text, layout, and GPU effects
|-
| <code>libplexy</code>
| Protocol and DMA-BUF frame handoff support
|-
| Unix socket protocol
| Communication path between clients and compositor
|-
| <code>plexyshell</code>
| Compositor and desktop shell runtime
|-
| Backend stack
| DRM/KMS, input handling, OpenGL, and compatibility bridge code
|}

== Render flow ==
# A client creates UI using functions from <code>plexy_ui.h</code>.
# The client renders its widget tree locally using <code>libplexycanvas</code>.
# The rendered frame is handed to the compositor using the PlexyDesk protocol and DMA-BUF-backed buffers.
# The compositor composites all visible client surfaces, applies shell chrome and effects, and renders desktop elements such as the dock and menubar.

== Design direction ==
PlexyDesk is not presented as a generic Wayland replacement. The codebase is built around a GPU-first rendering path and a project-specific display protocol, while also carrying active bridge work around Wayland and X11 interoperability.

== Important runtime pieces ==
* <code>src/shells/gnu_liquid/main.cpp</code> is the active compositor runtime entry point described in the Makefile
* <code>src/renderer/</code> contains compositor rendering, background, dock, menubar, shader, and async rendering code
* <code>src/backend/</code> contains DRM and display backend support
* <code>src/input/</code> contains libinput integration and focus policy code
* <code>src/server/</code> contains socket server code for the compositor side of the protocol
* <code>src/wayland/</code> contains bridge and interoperability work including XWM-related files
* <code>src/core/</code> contains shell runtime, event loop, dock manager, and display layout state

== Public API surface ==
The public API is exposed through headers in <code>include/plexy/</code>. In particular, <code>plexy_ui.h</code> documents:
* application lifecycle
* window creation
* widget creation
* flexbox-like layout controls
* styling helpers
* event callbacks
* desktop menubar integration

== Repository structure ==
{| class="wikitable"
|-
! Path
! Notes
|-
| <code>src/</code>
| Main compositor, runtime, renderer, input, backend, and bridge code
|-
| <code>lib/</code>
| Shared client-side support libraries
|-
| <code>include/plexy/</code>
| Public headers for application authors
|-
| <code>examples/</code>
| Small standalone sample applications
|-
| <code>apps/</code>
| Larger experiments such as terminal, browser, clock, and utilities
|-
| <code>tasks/</code>
| Engineering notes and implementation logs
|}

== Development note ==
The Makefile notes that the old <code>src/uikit/</code> code remains in the repository, but is no longer compiled into the compositor. The compositor now consumes the canvas library through the C API instead.

== Related pages ==
* [[Getting Started]]
* [[Developer Guide]]
* [[Examples]]

Getting Started

2026-03-21T19:32:54Z

Plexydesk: Add getting started guide

= Getting Started =

This page is the fastest path from a fresh clone to a running PlexyDesk build.

== Recommended environment ==
PlexyDesk is currently easiest to build on Debian or Ubuntu style systems with a working GPU stack, DRM/KMS access, and a user session where you can start the compositor from a TTY.

== Install dependencies ==
Run the dependency installer from the repository root:

<pre>
./install-deps.sh
</pre>

The script installs:
* build tools such as <code>gcc</code>, <code>g++</code>, <code>meson</code>, and <code>ninja</code>
* graphics libraries including DRM, GBM, EGL, OpenGL, GLEW, and related Mesa packages
* input and system libraries such as <code>libinput</code>, <code>libudev</code>, and <code>libsystemd</code>
* Wayland and X11/Xorg development packages
* font and text rendering packages including Pango, FreeType, and Fontconfig
* optional WebKitGTK support for browser-oriented examples

== Build the project ==
Release build:

<pre>
make
</pre>

Debug build with verbose logging:

<pre>
BUILD_MODE=debug make
</pre>

The Makefile defaults to a release build and applies aggressive optimization flags there. Debug mode keeps symbols and turns on additional logging macros.

== Run PlexyDesk ==
The simplest direct launch is:

<pre>
./plexyshell
</pre>

== Run with systemd user units ==
System installs and package installs place user units for the shell runtime:
* <code>plexy.slice</code>
* <code>plexyshell.service</code>

Typical flow:

<pre>
make install
systemctl --user start plexyshell.service
./scripts/systemd/status-plexyshell-service.sh
</pre>

For a development machine where you do not want a system-wide install, use:

<pre>
./scripts/systemd/install-user-units.sh
</pre>

== Build a .deb package ==
The repository includes a Docker-assisted package flow for Ubuntu:

<pre>
chmod +x scripts/docker-build-ubuntu-deb.sh
./scripts/docker-build-ubuntu-deb.sh 22.04 dist
# or
./scripts/docker-build-ubuntu-deb.sh 24.04 dist
</pre>

The package is written into <code>dist/</code>. After installing it on a target machine, launch PlexyDesk with:

<pre>
plexydesk
</pre>

Run it as your normal user from a TTY session, not as root.

== Configuration ==
The example configuration file documents the supported sections and defaults. Expected locations are:
* <code>$XDG_CONFIG_HOME/plexyshell/plexyshell.conf</code>
* <code>/etc/plexyshell/plexyshell.conf</code>

Common sections include:
* <code>[appearance]</code> for theme and scale factor
* <code>[display]</code> and <code>[display_layout:...]</code> for monitor placement
* <code>[background]</code> for wallpaper or animated background
* <code>[compositor]</code> for window chrome and effect tuning
* <code>[dock]</code> and <code>[menubar]</code> for shell behavior
* <code>[terminal]</code> for terminal fonts and colors

== Basic controls ==
{| class="wikitable"
|-
! Input
! Action
|-
| Mouse drag
| Move a window
|-
| Corner drag
| Resize a window
|-
| Tab
| Cycle windows
|-
| F6
| Toggle cylindrical desktop mode
|-
| W / Q
| Close focused window
|-
| Esc
| Exit
|}

== Where to go next ==
* [[Architecture]] for how the compositor and client stack fit together
* [[Developer Guide]] for the important source files and build entry points
* [[Examples]] for code you can compile and extend