SCRYMAMEReferenceSessionwindowAlso in DOSBox-X

MAMESession

window

Find where the session's window is on your displays and whether another window covers it, or bring it in front.

window(front=false)

Try it

On Gridlee, started with shared=true so that it has a window to report.
Ask

Where is the emulator's window, and can I see it?

Call
window()
Reply 1 of 3 fields
{
  "status": "ok"
}

The run hides the window block and the summary here, because where the window is differs on every host. status is ok: the host listed the window.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "window": {
    "display": "<volatile>",
    "bounds": "<volatile>",
    "onscreen": true,
    "front": "<volatile>",
    "fullscreen": false
  }
}

Arguments

front boolean, default false
true brings the window in front of whatever covers it and reads the result back. Left out, the window is reported where it is and nothing moves.

What comes back

window
Where it is: display, bounds, onscreen, fullscreen and front. front is true when no other application's window covers its centre; it does not mean the window has the keyboard focus.
size
Only when start named a size: what was asked, what is seen, and whether it matches within tolerance_px.
All 5 reply fields
  • activation (string)
  • asked_display (integer)
  • seen (object)
  • size (object)
  • window (object)

What it refuses

Why it works this way

front answers one question: can a person see the picture? It is true when the window is on screen and no other application's window covers its centre. It is not the keyboard focus, which a window nothing covers can be without.

window answers at any time, a running machine included. Without front it moves nothing and reports the window wherever you put it. With front, a session started with background=true may stay behind, and the refusal names that as the likely cause.

A size given to start is checked here, at any moment, a start still stopped included, because MAME sizes its window when it creates it. The size the server chose by itself is never checked.

More on why
  • compared says which rectangle was measured: client, the area inside the frame, on Windows; outer on macOS, which has no client area, so a title bar's height is allowed.
  • height_free is true when the emulator fits the height to the picture's aspect by itself, so only the width is checked. MAME does this on Windows.
  • display is the operating system's index, and fullscreen is true when the window's bounds are the display's.
  • On a window_not_visible refusal, asked_display is the display start asked for and activation what bringing it forward answered.
The contract your client receives
Text
Where the watched window is on the host, at any time, a running machine included. `front`
brings it in front of whatever covers it and reads that back.

Reply: `window` (`display`, the OS's index; `bounds`; `onscreen`; `front`, on screen with no other application's window covering its centre; `fullscreen`); `size` when the session was started with a stated `size`: `asked`, `seen`, which rectangle was `compared` (`client` or `outer`), `tolerance_px`, `height_free` and `matches`.

Refused: no session (`no_session`), one that died (`session_broken`), a session started without `shared` (`no_channel`), a window that never appears or, with `front`, is still covered after the activation (`window_not_visible`, naming what was seen; on a `background=true` session it names that as what may keep it behind). Without `front` the window is answered wherever the owner put it.

Reference: REFERENCE.md, The session.
Tools