# SDK: Ereignisse und Kontext > app.context, jedes Ereignis von app.on und jede Frage von app.answer, mit ihren Daten. Source: https://pithyx.org/de/docs/reference/sdk/events-context/ Markdown: https://pithyx.org/de/docs/reference/sdk/events-context.md `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 ### LaunchArgs Why and with what the app's window was opened, in the context and with `launch`. #### Eigenschaften ##### args ```ts args: unknown; ``` App-defined arguments, for example a view to show. ##### file? ```ts optional file?: FileRef; ``` A file to open, only of a type the manifest's `fileHandlers` declare. ##### notification? ```ts optional notification?: NotificationActivation; ``` The user clicked a notification of the app while no window of it was open (see `notificationAction`). --- ### GroupRef One of the user's groups. The built-in group every user belongs to is left out. #### Eigenschaften ##### id ```ts id: number; ``` Stable id (the group's Linux gid). ##### name ```ts name: string; ``` The group's name. --- ### AppContext Everything an app needs to start, sent once in `init`. No permission is needed for any of it. #### Eigenschaften ##### app ```ts app: object; ``` The app itself. ###### id ```ts id: string; ``` The app id from the manifest, such as `com.example.notes`. ###### version ```ts version: string; ``` The installed version of the app. ##### instance ```ts instance: string; ``` Id of this window, unique per desktop tab. ##### user ```ts 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 ```ts id: number; ``` Stable id of the user: the Linux uid, also `X-Pithyx-User-Id` for the backend; never given to another user. ###### name ```ts name: string; ``` The user name, lower case. ###### displayName ```ts displayName: string | null; ``` The name to show, if the user set one. ###### groups ```ts groups: GroupRef[]; ``` The user's groups; listing other users and groups needs `directory.read`. ###### isAdmin ```ts isAdmin: boolean; ``` Whether the user is an administrator. ###### twoFactor ```ts twoFactor: boolean; ``` Whether the user signs in with a second factor. ##### language ```ts language: string; ``` The user's language for texts, a BCP 47 language tag such as `de`; `locale` starts with it. ##### locale ```ts 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 ```ts timeZone: string; ``` IANA time zone of the user, for example `Europe/Berlin`. Dates cross the API as UTC. ##### theme ```ts theme: Theme; ``` The desktop's look; the SDK has already applied it. `themeChange` replaces it. ##### sizeClass ```ts sizeClass: SizeClass; ``` The width class of the window; `sizeClassChange` follows it. ##### launch ```ts launch: LaunchArgs; ``` Why and with what the window was opened. ##### session ```ts session: unknown; ``` The state this window saved with `session.save` before a reload or on another device, or null. ##### permissions ```ts permissions: string[]; ``` Permissions this app holds now; `permissionsChange` replaces the list. ##### capabilities ```ts capabilities: string[]; ``` Every method name the desktop supports; check before calling one (see `supports`). ##### box ```ts box: object; ``` The box the app runs on: its name (host name) and the Pithyx version. ###### name ```ts name: string; ``` The box's host name. ###### version ```ts version: string; ``` The Pithyx version of the box. ##### visible ```ts visible: boolean; ``` Whether the window can be seen (not minimized); `visibilityChange` follows it. ##### online ```ts online: boolean; ``` Whether the desktop reaches the box; `connectionChange` follows it. ##### logLevel ```ts logLevel: AppLogLevel; ``` Whether `debug` log entries reach the daemon; `logLevelChange` follows it. ##### backend ```ts backend: BackendInfo | null; ``` The app's backend, or null for an app without one. `backendStatus` follows its status. ##### storage ```ts storage: StorageInfo[]; ``` The storage requests of the manifest with their state; `storageChange` replaces the list. ##### host ```ts host: object; ``` The desktop that serves the app. ###### version ```ts version: string; ``` The SDK version of the desktop. ###### protocol ```ts protocol: number; ``` The protocol version both sides use. --- ### Events Events the desktop sends. An app ignores events it does not know, so new events are a minor change. #### Eigenschaften ##### launch ```ts launch: LaunchArgs; ``` A `single` app was launched again; the new launch arguments. ##### focus ```ts focus: Record; ``` The window got the focus. ##### blur ```ts blur: Record; ``` The window lost the focus. ##### minimize ```ts minimize: Record; ``` The window was minimized. ##### restore ```ts restore: Record; ``` The window was shown again after it was minimized. ##### themeChange ```ts themeChange: Theme; ``` The look changed (light or dark, accent, density); the SDK has applied it and updated `context.theme`. ##### localeChange ```ts localeChange: object; ``` The user changed language, formats or time zone. The SDK updates the context and `app.format` follows. ###### language ```ts language: string; ``` The new language for texts. ###### locale ```ts locale: string; ``` The new BCP 47 tag for formats. ###### timeZone ```ts timeZone: string; ``` The new IANA time zone. ##### sizeClassChange ```ts sizeClassChange: object; ``` The window crossed a width class. The SDK updates `context.sizeClass`. ###### sizeClass ```ts sizeClass: SizeClass; ``` The new width class. ##### openFile ```ts openFile: object; ``` The user opened a file with the app while its window was open. Only types from `fileHandlers`. ###### file ```ts file: FileRef; ``` The file to open. ##### appUpdated ```ts appUpdated: object; ``` Another version of the app is installed, by an update or a rollback; reload to use it (unsaved work first). ###### version ```ts version: string; ``` The new version. ##### visibilityChange ```ts 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 ```ts visible: boolean; ``` Whether the window can be seen. ##### connectionChange ```ts connectionChange: object; ``` The desktop lost or regained the connection to the box, for example while it restarts. Updates `context.online`. ###### online ```ts online: boolean; ``` Whether the desktop reaches the box. ##### backendStatus ```ts backendStatus: object; ``` The backend's status changed. The SDK updates `context.backend.status` and `context.backend.reason`. ###### status ```ts status: BackendStatus; ``` The new status. ###### reason? ```ts optional reason?: BackendUnavailableReason; ``` Why the backend cannot start, only while it is `unavailable` for that reason. ##### permissionsChange ```ts 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`](https://pithyx.org/de/docs/reference/errors/#app.permission.denied). Revoking access to the app ends its windows. ###### permissions ```ts permissions: string[]; ``` Every permission the app holds now. ##### storageChange ```ts storageChange: object; ``` A storage mapping changed, or its pool was locked or came back. The SDK replaces `context.storage`. ###### storage ```ts storage: StorageInfo[]; ``` Every storage request with its state now. ##### notificationAction ```ts notificationAction: NotificationActivation; ``` The user clicked a notification of the app or one of its buttons while a window of the app was open. ##### logLevelChange ```ts logLevelChange: object; ``` An administrator switched debug logging for the app on or off. The SDK updates `context.logLevel`. ###### level ```ts level: AppLogLevel; ``` The new log level. ##### sharesChanged ```ts sharesChanged: Record; ``` 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 ```ts folderChanged: FolderChange; ``` Changes of a folder watched with `files.watch`. ##### uploadProgress ```ts uploadProgress: UploadProgress; ``` Progress of an upload that has an `upload` id. ##### jobChanged ```ts jobChanged: JobInfo; ``` A job the app started changed: progress, then its final state. --- ### Queries Questions the desktop asks and waits for, each with the answer it expects. #### Eigenschaften ##### beforeClose ```ts 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 ```ts data: Record; ``` Carries nothing. ###### answer ```ts answer: object; ``` Whether the window may close. ###### answer.allow ```ts allow: boolean; ``` False keeps the window open. ##### beforeUnload ```ts 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 ```ts data: object; ``` Why the window goes away. ###### data.reason ```ts reason: UnloadReason; ``` Sign-out, shutdown, restart or update. ###### answer ```ts answer: Record; ``` Nothing; the answer is ignored. ## Typenaliasse ### EventHandler ```ts type EventHandler = (data) => void; ``` A listener for one event of the desktop, registered with `app.on`. #### Typenparameter | Typenparameter | | --------------------------------------- | | `E` _extends_ [`EventName`](#eventname) | #### Parameter | Parameter | Typ | Beschreibung | | --------- | -------------------------- | ------------------------------------------------------------- | | `data` | [`Events`](#events)\[`E`\] | What the event carries; see [Events](#events) for each event. | #### Rückgabewert `void` --- ### QueryHandler ```ts type QueryHandler = (data) => Queries[Q]['answer'] | Promise; ``` Answers one question of the desktop, registered with `app.answer`; may answer asynchronously. #### Typenparameter | Typenparameter | | --------------------------------------- | | `Q` _extends_ [`QueryName`](#queryname) | #### Parameter | Parameter | Typ | Beschreibung | | --------- | ---------------------------------------- | ---------------------------------------------------------------------- | | `data` | [`Queries`](#queries)\[`Q`\]\[`"data"`\] | What the desktop asks with; see [Queries](#queries) for each question. | #### Rückgabewert \| [`Queries`](#queries)\[`Q`\]\[`"answer"`\] \| `Promise`\<[`Queries`](#queries)\[`Q`\]\[`"answer"`\]\> The answer the question expects, or a promise of it. --- ### SizeClass ```ts 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 ```ts type AppLogLevel = 'debug' | 'info'; ``` Whether `debug` entries of `app.log` go to the daemon (`debug`) or only to the browser console (`info`). --- ### EventName ```ts type EventName = keyof Events; ``` The name of an event the desktop sends. --- ### UnloadReason ```ts type UnloadReason = 'logout' | 'shutdown' | 'restart' | 'update'; ``` Why `beforeUnload` is asked. --- ### QueryName ```ts type QueryName = keyof Queries; ``` The name of a question the desktop asks. ## Variablen ### BEFORE\_CLOSE\_TIMEOUT ```ts const BEFORE_CLOSE_TIMEOUT: 5000 = 5000; ``` The desktop waits this long for an answer to `beforeClose`. --- ### BEFORE\_UNLOAD\_TIMEOUT ```ts const BEFORE_UNLOAD_TIMEOUT: 2000 = 2000; ``` The desktop waits this long for an answer to `beforeUnload`.