# `tecs.platform.window` Host-neutral state and commands for one application window. Nupp owns the requested configuration and the last state observed from the host. Rust owns the `winit` window. Game-facing setters enqueue typed commands; they do not update getters optimistically because a compositor may reject or defer a request. The host drains commands, applies them, and reports a complete state snapshot or a failure for the originating serial. ## Constructors ### `newWindow` _constructor_ ```nupp function newWindow(options: Options?): Window ``` Creates a detached window contract without opening an OS window. #### Arguments | Name | Type | Description | | --- | --- | --- | | `options` | `Options?` | the copied and validated creation options | #### Returns | Type | Description | | --- | --- | | `Window` | a window ready for the Rust host to attach | ## Types ### `Command` _type_ ```nupp type Command = SetTitleCommand | SetSizeCommand | SetPositionCommand | SetVisibleCommand | SetResizableCommand | SetFullscreenCommand | SetCursorVisibleCommand | SetCursorGrabCommand | RequestRedrawCommand ``` One command drained by the Rust `winit` adapter. ### `CommandFailure` _record_ ```nupp record CommandFailure serial: integer reason: string end ``` A host rejection associated with one command serial. #### Fields ##### `serial` ```nupp serial: integer ``` ##### `reason` ```nupp reason: string ``` ### `CreateOptions` _record_ ```nupp record CreateOptions title: string width: integer height: integer resizable: boolean fullscreen: boolean decorations: boolean visible: boolean alwaysOnTop: boolean transparent: boolean x: integer? y: integer? minWidth: integer? minHeight: integer? maxWidth: integer? maxHeight: integer? end ``` The validated creation request read by the Rust host. #### Fields ##### `title` ```nupp title: string ``` ##### `width` ```nupp width: integer ``` ##### `height` ```nupp height: integer ``` ##### `resizable` ```nupp resizable: boolean ``` ##### `fullscreen` ```nupp fullscreen: boolean ``` ##### `decorations` ```nupp decorations: boolean ``` ##### `visible` ```nupp visible: boolean ``` ##### `alwaysOnTop` ```nupp alwaysOnTop: boolean ``` ##### `transparent` ```nupp transparent: boolean ``` ##### `x` ```nupp x: integer? ``` ##### `y` ```nupp y: integer? ``` ##### `minWidth` ```nupp minWidth: integer? ``` ##### `minHeight` ```nupp minHeight: integer? ``` ##### `maxWidth` ```nupp maxWidth: integer? ``` ##### `maxHeight` ```nupp maxHeight: integer? ``` ### `CursorGrab` _type_ ```nupp type CursorGrab = "none" | "confined" | "locked" ``` A pointer confinement mode understood by `winit`. ### `HostState` _record_ ```nupp record HostState id: integer title: string width: integer height: integer pixelWidth: integer pixelHeight: integer scaleFactor: number x: integer y: integer focused: boolean visible: boolean minimized: boolean maximized: boolean fullscreen: boolean occluded: boolean resizable: boolean cursorVisible: boolean cursorGrab: CursorGrab end ``` A complete host observation applied atomically to a window. #### Fields ##### `id` ```nupp id: integer ``` ##### `title` ```nupp title: string ``` ##### `width` ```nupp width: integer ``` ##### `height` ```nupp height: integer ``` ##### `pixelWidth` ```nupp pixelWidth: integer ``` ##### `pixelHeight` ```nupp pixelHeight: integer ``` ##### `scaleFactor` ```nupp scaleFactor: number ``` ##### `x` ```nupp x: integer ``` ##### `y` ```nupp y: integer ``` ##### `focused` ```nupp focused: boolean ``` ##### `visible` ```nupp visible: boolean ``` ##### `minimized` ```nupp minimized: boolean ``` ##### `maximized` ```nupp maximized: boolean ``` ##### `fullscreen` ```nupp fullscreen: boolean ``` ##### `occluded` ```nupp occluded: boolean ``` ##### `resizable` ```nupp resizable: boolean ``` ##### `cursorVisible` ```nupp cursorVisible: boolean ``` ##### `cursorGrab` ```nupp cursorGrab: CursorGrab ``` ### `Options` _type_ ```nupp type Options = { title: string?, width: integer?, height: integer?, resizable: boolean?, fullscreen: boolean?, borderless: boolean?, hidden: boolean?, alwaysOnTop: boolean?, transparent: boolean?, x: integer?, y: integer?, minWidth: integer?, minHeight: integer?, maxWidth: integer?, maxHeight: integer? } ``` Optional settings copied when the application is constructed. ### `RequestRedrawCommand` _record_ ```nupp record RequestRedrawCommand kind: "requestRedraw" serial: integer end ``` A request for a redraw callback on the next suitable host turn. #### Fields ##### `kind` ```nupp kind: "requestRedraw" ``` ##### `serial` ```nupp serial: integer ``` ### `SetCursorGrabCommand` _record_ ```nupp record SetCursorGrabCommand kind: "setCursorGrab" serial: integer mode: CursorGrab end ``` A request to change pointer confinement. #### Fields ##### `kind` ```nupp kind: "setCursorGrab" ``` ##### `serial` ```nupp serial: integer ``` ##### `mode` ```nupp mode: CursorGrab ``` ### `SetCursorVisibleCommand` _record_ ```nupp record SetCursorVisibleCommand kind: "setCursorVisible" serial: integer visible: boolean end ``` A request to show or hide the pointer. #### Fields ##### `kind` ```nupp kind: "setCursorVisible" ``` ##### `serial` ```nupp serial: integer ``` ##### `visible` ```nupp visible: boolean ``` ### `SetFullscreenCommand` _record_ ```nupp record SetFullscreenCommand kind: "setFullscreen" serial: integer fullscreen: boolean end ``` A request to enter or leave borderless desktop fullscreen. #### Fields ##### `kind` ```nupp kind: "setFullscreen" ``` ##### `serial` ```nupp serial: integer ``` ##### `fullscreen` ```nupp fullscreen: boolean ``` ### `SetPositionCommand` _record_ ```nupp record SetPositionCommand kind: "setPosition" serial: integer x: integer y: integer end ``` A request to move the top-left client position. #### Fields ##### `kind` ```nupp kind: "setPosition" ``` ##### `serial` ```nupp serial: integer ``` ##### `x` ```nupp x: integer ``` ##### `y` ```nupp y: integer ``` ### `SetResizableCommand` _record_ ```nupp record SetResizableCommand kind: "setResizable" serial: integer resizable: boolean end ``` A request to enable or disable edge resizing. #### Fields ##### `kind` ```nupp kind: "setResizable" ``` ##### `serial` ```nupp serial: integer ``` ##### `resizable` ```nupp resizable: boolean ``` ### `SetSizeCommand` _record_ ```nupp record SetSizeCommand kind: "setSize" serial: integer width: integer height: integer end ``` A request to change the logical client size. #### Fields ##### `kind` ```nupp kind: "setSize" ``` ##### `serial` ```nupp serial: integer ``` ##### `width` ```nupp width: integer ``` ##### `height` ```nupp height: integer ``` ### `SetTitleCommand` _record_ ```nupp record SetTitleCommand kind: "setTitle" serial: integer title: string end ``` A request to change the desktop title. #### Fields ##### `kind` ```nupp kind: "setTitle" ``` ##### `serial` ```nupp serial: integer ``` ##### `title` ```nupp title: string ``` ### `SetVisibleCommand` _record_ ```nupp record SetVisibleCommand kind: "setVisible" serial: integer visible: boolean end ``` A request to map or unmap the window. #### Fields ##### `kind` ```nupp kind: "setVisible" ``` ##### `serial` ```nupp serial: integer ``` ##### `visible` ```nupp visible: boolean ``` ### `Window` _record_ ```nupp record Window creationOptions: function(borrows self: Window): CreateOptions isAttached: function(borrows self: Window): boolean id: function(borrows self: Window): integer title: function(borrows self: Window): string getSize: function(borrows self: Window): (integer, integer) getPixelSize: function(borrows self: Window): (integer, integer) scaleFactor: function(borrows self: Window): number position: function(borrows self: Window): (integer, integer) hasFocus: function(borrows self: Window): boolean isVisible: function(borrows self: Window): boolean isMinimized: function(borrows self: Window): boolean isMaximized: function(borrows self: Window): boolean isFullscreen: function(borrows self: Window): boolean isOccluded: function(borrows self: Window): boolean isResizable: function(borrows self: Window): boolean isCursorVisible: function(borrows self: Window): boolean cursorGrab: function(borrows self: Window): CursorGrab setTitle: function(exclusive self: Window, title: string): integer setSize: function(exclusive self: Window, width: integer, height: integer): integer setPosition: function(exclusive self: Window, x: integer, y: integer): integer setVisible: function(exclusive self: Window, visible: boolean): integer setResizable: function(exclusive self: Window, resizable: boolean): integer setFullscreen: function(exclusive self: Window, fullscreen: boolean): integer setCursorVisible: function(exclusive self: Window, visible: boolean): integer setCursorGrab: function(exclusive self: Window, mode: CursorGrab): integer requestRedraw: function(exclusive self: Window): integer end ``` The game-facing handle for one Rust-owned window. #### Methods ##### `creationOptions` ```nupp creationOptions: function(borrows self: Window): CreateOptions ``` Returns a detached copy of the validated creation request. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `CreateOptions` | | ##### `isAttached` ```nupp isAttached: function(borrows self: Window): boolean ``` Reports whether the Rust host has attached an OS window. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `id` ```nupp id: function(borrows self: Window): integer ``` Returns the application-local host window id, or zero before attachment. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `title` ```nupp title: function(borrows self: Window): string ``` Returns the last title acknowledged by the host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `string` | | ##### `getSize` ```nupp getSize: function(borrows self: Window): (integer, integer) ``` Returns the last logical client size observed from the host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | | `integer` | | ##### `getPixelSize` ```nupp getPixelSize: function(borrows self: Window): (integer, integer) ``` Returns the last physical drawable size observed from the host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | | `integer` | | ##### `scaleFactor` ```nupp scaleFactor: function(borrows self: Window): number ``` Returns the current physical-pixels-per-logical-unit ratio. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `number` | | ##### `position` ```nupp position: function(borrows self: Window): (integer, integer) ``` Returns the last desktop position observed from the host. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | | `integer` | | ##### `hasFocus` ```nupp hasFocus: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isVisible` ```nupp isVisible: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isMinimized` ```nupp isMinimized: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isMaximized` ```nupp isMaximized: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isFullscreen` ```nupp isFullscreen: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isOccluded` ```nupp isOccluded: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isResizable` ```nupp isResizable: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `isCursorVisible` ```nupp isCursorVisible: function(borrows self: Window): boolean ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `cursorGrab` ```nupp cursorGrab: function(borrows self: Window): CursorGrab ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `CursorGrab` | | ##### `setTitle` ```nupp setTitle: function(exclusive self: Window, title: string): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `title` | `string` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setSize` ```nupp setSize: function(exclusive self: Window, width: integer, height: integer): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `width` | `integer` | | | `height` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setPosition` ```nupp setPosition: function(exclusive self: Window, x: integer, y: integer): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `x` | `integer` | | | `y` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setVisible` ```nupp setVisible: function(exclusive self: Window, visible: boolean): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `visible` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setResizable` ```nupp setResizable: function(exclusive self: Window, resizable: boolean): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `resizable` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setFullscreen` ```nupp setFullscreen: function(exclusive self: Window, fullscreen: boolean): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `fullscreen` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setCursorVisible` ```nupp setCursorVisible: function(exclusive self: Window, visible: boolean): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `visible` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `setCursorGrab` ```nupp setCursorGrab: function(exclusive self: Window, mode: CursorGrab): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | | `mode` | `CursorGrab` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `requestRedraw` ```nupp requestRedraw: function(exclusive self: Window): integer ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `Window` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ## Functions ### `applyState` _function_ ```nupp function applyState(exclusive window: Window, state: HostState): nil ``` Replaces observed state after the host applies commands or reads the OS. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the attached window contract | | `state` | `HostState` | the complete new state | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `attach` _function_ ```nupp function attach(exclusive window: Window, state: HostState): nil ``` Attaches the OS window and atomically installs its initial observed state. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the contract the host created the OS window for | | `state` | `HostState` | the complete initial state | #### Returns | Type | Description | | --- | --- | | `nil` | | #### Raises - when already attached or when the state is invalid ### `detach` _function_ ```nupp function detach(exclusive window: Window): nil ``` Detaches an OS window after host teardown. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the contract to detach | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `drainCommands` _function_ ```nupp function drainCommands(exclusive window: Window): {Command} ``` Removes the current pending command batch for the host to process. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the window whose requests the host is draining | #### Returns | Type | Description | | --- | --- | | `{Command}` | the ordered command batch, which the caller owns | ### `handleEvent` _function_ ```nupp function handleEvent(exclusive window: Window, event: platformevents.Event): nil ``` Folds a translated window event before game observers receive it. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the window contract receiving the event | | `event` | `platformevents.Event` | the ordered platform event | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `reportFailure` _function_ ```nupp function reportFailure(exclusive window: Window, serial: integer, reason: string): nil ``` Records a non-empty operational failure for one command. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the originating window | | `serial` | `integer` | the rejected command serial | | `reason` | `string` | the host failure suitable for diagnostics | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `takeFailures` _function_ ```nupp function takeFailures(exclusive window: Window): {CommandFailure} ``` Removes the current command failures for game-side diagnostics. #### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive window` | `Window` | the window whose failures are consumed | #### Returns | Type | Description | | --- | --- | | `{CommandFailure}` | the ordered failure batch, which the caller owns |