io7m | single-page | multi-page | JSycamore User Manual
2.2. Architecture
Previous
2. Model
Up
2.4. Windows
Next

# 2.3. Screens

- 2.3.1. Overview
- 2.3.2. Services
- 2.3.3. Events
  - 2.3.3.1. Output Events
  - 2.3.3.2. Input Event Dispatch
    - 2.3.3.2.1. Description
    - 2.3.3.2.2. Mouse Events
    - 2.3.3.2.3. Keyboard Events
- 2.3.4. Theme
- 2.3.5. Viewport

## 2.3.1. Overview

1
A screen is the top-level object in the jsycamore package. A screen acts as a container for windows, and provides access to various services such as facilities for opening menus, handling text selections, etc.
2
Most applications will only create a single screen, although there are no restrictions on creating multiple screens. Windows (and the components contained within) are confined to a single screen instance, and cannot be moved between screen instances.

## 2.3.2. Services

1
Screen instances expose service directories. Component implementations on a given screen can obtain references to various services via the screen's service directory. Screens are required to provide at least the following mandatory services:

### 2.3.2.2. Required Services

Type | Description
--- | ---
SyWindowServiceType | A service for creating and managing windows.
SyMenuServiceType | A service for creating and managing menus.
SyTextSelectionServiceType | A service for managing text selection.

## 2.3.3. Events

## 2.3.3.1. Output Events

1
A screen provides an observable stream of output events to which external code may subscribe.

## 2.3.3.2. Input Event Dispatch

## 2.3.3.2.1. Description

1
When any of the methods on the SyScreenMouseEventsType and SyScreenKeyEventsType interfaces are called, the screen will dispatch appropriate events to components inside windows that are visible on the screen.

## 2.3.3.2.2. Mouse Events

1
When dispatching mouse events, the process is as follows for an arbitrary mouse event e:

### 2.3.3.2.2.2. Mouse Event Dispatch

1. Get a list of the visible windows in order such that the frontmost windows are at the start of the list, and the rearmost windows are at the end of the list.
2. For each window w in the list of visible windows:
   1. If the viewport-space position of the mouse event (the cursor position) falls within the viewport-space bounds of w, then ask w for the active component c that is overlapped by the cursor. The window implementation is required to return the most specific component for the given position; the component that is deepest within the tree of components for the given position. If there is no appropriate c, then continue on to the next window.
   2. Assuming there was an existing component c, call the eventSend method on c, passing it the event e. The method will return a value that indicates whether the component consumed the event. If the event was consumed, execution stops here. Otherwise, if the event was not consumed, then the eventSend method is called on each recursively selected ancestor of c until either one of the ancestors consumes the event, or there are no more ancestors. If the event is consumed, execution stops here. If there are no more ancestors, we return to the first step and try the next visible window.
   3. If no component in any of the examined windows consumes e, then e is discarded.

3
Typically, successfully dispatching a mouse event to a window will result in that window becoming focused.

## 2.3.3.2.3. Keyboard Events

1
Keyboard events...

## 2.3.4. Theme

1
A screen holds a reference to the current theme.

## 2.3.5. Viewport

1
A screen defines a viewport within which are placed windows. The viewport has an explicitly-defined size, but this may be freely changed at any point.
2
Applications embedding jsycamore inside fullscreen applications, or projected into 3D spaces, are responsible for translating the platform-specific coordinates produced by keyboard and mouse input systems into the correct viewport coordinate space. For example, jsycamore can be embedded into 3D scenes by casting rays in whatever is the host 3D engine's coordinate space, and then converting the ray/plane intersection coordinates to jsycamore's viewport space:

### 2.3.5.3. 3D Projection

2.2. Architecture
Previous
2. Model
Up
2.4. Windows
Next
io7m | single-page | multi-page | JSycamore User Manual