Reference: desktop services¶
Capabilities, desktop preferences, clipboard, opening URLs and files, and native file dialogs. How-to: File dialogs, Clipboard.
Desktop services depend on the operating system and session. In the host's headless test mode
(NATIVEHTMLKIT_TEST_MODE=1) clipboard, file dialogs, external open and attention requests are
refused with NativeHTMLKit.RpcException (code -32001, unsupported). Check
Get-NativeHTMLKitCapabilities and handle RpcException instead of assuming a service exists.
Get-NativeHTMLKitCapabilities¶
Alias: Get-NHKCapabilities
Returns what the running host offers (host.capabilities).
Get-NativeHTMLKitCapabilities [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
Returns an object. Top-level fields for Core 1.0.3 include native and headless,
platform (linux, windows), max_windows, max_documents, renderer (cpu), css_profile,
window_positioning, limits (frame_bytes, pending_requests, ...), the service booleans
clipboard_text, file_dialogs, external_open, drag_drop, ime, accessibility (enabled API
surfaces; $false in headless mode), features (per-feature implemented/available detail; null
means not observed) and native_preferences.
$caps = Get-NativeHTMLKitCapabilities -Application $app
if (-not $caps.file_dialogs) { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element browse -Name disabled }
Get-NativeHTMLKitPreferences¶
Alias: Get-NHKPreferences
Returns the observed desktop preferences (desktop.preferences): color_scheme,
reduced_motion, high_contrast (each $null when not observed), available, source
(headless in test mode), revision and scope. Changes are announced by the
desktop.preferences_changed notification (see Register-NativeHTMLKitNotification). Documents
follow the observed preferences in CSS media queries unless overridden with
Set-NativeHTMLKitEnvironment.
Get-NativeHTMLKitPreferences [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
Get-NativeHTMLKitClipboard¶
Alias: Get-NHKClipboard
Reads plain text from the system clipboard (clipboard.read_text).
Get-NativeHTMLKitClipboard [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
Returns [string] (empty when the clipboard holds no text). Errors NativeHTMLKit.RpcException
when the clipboard is unavailable (headless: Clipboard requires a native event loop).
Set-NativeHTMLKitClipboard¶
Alias: Set-NHKClipboard
Writes plain text to the system clipboard (clipboard.write_text).
Set-NativeHTMLKitClipboard [-Application] <Object> [-Text] <string> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
-Text |
string |
yes | - | Text to copy. May be empty. |
Errors as for Get-NativeHTMLKitClipboard.
Open-NativeHTMLKitExternal¶
Alias: Open-NHKExternal
Opens a URL or a document with the desktop's default handler (desktop.open_external), or with
-Reveal shows a file in the file manager (desktop.reveal_file; the path is resolved against the
PowerShell location). Accepted targets are http, https, mailto and file URIs and absolute
local paths; a relative path fails with code -32602, other schemes and executable file types
(programs, scripts, shortcuts) are denied with code -32003.
-Window names the parent window for any desktop prompt. Waits up to 60 seconds.
Open-NativeHTMLKitExternal [-Application] <Object> [-Target] <string> [[-Window] <Object>] [-Reveal] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
-Target |
string |
yes | - | URI or absolute path; with -Reveal a file path (relative paths are resolved against the PowerShell location). |
-Window |
NativeHTMLKit.Window |
no | - | Parent window; must belong to -Application. |
-Reveal |
switch |
no | off | Show the file in the file manager instead of opening it. |
Returns the host result (accepted, cancelled, ...).
Show-NativeHTMLKitFileDialog¶
Alias: Show-NHKFileDialog
Shows a native Open, Save or Choose-folder dialog attached to a window (dialog.open_files,
dialog.save_file, dialog.choose_folder) and waits without a deadline while the user decides,
pumping events meanwhile. Only one native dialog per window can be open at a time (a second one
fails with code -32005, busy).
Show-NativeHTMLKitFileDialog [-Window] <Object> [[-Kind] <string>] [[-Title] <string>] [[-Directory] <string>] [[-FileName] <string>] [[-Filters] <Object[]>] [[-Multiple] <bool>] [-NoWait] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Window |
NativeHTMLKit.Window |
yes | - | Parent window. |
-Kind |
string |
no | 'OpenFiles' |
OpenFiles, SaveFile or ChooseFolder. One of: OpenFiles, SaveFile, ChooseFolder. |
-Title |
string |
no | - | Dialog title. |
-Directory |
string |
no | - | Initial folder (resolved against the PowerShell location). |
-FileName |
string |
no | - | Suggested file name; only with -Kind SaveFile. |
-Filters |
object[] |
no | @() |
Array of @{ name = 'Images'; extensions = @('png', 'jpg') } (extensions without dot). Ignored for ChooseFolder. |
-Multiple |
bool |
no | $false |
OpenFiles only: allow several files. |
-NoWait |
switch |
no | off | Return a NativeHTMLKit.Request immediately instead of waiting. |
Returns @{ cancelled; paths }: cancelled is $true and paths empty when the user
cancelled. With -NoWait, a NativeHTMLKit.Request: Wait-NativeHTMLKitRpc returns the same
result later, Stop-NativeHTMLKitRpc closes the dialog. Errors NativeHTMLKit.RpcException
when dialogs are unavailable (headless: code -32001 Native file dialogs are unavailable in headless mode).
try {
$pick = Show-NativeHTMLKitFileDialog -Window $window -Kind OpenFiles -Multiple $true -Title 'Import logs' -Filters @(@{ name = 'Logs'; extensions = @('log', 'txt') })
if (-not $pick.cancelled) { foreach ($path in $pick.paths) { Import-Log $path } }
} catch [NativeHTMLKit.RpcException] {
Set-NativeHTMLKitDocumentText -Document $doc -Element status -Text $_.Exception.RpcMessage
}
Source: nativehtmlkit-powershell/docs/reference/desktop.md ยท edit the page there.