SDK: events and context
app.context is what the desktop told the app at start, kept current by the events. app.on(event, handler) listens to an event and app.answer(query, handler) answers a question of the desktop.
Generated from the TSDoc comments of @pithyx/sdk 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.
Interfaces
Section titled “Interfaces”LaunchArgs
Section titled “LaunchArgs”Why and with what the app’s window was opened, in the context and with launch.
Properties
Section titled “Properties”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?
Section titled “notification?”optional notification?: NotificationActivation;The user clicked a notification of the app while no window of it was open (see notificationAction).
GroupRef
Section titled “GroupRef”One of the user’s groups. The built-in group every user belongs to is left out.
Properties
Section titled “Properties”id: number;Stable id (the group’s Linux gid).
name: string;The group’s name.
AppContext
Section titled “AppContext”Everything an app needs to start, sent once in init. No permission is needed for any of it.
Properties
Section titled “Properties”app: object;The app itself.
id: string;The app id from the manifest, such as com.example.notes.
version
Section titled “version”version: string;The installed version of the app.
instance
Section titled “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
Section titled “displayName”displayName: string | null;The name to show, if the user set one.
groups
Section titled “groups”groups: GroupRef[];The user’s groups; listing other users and groups needs directory.read.
isAdmin
Section titled “isAdmin”isAdmin: boolean;Whether the user is an administrator.
twoFactor
Section titled “twoFactor”twoFactor: boolean;Whether the user signs in with a second factor.
language
Section titled “language”language: string;The user’s language for texts, a BCP 47 language tag such as de; locale starts with it.
locale
Section titled “locale”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
Section titled “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
Section titled “sizeClass”sizeClass: SizeClass;The width class of the window; sizeClassChange follows it.
launch
Section titled “launch”launch: LaunchArgs;Why and with what the window was opened.
session
Section titled “session”session: unknown;The state this window saved with session.save before a reload or on another device, or null.
permissions
Section titled “permissions”permissions: string[];Permissions this app holds now; permissionsChange replaces the list.
capabilities
Section titled “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
Section titled “version”version: string;The Pithyx version of the box.
visible
Section titled “visible”visible: boolean;Whether the window can be seen (not minimized); visibilityChange follows it.
online
Section titled “online”online: boolean;Whether the desktop reaches the box; connectionChange follows it.
logLevel
Section titled “logLevel”logLevel: AppLogLevel;Whether debug log entries reach the daemon; logLevelChange follows it.
backend
Section titled “backend”backend: BackendInfo | null;The app’s backend, or null for an app without one. backendStatus follows its status.
storage
Section titled “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
Section titled “version”version: string;The SDK version of the desktop.
protocol
Section titled “protocol”protocol: number;The protocol version both sides use.
Events
Section titled “Events”Events the desktop sends. An app ignores events it does not know, so new events are a minor change.
Properties
Section titled “Properties”launch
Section titled “launch”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
Section titled “minimize”minimize: Record<string, never>;The window was minimized.
restore
Section titled “restore”restore: Record<string, never>;The window was shown again after it was minimized.
themeChange
Section titled “themeChange”themeChange: Theme;The look changed (light or dark, accent, density); the SDK has applied it and updated context.theme.
localeChange
Section titled “localeChange”localeChange: object;The user changed language, formats or time zone. The SDK updates the context and app.format follows.
language
Section titled “language”language: string;The new language for texts.
locale
Section titled “locale”locale: string;The new BCP 47 tag for formats.
timeZone
Section titled “timeZone”timeZone: string;The new IANA time zone.
sizeClassChange
Section titled “sizeClassChange”sizeClassChange: object;The window crossed a width class. The SDK updates context.sizeClass.
sizeClass
Section titled “sizeClass”sizeClass: SizeClass;The new width class.
openFile
Section titled “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
Section titled “appUpdated”appUpdated: object;Another version of the app is installed, by an update or a rollback; reload to use it (unsaved work first).
version
Section titled “version”version: string;The new version.
visibilityChange
Section titled “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
Section titled “visible”visible: boolean;Whether the window can be seen.
connectionChange
Section titled “connectionChange”connectionChange: object;The desktop lost or regained the connection to the box, for example while it restarts. Updates context.online.
online
Section titled “online”online: boolean;Whether the desktop reaches the box.
backendStatus
Section titled “backendStatus”backendStatus: object;The backend’s status changed. The SDK updates context.backend.status and context.backend.reason.
status
Section titled “status”status: BackendStatus;The new status.
reason?
Section titled “reason?”optional reason?: BackendUnavailableReason;Why the backend cannot start, only while it is unavailable for that reason.
permissionsChange
Section titled “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
Section titled “permissions”permissions: string[];Every permission the app holds now.
storageChange
Section titled “storageChange”storageChange: object;A storage mapping changed, or its pool was locked or came back. The SDK replaces context.storage.
storage
Section titled “storage”storage: StorageInfo[];Every storage request with its state now.
notificationAction
Section titled “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
Section titled “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
Section titled “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
Section titled “folderChanged”folderChanged: FolderChange;Changes of a folder watched with files.watch.
uploadProgress
Section titled “uploadProgress”uploadProgress: UploadProgress;Progress of an upload that has an upload id.
jobChanged
Section titled “jobChanged”jobChanged: JobInfo;A job the app started changed: progress, then its final state.
Queries
Section titled “Queries”Questions the desktop asks and waits for, each with the answer it expects.
Properties
Section titled “Properties”beforeClose
Section titled “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
Section titled “answer”answer: object;Whether the window may close.
answer.allow
Section titled “answer.allow”allow: boolean;False keeps the window open.
beforeUnload
Section titled “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
Section titled “data.reason”reason: UnloadReason;Sign-out, shutdown, restart or update.
answer
Section titled “answer”answer: Record<string, never>;Nothing; the answer is ignored.
Type Aliases
Section titled “Type Aliases”EventHandler
Section titled “EventHandler”type EventHandler<E> = (data) => void;A listener for one event of the desktop, registered with app.on.
Type Parameters
Section titled “Type Parameters”| Type Parameter |
|---|
E extends EventName |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
Events[E] |
What the event carries; see Events for each event. |
Returns
Section titled “Returns”void
QueryHandler
Section titled “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.
Type Parameters
Section titled “Type Parameters”| Type Parameter |
|---|
Q extends QueryName |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
data |
Queries[Q]["data"] |
What the desktop asks with; see Queries for each question. |
Returns
Section titled “Returns”| Queries[Q]["answer"]
| Promise<Queries[Q]["answer"]>
The answer the question expects, or a promise of it.
SizeClass
Section titled “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
Section titled “AppLogLevel”type AppLogLevel = 'debug' | 'info';Whether debug entries of app.log go to the daemon (debug) or only to the browser console (info).
EventName
Section titled “EventName”type EventName = keyof Events;The name of an event the desktop sends.
UnloadReason
Section titled “UnloadReason”type UnloadReason = 'logout' | 'shutdown' | 'restart' | 'update';Why beforeUnload is asked.
QueryName
Section titled “QueryName”type QueryName = keyof Queries;The name of a question the desktop asks.
Variables
Section titled “Variables”BEFORE_CLOSE_TIMEOUT
Section titled “BEFORE_CLOSE_TIMEOUT”const BEFORE_CLOSE_TIMEOUT: 5000 = 5000;The desktop waits this long for an answer to beforeClose.
BEFORE_UNLOAD_TIMEOUT
Section titled “BEFORE_UNLOAD_TIMEOUT”const BEFORE_UNLOAD_TIMEOUT: 2000 = 2000;The desktop waits this long for an answer to beforeUnload.