RedWizardsLab/EchoHub
1
0
Fork 0
mirror of https://github.com/RedWizardsLab/EchoHub.git synced 2026-09-07 07:36:01 +02:00
Code Issues 2 Packages Projects Releases 10 Wiki Activity

deploy: 0105f798e0

Browse Source
This commit is contained in:
HueByte
2026-07-23 09:48:40 +00:00
parent 37bd8c0f57
commit 32c664518a
144 changed files with 5098 additions and 6498 deletions
Download Patch File Download Diff File Expand all files Collapse all files
auriondocs/Synthesis/clipboard-tools.md
+9 -11
View File
@@ -1,31 +1,29 @@
# Clipboard utilities
> Helpers for clipboard interactions: files and images.
> Clipboard helpers for files and images used in the UI.
This guide describes the clipboard-focused utilities in the client: one helper that exposes file-list clipboard contents, another that normalizes image clipboard data into PNG bytes, and the UI entry points that call those helpers to stage attachments or consume images.
This topic covers small, focused helpers that let the UI treat clipboard contents as first-class attachments: one helper extracts file paths from a file-list clipboard, another canonicalizes whatever image bytes are available into a PNG, and the window UI calls them when the user pastes or triggers clipboard-driven actions. The helpers centralize platform differences (Windows, Linux, macOS fallbacks) and intentionally present a simple success/failure API so the UI can degrade gracefully when clipboard content or platform support is missing.
## ClipboardFiles.cs
Clipboard file utilities for handling file lists.
Provides clipboard file handling utilities.
The [ClipboardFiles](../Code/src/EchoHub.Client/Services/ClipboardFiles.cs.md) static class provides a single, platform-aware API (exposed via TryGetFiles) to read file paths when the OS clipboard contains a file-list. It hides OS-specific handling—on Windows it reads CF_HDROP with a short retry loop to tolerate clipboard contention, on Linux it uses text/uri-list through wl-paste or xclip—and it performs existence checks and filters out non-file entries so callers receive only existing paths. TryGetFiles returns true only when at least one valid file path is found, otherwise false, allowing callers to fall back if no usable file-list is present; this class is consumed by the UI layer ([MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md)).
The [ClipboardFiles](../Code/src/EchoHub.Client/Services/ClipboardFiles.cs.md) type is a static helper that exposes a single, simple consumption pattern: call TryGetFiles to ask the OS clipboard for a list of file paths. TryGetFiles returns true only when one or more existing file paths are discovered; it filters out non-existent or malformed entries and returns false on platforms that don’t support a file-list clipboard or when no valid paths are present. Internally the helper normalizes platform differences (CF_HDROP on Windows, text/uri-list on Linux using command-line helpers) and logs exceptions rather than throwing, so callers receive a boolean+list result they can act on without having to catch clipboard-specific exceptions. In the app this helper is consumed by the UI layer: the [MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md) calls into ClipboardFiles.TryGetFiles to obtain file paths to be staged or attached.
## ClipboardImage.cs
Clipboard image utilities for copying images to the clipboard.
Provides clipboard image utilities.
The [ClipboardImage](../Code/src/EchoHub.Client/Services/ClipboardImage.cs.md) static class exposes TryGetPng to extract whatever image is currently on the OS clipboard and return it as PNG-encoded bytes suitable for saving, embedding, or transmitting. It normalizes multiple clipboard image formats: it prefers a native PNG clipboard format to preserve alpha, and falls back to platform bitmaps (CF_DIB on Windows) by wrapping DIB bytes in a minimal BMP header and decoding/re-encoding to PNG via DibToPng; malformed DIB input yields null and TryGetPng surfaces that as a failure (false). TryGetPng routes to OS-specific helpers, logs errors rather than throwing, and returns false on unsupported platforms or on failure; [MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md) depends on this helper to obtain clipboard image bytes.
The [ClipboardImage](../Code/src/EchoHub.Client/Services/ClipboardImage.cs.md) static class exposes TryGetPng to produce a canonical PNG byte array from whatever image representation the OS clipboard currently holds. TryGetPng dispatches platform-specific work to methods such as TryGetWindows, TryGetLinux, or TryGetMacOS based on runtime OperatingSystem checks, preserves native PNG clipboard bytes when present (using PngMagic or platform-registered formats), and converts other formats — notably DIB/CF_DIB on Windows — by wrapping the DIB in a minimal BMP and using an image loader to re-encode as PNG via the DibToPng helper. The API favors robustness: all clipboard- and image-decoding exceptions are logged and swallowed so callers get a simple true/false outcome, and the docs call out platform and threading caveats (for example, STA requirements on Windows and header validation for DIB inputs). The [MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md) uses ClipboardImage.TryGetPng when it needs a pasteable PNG payload from the clipboard for staging or insertion.
## MainWindow.cs
`MainWindow` collaborates directly with `ClipboardFiles` and other members of this topic (2 dependency links).
The [MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md) UI class defines a large set of interactive behaviors and a handful of members that interact with the clipboard: notably methods named StageFiles, SetStagedAttachments and GuardedClipboardAction appear in its surface. Per the documented relationships, MainWindow delegates platform specifics to the clipboard helpers: it invokes [ClipboardFiles](../Code/src/EchoHub.Client/Services/ClipboardFiles.cs.md).TryGetFiles to obtain file paths copied by the user and then uses its own staging APIs (SetStagedAttachments/StageFiles) to prepare those paths for attachment. Likewise, MainWindow can call [ClipboardImage](../Code/src/EchoHub.Client/Services/ClipboardImage.cs.md).TryGetPng to obtain a normalized PNG byte array when the user has copied an image, allowing the UI to save, embed, or attach that image without per-OS handling. GuardedClipboardAction provides a place to centralize error handling and UI feedback around those clipboard calls so failures from the helpers (they return false rather than throwing) can be handled gracefully.
The [MainWindow](../Code/src/EchoHub.Client/UI/MainWindow.cs.md) source defines the interactive UI surface and numerous event handlers and helpers related to input, message lists, and clipboard interactions. Of particular relevance to this topic are methods such as GuardedClipboardAction, StageFiles, SetStagedAttachments, and CopyToClipboard: GuardedClipboardAction is the safe wrapper for performing clipboard operations (honoring the helpers’ failure semantics), StageFiles and SetStagedAttachments are the paths by which file lists or image bytes obtained from the clipboard are moved into the UI’s pending-attachment state, and CopyToClipboard implements copy behavior the UI exposes. When a paste or clipboard-driven accept occurs, MainWindow calls into the clipboard helpers — invoking [ClipboardImage](../Code/src/EchoHub.Client/Services/ClipboardImage.cs.md).TryGetPng to request a PNG payload or [ClipboardFiles](../Code/src/EchoHub.Client/Services/ClipboardFiles.cs.md).TryGetFiles to obtain file paths — and then uses its staging methods to present those attachments to the rest of the UI or to the send/attach pipeline.
How the pieces fit
- The two service classes encapsulate platform-specific clipboard concerns: [ClipboardFiles] returns a filtered list of existing file paths or false; [ClipboardImage] returns a PNG byte array or false.
- [MainWindow] orchestrates user-facing clipboard flows: it calls those helpers from StageFiles/SetStagedAttachments and related clipboard actions, then integrates the results into the message-composition and attachment UI.
- The helpers favor returning a simple success/failure result (and normalized data) so the UI can decide whether to stage attachments, embed image bytes, or fall back to alternative input methods.
MainWindow is the orchestrator: on paste or clipboard actions it uses GuardedClipboardAction to safely call the two helpers and translate their boolean+payload results into staged attachments (files or PNG bytes). The clipboard helpers isolate platform differences and error handling so the window code only needs to check success/failure and process the returned paths or bytes. This keeps clipboard I/O contained in small, testable utilities while the window code focuses on user flow and attachment lifecycle.
---
*Covers 3 of 3 source files identified for this topic.*
*Synthesised by Aurion on 2026-07-23 05:53:51 UTC*
*Synthesised by AurionDocs on 2026-07-23 09:33:02 UTC*