Windows

Windows are, by default, recipients of multiple types of input events.

In most cases, the size and position (and source size and source position) of pointer and touch events determine where the focus of the input goes. That is, the window that surrounds the size and position of the pointer or touch event is usually the one that receives the input event. However, there are several things that can impact whether a window is the focus for input events:

a window's life cycle: The window's life cycle affects focus. When windows are created and destroyed, they gain and lose sensitivity to input events.
a window's visibility: When something changes that affects the visibility of a window, it also impacts input focus. If a window goes from being visible to being invisible, it loses input focus.
a window's z-order: A window's z-order determines whether the window gets input focus. Generally speaking, when there are two windows overlapping, the one that has the higher z-order (the one on top) gets input focus over the other window.

Setting a window's SCREEN_PROPERTY_SENSITIVITY property is a simple way to change the behavior of how a window accepts input events. The window's SCREEN_PROPERTY_SENSITIVITY can be set to a combination of Screen sensitivity masks. If you're looking for a more advanced way of directing input events within a window, you can use sessions.

The input focus is tracked within each window group, not just on the display. The property SCREEN_PROPERTY_FOCUS is used for this purpose. The display tracks the top-level application window that's visible on the display that has input focus. The group tracks the window within the group that has input focus. For the window, SCREEN_PROPERTY_FOCUS is just an indicator to state whether the window currently has input focus.

Idle state

If there are no input events received by a group or a display within the period of time set by SCREEN_PROPERTY_IDLE_TIMEOUT, then the group or display may go into an idle state (SCREEN_PROPERTY_IDLE_STATE). When in idle state, a display manager may choose to power down the display to, say, conserve energy.

Your application can influence what the window wants to happen when the display goes idle by setting its SCREEN_PROPERTY_IDLE_MODE property. The window can choose to either allow the display to go idle, and potentially turn off, or request that the display continue to be powered on even after the SCREEN_PROPERTY_IDLE_TIMEOUT has expired. A window may set its idle mode to SCREEN_IDLE_MODE_KEEP_AWAKE if, for instance, it's performing video playback. In this case, even though there's no input, the display needs to remain powered up to show the video. Refer to Screen idle mode types for valid idle modes. The windows whose SCREEN_PROPERTY_IDLE_MODE are set to SCREEN_IDLE_MODE_KEEP_AWAKE are tallied into the display's SCREEN_PROPERTY_KEEP_AWAKES property.

When a display manager is evaluating whether to power down the display, it takes into account the display's SCREEN_PROPERTY_KEEP_AWAKES property. This property lets the display manager know the number of windows (on that display) that requested that the display remain powered up. Although windows can suggest what the display should do, it's ultimately the display manager that makes the call on whether the display is powered up or down.