Maul Window API reference

Generated from the public headers, which are the source of truth: 107 functions across 15 headers.

base.h

The base of the Maul Window API: the library version, the export and attribute macros, and the result codes every fallible function returns.

mwinVersion mwinGetVersion(void);

Returns the version of the library that was linked, which may differ from the MWIN_VERSION macros a program was compiled with.

Returns: The library version.

Thread safety. Safe from any thread.

const char* mwinGetResultName(mwinResult result);

Returns the name of a result code, for diagnostics.

Parameters:

Returns: A static, NUL-terminated string such as "mwin_errorCapacity".

Thread safety. Safe from any thread.

accessibility.h

The hooks a program's accessibility adapters need from its windows. The library knows nothing of the tree. It hands the platform the root the program implements, tells the program when a client first asks for a window's tree, and on the web keeps an element next to the canvas for the program's ARIA elements (its selector is in mwinNativeHandles). The focus on an element there, where a screen reader may move it, is the window's as the canvas's is, and keys there reach the program; the page keeps their default actions, and a field there (an input, text area, select or editable element) keeps the text typed into it, which comes as no mwin_eventTextInput. A focus request leaves the focus on such an element. On Linux, AT-SPI is a service of the application on the session's accessibility bus, and asks nothing of the window system. Its adapter takes the window's place, size and focus from the window's state and events.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestAccessibilityRoot( mwinContext* context, mwinWindowId window, void* root, mwinRequestId* requestOut);

Hands the platform's accessibility clients the root of the window's tree, which the program's adapter implements, or no root.

On Win32 the root is an IRawElementProviderSimple*. The window answers WM_GETOBJECT for UiaRootObjectId with it, and UI Automation takes references of its own. The provider must stay valid while it is the window's root. When the window is destroyed, UI Automation is told to let go of it.

On macOS the root is an object of the NSAccessibility protocol (an NSAccessibilityElement, say), whose accessibility parent is the window's view (mwinNativeHandles). The view gives it as its child and asks it what is focused and what is under a point; the window holds a reference to it while it is the root.

On iOS the root is an object of the UIAccessibility protocols (a UIAccessibilityElement, say), whose container is the window's view. The view gives it as its only accessibility element, and holds a reference to it while it is the root.

On Android the root is the jobject of an android.view.accessibility.AccessibilityNodeProvider, whose nodes name the window's view (mwinNativeHandles) as their source and parent. The view gives it as its provider, and holds a global reference to it while it is the root; the view changes with the activity, the root staying. A root that also implements the library's Java interface maul.window.Explorer, or that has a public method int virtualViewAt(float x, float y) of the same meaning (a library's provider that cannot name this one's interface), is explored by touch: Android sends touch exploration to the window's input rather than to its view, so while there is a root the library takes those hovers, asks the root for the virtual view under the finger, and announces the one entered and the one left, as ExploreByTouchHelper does. The program sees no touch for them. An application that shrinks its code keeps that method with java/proguard-rules.pro.

X11, Wayland and the web take no root and answer mwin_outcomeUnsupported.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

clipboard.h

The clipboard, as UTF-8 text. Writing and reading are requests of a window, answered by a completion like any other: the browser's clipboard answers later and may ask the user first, and on Wayland only a focused window may use it. A later request of the same kind on the same window supersedes a waiting one, so two reads in one frame paste once unless the program counts the superseded read. A read that completes with mwin_outcomeDone leaves the text it found in the context, where mwinRequest_GetClipboardText copies it out under the read's request until another read finds text; a read refused or too large leaves it. Asked with any other request, the getter answers mwin_errorStale, so a completion is never answered with another read's text. Text another program put there is checked before the program sees it: ill-formed UTF-8 has each maximal ill-formed subpart replaced with U+FFFD, and text past the clipboardBytes limit, after that, completes the read with mwin_outcomeTooLarge. An empty clipboard, or one without text, reads as empty text. What the program wrote stays in the context while the platform may ask for it, until the next write or the context's end. Beside text, the clipboard takes data by MIME type, its bytes passed through as they are: an image as image/png the program encodes itself. A write offers up to MWIN_MAX_CLIPBOARD_ITEMS items, one of which may be text/plain, offered as the platform's text and read with the text calls; a text write replaces the data, a data write the text. X11 and Wayland also keep the primary selection, the text last selected, apart from the clipboard: mwinWindow_RequestPrimaryWrite and mwinWindow_RequestPrimaryRead, unsupported elsewhere.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestClipboardWrite(mwinContext* context, mwinWindowId window, const char* text, size_t length, mwinRequestId* requestOut);

Asks to put text on the clipboard.

Parameters:

Returns: mwin_success; mwin_errorCapacity for text past the clipboardBytes limit, when the context cannot hold it, or when the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL context or text that is not UTF-8.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestClipboardRead(mwinContext* context, mwinWindowId window, mwinRequestId* requestOut);

Asks for the clipboard's text; when the request completes with mwin_outcomeDone, mwinRequest_GetClipboardText has it.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRequest_GetClipboardText(const mwinContext* context, mwinRequestId request, char* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the text a clipboard read found, while it is the text the last read found: the read completed with mwin_outcomeDone, and no read since (of any window) found other text.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the text does not fit; mwin_errorStale for a request that is no read answered done, or whose text a later read replaced; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestClipboardWriteData( mwinContext* context, mwinWindowId window, const mwinClipboardItem* items, uint32_t count, mwinRequestId* requestOut);

Asks to put data on the clipboard, by MIME type, copied before the call returns.

Parameters:

Returns: mwin_success; mwin_errorCapacity for bytes past the clipboardBytes limit in all, when the context cannot hold them, or when the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorLimit for more than MWIN_MAX_CLIPBOARD_ITEMS items or a type longer than MWIN_MAX_CLIPBOARD_MIME; mwin_errorInvalid for a NULL context or items, no items, a type that is not a MIME type or comes twice, or a text/plain item that is not UTF-8.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestClipboardReadData(mwinContext* context, mwinWindowId window, const char* mime, size_t mimeLength, mwinRequestId* requestOut);

Asks for the clipboard's data of a MIME type; when the request completes with mwin_outcomeDone, mwinRequest_GetClipboardData has it. A clipboard without that type completes it with mwin_outcomeFailed; data past the clipboardBytes limit with mwin_outcomeTooLarge.

Parameters:

Returns: As mwinWindow_RequestClipboardRead, with mwin_errorLimit for a type longer than MWIN_MAX_CLIPBOARD_MIME, and mwin_errorInvalid for a type that is not a MIME type, or text/plain.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRequest_GetClipboardData(const mwinContext* context, mwinRequestId request, void* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the data a data read found, as mwinRequest_GetClipboardText does the text.

Parameters:

Returns: As mwinRequest_GetClipboardText.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestPrimaryWrite(mwinContext* context, mwinWindowId window, const char* text, size_t length, mwinRequestId* requestOut);

Asks to make text the primary selection, where the platform has one (X11, Wayland); others answer mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestClipboardWrite.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestPrimaryRead(mwinContext* context, mwinWindowId window, mwinRequestId* requestOut);

Asks for the primary selection's text; when the request completes with mwin_outcomeDone, mwinRequest_GetPrimaryText has it, checked as the clipboard's is.

Parameters:

Returns: As mwinWindow_RequestClipboardRead.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRequest_GetPrimaryText(const mwinContext* context, mwinRequestId request, char* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the text a primary selection read found, as mwinRequest_GetClipboardText does the clipboard's.

Parameters:

Returns: As mwinRequest_GetClipboardText.

Thread safety. Main thread only.

context.h

The context and the run function. A program describes itself in an application def (three functions and the context's def) and hands it to mwinRun, which creates the context, calls init, calls frame once per frame, calls quit and destroys the context. On Win32, X11 and Wayland mwinRun pumps the platform itself; on the web and on mobile platforms the platform's loop drives it. The program cannot tell the two apart. Every limit on memory and work is named in mwinLimits, with a default a program may change. Everything the context needs is allocated when it is created, through the def's allocator.

static inline mwinContextDef mwinDefaultContextDef(void);

Returns the default context def: the default limits (8 windows; per window 32 requests, 256 notifications, 256 input records per class and 4,096 bytes of text; 1,024 title bytes; 16 monitors; 256 bytes of locales; 8 gamepads; 1 MiB of clipboard text; 256 files and 1 MiB of paths or text per drop; 256 files and 1 MiB of paths per dialog; 16 cursors), the C library's allocator and the native backend. Built in the program from the headers it includes, so that the library never writes a def of its own layout into the program's.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

static inline mwinAppDef mwinDefaultAppDef(void);

Returns the default application def: the default context def, the ABI version of the headers the program is built with, and no functions. Built in the program, so that the version is the program's: mwinRun refuses a def built for another release's binary interface rather than read it in another layout.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MWIN_NODISCARD MWIN_API mwinResult mwinRun(const mwinAppDef* def);

Runs a program: creates the context, calls init, then frame until a frame returns mwin_frameStop, then quit, and destroys the context. Where the platform owns the loop (the web, iOS) this function may never return, or, on the web without Emscripten, return mwin_success once init has succeeded while the page's frames run the program on; either way put cleanup in quit. On iOS init runs when the application's first scene connects, and a program that stops or fails there ends with quit while the application runs on. On Android the platform begins the run, not the program: see mwinAndroidMain; there this function returns mwin_errorUnsupported. It is never called from inside a running program's functions.

Parameters:

Returns: init's status when it failed; mwin_success after a stop; mwin_errorCapacity when the allocator cannot give the context its memory; mwin_errorUnsupported for a backend this build lacks; mwin_errorPlatform when the window system cannot be reached; mwin_errorInvalid for a missing function, a bad cookie or a zero limit.

Thread safety. Main thread only.

mwinAppDef mwinAndroidMain(void);

Defined by the program on Android, in place of the main that calls mwinRun elsewhere: returns the program, which the library then runs as mwinRun would. The library's activity (maul.window.Activity, named in the manifest with the program's library as android.app.lib_name) calls it when it is created and no program runs; init runs at once, and frames follow on the main thread while the activity is started. The program outlives its activity: one the system creates anew (a configuration change, the user coming back) joins the running program, the window's surface going with the old one and coming with the new. A program that stops or fails ends with quit and finishes its activity; a later activity calls this function anew, in the same process, so the program keeps nothing it needs fresh in statics. A shared build of this library finds the function in the program's library, which must export it.

Returns: The program, as mwinRun takes it.

Thread safety. Called on the main thread.

uint64_t mwinContext_GetMisuse(const mwinContext* context);

Returns how many calls the context has refused as invalid input (mwin_errorInvalid), past a named bound (mwin_errorLimit) or from inside its allocator (mwin_errorBusy): a count release builds can watch to catch a program's bugs. Stale ids are not misuse.

Parameters:

Returns: The count; 0 for a NULL context.

Thread safety. Main thread only.

dialog.h

File dialogs: open one file or many, save one, or choose a folder, as requests of a window answered by a completion like any other. The window stays live while the dialog shows, and frames go on. A dialog chosen from completes with mwin_outcomeDone, and its paths wait under the request's id for mwinRequest_GetDialogFiles until the next dialog completes; one the user closes completes with mwin_outcomeCancelled; a choice past the dialogFiles or dialogBytes limits with mwin_outcomeTooLarge, as a whole, since a limit says nothing about which files to keep. A chosen file the platform cannot give as a path (one that is not UTF-8, one with no path, a document Android could not copy) is left out and the answer marked truncated, as a drop is; a choice of no file that could be given fails with mwin_outcomeFailed. A page names no files, so the web has no dialogs (mwin_outcomeUnsupported). Android's documents have no paths either: the documents an Android dialog opens are copied into the application's cache first, and their copies' paths answered; saving and choosing a folder are unsupported there.

mwinFileDialogDef mwinDefaultFileDialogDef(void);

Returns the default file dialog def: a dialog to open one file, with the platform's title and folder and no filters.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestFileDialog(mwinContext* context, mwinWindowId window, const mwinFileDialogDef* def, mwinRequestId* requestOut);

Asks for a file dialog over a window. Its text is copied at the call.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the context cannot hold the copy or the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorLimit for text past its bound (the title MWIN_MAX_DIALOG_TITLE_BYTES, the folder and name MWIN_MAX_ADDRESS_BYTES, a filter's name and extensions MWIN_MAX_DIALOG_FILTER_BYTES) or more than MWIN_MAX_DIALOG_FILTERS filters; mwin_errorInvalid for a NULL context or def, an invalid def, text that is not UTF-8 or holds a NUL, a folder that is not absolute, a filter without a name or extensions, or an extension with a dot, '*' or '?'.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRequest_GetDialogFiles( const mwinContext* context, mwinRequestId request, char* bufferOut, size_t capacity, size_t* lengthOut, size_t* countOut, bool* truncatedOut);

Copies the paths a dialog chose out: absolute, UTF-8, each ended by a NUL.

Parameters:

Returns: mwin_success; mwin_errorCapacity with the bytes needed when they do not fit; mwin_errorStale for a request that did not complete with mwin_outcomeDone or whose paths a later dialog replaced; mwin_errorInvalid for a NULL context or lengthOut.

Thread safety. Main thread only.

drop.h

Drag and drop onto windows. While something is dragged over a window the program hears mwin_eventDragEntered, mwin_eventDragMoved (merged when motion waits) and mwin_eventDragLeft, so it can show where a drop would land; a drop brings mwin_eventDropped instead of the leaving. Windows take every drag that carries files or text. A drop's files and text wait in the context under the drop's id until the next drop, where these functions copy them out. Files come as their paths in UTF-8, each ended by a NUL; on the web, where a page never sees paths, as their names. A path that is not UTF-8 is left out, since no program could name the file with it, and text from another program has each maximal ill-formed subpart replaced with U+FFFD. Files past the droppedFiles limit, or paths past dropBytes, are left out whole, and text past dropBytes is left out; the drop's record says when anything was. A path names a file; it grants no access the program did not already have. On Android, whose documents have no paths, a drop's documents are copied into the application's cache first, and the drop gives their copies' paths once they are whole.

MWIN_NODISCARD MWIN_API mwinResult mwinDrop_GetFiles(const mwinContext* context, mwinDropId drop, char* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the paths of a drop's files, each ended by a NUL.

Parameters:

Returns: mwin_success; mwin_errorCapacity when they do not fit; mwin_errorStale for a drop a later one replaced; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinDrop_GetText(const mwinContext* context, mwinDropId drop, char* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the text of a drop.

Parameters:

Returns: As mwinDrop_GetFiles.

Thread safety. Main thread only.

event.h

The event stream. The program drains it in frame with mwinContext_NextEvent, which returns every record in the order it arrived, across windows. Records wait in storage per window, each with its own limit, so one busy window cannot push out another's records. Notifications that must be handled before the platform goes on (the application's lifecycle, a lost or restored surface) come before all others; when the platform waits for the program to handle one, the library runs a frame at once, from inside the platform's call, so the program sees it in time. The context's own notifications carry the null window id. A request's completion comes after the notifications the change caused: a size request is answered after mwin_eventResized. Input comes in four classes, each with its own storage per window. Discrete records (keys, text, buttons, touches and pen contacts beginning or ending) are never merged: when their storage is full the window gets mwin_eventInputStateReset instead, which also follows every loss of focus, after which no key or button counts as held and no composition is shown. Motion, raw deltas and the wheel are delivered sample by sample while there is room, and merged into the newest waiting record of their kind when there is not; sampleCount says how many a record stands for. Text in a record stays valid until the frame that drained it returns. Gamepads' records are the context's, in storage of their own: their buttons never merge, and a gamepad whose button records were lost gets mwin_eventInputStateReset; an axis moving when its storage is full merges into the newest waiting record of that axis. An input method composes text in place before it commits it. While a window accepts text (mwinWindow_RequestTextInput), mwin_eventImePreedit reports the text being composed, with its caret, its selection and styled segments; an empty preedit ends the composition. A newer composition replaces one still waiting for the same window, or its end, so one composition may follow another with no end between them. Committed text arrives as mwin_eventTextInput. While the input method composes, the keys it consumes produce no key records: a key that types a character and goes down during a composition is left out, and so is its release. A reset ends the composition shown, not the input method's: its keys stay left out until it ends its composition with an empty preedit or the focus leaves.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_NextEvent(mwinContext* context, mwinEvent* eventOut);

Takes the next record of the stream.

Parameters:

Returns: mwin_success; mwin_empty when the stream is drained; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

gamepad.h

Gamepads, an optional component (MAUL_WINDOW_GAMEPAD, on by default): without it these functions are not in the library and a call to one fails to link. A gamepad the platform knows the layout of is mapped: its controls come by where they are on a standard pad (the south face button, the left stick), never by the letters printed on them. One it does not know comes raw, as numbered buttons and axes, its hats as pairs of axes. Each connection has its own id; mwin_eventGamepadAdded and mwin_eventGamepadRemoved report hotplug, mwin_eventGamepadChanged a change of its facts (its battery, or a capability Android finds a moment after the pad is added). Its buttons and axes come as records in the stream, whatever window has the focus, and its state can be read at any time. Values are the platform's own, with no dead zone: sticks run from -1 to 1, right and down positive, and triggers from 0 to 1.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetGamepads(const mwinContext* context, mwinGamepadId* gamepadsOut, size_t capacity, size_t* countOut);

Lists the gamepads connected now, in the order they came.

Parameters:

Returns: mwin_success, also when they do not all fit, with the first capacity written and the total in countOut; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_GetInfo(const mwinContext* context, mwinGamepadId gamepad, mwinGamepadInfo* infoOut);

Reads what the platform tells about a gamepad.

Parameters:

Returns: mwin_success; mwin_errorStale for a gamepad no longer connected; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_GetState(const mwinContext* context, mwinGamepadId gamepad, mwinGamepadState* stateOut);

Reads a gamepad's controls as the platform last reported them, which may be ahead of the records not yet drained. After a mwin_eventInputStateReset about a gamepad, this is where its state is.

Parameters:

Returns: As mwinGamepad_GetInfo.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_SetRumble(mwinContext* context, mwinGamepadId gamepad, float low, float high, uint32_t durationMs);

Runs a gamepad's motors, the low frequency (heavy) one and the high frequency (light) one, each from 0 (still) to 1, for a time or until the next call: the latest call wins, and a duration of 0 stops them.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a gamepad without mwin_padRumble; mwin_errorPlatform when the platform refused; mwin_errorStale for a gamepad no longer connected; mwin_errorInvalid for a NULL context or a strength outside 0 to 1.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_SetTriggerRumble(mwinContext* context, mwinGamepadId gamepad, float left, float right, uint32_t durationMs);

Runs the motors in a gamepad's triggers, each from 0 (still) to 1, for a time or until the next call, as mwinGamepad_SetRumble runs the others: the latest call wins, a duration of 0 stops them, and the two calls do not touch each other's motors.

Parameters:

Returns: As mwinGamepad_SetRumble, with mwin_errorUnsupported for a gamepad without mwin_padTriggerRumble.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_EnableMotion(mwinContext* context, mwinGamepadId gamepad, bool enabled);

Turns a gamepad's motion sensors on or off. They are off when it connects, as they cost its battery and its link; turning them either way starts its motion anew, all zero.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a gamepad without mwin_padMotion; mwin_errorPlatform when the platform refused; mwin_errorStale for a gamepad no longer connected; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_IsMotionEnabled(const mwinContext* context, mwinGamepadId gamepad, bool* enabledOut);

Reads whether a gamepad's motion sensors are on: turned on with mwinGamepad_EnableMotion and not off since. A gamepad without mwin_padMotion reads off.

Parameters:

Returns: mwin_success; mwin_errorStale for a gamepad no longer connected; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_TakeMotion(mwinContext* context, mwinGamepadId gamepad, mwinGamepadMotion* motionOut);

Takes a gamepad's motion, starting the angle turned anew: the latest acceleration and rotation rate, and the angle turned since it was last taken. All zero while its sensors are off or before their first sample.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a gamepad without mwin_padMotion; mwin_errorStale for a gamepad no longer connected; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

input.h

Keyboard, mouse, touch and pen. A key has two names: its code, the physical key by its place on a keyboard (the USB HID usage, so "the key right of Tab" is mwin_codeKeyQ on every layout), and its key, what the current layout makes of it. Text is not keys: typed characters arrive as mwin_eventTextInput, which also carries what an input method composed. The cursor's position arrives as mwin_eventCursorMoved in the window's logical units; relative motion from the device arrives separately as mwin_eventRawPointerDelta, unscaled, and keeps coming while the cursor is captured.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestVirtualKeyboard(mwinContext* context, mwinWindowId window, bool visible, mwinInputPurpose purpose, mwinRequestId* requestOut);

Asks to show or hide the on-screen keyboard over a window, where the platform has one; others answer mwin_outcomeUnsupported. mwin_eventVirtualKeyboardChanged reports the part it covers. It asks the platform for a state, and switches no part of the library.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for an unknown purpose.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestTextInput(mwinContext* context, mwinWindowId window, bool enabled, mwinRequestId* requestOut);

Asks a window to accept text, or to stop: while it does, input methods compose into it and mwin_eventImePreedit reports their compositions. It asks the platform for a state of the window, which mwinWindowState's textInput reports, and switches no part of the library.

Parameters:

Returns: As mwinWindow_RequestTitle.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestTextInputCaret(mwinContext* context, mwinWindowId window, mwinRect caret, mwinRequestId* requestOut);

Tells the platform where a window's caret is, which it places the input method's candidate window by. The window keeps the caret while text input is turned off and on again; ask again when the caret moves. Empty at the window's start.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for a caret that is not finite or has a negative size.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestCursorMode(mwinContext* context, mwinWindowId window, mwinCursorMode mode, mwinRequestId* requestOut);

Asks for a cursor mode over a window.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for an unknown mode.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestCursorShape(mwinContext* context, mwinWindowId window, mwinCursorShape shape, mwinRequestId* requestOut);

Asks for one of the system's cursor images over a window.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for an unknown shape.

Thread safety. Main thread only.

mwinCursorDef mwinDefaultCursorDef(void);

Returns the default cursor def: no images, the hotspot at 0, 0.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MWIN_NODISCARD MWIN_API mwinResult mwinCreateCursor(mwinContext* context, const mwinCursorDef* def, mwinCursorId* cursorOut);

Makes a cursor from images, to show over windows with mwinWindow_RequestCursorImage. Each window takes the image for its scale: the smallest at least the first image's size times the scale, else the largest, its hotspot scaled with it.

Parameters:

Returns: mwin_success; mwin_errorLimit for more images than MWIN_MAX_CURSOR_IMAGES or an image larger than MWIN_MAX_CURSOR_SIZE a side; mwin_errorInvalid for a NULL argument, a def without its cookie, no images, an image without pixels, with no width or height, or a stride below its width times 4, an image not wider than the one before, or a hotspot outside the first image; mwin_errorCapacity past the limit's cursors or when the allocator fails.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinDestroyCursor(mwinContext* context, mwinCursorId cursor);

Destroys a cursor. Windows showing it show the default shape.

Parameters:

Returns: mwin_success; mwin_errorInvalid for a NULL context; mwin_errorStale for an id that is not live.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestCursorImage(mwinContext* context, mwinWindowId window, mwinCursorId cursor, mwinRequestId* requestOut);

Asks for a cursor made with mwinCreateCursor over a window, in place of a shape until a shape is asked for again. Platforms without image cursors (iOS) answer mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorStale for a cursor that is not live.

Thread safety. Main thread only.

mwinKey mwinContext_MapKeyCode(const mwinContext* context, mwinKeyCode code);

Returns what a physical key means under the current keyboard layout, as a key record would carry it.

Parameters:

Returns: The key; 0 for a NULL context, an unknown code, a key the layout gives no meaning, or a call from the free hook once quit has returned.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetKeyboardLayout(const mwinContext* context, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the name of the current keyboard layout, as the platform gives it, for showing which layout key labels come from.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the name does not fit; mwin_errorInvalid for a NULL argument; mwin_errorState from the free hook once quit has returned.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetKeyReach(const mwinContext* context, mwinKeyCode code, mwinModifiers modifiers, mwinKeyReach* reachOut);

Tells whether a chord reaches the program on the platform the context runs on, for a rebinding UI to refuse a chord that never arrives and warn about one the platform may take: Ctrl+W in Chromium, Alt+Tab on Windows and Command+Tab on Apple's systems never arrive; the desktop's configurable shortcuts are uncertain. The answer is the library's knowledge of the platform, not a promise: a desktop may keep chords nothing lists.

Parameters:

Returns: mwin_success; mwin_errorInvalid for a NULL argument or a code that is not a key; mwin_errorState from the free hook once quit has returned.

Thread safety. Main thread only.

monitor.h

Monitors. Each has an id that stays the same while it is connected; mwin_eventMonitorAdded and mwin_eventMonitorRemoved report hotplug, mwin_eventMonitorChanged a change of its facts, and a window whose monitor changes gets mwin_eventDisplayChanged. Listing the monitors gives a consistent snapshot of those connected.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetMonitors(const mwinContext* context, mwinMonitorId* monitorsOut, size_t capacity, size_t* countOut);

Lists the monitors connected now.

Parameters:

Returns: mwin_success, also when they do not all fit, with the first capacity written and the total in countOut; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinMonitor_GetInfo(const mwinContext* context, mwinMonitorId monitor, mwinMonitorInfo* infoOut);

Reads what the platform tells about a monitor.

Parameters:

Returns: mwin_success; mwin_errorStale for a monitor no longer connected; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

native.h

The native handles a GPU layer needs to create a surface for a window, one bundle per surface generation. This library includes no graphics API header: the handles are the window system's own, as opaque pointers, and the GPU layer turns them into its surface. A lost surface ends a generation; the window's id stays, and the bundle of the next generation arrives with mwin_eventSurfaceRestored.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetNativeHandles(const mwinContext* context, mwinWindowId window, mwinNativeHandles* handlesOut);

Reads a window's native handles for its current surface.

Parameters:

Returns: mwin_success; mwin_errorState while the window has no surface (before mwin_eventWindowCreated, or between mwin_eventSurfaceLost and mwin_eventSurfaceRestored): the program waits for the record that brings the surface, as only reading its records changes this state; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

services.h

What a game or an editor asks of the system around its windows: opening a web or mail address in the user's default program, showing a file in the file manager, keeping the display awake while a window shows, and a message box for an error before any window, or without one. The first three are requests of a window, answered by a completion like any other: the platform may ask the user, or answer later. An address is only http, https or mailto, and holds no spaces or control characters, since a platform may hand it to another program; a path is absolute. Both are copied at the call.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestOpenUrl(mwinContext* context, mwinWindowId window, const char* url, size_t length, mwinRequestId* requestOut);

Asks the system to open a web or mail address in the user's default program.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the context cannot hold the copy or the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorLimit for more than MWIN_MAX_ADDRESS_BYTES; mwin_errorInvalid for a NULL context or an address this does not open.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestRevealFile(mwinContext* context, mwinWindowId window, const char* path, size_t length, mwinRequestId* requestOut);

Asks the file manager to show a file, selected where it can.

Parameters:

Returns: As mwinWindow_RequestOpenUrl; mwin_errorInvalid also for a path that is not absolute.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestKeepAwake(mwinContext* context, mwinWindowId window, bool awake, mwinRequestId* requestOut);

Asks the system to keep the display awake, with no screensaver or dimming, while the window shows; or no longer. The window's state says whether it does (mwinWindowState's awake). It asks the platform for a state, and switches no part of the library.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the window has its limit of requests in flight; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

static inline mwinMessageBoxDef mwinDefaultMessageBoxDef(void);

Returns the default message box def: no title or message, an error with an OK button, and the ABI version of the headers the program is built with. Built in the program, so that the version is the program's.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MWIN_NODISCARD MWIN_API mwinResult mwinShowMessageBox(const mwinMessageBoxDef* def, bool* acceptedOut);

Shows a message box and waits for the user. It needs no context, so a program can report an error that stops it from starting. On Linux it runs zenity or kdialog, whichever is there, else draws one itself on the X server DISPLAY names. On iOS it needs a scene in the foreground, which the application does not show yet in the program's init: there it fails. Android has none a program could wait for: it forbids waiting on the main thread.

Parameters:

Returns: mwin_success; mwin_errorVersion for a def built from another release's headers, checked first; mwin_errorUnsupported where the platform has no message box (Android, Linux without zenity, kdialog, or an X server, the test backend alone); mwin_errorPlatform when it failed; mwin_errorLimit for a title past MWIN_MAX_MESSAGE_TITLE_BYTES or a message past MWIN_MAX_MESSAGE_BYTES; mwin_errorInvalid for a NULL or invalid def, or text that is not UTF-8 or holds a NUL.

Thread safety. Main thread only.

system.h

What the system says about the user's preferences and the machine: the theme and accent color, reduced motion and text scale, the power source, and the preferred locales. Each has a notification when it changes; the values are read at any time.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetSystemFacts(const mwinContext* context, mwinSystemFacts* factsOut);

Reads the system's preferences and facts.

Parameters:

Returns: mwin_success; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetPreferredLocales(const mwinContext* context, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the user's preferred locales, most preferred first, as BCP 47 tags separated by commas ("de-DE,en-GB"); empty where the platform does not say. 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. Windows hands over its list only whole, so there such a list keeps only its first language, the one Windows shows, where it fits.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the list does not fit; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

test.h

The test backend, a headless platform for contract tests. It exists only in builds with MAUL_WINDOW_TEST_BACKEND and only in a context created with mwin_backendTest; it is never a fallback. It answers each request at the next pump, as the answer set for its kind says, and takes what a platform would report from mwinContext_PostTestEvent, which sends it through the same path a real backend's reports take.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestAnswer(mwinContext* context, mwinRequestKind kind, mwinOutcome outcome);

Sets how the test platform answers requests of a kind from now on. mwin_outcomeDone, the default, carries a request out at the next pump.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context, an unknown kind or an answer the platform cannot give.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_EnableTestHold(mwinContext* context, bool enabled);

Turns the test platform's hold on or off: while it is on, no request is answered; once it is off, they are answered again from the next pump.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_IsTestHoldEnabled(const mwinContext* context, bool* enabledOut);

Reads whether the test platform holds requests: turned on with mwinContext_EnableTestHold and not off since.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_PostTestEvent(mwinContext* context, const mwinEvent* event);

Reports what the platform would: the user resized or closed a window, focus moved, the scale changed, a key went down, text was typed, the application is suspending. The report reaches the stream at the next pump, stamped with the time of this call; text is copied from the record's pointer, and a composition's offsets are fitted to its text as a platform's are. The pump runs a frame at once after a lifecycle or surface report, as a platform that waits for the program would make it; a lifecycle report needs no window. Completions, input state resets and the created and destroyed records are the core's and refused.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorCapacity when 1,024 reports or 64 KiB of their text already wait; mwin_errorUnsupported for a context of another backend; mwin_errorLimit for a composition of more than MWIN_MAX_PREEDIT_SEGMENTS segments; mwin_errorInvalid for a NULL argument, a record kind only the core makes, a key's record of an unknown key code, or text that is not UTF-8.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestTime(mwinContext* context, uint64_t timeNs);

Sets the test platform's clock, which stamps every record.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context or a time before the current one.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestScale(mwinContext* context, float scale);

Sets the scale the test platform gives windows it creates or resizes from now on; 1 at first.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context or a scale that is not positive and finite.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetTestTitle(const mwinContext* context, mwinWindowId window, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the title the test platform shows for a window.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the title does not fit; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinAddTestMonitor(mwinContext* context, const mwinMonitorInfo* info, mwinMonitorId* monitorOut);

Connects a monitor to the test platform, at once: its mwin_eventMonitorAdded waits in the stream when this returns. Windows the platform makes from now on show on the primary monitor.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the context has its limit of monitors; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinMonitor_SetTestInfo(mwinContext* context, mwinMonitorId monitor, const mwinMonitorInfo* info);

Changes a connected monitor's facts, at once.

Parameters:

Returns: mwin_success; mwin_errorStale for a monitor no longer connected; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRemoveTestMonitor(mwinContext* context, mwinMonitorId monitor);

Disconnects a monitor, at once.

Parameters:

Returns: mwin_success; mwin_errorStale for a monitor no longer connected; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestSystemFacts(mwinContext* context, const mwinSystemFacts* facts);

Sets the system's preferences and facts, at once; a change of the look posts mwin_eventThemeChanged, of the power mwin_eventPowerChanged.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestLocales(mwinContext* context, const char* locales, size_t length);

Sets the user's preferred locales, at once, as a platform reports them: a list past the localeBytes limit keeps the longest beginning of it that fits. A change posts mwin_eventLocaleChanged.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context or tags kept that are not UTF-8.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinAddTestGamepad(mwinContext* context, const mwinGamepadInfo* info, mwinGamepadId* gamepadOut);

Connects a gamepad to the test platform, at once: its mwin_eventGamepadAdded waits in the stream when this returns.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the context has its limit of gamepads; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_SetTestInfo(mwinContext* context, mwinGamepadId gamepad, const mwinGamepadInfo* info);

Changes a connected gamepad's facts, at once.

Parameters:

Returns: mwin_success; mwin_errorStale for a gamepad no longer connected; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinRemoveTestGamepad(mwinContext* context, mwinGamepadId gamepad);

Disconnects a gamepad, at once.

Parameters:

Returns: As mwinGamepad_SetTestInfo, with mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_SetTestButton(mwinContext* context, mwinGamepadId gamepad, mwinGamepadButton button, bool down);

Presses or lets go a gamepad's button, at once; a button already so posts nothing.

Parameters:

Returns: As mwinRemoveTestGamepad; mwin_errorInvalid for a button below 0 or past 255.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_SetTestAxis(mwinContext* context, mwinGamepadId gamepad, mwinGamepadAxis axis, float value);

Moves a gamepad's axis, at once; a value it has already posts nothing.

Parameters:

Returns: As mwinRemoveTestGamepad; mwin_errorInvalid for an axis below 0 or past 255.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_GetTestRumble(const mwinContext* context, mwinGamepadId gamepad, float* lowOut, float* highOut, uint32_t* durationMsOut, size_t* countOut);

Reads the last rumble a gamepad of the test platform was given.

Parameters:

Returns: As mwinGamepad_SetTestInfo.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_GetTestTriggerRumble( const mwinContext* context, mwinGamepadId gamepad, float* leftOut, float* rightOut, uint32_t* durationMsOut, size_t* countOut);

Reads the last trigger rumble a gamepad of the test platform was given.

Parameters:

Returns: As mwinGamepad_SetTestInfo.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_IsTestMotionEnabled(const mwinContext* context, mwinGamepadId gamepad, bool* enabledOut);

Reads whether the test platform was told to turn a gamepad's motion sensors on.

Parameters:

Returns: As mwinGamepad_SetTestInfo.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinGamepad_PostTestMotion(mwinContext* context, mwinGamepadId gamepad, const float acceleration[3], const float rotationRate[3], uint64_t timeNs);

Gives a gamepad's motion sensors a sample, at once, as the platform would; kept only while they are on.

Parameters:

Returns: As mwinRemoveTestGamepad, with mwin_errorInvalid for a NULL array.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestKeyReach(mwinContext* context, mwinKeyCode code, mwinModifiers modifiers, mwinKeyReach reach);

Sets what mwinContext_GetKeyReach answers for a chord on the test platform, which answers mwin_keyReachDelivered for every chord until set. Setting mwin_keyReachDelivered forgets the chord.

Parameters:

Returns: mwin_success; mwin_errorCapacity when 32 chords are already set; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context, a code that is not a key or an answer out of range.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestClipboard(mwinContext* context, const char* bytes, size_t length);

Puts bytes on the test platform's clipboard, at once, as another program would: they need not be UTF-8.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the allocator has no room; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context, or NULL bytes with a length.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestClipboardUtf16(mwinContext* context, const uint16_t* units, size_t length);

Puts UTF-16 on the test platform's clipboard, as Windows keeps it: it need not be well-formed.

Parameters:

Returns: As mwinContext_SetTestClipboard.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestClipboard(const mwinContext* context, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the test platform's clipboard as bytes: what the program last wrote, or what mwinContext_SetTestClipboard put there.

Parameters:

Returns: mwin_success; mwin_errorCapacity when they do not fit; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestClipboardData(mwinContext* context, const char* mime, size_t mimeLength, const void* bytes, size_t length);

Puts data of one MIME type on the test platform's clipboard, at once, as another program would: its text goes.

Parameters:

Returns: As mwinContext_SetTestClipboard, with mwin_errorLimit for a type longer than MWIN_MAX_CLIPBOARD_MIME.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestClipboardData( const mwinContext* context, const char* mime, size_t mimeLength, void* bufferOut, size_t capacity, size_t* lengthOut);

Reads the test platform's clipboard data of a MIME type, as the program last wrote it or mwinContext_SetTestClipboardData put it there.

Parameters:

Returns: As mwinContext_GetTestClipboard, with mwin_errorInvalid for a type the clipboard does not hold.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestPrimary(mwinContext* context, const char* bytes, size_t length);

Puts bytes in the test platform's primary selection, at once, as another program would: they need not be UTF-8.

Parameters:

Returns: As mwinContext_SetTestClipboard.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestPrimary(const mwinContext* context, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the test platform's primary selection as bytes.

Parameters:

Returns: As mwinContext_GetTestClipboard.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_PostTestDrop( mwinContext* context, mwinWindowId window, mwinPosition position, const char* files, size_t filesLength, const char* text, size_t textLength);

Drops files and text on a window of the test platform: gathered at once, delivered in order with the reports at the next pump. The drag's own records are reported with mwinContext_PostTestEvent.

Parameters:

Returns: mwin_success; mwin_errorState while an earlier drop waits; mwin_errorCapacity when 1,024 reports wait; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context, or files that are NULL with a length or not ended by a NUL.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestOpened(const mwinContext* context, mwinRequestKind kind, char* bufferOut, size_t capacity, size_t* lengthOut);

Reads the last address the test platform opened (mwin_requestOpenUrl) or path it revealed (mwin_requestRevealFile).

Parameters:

Returns: mwin_success; mwin_errorCapacity when it does not fit; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument or another kind.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_SetTestDialogFiles(mwinContext* context, const char* files, size_t length);

Sets the paths the next file dialogs choose when they are done: each ended by a NUL. None makes a done dialog fail.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context, or paths too long or not ended by a NUL.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestDialog(const mwinContext* context, char* bufferOut, size_t capacity, size_t* lengthOut);

Copies out the last file dialog the backend was asked for, as lines: its kind as a digit, title, folder and name, then each filter as its name, ':' and its extensions.

Parameters:

Returns: As mwinContext_GetTestOpened.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinContext_GetTestIcon(const mwinContext* context, size_t* countOut, uint64_t* checksumOut);

Reads the icon the backend was last given: how many images, and a checksum of them in order, 64-bit FNV-1a over each image's width and height (4 bytes each, least significant first) and its pixels, packed.

Parameters:

Returns: mwin_success; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetTestCursor(const mwinContext* context, mwinWindowId window, mwinCursorId* cursorOut, uint32_t* imageOut);

Reads the cursor made from images a window shows, with the image it took for the test backend's scale.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetTestVirtualKeyboard(const mwinContext* context, mwinWindowId window, bool* visibleOut, mwinInputPurpose* purposeOut);

Reads what a window last had carried out of its on-screen keyboard requests: whether the keyboard shows, and the purpose asked for. Hidden with mwin_purposeText before any.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetTestTextInput(const mwinContext* context, mwinWindowId window, bool* enabledOut, mwinRect* caretOut);

Reads what a window last had carried out of its text input and caret requests: whether it accepts text, and its caret, which a platform places candidate windows by. Not accepting, with an empty caret, before any.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_AskTestAccessibility(mwinContext* context, mwinWindowId window);

Plays an accessibility client asking the window for its tree, as a screen reader would: the first time, mwin_eventAccessibilityRequested follows.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorUnsupported for a context of another backend; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

window.h

Windows. A window is created at once as an id; the platform makes it real later and says so with mwin_eventWindowCreated. Every change to a window is a request: the call returns a request id, and exactly one mwin_eventRequestCompleted answers it, after the notifications the change caused. A later request of the same kind on the same window supersedes an earlier one still in flight. Nothing closes a window by itself. The platform's close button sends mwin_eventCloseRequested; the program destroys the window, or does not. Sizes come in three kinds: the logical size (the unit the program lays out in), the size in pixels, and the scale between them. Each has its own notification.

mwinWindowDef mwinDefaultWindowDef(void);

Returns the default window def: 1,280 by 720 logical units, windowed, visible, resizable and decorated, not always on top, with no title.

Returns: The def, with a valid cookie.

Thread safety. Safe from any thread.

MWIN_NODISCARD MWIN_API mwinResult mwinCreateWindow(mwinContext* context, const mwinWindowDef* def, mwinWindowId* windowOut, mwinRequestId* requestOut);

Creates a window. Its id is valid at once; mwin_eventWindowCreated follows when the platform has made it, then the completion of the request. On iPadOS a window with no scene free waits for the new scene it asks the system for, up to ten seconds: past that, or when the system refuses, the request completes mwin_outcomeFailed and no mwin_eventWindowCreated comes. Without several scenes (an iPhone, or an Info.plist without UIApplicationSupportsMultipleScenes) such a window completes mwin_outcomeUnsupported.

Parameters:

Returns: mwin_success; mwin_errorCapacity when the context has its limit of windows or the title passes the titleBytes limit; mwin_errorLimit for a canvas selector past MWIN_MAX_CANVAS_SELECTOR_BYTES; mwin_errorStale for an owner that no longer exists; mwin_errorInvalid for a NULL argument or an otherwise invalid def.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinDestroyWindow(mwinContext* context, mwinWindowId window);

Destroys a window at once: its id becomes stale, its requests in flight complete as cancelled, and mwin_eventWindowDestroyed follows. Notifications of the window not yet drained are dropped. The windows it owns are destroyed first, theirs before them.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL context.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_GetState(const mwinContext* context, mwinWindowId window, mwinWindowState* stateOut);

Reads what the program has been told about a window.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorInvalid for a NULL argument.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestTitle(mwinContext* context, mwinWindowId window, const char* title, size_t length, mwinRequestId* requestOut);

Asks for a new title.

Parameters:

Returns: mwin_success; mwin_errorStale for a window that no longer exists; mwin_errorCapacity when the window has its limit of requests in flight or the title is too long; mwin_errorInvalid for a NULL context or a title that is not UTF-8.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestSize(mwinContext* context, mwinWindowId window, mwinSize size, mwinRequestId* requestOut);

Asks for a new logical size of the area the program draws in. mwin_eventResized and mwin_eventPixelSizeChanged report what the platform chose, which may differ.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for a size that is not positive and finite.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestPosition(mwinContext* context, mwinWindowId window, mwinPosition position, mwinRequestId* requestOut);

Asks to move a window. Wayland does not let programs place windows, and answers mwin_outcomeUnsupported, except popups. A popup's position is from the top left of its owner's client area.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for a position that is not finite.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestMode(mwinContext* context, mwinWindowId window, mwinWindowMode mode, mwinRequestId* requestOut);

Asks for a mode: windowed, borderless fullscreen, minimized or maximized. A popup, always windowed, answers mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for an unknown mode.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestVisible(mwinContext* context, mwinWindowId window, bool visible, mwinRequestId* requestOut);

Asks to show or hide a window. It asks the platform for a state of the window, which mwinWindowState's visible reports, and switches no part of the library.

Parameters:

Returns: As mwinWindow_RequestTitle.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestSizeLimits(mwinContext* context, mwinWindowId window, mwinSize minimum, mwinSize maximum, mwinRequestId* requestOut);

Asks for limits on the logical size the user can give the window; a zero width or height leaves that side free.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for limits that are not finite, negative, or crossed.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestAspectRatio(mwinContext* context, mwinWindowId window, uint32_t width, uint32_t height, mwinRequestId* requestOut);

Asks the platform to keep the window's width to height at a ratio while the user resizes it; 0 by 0 lifts the constraint.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for a ratio with one side zero.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestStyle(mwinContext* context, mwinWindowId window, mwinWindowStyle style, mwinRequestId* requestOut);

Asks for a style: resizable, decorated, always on top. A popup, undecorated and above its owner, answers mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for unknown flags.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestOpacity(mwinContext* context, mwinWindowId window, float opacity, mwinRequestId* requestOut);

Asks for the window's opacity, where the platform can blend windows; others answer mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorInvalid for an opacity outside 0 to 1.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestHitRegions(mwinContext* context, mwinWindowId window, const mwinHitRegion* regions, uint32_t count, mwinRequestId* requestOut);

Tells the platform what the parts of the window's client area are, replacing what it was told before: a later region over an earlier one, and the client everywhere else. A press on a caption or an edge moves or resizes the window through the platform, and is not reported. The regions are copied at the call. The web answers mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorLimit for more regions than MWIN_MAX_HIT_REGIONS, and mwin_errorInvalid for a region not finite, of a negative size or of an unknown kind.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestIcon(mwinContext* context, mwinWindowId window, const mwinIconImage* images, uint32_t count, mwinRequestId* requestOut);

Asks for the window's icon, as its title bar, the taskbar and the window switcher show it; each platform takes the images nearest the sizes it shows. The images are copied at the call. The web, whose page has one icon for every canvas, and Wayland compositors without toplevel icons answer mwin_outcomeUnsupported.

Parameters:

Returns: As mwinWindow_RequestTitle, with mwin_errorCapacity when the context cannot hold the copy, mwin_errorLimit for more images than MWIN_MAX_ICON_IMAGES or an image larger than MWIN_MAX_ICON_SIZE a side, and mwin_errorInvalid for an image without pixels, with no width or height, or a stride shorter than its row.

Thread safety. Main thread only.

MWIN_NODISCARD MWIN_API mwinResult mwinWindow_RequestFocus(mwinContext* context, mwinWindowId window, mwinRequestId* requestOut);

Asks for keyboard focus. Platforms may refuse to take focus from another program, and answer mwin_outcomeDenied.

Parameters:

Returns: As mwinWindow_RequestTitle.

Thread safety. Main thread only.