7c968d4c60
This patch removes the policy for controlling the X-Ray mode from nitpicker to the separate component os/app/xray_trigger. Fixes #1690
216 lines
8.6 KiB
Plaintext
216 lines
8.6 KiB
Plaintext
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="pointer" domain="pointer"/>
|
||
! <policy label="status_bar" domain="panel"/>
|
||
! <policy label="" 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.
|
||
|
||
|
||
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.
|