The services around a program's windows are requests of a window, answered by a completion like every other: the platform may ask the user first or answer late, and a platform without the service answers mwin_outcomeUnsupported. The window is the one the platform places what it shows against.
mwinWindow_RequestFileDialog opens the platform's dialog for one file, several files, a file to save, or a folder (mwinDefaultFileDialogDef), with a title, a starting folder, the name a save dialog offers, and filters. Frames go on while it shows.
; ("png;jpg"), matched in any case, so they mean the same everywhere. Folder dialogs ignore them; no filters offers every file.mwinRequest_GetDialogFiles copies out the chosen paths under the request's id, absolute, UTF-8, each ended by a NUL. Closing the dialog completes the request cancelled; more than dialogFiles paths or dialogBytes bytes completes it too large.truncatedOut says so, as a drop's truncated does. That covers a path that is not UTF-8, a portal's choice that is no local file, an item with no file system path on Windows, and a document Android could not read or copy. When no chosen file is left, the dialog completes failed. The limits work differently: a choice past them completes too large as a whole, because a limit says nothing about which files to keep.| Platform | The dialog |
|---|---|
| Windows | The common item dialog, owned by the window. |
| macOS | An open or save panel as a sheet on its window, with the filters as a menu under it. |
| Linux | The desktop portal's file chooser over the session bus, else zenity. |
| iOS | The document picker. Opened files are the application's copies; a save exports an empty file to the place chosen, which the program then writes. |
| Android | The document picker; documents are copied into the application's cache between frames, and one whose application sends nothing for five seconds is left out, the answer marked truncated. A later dialog, or destroying the window, stops a copy. No save and no folder. |
| The web | None: a page's file input gives contents, never paths. |
mwinWindow_RequestOpenUrl opens an http://, https:// or mailto: address in the user's program for it. Other schemes, spaces and control characters are refused at the call: the platform hands the address to another program, which could take another scheme as a command. A program that wants to open a local file reveals it instead.mwinWindow_RequestRevealFile shows a file, by its absolute path, in the file manager with the file selected. iOS, Android and the web have no file manager to show it in.mwinWindow_RequestKeepAwake keeps the display on while the window shows and is not minimized; awake in the window state says it holds. Over all windows it is one wish of the program, let go when no live, shown window asks.mwinShowMessageBox shows a modal box with a title, a message, a kind (information, warning, error) and a choice of buttons (OK, OK and Cancel, Yes and No), waits for the user, and says whether the box was accepted. It needs no context: a program reports with it the error that stops it from starting. So its def, like the application def, carries the version of the headers the program was built with, and a def built against another release is refused with mwin_errorVersion.
On Linux it runs zenity or kdialog; where neither is there it draws a plain box of its own on the X server DISPLAY names, in the core "fixed" font, so text beyond Latin-1 shows as "?". Without any of them it answers mwin_errorUnsupported, and the program falls back to its standard error. Android has no message box: it forbids waiting on its main thread.
mwinContext_GetSystemFacts gives the user's preferences and the power state:
Changes arrive as mwin_eventThemeChanged and mwin_eventPowerChanged. mwinContext_GetPreferredLocales gives the user's languages in order as BCP 47 tags separated by commas (de-DE,en-GB), and mwin_eventLocaleChanged says they changed. On every platform, a list longer than the localeBytes limit keeps the longest beginning of it that fits: the first tag that does not fit is left out with every tag after it, so a less preferred language never appears without the ones before it. Windows hands over its list only whole, so there a list past the limit keeps just its first language, the one Windows shows, where it fits.
Not every platform knows every fact. On Linux they come from the desktop portal, UPower and the environment, so they are unknown for the first frames and then arrive as change records. The locales on Linux start from the program's own environment, which is normally what the desktop set at login (LANGUAGE=fr ./game puts fr first). After that they follow the desktop: a language changed in GNOME's settings (AccountsService) or KDE Plasma's (plasma-localerc) while the program runs replaces the list, and mwin_eventLocaleChanged says so. Only a change counts: what the desktop says at the start leaves the environment's list in place, and a list that names no language the library knows goes back to the starting one. A list whose first language does not fit the localeBytes limit is empty, as on every platform. Without a system bus or a configuration folder the starting list simply stays. A page knows no accent, text scale or power saving. A fact a platform does not tell stays unknown, never guessed.
The accessibility tree belongs to the program (Maul UI builds one); the window only hands its root to the platform:
mwinWindow_RequestAccessibilityRoot gives the platform the program's root: UI Automation's provider on Windows, an NSAccessibility object on macOS, a UIAccessibility object on iOS, an AccessibilityNodeProvider on Android. A root that also implements maul.window.Explorer, or has a public int virtualViewAt(float x, float y), is explored by touch on Android.mwin_eventAccessibilityRequested comes the first time a client asks a window for its tree, so a program can build its tree only once someone needs it.