This document outlines functionality, user interface design and considerations for improvements of screen management in Plasma.

Terms

screen: the combination of outputs
output: an output is a monitor connection to the system, it usually has the following properties:
- connected: cable plugged in or not
- enabled: used for displaying content, disconnected outputs can't be
- list of modes: each mode is a resolution (screen width and height pixels) and a refresh rate (for example 60Hz)
- position: the relative position to the top-left corner of the whole screen (useful only for multiscreen setups)
- current mode: the currently set mode
- preferred mode: the preferred mode, usually one of the highest resolution with a pleasant refresh rate
mode: a resolution (screen width and height pixels) and a refresh rate (for example 1920x1080 at 60Hz)

Usage cases

Here are some examples of what kind of scenarios kscreen serves.

Laptop

This is the most simple use. The resolution is picked as the preferred resolution of the only available output, the laptop's display panel. The user doesn't have to do anything, it 'just works'.

Static Workstation

The user has a more or less static setup, for example two monitors next to each other on a desktop computer.

After installation, the user has to set the relative position of the displays, so the mouse cursor leaves one and enters another output on the physically adjacent edges. Ideally, he does this once, from then on, settings are stored and adjusted on login.

Docking Station

A laptop that is sometimes connected to a docking station with additional monitors connected.

Docking stations are basically multiple connections in one. Docking station-connected monitors are essentially the same as directly connected monitors, through HDMI, VGA, etc.. They're usually identified as DisplayPort connections. An interesting detail about docked monitors is that they might not show up until connected, so they might be either displayed, but disconnected (and thus not enabled), connected and enabled, or not present at all. Not displaying disconnected displays in the UI of course solved this dichotomy, at the technical level, it's handled correctly.

Kscreen restores previously saved settings when this docking station (and monitor) is connected. The use may close the lid of the laptop, in that case, all screen contents moves to the external monitor. (There's a setting to suspend the machine regardless, in that case, screen content isn't changed. Output connections are reconsidered post-resume and restored.

Beamer

A projector is connected to a laptop to hold a presentation.

The key thing here is that an application such as Okular or libreoffice should use the projector and laptop display correctly. The fullscreen presentation goes to the primary monitor, preview and notes on the laptop screen. It shouldn't move an open email client or other application to the projector when it's plugged in, for example.

How KScreen works

To understand how kscreen solves the above problems, it's helpful to understand how it roughly works under the hood. The user-visible components running on the user's system are a system settings module and a daemon that watches hardware changes and restores previously set configurations.

Systemsettings module

The config module in system settings is located under "Display and Monitor" -> "Display Configuration". It offers a drag-and-drop ui to position and set up displays. It allows to configure:

Relative position of outputs. This is also used to select the screen that's configured in the lower part of the ui. (Useful only for multiscreen.)
"Primary display" (used for the "main" Plasma panel)
Per output:
- enabled / disabled
- resolution (list of width / height combinations, usually between 3 and 40 possible sizes (0)
- orientation: normal, rotated 90 degrees left and right, upside down
- refresh rate: usually two or three possible rates, e.g. 30Hz, 60Hz, depends on the resolution

It also offers:

display output identifier: this will show the output's name on each enabled output as on-screen display, triggered by the little (i) button in the bottom-right corner of the drag and drop interface. It's useful to find out which monitor is which in the dnd previews.
scale display: a custom display scaling factor, opens a new window to set scaling factor with preview. This one's tricky, since we can only set one scaling factor for the whole screen on X11, in Wayland, per-display scaling factors will be possible, but it's not implemented yet.
unify outputs: this will pick the highest common resolution for all enabled outputs connected, and place them on top of each other

(0) The resolution control changes depending on the number of modes, if there's less than 16 sizes in it, it's displayed as slider, if there are more, it becomes a combobox. Interestingly, this makes the ui to set up either screen in the screenshots slightly different, depending on which one is selected (assuming one of the screens has more, and one less than 15 modes.

You can find screenshots of the current kscreen module here: https://phabricator.kde.org/M63

kded background process

KScreen runs a daemon in the background, which does the following:

On session start and resume from suspend, it checks the currently connected outputs and restores a previously configured screen setup (position, outputs enabled, disabled, modes, etc.).
When an output is connected, it will again try to find a previously stored configuration and apply it.
In both cases, if it doesn't find a previous configuration, it will try to guess, usually enable a newly connected output (so get plasma to render a wallpaper on) it and position it next to the other connected outputs.
When the lid of the laptop is closed while an external output is still connected, it will disable the laptop display and move the laptop screens content (panel, windows, wallpaper etc.) to the external monitor.
When the laptop lid is opened, it will move things back to the config used before closing the lid.
When the configuration is changed, for example from the system settings module, it will save this new configuration in a config file with a combined hash of all monitors' edid information. This makes "pretty sure" that a configuration is specific to a unique combination of connected monitors.

Kscreen's kded is not directly visible to the user, it doesn't have an OSD and doesn't prompt for anything.

libkscreen

Libkscreen is a library than handles all these tasks. It's mostly irrelevant from a design point of view. It means that we can use the same user interface for wayland as well as for X11. Libkscreen handles this internally by using different backend plugins.