# tecs.platform.os


Runtime capabilities, clipboard access, and desktop services.

## Capabilities

Ask the installed build instead of inferring support from a target name.
`capabilities` distinguishes targets that share an operating system but differ
in JIT, worker, shader, storage, or device support. It reports the process
sandbox separately because that environment can restrict filesystem and child
process access without changing the target.

## Clipboard

The clipboard belongs to the desktop and can change between frames.
`events.clipboardUpdate` reports a change; read the current value when the
event arrives or when the user requests paste. Text stays UTF-8, keeps its line
endings, and stops at the first NUL. `clipboardData` preserves NULs.

Headless builds report the clipboard as unavailable. Primary selection remains
independent of the clipboard. On platforms without a shared primary selection,
reads may return only the value this process wrote.

## Process signals

SDL applications already receive `SIGINT` and `SIGTERM` as the public
`tecs.platform.events.on.quit` event and then run their normal shutdown
lifecycle. A headless loop can retain a [`SignalListener`](/modules/platform/os/#tecs.platform.os.SignalListener)
instead. `tecs.runtime.poll` transfers signals out of the native handler, and
`next` drains them without waiting:

```teal
tecs.scoped(function(scope: tecs.Scope)
    local signals <const> = scope:own(
        tecs.platform.os.newSignalListener()
    )

    local running = true
    while running do
        tecs.runtime.poll()
        local signal <const> = signals:next()
        if signal == "interrupt" or signal == "terminate" then
            running = false
        end
    end
end)
```

The native handler only sets atomic flags. It never calls Lua, allocates, or
locks. Repeated instances of one signal may coalesce before the next runtime
poll, as operating-system signals ordinarily may. When different signals are
pending in one poll, `next` returns them in the enum order rather than claiming
an arrival order the operating system did not preserve. Closing the last
listener stops interception, so a later signal follows the platform's
termination behavior again.


## Module contents

### Constructors

| Constructor | Description |
| --- | --- |
| [`newSignalListener`](/modules/platform/os/#tecs.platform.os.newSignalListener) | Creates a listener for process signals in a headless loop. |

### Types

| Type | Kind | Description |
| --- | --- | --- |
| [`Capabilities`](/modules/platform/os/#tecs.platform.os.Capabilities) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes what this build can do on this target. |
| [`DialogFilter`](/modules/platform/os/#tecs.platform.os.DialogFilter) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes one file-type filter. |
| [`DialogOptions`](/modules/platform/os/#tecs.platform.os.DialogOptions) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes dialog configuration. |
| [`DialogResult`](/modules/platform/os/#tecs.platform.os.DialogResult) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes a completed dialog. |
| [`Locale`](/modules/platform/os/#tecs.platform.os.Locale) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes one language the user prefers. |
| [`Power`](/modules/platform/os/#tecs.platform.os.Power) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes the machine's power source and remaining charge. |
| [`ProcessSignal`](/modules/platform/os/#tecs.platform.os.ProcessSignal) | <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span> | ProcessSignal identifies an interrupt, termination, hangup, or quit request sent to this process. |
| [`SignalListener`](/modules/platform/os/#tecs.platform.os.SignalListener) | <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span> | A SignalListener receives process signals in a headless loop. |

### Functions

| Function | Kind | Description |
| --- | --- | --- |
| [`capabilities`](/modules/platform/os/#tecs.platform.os.capabilities) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the capabilities of the running build. |
| [`clearClipboard`](/modules/platform/os/#tecs.platform.os.clearClipboard) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Withdraws what this application put on the system. |
| [`clipboardAvailable`](/modules/platform/os/#tecs.platform.os.clipboardAvailable) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reports whether a clipboard is available. |
| [`clipboardData`](/modules/platform/os/#tecs.platform.os.clipboardData) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the clipboard bytes for mimeType, or nil when it offers none. |
| [`clipboardMimeTypes`](/modules/platform/os/#tecs.platform.os.clipboardMimeTypes) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the clipboard MIME types in platform order. |
| [`clipboardText`](/modules/platform/os/#tecs.platform.os.clipboardText) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the clipboard text, or an empty string when it holds none. |
| [`hasClipboardData`](/modules/platform/os/#tecs.platform.os.hasClipboardData) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reports whether the clipboard offers mimeType. |
| [`hasClipboardText`](/modules/platform/os/#tecs.platform.os.hasClipboardText) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reports whether the clipboard holds text. |
| [`hasPrimarySelection`](/modules/platform/os/#tecs.platform.os.hasPrimarySelection) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reports whether the primary selection holds text. |
| [`messageBox`](/modules/platform/os/#tecs.platform.os.messageBox) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Shows a native informational, warning or error dialog. |
| [`openFile`](/modules/platform/os/#tecs.platform.os.openFile) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Opens a native file picker. |
| [`openFolder`](/modules/platform/os/#tecs.platform.os.openFolder) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Opens a native folder picker. |
| [`openURL`](/modules/platform/os/#tecs.platform.os.openURL) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Opens an absolute URI with the operating system's preferred application. |
| [`power`](/modules/platform/os/#tecs.platform.os.power) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the current battery or external-power state. |
| [`preferredLocales`](/modules/platform/os/#tecs.platform.os.preferredLocales) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the user's preferred locales in priority order. |
| [`primarySelection`](/modules/platform/os/#tecs.platform.os.primarySelection) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns text from the platform's primary selection. |
| [`resetCapabilities`](/modules/platform/os/#tecs.platform.os.resetCapabilities) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Forgets the cached answer. |
| [`saveFile`](/modules/platform/os/#tecs.platform.os.saveFile) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Opens a native save-file picker. |
| [`setClipboardText`](/modules/platform/os/#tecs.platform.os.setClipboardText) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Puts text on the clipboard, replacing whatever was there. |
| [`setPrimarySelection`](/modules/platform/os/#tecs.platform.os.setPrimarySelection) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Puts text in the primary selection. |
| [`updateDialogs`](/modules/platform/os/#tecs.platform.os.updateDialogs) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Settles file and folder dialogs that have answered. |

## Constructors

<a id="tecs.platform.os.newSignalListener"></a>
### tecs.platform.os.newSignalListener <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Creates a listener for process signals in a headless loop.

The listener receives `"interrupt"` for `SIGINT`, `"terminate"` for
`SIGTERM`, `"hangup"` for `SIGHUP`, and `"quit"` for `SIGQUIT` on POSIX.
Windows maps Ctrl-C and Ctrl-Break to `"interrupt"`, and console close,
logoff, and shutdown to `"terminate"`. Unsupported signals simply never
arrive on that platform.

SDL applications normally observe `tecs.platform.events.on.quit` instead.
SDL converts SIGINT and SIGTERM to that event and the application performs
its normal shutdown lifecycle before the process-wide runtime pump.



```teal
function tecs.platform.os.newSignalListener(
    selected: {ProcessSignal}
): SignalListener, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `selected` | `{`[`ProcessSignal`](/modules/platform/os/#tecs.platform.os.ProcessSignal)`}` | The caller supplies the signal names to retain, or omits the list to retain every supported name. An empty list and duplicate or unknown names raise as programmer errors. |

#### Returns

| Type | Description |
| --- | --- |
| [`SignalListener`](/modules/platform/os/#tecs.platform.os.SignalListener) | Returns a caller-owned listener. |
| `string` | Returns the platform reason when native signal handling cannot be installed. |

#### Examples

```teal
tecs.scoped(function(scope: tecs.Scope)
    local signals, reason = tecs.platform.os.newSignalListener({
        "interrupt", "terminate"
    })
    if signals == nil then
        error(reason)
    end
    scope:own(signals)

    local running = true
    local function update()
        tecs.runtime.poll()
        local signal <const> = signals:next()
        if signal ~= nil then
            running = false
        end
    end

    while running do
        update()
    end
end)
```

## Types

<a id="tecs.platform.os.Capabilities"></a>
### tecs.platform.os.Capabilities <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes what this build can do on this target.


```teal
record tecs.platform.os.Capabilities
    target: string
    architecture: string
    sandbox: string
    jit: boolean
    ffi: boolean
    dynamicLibraries: boolean
    hotReload: boolean
    runtimeShaders: boolean
    packagedShaders: boolean
    shaderFormats: {string}
    touch: boolean
    gamepad: boolean
    sensors: boolean
    workers: boolean
    cores: integer
    writableStorage: boolean
end
```

<a id="tecs.platform.os.Capabilities.target"></a>
#### tecs.platform.os.Capabilities.target <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. This is the platform name, such as "macOS" or "Android". A
licensed port answers with its own name instead, since everything here
describes the platform actually installed.


```teal
tecs.platform.os.Capabilities.target: string
```

<a id="tecs.platform.os.Capabilities.architecture"></a>
#### tecs.platform.os.Capabilities.architecture <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. This is the CPU architecture this build targets.


```teal
tecs.platform.os.Capabilities.architecture: string
```

<a id="tecs.platform.os.Capabilities.sandbox"></a>
#### tecs.platform.os.Capabilities.sandbox <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports `"none"`, `"unknownContainer"`, `"flatpak"`,
`"snap"` or `"macOS"` for the process environment SDL detects. A
sandbox can restrict filesystem and child-process access independently
of the target and the build's other capabilities.


```teal
tecs.platform.os.Capabilities.sandbox: string
```

<a id="tecs.platform.os.Capabilities.jit"></a>
#### tecs.platform.os.Capabilities.jit <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. This reports whether the runtime generates machine code.
False on a target that requires interpretation.


```teal
tecs.platform.os.Capabilities.jit: boolean
```

<a id="tecs.platform.os.Capabilities.ffi"></a>
#### tecs.platform.os.Capabilities.ffi <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. This is always true because every supported build requires
the FFI.


```teal
tecs.platform.os.Capabilities.ffi: boolean
```

<a id="tecs.platform.os.Capabilities.dynamicLibraries"></a>
#### tecs.platform.os.Capabilities.dynamicLibraries <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether a library can load by name at run time. It is false where every
build links every library into the executable.


```teal
tecs.platform.os.Capabilities.dynamicLibraries: boolean
```

<a id="tecs.platform.os.Capabilities.hotReload"></a>
#### tecs.platform.os.Capabilities.hotReload <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether this build supports development-time content reload.
Named independently of any one kind the watcher reloads.


```teal
tecs.platform.os.Capabilities.hotReload: boolean
```

<a id="tecs.platform.os.Capabilities.runtimeShaders"></a>
#### tecs.platform.os.Capabilities.runtimeShaders <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether this build can compile shaders from source
at run time.


```teal
tecs.platform.os.Capabilities.runtimeShaders: boolean
```

<a id="tecs.platform.os.Capabilities.packagedShaders"></a>
#### tecs.platform.os.Capabilities.packagedShaders <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether the engine reads shaders from a packaged artifact. Independent of
`runtimeShaders`: a development build may have both, and a release has
only this.


```teal
tecs.platform.os.Capabilities.packagedShaders: boolean
```

<a id="tecs.platform.os.Capabilities.shaderFormats"></a>
#### tecs.platform.os.Capabilities.shaderFormats <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Lists the shader formats this target consumes. It contains one entry, since a build supplies
one format.


```teal
tecs.platform.os.Capabilities.shaderFormats: {string}
```

<a id="tecs.platform.os.Capabilities.touch"></a>
#### tecs.platform.os.Capabilities.touch <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether the machine currently has a touch device. This describes the machine
rather than of the target: a desktop with a touchscreen has one.


```teal
tecs.platform.os.Capabilities.touch: boolean
```

<a id="tecs.platform.os.Capabilities.gamepad"></a>
#### tecs.platform.os.Capabilities.gamepad <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports true because every target reaches gamepads through the same subsystem,
so only the connected devices vary, which the `gamepads`
method on [`Input`](/modules/input/#tecs.input.Input) answers.


```teal
tecs.platform.os.Capabilities.gamepad: boolean
```

<a id="tecs.platform.os.Capabilities.sensors"></a>
#### tecs.platform.os.Capabilities.sensors <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether the device carries a gyroscope or an accelerometer. This says
nothing about a gamepad's sensors, which `hasSensor` on
[`Gamepad`](/modules/input/#tecs.input.Gamepad) answers per device.


```teal
tecs.platform.os.Capabilities.sensors: boolean
```

<a id="tecs.platform.os.Capabilities.workers"></a>
#### tecs.platform.os.Capabilities.workers <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether work can run off the main thread.


```teal
tecs.platform.os.Capabilities.workers: boolean
```

<a id="tecs.platform.os.Capabilities.cores"></a>
#### tecs.platform.os.Capabilities.cores <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the number of logical cores for sizing a worker pool.


```teal
tecs.platform.os.Capabilities.cores: integer
```

<a id="tecs.platform.os.Capabilities.writableStorage"></a>
#### tecs.platform.os.Capabilities.writableStorage <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports true because every target has somewhere to write,
and `tecs.io.files.preferencePath` and `tecs.io.files.cachePath` answer
where: the field exists so a caller can ask rather than assume, not
because a target answers no.


```teal
tecs.platform.os.Capabilities.writableStorage: boolean
```

<a id="tecs.platform.os.DialogFilter"></a>
### tecs.platform.os.DialogFilter <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes one file-type filter.


```teal
record tecs.platform.os.DialogFilter
    name: string
    pattern: string
end
```

<a id="tecs.platform.os.DialogFilter.name"></a>
#### tecs.platform.os.DialogFilter.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the label shown beside the filter, such as
`"Images"`.


```teal
tecs.platform.os.DialogFilter.name: string
```

<a id="tecs.platform.os.DialogFilter.pattern"></a>
#### tecs.platform.os.DialogFilter.pattern <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets semicolon-separated extensions, such as
`"png;jpg;jpeg"`.


```teal
tecs.platform.os.DialogFilter.pattern: string
```

<a id="tecs.platform.os.DialogOptions"></a>
### tecs.platform.os.DialogOptions <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes dialog configuration.


```teal
record tecs.platform.os.DialogOptions
    window: Window
    filters: {DialogFilter}
    defaultLocation: string
    multiple: boolean
end
```

<a id="tecs.platform.os.DialogOptions.window"></a>
#### tecs.platform.os.DialogOptions.window <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the window that owns the dialog.


```teal
tecs.platform.os.DialogOptions.window: Window
```

<a id="tecs.platform.os.DialogOptions.filters"></a>
#### tecs.platform.os.DialogOptions.filters <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the available file-type filters.


```teal
tecs.platform.os.DialogOptions.filters: {DialogFilter}
```

<a id="tecs.platform.os.DialogOptions.defaultLocation"></a>
#### tecs.platform.os.DialogOptions.defaultLocation <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the initial file or folder. Omit it to let the
platform choose.


```teal
tecs.platform.os.DialogOptions.defaultLocation: string
```

<a id="tecs.platform.os.DialogOptions.multiple"></a>
#### tecs.platform.os.DialogOptions.multiple <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Allows the user to select more than one path.


```teal
tecs.platform.os.DialogOptions.multiple: boolean
```

<a id="tecs.platform.os.DialogResult"></a>
### tecs.platform.os.DialogResult <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes a completed dialog.


```teal
record tecs.platform.os.DialogResult
    paths: {string}
    filter: integer
    canceled: boolean
end
```

<a id="tecs.platform.os.DialogResult.paths"></a>
#### tecs.platform.os.DialogResult.paths <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Contains selected paths. It is empty when the user canceled.


```teal
tecs.platform.os.DialogResult.paths: {string}
```

<a id="tecs.platform.os.DialogResult.filter"></a>
#### tecs.platform.os.DialogResult.filter <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the one-based selected filter, or zero when no
filter applies.


```teal
tecs.platform.os.DialogResult.filter: integer
```

<a id="tecs.platform.os.DialogResult.canceled"></a>
#### tecs.platform.os.DialogResult.canceled <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether the user canceled the dialog.


```teal
tecs.platform.os.DialogResult.canceled: boolean
```

<a id="tecs.platform.os.Locale"></a>
### tecs.platform.os.Locale <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes one language the user prefers.


```teal
record tecs.platform.os.Locale
    language: string
    country: string
end
```

<a id="tecs.platform.os.Locale.language"></a>
#### tecs.platform.os.Locale.language <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Contains an ISO 639 language code, such as `"en"`.


```teal
tecs.platform.os.Locale.language: string
```

<a id="tecs.platform.os.Locale.country"></a>
#### tecs.platform.os.Locale.country <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Contains an ISO 3166 country code, such as `"US"`, or an empty string when the
platform names only a language.


```teal
tecs.platform.os.Locale.country: string
```

<a id="tecs.platform.os.Power"></a>
### tecs.platform.os.Power <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes the machine's power source and remaining charge.


```teal
record tecs.platform.os.Power
    state: string
    seconds: integer
    percent: integer
end
```

<a id="tecs.platform.os.Power.state"></a>
#### tecs.platform.os.Power.state <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports `"unknown"`, `"onBattery"`, `"noBattery"`, `"charging"`,
`"charged"` or `"error"`.


```teal
tecs.platform.os.Power.state: string
```

<a id="tecs.platform.os.Power.seconds"></a>
#### tecs.platform.os.Power.seconds <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports seconds of battery life remaining, or -1 when
unavailable.


```teal
tecs.platform.os.Power.seconds: integer
```

<a id="tecs.platform.os.Power.percent"></a>
#### tecs.platform.os.Power.percent <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports charge percentage in 0..100, or -1 when unavailable.


```teal
tecs.platform.os.Power.percent: integer
```

<a id="tecs.platform.os.ProcessSignal"></a>
### tecs.platform.os.ProcessSignal <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span>

`ProcessSignal` identifies an interrupt, termination, hangup, or quit
request sent to this process.


```teal
enum tecs.platform.os.ProcessSignal
    "hangup"
    "interrupt"
    "quit"
    "terminate"
end
```

<a id="tecs.platform.os.SignalListener"></a>
### tecs.platform.os.SignalListener <span class="tealdoc-kind-badge tealdoc-kind-interface">interface</span>

A `SignalListener` receives process signals in a headless loop.


```teal
interface tecs.platform.os.SignalListener is Closeable
    isClosed: function(self): boolean
    next: function(self): ProcessSignal
    pending: function(self): integer
end
```

#### Interfaces

| Interface |
| --- |
| [`Closeable`](/modules/#tecs.Closeable) |

<a id="tecs.platform.os.SignalListener.isClosed"></a>
#### tecs.platform.os.SignalListener:isClosed <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether this listener has been closed.



```teal
function tecs.platform.os.SignalListener.isClosed(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `SignalListener` | The listener to inspect. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns true after `close`. |

<a id="tecs.platform.os.SignalListener.next"></a>
#### tecs.platform.os.SignalListener:next <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Removes and returns one queued signal without waiting.

The call returns nil when no selected signal has arrived since the
listener was created or last drained. Signals transferred by the same
runtime poll are returned in enum order, not arrival order.


```teal
function tecs.platform.os.SignalListener.next(self): ProcessSignal
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `SignalListener` | The open listener whose queue advances. |

##### Returns

| Type | Description |
| --- | --- |
| [`ProcessSignal`](/modules/platform/os/#tecs.platform.os.ProcessSignal) | Returns one selected signal, or nil when none is pending. |

<a id="tecs.platform.os.SignalListener.pending"></a>
#### tecs.platform.os.SignalListener:pending <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the number of signals waiting to be read.

Signals of the same kind may coalesce before a runtime poll. The count
covers deliveries already transferred to this listener.


```teal
function tecs.platform.os.SignalListener.pending(self): integer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `SignalListener` | The open listener to inspect. |

##### Returns

| Type | Description |
| --- | --- |
| `integer` | Returns the queued delivery count. |

## Functions

<a id="tecs.platform.os.capabilities"></a>
### tecs.platform.os.capabilities <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the capabilities of the running build.

The function caches its answer because these values do not change while a
platform remains installed. The platform generation keys the cache, so
installing a platform drops the value without
anybody calling `resetCapabilities`.


```teal
function tecs.platform.os.capabilities(): Capabilities
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| [`Capabilities`](/modules/platform/os/#tecs.platform.os.Capabilities) | The same table on every call until the platform changes. Shared, so a caller that means to keep it does not also mean to edit it. |

<a id="tecs.platform.os.clearClipboard"></a>
### tecs.platform.os.clearClipboard <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Withdraws what this application put on the system.

The clipboard is left empty rather than restored to what preceded the
write, because nothing anywhere remembers what that was.


```teal
function tecs.platform.os.clearClipboard(): boolean
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.clipboardAvailable"></a>
### tecs.platform.os.clipboardAvailable <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reports whether a clipboard is available.

False in a process that never brought up video, where every other function
here answers empty or false. Distinguishes that from a clipboard that is
simply empty, which no other return value can.


```teal
function tecs.platform.os.clipboardAvailable(): boolean
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.clipboardData"></a>
### tecs.platform.os.clipboardData <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the clipboard bytes for `mimeType`, or nil when it offers none.

The caller releases the returned
[`Buffer`](/modules/io/#tecs.io.Buffer).
Returns nil rather than an empty buffer because the clipboard can offer a
MIME type with no bytes, which differs from not offering that type.


```teal
function tecs.platform.os.clipboardData(mimeType: string): IOBuffer
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `mimeType` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| [`IOBuffer`](/modules/io/#tecs.io.Buffer) |  |

<a id="tecs.platform.os.clipboardMimeTypes"></a>
### tecs.platform.os.clipboardMimeTypes <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the clipboard MIME types in platform order.

The same list `clipboardUpdate` carries, for a caller that wants to ask
rather than wait to be told. Empty when the clipboard is empty.


```teal
function tecs.platform.os.clipboardMimeTypes(): {string}
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `{string}` |  |

<a id="tecs.platform.os.clipboardText"></a>
### tecs.platform.os.clipboardText <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the clipboard text, or an empty string when it holds none.

Empty is also the answer when the clipboard holds something that is not
text, and when there is no video. Ask `hasClipboardText` to tell those from text
that is genuinely empty.


```teal
function tecs.platform.os.clipboardText(): string
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `string` |  |

<a id="tecs.platform.os.hasClipboardData"></a>
### tecs.platform.os.hasClipboardData <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reports whether the clipboard offers `mimeType`.


```teal
function tecs.platform.os.hasClipboardData(mimeType: string): boolean
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `mimeType` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.hasClipboardText"></a>
### tecs.platform.os.hasClipboardText <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reports whether the clipboard holds text.

Cheaper than reading it: no allocation crosses the boundary, and on a
platform where a read negotiates with the owning application, no
negotiation happens.


```teal
function tecs.platform.os.hasClipboardText(): boolean
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.hasPrimarySelection"></a>
### tecs.platform.os.hasPrimarySelection <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reports whether the primary selection holds text.


```teal
function tecs.platform.os.hasPrimarySelection(): boolean
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.messageBox"></a>
### tecs.platform.os.messageBox <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Shows a native informational, warning or error dialog.


```teal
function tecs.platform.os.messageBox(
    kind: string, title: string, message: string, window: Window
): boolean, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `string` |  |
| `title` | `string` |  |
| `message` | `string` |  |
| `window` | `Window` |  |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |
| `string` |  |

<a id="tecs.platform.os.openFile"></a>
### tecs.platform.os.openFile <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Opens a native file picker.


```teal
function tecs.platform.os.openFile(
    options: DialogOptions
): Future<DialogResult>
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | [`DialogOptions`](/modules/platform/os/#tecs.platform.os.DialogOptions) |  |

#### Returns

| Type | Description |
| --- | --- |
| [`Future`](/modules/Future/)`<`[`DialogResult`](/modules/platform/os/#tecs.platform.os.DialogResult)`>` |  |

<a id="tecs.platform.os.openFolder"></a>
### tecs.platform.os.openFolder <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Opens a native folder picker.


```teal
function tecs.platform.os.openFolder(
    options: DialogOptions
): Future<DialogResult>
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | [`DialogOptions`](/modules/platform/os/#tecs.platform.os.DialogOptions) |  |

#### Returns

| Type | Description |
| --- | --- |
| [`Future`](/modules/Future/)`<`[`DialogResult`](/modules/platform/os/#tecs.platform.os.DialogResult)`>` |  |

<a id="tecs.platform.os.openURL"></a>
### tecs.platform.os.openURL <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Opens an absolute URI with the operating system's preferred application.

This is not limited to web URLs. The operating system may route `https:`
to a browser, `mailto:` to a mail client, and application-specific schemes
such as `steam:` to their registered handler. Tecs passes the string to SDL
without parsing it, so the platform decides which schemes it accepts and
which application handles them.



```teal
function tecs.platform.os.openURL(url: string): boolean, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `url` | `string` | The caller supplies a non-empty absolute URI. Embedded NUL bytes are not supported by SDL's C-string boundary. |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns true after the operating system accepts the launch request. |
| `string` | Returns SDL's reason when the URI is empty, unsupported, malformed, or cannot be opened. |

<a id="tecs.platform.os.power"></a>
### tecs.platform.os.power <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the current battery or external-power state.


```teal
function tecs.platform.os.power(): Power
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| [`Power`](/modules/platform/os/#tecs.platform.os.Power) |  |

<a id="tecs.platform.os.preferredLocales"></a>
### tecs.platform.os.preferredLocales <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the user's preferred locales in priority order.


```teal
function tecs.platform.os.preferredLocales(): {Locale}
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `{`[`Locale`](/modules/platform/os/#tecs.platform.os.Locale)`}` |  |

<a id="tecs.platform.os.primarySelection"></a>
### tecs.platform.os.primarySelection <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns text from the platform's primary selection.

On X11 and Wayland, selecting text places it in a clipboard separate from
the ordinary copy-and-paste clipboard, commonly pasted with the middle
mouse button. Platforms without that concept expose only the value this
process last supplied through `setPrimarySelection`; other applications do
not see it. This function does not read `clipboardText`.



```teal
function tecs.platform.os.primarySelection(): string
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `string` | Returns UTF-8 text, or an empty string when the selection is empty or no video subsystem is available. |

<a id="tecs.platform.os.resetCapabilities"></a>
### tecs.platform.os.resetCapabilities <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Forgets the cached answer. Capability lookup notices a platform change without this.


```teal
function tecs.platform.os.resetCapabilities()
```

#### Arguments

None.

#### Returns

None.

<a id="tecs.platform.os.saveFile"></a>
### tecs.platform.os.saveFile <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Opens a native save-file picker. Returns at most one path.


```teal
function tecs.platform.os.saveFile(
    options: DialogOptions
): Future<DialogResult>
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | [`DialogOptions`](/modules/platform/os/#tecs.platform.os.DialogOptions) |  |

#### Returns

| Type | Description |
| --- | --- |
| [`Future`](/modules/Future/)`<`[`DialogResult`](/modules/platform/os/#tecs.platform.os.DialogResult)`>` |  |

<a id="tecs.platform.os.setClipboardText"></a>
### tecs.platform.os.setClipboardText <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Puts `text` on the clipboard, replacing whatever was there.

The platform copies the string before this call returns. Returns false
when the platform refused, which includes having no video.


```teal
function tecs.platform.os.setClipboardText(text: string): boolean
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.setPrimarySelection"></a>
### tecs.platform.os.setPrimarySelection <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Puts `text` in the primary selection.

Succeeds on a platform that has no shared primary selection, where the
value remains visible only to this process.


```teal
function tecs.platform.os.setPrimarySelection(text: string): boolean
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |

#### Returns

| Type | Description |
| --- | --- |
| `boolean` |  |

<a id="tecs.platform.os.updateDialogs"></a>
### tecs.platform.os.updateDialogs <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Settles file and folder dialogs that have answered.

[`runtime.poll`](/modules/runtime/#tecs.runtime.poll) calls this while a
dialog is open. It remains public for a test or a specialized headless loop
that deliberately drives dialogs alone.


```teal
function tecs.platform.os.updateDialogs(): integer
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `integer` |  |