SDK: Ereignisse und Kontext
app.context ist das, was der Desktop der App beim Start mitgeteilt hat, und wird durch die Ereignisse aktuell gehalten. app.on(event, handler) hört auf ein Ereignis, app.answer(query, handler) beantwortet eine Frage des Desktops.
Beim Build aus den TSDoc-Kommentaren von @pithyx/sdk 1.0.0-rc.9 erzeugt; der Text unter den Überschriften ist der Kommentar im Quelltext und bleibt Englisch.
Schnittstellen
Abschnitt betitelt „Schnittstellen“LaunchArgs
Abschnitt betitelt „LaunchArgs“Why and with what the app’s window was opened, in the context and with launch.
Eigenschaften
Abschnitt betitelt „Eigenschaften“args: unknown;App-defined arguments, for example a view to show.
optional file?: FileRef;A file to open, only of a type the manifest’s fileHandlers declare.
notification?
Abschnitt betitelt „notification?“optional notification?: NotificationActivation;The user clicked a notification of the app while no window of it was open (see notificationAction).
GroupRef
Abschnitt betitelt „GroupRef“One of the user’s groups. The built-in group every user belongs to is left out.
Eigenschaften
Abschnitt betitelt „Eigenschaften“id: number;Stable id (the group’s Linux gid).
name: string;The group’s name.
AppContext
Abschnitt betitelt „AppContext“Everything an app needs to start, sent once in init. No permission is needed for any of it.
Eigenschaften
Abschnitt betitelt „Eigenschaften“app: object;The app itself.
id: string;The app id from the manifest, such as com.example.notes.
version
Abschnitt betitelt „version“version: string;The installed version of the app.
instance
Abschnitt betitelt „instance“instance: string;Id of this window, unique per desktop tab.
user: object;The signed-in user, for display and to adapt the interface. A backend identifies the user only by the
X-Pithyx-User headers the proxy sets (see backend.token), never by anything the window sends.
id: number;Stable id of the user: the Linux uid, also X-Pithyx-User-Id for the backend; never given to another user.
name: string;The user name, lower case.
displayName
Abschnitt betitelt „displayName“displayName: string | null;The name to show, if the user set one.
groups: GroupRef[];The user’s groups; listing other users and groups needs directory.read.
isAdmin
Abschnitt betitelt „isAdmin“isAdmin: boolean;Whether the user is an administrator.
twoFactor
Abschnitt betitelt „twoFactor“twoFactor: boolean;Whether the user signs in with a second factor.
language
Abschnitt betitelt „language“language: string;The user’s language for texts, a BCP 47 language tag such as de; locale starts with it.
locale: string;BCP 47 tag for formats: the user’s language with the region of the box’s formats, for example de-AT. The SDK
sets it as lang on the app’s root element; the formatters (app.format) follow it.
timeZone
Abschnitt betitelt „timeZone“timeZone: string;IANA time zone of the user, for example Europe/Berlin. Dates cross the API as UTC.
theme: Theme;The desktop’s look; the SDK has already applied it. themeChange replaces it.
sizeClass
Abschnitt betitelt „sizeClass“sizeClass: SizeClass;The width class of the window; sizeClassChange follows it.
launch: LaunchArgs;Why and with what the window was opened.
session
Abschnitt betitelt „session“session: unknown;The state this window saved with session.save before a reload or on another device, or null.
permissions
Abschnitt betitelt „permissions“permissions: string[];Permissions this app holds now; permissionsChange replaces the list.
capabilities
Abschnitt betitelt „capabilities“capabilities: string[];Every method name the desktop supports; check before calling one (see supports).
box: object;The box the app runs on: its name (host name) and the Pithyx version.
name: string;The box’s host name.
version
Abschnitt betitelt „version“version: string;The Pithyx version of the box.
visible
Abschnitt betitelt „visible“visible: boolean;Whether the window can be seen (not minimized); visibilityChange follows it.
online: boolean;Whether the desktop reaches the box; connectionChange follows it.
logLevel
Abschnitt betitelt „logLevel“logLevel: AppLogLevel;Whether debug log entries reach the daemon; logLevelChange follows it.
backend
Abschnitt betitelt „backend“backend: BackendInfo | null;The app’s backend, or null for an app without one. backendStatus follows its status.
storage
Abschnitt betitelt „storage“storage: StorageInfo[];The storage requests of the manifest with their state; storageChange replaces the list.
host: object;The desktop that serves the app.
version
Abschnitt betitelt „version“version: string;The SDK version of the desktop.
protocol
Abschnitt betitelt „protocol“protocol: number;The protocol version both sides use.
Events the desktop sends. An app ignores events it does not know, so new events are a minor change.
Eigenschaften
Abschnitt betitelt „Eigenschaften“launch: LaunchArgs;A single app was launched again; the new launch arguments.
focus: Record<string, never>;The window got the focus.
blur: Record<string, never>;The window lost the focus.
minimize
Abschnitt betitelt „minimize“minimize: Record<string, never>;The window was minimized.
restore
Abschnitt betitelt „restore“restore: Record<string, never>;The window was shown again after it was minimized.
themeChange
Abschnitt betitelt „themeChange“themeChange: Theme;The look changed (light or dark, accent, density); the SDK has applied it and updated context.theme.
localeChange
Abschnitt betitelt „localeChange“localeChange: object;The user changed language, formats or time zone. The SDK updates the context and app.format follows.
language
Abschnitt betitelt „language“language: string;The new language for texts.
locale: string;The new BCP 47 tag for formats.
timeZone
Abschnitt betitelt „timeZone“timeZone: string;The new IANA time zone.
sizeClassChange
Abschnitt betitelt „sizeClassChange“sizeClassChange: object;The window crossed a width class. The SDK updates context.sizeClass.
sizeClass
Abschnitt betitelt „sizeClass“sizeClass: SizeClass;The new width class.
openFile
Abschnitt betitelt „openFile“openFile: object;The user opened a file with the app while its window was open. Only types from fileHandlers.
file: FileRef;The file to open.
appUpdated
Abschnitt betitelt „appUpdated“appUpdated: object;Another version of the app is installed, by an update or a rollback; reload to use it (unsaved work first).
version
Abschnitt betitelt „version“version: string;The new version.
visibilityChange
Abschnitt betitelt „visibilityChange“visibilityChange: object;The window was minimized or shown again. Minimizing does not change the frame’s own visibility, so this is the
way to pause work nobody sees. The SDK updates context.visible.
visible
Abschnitt betitelt „visible“visible: boolean;Whether the window can be seen.
connectionChange
Abschnitt betitelt „connectionChange“connectionChange: object;The desktop lost or regained the connection to the box, for example while it restarts. Updates context.online.
online: boolean;Whether the desktop reaches the box.
backendStatus
Abschnitt betitelt „backendStatus“backendStatus: object;The backend’s status changed. The SDK updates context.backend.status and context.backend.reason.
status: BackendStatus;The new status.
reason?
Abschnitt betitelt „reason?“optional reason?: BackendUnavailableReason;Why the backend cannot start, only while it is unavailable for that reason.
permissionsChange
Abschnitt betitelt „permissionsChange“permissionsChange: object;An administrator granted or revoked permissions of the app; permissions is the complete new list. The SDK
replaces context.permissions; calls that need a revoked permission fail with app.permission.denied. Revoking
access to the app ends its windows.
permissions
Abschnitt betitelt „permissions“permissions: string[];Every permission the app holds now.
storageChange
Abschnitt betitelt „storageChange“storageChange: object;A storage mapping changed, or its pool was locked or came back. The SDK replaces context.storage.
storage
Abschnitt betitelt „storage“storage: StorageInfo[];Every storage request with its state now.
notificationAction
Abschnitt betitelt „notificationAction“notificationAction: NotificationActivation;The user clicked a notification of the app or one of its buttons while a window of the app was open.
logLevelChange
Abschnitt betitelt „logLevelChange“logLevelChange: object;An administrator switched debug logging for the app on or off. The SDK updates context.logLevel.
level: AppLogLevel;The new log level.
sharesChanged
Abschnitt betitelt „sharesChanged“sharesChanged: Record<string, never>;The list of shares the user can use may have changed: a share was created, renamed, described or deleted, or the
user’s access changed. Call files.shares again. Sent only to apps that hold files.shares; it carries nothing,
so it never tells an app about shares the user cannot use.
folderChanged
Abschnitt betitelt „folderChanged“folderChanged: FolderChange;Changes of a folder watched with files.watch.
uploadProgress
Abschnitt betitelt „uploadProgress“uploadProgress: UploadProgress;Progress of an upload that has an upload id.
jobChanged
Abschnitt betitelt „jobChanged“jobChanged: JobInfo;A job the app started changed: progress, then its final state.
Queries
Abschnitt betitelt „Queries“Questions the desktop asks and waits for, each with the answer it expects.
Eigenschaften
Abschnitt betitelt „Eigenschaften“beforeClose
Abschnitt betitelt „beforeClose“beforeClose: object;The user closes the window. Answer allow: false to keep it open (for example to ask about unsaved changes).
The desktop waits at most 5 seconds and then offers to close the window anyway. See window.setDirty.
data: Record<string, never>;Carries nothing.
answer: object;Whether the window may close.
answer.allow
Abschnitt betitelt „answer.allow“allow: boolean;False keeps the window open.
beforeUnload
Abschnitt betitelt „beforeUnload“beforeUnload: object;The window is about to go away: the user signs out (logout), the box shuts down or restarts, or Pithyx installs
an update. Save what you can; the desktop waits at most 2 seconds. It cannot be refused.
data: object;Why the window goes away.
data.reason
Abschnitt betitelt „data.reason“reason: UnloadReason;Sign-out, shutdown, restart or update.
answer: Record<string, never>;Nothing; the answer is ignored.
Typenaliasse
Abschnitt betitelt „Typenaliasse“EventHandler
Abschnitt betitelt „EventHandler“type EventHandler<E> = (data) => void;A listener for one event of the desktop, registered with app.on.
Typenparameter
Abschnitt betitelt „Typenparameter“| Typenparameter |
|---|
E extends EventName |
Parameter
Abschnitt betitelt „Parameter“| Parameter | Typ | Beschreibung |
|---|---|---|
data |
Events[E] |
What the event carries; see Events for each event. |
Rückgabewert
Abschnitt betitelt „Rückgabewert“void
QueryHandler
Abschnitt betitelt „QueryHandler“type QueryHandler<Q> = (data) => Queries[Q]['answer'] | Promise<Queries[Q]['answer']>;Answers one question of the desktop, registered with app.answer; may answer asynchronously.
Typenparameter
Abschnitt betitelt „Typenparameter“| Typenparameter |
|---|
Q extends QueryName |
Parameter
Abschnitt betitelt „Parameter“| Parameter | Typ | Beschreibung |
|---|---|---|
data |
Queries[Q]["data"] |
What the desktop asks with; see Queries for each question. |
Rückgabewert
Abschnitt betitelt „Rückgabewert“| Queries[Q]["answer"]
| Promise<Queries[Q]["answer"]>
The answer the question expects, or a promise of it.
SizeClass
Abschnitt betitelt „SizeClass“type SizeClass = 'compact' | 'medium' | 'expanded';The size class of the app’s window: compact below 600 px, medium up to 1023 px, expanded above (see the desktop).
AppLogLevel
Abschnitt betitelt „AppLogLevel“type AppLogLevel = 'debug' | 'info';Whether debug entries of app.log go to the daemon (debug) or only to the browser console (info).
EventName
Abschnitt betitelt „EventName“type EventName = keyof Events;The name of an event the desktop sends.
UnloadReason
Abschnitt betitelt „UnloadReason“type UnloadReason = 'logout' | 'shutdown' | 'restart' | 'update';Why beforeUnload is asked.
QueryName
Abschnitt betitelt „QueryName“type QueryName = keyof Queries;The name of a question the desktop asks.
Variablen
Abschnitt betitelt „Variablen“BEFORE_CLOSE_TIMEOUT
Abschnitt betitelt „BEFORE_CLOSE_TIMEOUT“const BEFORE_CLOSE_TIMEOUT: 5000 = 5000;The desktop waits this long for an answer to beforeClose.
BEFORE_UNLOAD_TIMEOUT
Abschnitt betitelt „BEFORE_UNLOAD_TIMEOUT“const BEFORE_UNLOAD_TIMEOUT: 2000 = 2000;The desktop waits this long for an answer to beforeUnload.