KcdMp.focus

Asks the game to give this frame the keyboard and the mouse cursor.

Neither keyboard nor cursor is the same as KcdMp.blur. With keepInput the frame holds the keyboard without shutting the game’s out: the game still gets the player’s keys while no text field of the page has the focus.

Whether the frame gets what it asked for is decided by its focus setting in ui.toml: "never" refuses everything, "input" (the default) grants the cursor at once and the keyboard only within five seconds of the player’s own click or key press in the frame, "open" grants the cursor at any time and the keyboard after the player’s first click in the frame.

The promise rejects with an Error that says why when the request is refused: "the frame's focus policy is never", "the keyboard comes with the player's click in the frame" (a request for the keyboard the player has not made a click or key press for), "too many keyboard requests without the player's input", "the frame is hidden" and "the web layer is not running".

Syntax

await KcdMp.focus(options?)

Parameter	Type
options	KcdMpFocusOptions	what the page asks for; leave it out, or leave both keyboard and cursor off, to give the focus up (optional)

Returns

Promise<void> - settles when the game has answered; rejects when the request is refused

KcdMpFocusOptions

What a page asks for with KcdMp.focus.

Field	Type
keyboard	boolean	true to receive the keys (typed text goes to the page’s text fields) (optional)
cursor	boolean	true to receive the mouse cursor (optional)
keepInput	boolean	true to let the game keep the player’s keys while no text field of the page has the focus, so the player can walk with the page open (optional)

Example

// a text field that takes the keyboard when the player clicks into it
document.querySelector("#say").addEventListener("click", async () => {
  try {
    await KcdMp.focus({ keyboard: true, cursor: true });
  } catch (e) {
    KcdMp.log.warn("no focus: " + e.message);
  }
});

See also

KcdMp.blur · KcdMp.onVisibility · the Focus and visibility group of the index