genode/repos/os/src/server/nitpicker

Nitpicker is the low-level GUI server of Genode. For the general concepts,
please refer to the following document:

:A Nitpicker’s guide to a minimal-complexity secure GUI:

  [http://genode-labs.com/publications/nitpicker-secure-gui-2005.pdf]


Nitpicker supports the following configuration options, supplied via Genode's
config mechanism.


Domains
~~~~~~~

Nitpicker clients are grouped into so-called domains where each domain can be
subjected to a different policy. The assignment of clients to domains is
expressed via '<policy>' nodes as illustrated by the following example:

! <config>
!   ...
!   <policy label_prefix="pointer"    domain="pointer"/>
!   <policy label_prefix="status_bar" domain="panel"/>
!   <default-policy                   domain=""/>
!   ...
! </config>

When a session is created, the session label as provided with the creation
request determines the policy rule to apply to the session. The policy with
the longest matching label comes into effect. In the example above, the
client labeled as "pointer" will be assigned to the domain named "pointer".
The client labeled as "status_bar" will be assigned to the domain "panel".
All other clients will be assigned to the third domain with an empty name.

The properties of each domain are declared via '<domain>' nodes. For example:

! <config>
!   ...
!  <domain name="pointer" layer="1" content="client" label="no" origin="pointer" />
!  <domain name="panel"   layer="2" content="client" label="no" />
!  <domain name=""        layer="3" content="tinted" label="yes"
!                         focus="click" ypos="18" height="-18" />
!   ...
! </config>

The 'name' attribute of a '<domain>' node corresponds to the 'domain'
declarations of the '<policy>' nodes.


Layering
--------

Each domain requires the definition of a 'layer', which is number. It allows
for constraining the stacking position of the domain's views to a certain part
of the global view stack. The front-most layer has the number 0. In the example
above, all views of the "pointer" domain are presented in front of all others
because the "pointer" domain is assigned to the lowest layer. All views of the
"panel" domain are placed behind the "pointer" but in front to all other views
that belong to the unnamed domain.


Domain-specific coordinate systems
----------------------------------

The operations issued by nitpicker clients refer to screen coordinates.
For each domain, the coordinate system can be constrained in the following
ways.

The 'origin' attribute specifies the location of the coordinate (0,0) on
screen. It can take the values "top_left", "top_right", "bottom_left",
"bottom_right", and "pointer". By default, the coordinate origin (0,0) refers
to the top-left screen corner. When configured to use the "pointer" as origin,
all views of the domain are positioned relative to the current pointer
position. If the mouse if moved, the movement will be applied to all views of
the domain. This enables the realization of pointer shapes outside of the
nitpicker server.

In addition to the coarse definition of the 'origin', it is possible to further
shift the origin by a fixed amount of pixels using the 'xpos' and 'ypos'
attributes. By specifying an 'ypos' value of 18 as in the example above, an
operation that places a view at (0,0) will position the view at (0,18). This is
useful to preserve a certain screen area for a panel.

The combination of the 'origin' attribute with 'xpos' and 'ypos' allows the
constraining of the screen at each border without the need to specify
values that depend on the screen dimension. E.g., for placing a panel at
the right screen border, the 'origin' attribute can be set to "top_right"
and the 'xpos' value to a negative width of the panel.


Domain-specific screen size constraints
---------------------------------------

The screen dimensions reported when a client requests the size of the screen
can be tweaked per domain. E.g., when preserving a part of the screen for a
panel, it is sensible to reduce the screen size reported to normal clients by
the size of the panel so that such clients can adjust themselves the part of
the screen not covered by the panel. The screen-size constrains are expressed
via the 'width' and 'height' attributes. If specifying a positive value, the
value is reported to the client as is. If specifying a negative value, the
value is subtracted from the physical dimensions. It is thereby possible to
shrink the reported screen size independent of the physical screen size.


Input-focus policy
------------------

The 'focus' attribute denotes if and how nitpicker assigns the input focus
to sessions of the configured domain.

:"none": No session of the domain ever receives the focus.

:"click": A session receives the focus when clicked with the mouse. After
  the mouse button is released, the session keeps the focus.

:"transient": A clicked session temporarily receives the input focus
  while a mouse button is pressed. Upon the release of the mouse button,
  the input focus is restored to the original session.

If not specified, the focus attribute defaults to 'none'.

Note that the input focus may also be manipulated via nitpicker's session
interface, which allows a client to yield the focus to other clients.

By default, nitpicker has a builtin click-to-focus policy where focus changes
are initiated exclusively by the user by clicking on a view of an unfocused
client. However, the builtin policy is not always desired. For example, in
console-like scenarios, the focus should always correspond to the visible
console regardless of any mouse clicks. Nitpicker supports such scenarios by
the use of an external focus-policy component (e.g., nit_focus). By setting
the '<config>' attribute 'focus' to "rom", the focus is obtained from an
external ROM module named "focus". The focus ROM is expected to have a 'label'
attribute with the value set to the label of the to-be focused client. When
using an external focus policy, domains configured as "click" are internally
handled like "transient" focusable domains. It is up to the external focus
policy component to make a new focus permanent by providing an updated "focus"
ROM.


Hovering policy
---------------

By default, a client receives motion events only when in possession of the
input focus and when the pointer is located over one of the client's views.
However, certain clients such as a window decorator or a panel expect to
observe motion events referring to their part of the GUI regardless of the
current input focus. Otherwise, such a client cannot give visual feedback about
the currently hovered window control. To accommodate such clients, the 'hover'
domain attribute can be set to the value "always" instead of the default value
"focused".


Tinting and labeling of screen regions
--------------------------------------

Nitpicker is able to tint and label screen regions according to the clients
that are present on screen. The tinting and labeling assists the user to
uncover Trojan Horses, which are applications that mimic the appearance of
trusted applications to sneak credentials from the user. Both the tinting
and labeling are influenced by a color configured via the 'color' attribute of
the domain.

If the domain's 'label' attribute is set to "yes", each view of the domain is
surrounded by a frame painted with the domain color. Furthermore, the textual
label of the session is painted as watermark over the view content.

If the 'content' attribute is set to "tinted", the client-provided content
is mixed with the domain color unless the client has the input focus. If set
to "client", no tinting is performed. The latter is useful for trusted domains
such as the pointer or a global panel.


Global key definitions
~~~~~~~~~~~~~~~~~~~~~~

Nitpicker is able to direct global key sequences to dedicated clients using
'<global-key>' nodes. Such a node contains the key name of the initiating key
of the sequence as 'name' attribute and the designated receiver of the sequence
as 'label' attribute. If specified, all events belonging to the sequence will
be reported to the client with the specified label. This enables clients to
handle global shortcuts. The client with the matching label will receive all
events until the number of concurrently pressed keys reaches zero. This way, it
is possible to handle chords of multiple keys starting with the key specified
in the '<key>' node. For the routing of global keys to clients, the order of
'<key>' nodes is important. If multiple nodes exists for different labels, the
first match will take effect. For example:

! <config>
!   ...
!   <global-key name="KEY_F11" label="launchpad -> testnit" />
!   <global-key name="KEY_F11" label="launchpad" />
!   ...
! </config>

The "launchpad" client will receive all key sequences starting with F11 unless
the "launchpad -> testnit" program is running. As soon as testnit gets started
by launchpad, testnit will receive the events. If the order was reversed,
launchpad would always receive the events.


Background color
~~~~~~~~~~~~~~~~

The background color can be defined via the '<background>' config node:

! <config>
!   ...
!   <background color="#112233" />
!   ...
! </config>


Status reporting
~~~~~~~~~~~~~~~~

Nitpicker can be configured to report parts of its internal state to the
outside world via report sessions. The reporting can be enabled using the
'<report>' node as follows:

! <config>
!   ...
!   <report focus="yes" />
!   ...
! </config>

The 'hover' attribute enables the reporting of the currently hovered session.
The 'focus' attribute enables the reporting of the currently focused session.
The 'pointer' attribute enables the reporting of the current absolute pointer
position.
The 'keystate' attribute enables the reporting of the currently pressed keys.
The 'clicked' attribute enables the reporting of the last clicked-on unfocused
client. This report is useful for a focus-managing component to implement a
focus-on-click policy.