PaperWM is an experimental Gnome Shell extension providing scrollable tiling of windows and per monitor workspaces. It's inspired by paper notebooks and tiling window managers.
Supports Gnome Shell from 3.28 to 43 on X11 and wayland.
While technically an extension it's to a large extent built on top of the Gnome desktop rather than merely extending it.
We hang out on zulip.
Clone the repo and check out the branch supporting the Gnome Shell version you're running.
- 44 (experimental, not officially supported yet, please report bugs): https://github.com/paperwm/PaperWM/tree/develop
- 43 (experimental, please report bugs): https://github.com/paperwm/PaperWM/tree/develop
- 42: https://github.com/paperwm/PaperWM/tree/gnome-42
- 40: https://github.com/paperwm/PaperWM/tree/gnome-40
- 3.28-3.38: https://github.com/paperwm/PaperWM/tree/gnome-3.38
Then run the install.sh
script
from the repository. The installer will create a link to the repo in
$XDG_DATA_HOME/gnome-shell/extensions/
. It will then ask if you want to apply
the recommended settings (see Recommended
Settings) and lastly it will ask to enable PaperWM.
./install.sh # install, load and enable paperwm
To uninstall simply run ./uninstall.sh
.
Running the extension will automatically install a user config file as described in User configuration & development.
There's three different gnome-desktop variants in Ubuntu:
ubuntu-desktop
: the defaultubuntu-gnome-desktop
: adds plain gnome sessions to the defaultvanilla-gnome-desktop
: a «plain» variant
The default ubuntu-desktop
ships with desktop-icons
which doesn't work
correctly with PaperWM (#145,
#218). Turning the extension
off in gnome-tweaks should work in
19.10,
but there's reports of this not
working
in 19.04, so your milage my vary.
For the easiest out of the box experience we reccommend ubuntu-gnome-desktop
.
vanilla-gnome-desktop
adds some keybindings which plays badly with PaperWM
(#233), making it unsuitable at
the moment.
Most functionality is available using a mouse, eg. activating a window at the edge of the monitor by clicking on it. In wayland its possible to navigate with 3-finger swipes on the trackpad. But the primary focus is making an environment which works well with a keyboard.
All keybindings start with the Super modifier. On most keyboards it's the Windows key, on mac keyboards it's the Command key. It's possible to modify the keyboard layout so that Super is switched with Alt making all the keybindings easier to reach. This can be done through Gnome Tweaks under Keybard & Mouse
⟶ Additional Layout Options
⟶ Alt/Win key behavior
⟶ Left Alt is swapped with Left Win
.
Most keybindings will grab the keyboard while Super is held down, only switching focus when Super is released. Escape will abort the navigation taking you back to the previously active window.
Adding Ctrl to a keybinding will take the current window with you when navigating.
Window management and navigation is based around the three following concepts.
New windows are automatically tiled to the right of the active window, taking up as much height as possible. SuperReturn will open a new window of the same type as the active window.
Activating a window will ensure it's fully visible, scrolling the tiling if necessary. Pressing Super. activates the window to the right. Super, activates the window to the left. On a US keyboard these keys are intuitively marked by < and >, they are also ordered the same way on almost all keyboard layouts. A minimap will be shown when Super is continually being pressed, as can be seen in the above screenshot.
Pressing SuperI will move the window to the right below the active window, tiling them vertically in a column. SuperO will do the opposite, pushing the bottom window out of the current column.
Swiping the trackpad horizontally with three fingers will scroll the tiling (only available in Wayland).
AltTab is of course also available.
PaperWM doesn't handle attached modal dialogs very well, so it's best to turn it off in Gnome Tweaks (under Windows).
Keybindings | |
---|---|
Super, or Super. | Activate the next or previous window |
SuperLeft or SuperRight | Activate the window to the left or right |
SuperUp or SuperDown | Activate the window above or below |
SuperHome or SuperEnd | Activate the first or last window |
SuperCtrl, or SuperCtrl. | Move the current window to the left or right |
SuperCtrlLeft or SuperCtrlRight | Move the current window to the left or right |
SuperCtrlUp or SuperCtrlDown | Move the current window up or down |
Supert | Take the window, placing it when finished navigating |
SuperTab or AltTab | Cycle through the most recently used windows |
SuperShiftTab or AltShiftTab | Cycle backwards through the most recently used windows |
SuperC | Center the active window horizontally |
SuperR | Resize the window (cycles through useful widths) |
SuperShiftR | Resize the window (cycles through useful heights) |
SuperF | Maximize the width of a window |
SuperShiftF | Toggle fullscreen |
SuperReturn or SuperN | Create a new window from the active application |
SuperBackspace | Close the active window |
SuperI | Absorb the window to the right into the active column |
SuperO | Expel the bottom window out to the right |
Pressing SuperAbove_Tab will slide the active workspace down revealing the stack as shown in the above screenshot. You can then flip through the most recently used workspaces with repeated Above_Tab presses while holding Super down. Above_Tab is the key above Tab (` in a US qwerty layout). Like alt-tab Shift is added to move in reverse order:
Pressing SuperPage_Down and SuperPage_Up will slide between workspaces sequentially:
The workspace name is shown in the top left corner replacing the Activities
button adding a few enhancements. Scrolling on the name will let you browse the workspace stack just like SuperAbove_Tab. Left clicking on the name opens Gnome overview, while right clicking the name lets you access and change the workspace name and the background color:
If you prefer to use another workspace indicator (or prefer none at all), you can hide this workspace name element from Gnome topbar by executing the following command from a terminal:
dconf write /org/gnome/shell/extensions/paperwm/show-workspace-indicator false
Swiping the trackpad vertically with three fingers lets you navigate the workspace stack (only available in Wayland).
There's a single scrollable tiling per workspace. Adding another monitor simply makes it possible to have another workspace visible. The workspace stack is shared among all the monitors, windows being resized vertically as necessary when workspace is displayed on another monitor.
PaperWM currently works best using the workspaces span monitors preference, this can be turned on with Gnome Tweaks under Workspaces. If you want to use workspaces only on primary you need to place the secondary monitor either below or above the primary (with the best result having it below).
Workspace Keybindings | |
---|---|
SuperAbove_Tab | Cycle through the most recently used workspaces |
SuperShiftAbove_Tab | Cycle backwards through the most recently used workspaces |
SuperCtrlAbove_Tab | Cycle through the most recently used, taking the active window with you |
SuperCtrlShiftAbove_Tab | Cycle backwards through the most recently used, taking the active window with you |
SuperPage_Down/Page_Up | Cycle sequentially through workspaces |
SuperCtrlPage_Down/Page_Up | Cycle sequentially through workspaces, taking the active window with you |
Monitor Keybindings | |
---|---|
SuperShiftArrow_key | Select neighbouring monitor |
SuperShiftCtrlArrow_key | Move active window to neighbouring monitor |
The scratch layer is an escape hatch to a familiar floating layout. This layer is intended to store windows that are globally useful like chat applications and in general serve as the kitchen sink. When the scratch layer is active it will float above the tiled windows, when hidden the windows will be minimized.
Opening a window when the scratch layer is active will make it float automatically.
Pressing SuperEscape toggles between showing and hiding the windows in the scratch layer. Activating windows in the scratch layer is done using SuperTab, the floating windows having priority in the list while active. When the tiling is active SuperShiftTab selects the most recently used scratch window.
SuperCtrlEscape will move a tiled window into the scratch layer or alternatively tile an already floating window. This functionality can also be accessed through the window context menu (AltSpace).
Keybindings | |
---|---|
SuperEscape | Toggle between showing and hiding the most recent scratch window |
SuperShiftEscape | Toggle between showing and hiding the scratch windows |
SuperCtrlEscape | Toggle between floating and tiling the current window |
SuperTab | Cycle through the most recently used scratch windows |
SuperH | Minimize the current window |
A default user configuration, user.js
, is created in ~/.config/paperwm/
with three functions init
, enable
and disable
. init
will run only once on startup, enable
and disable
will be run whenever extensions are being told to disable and enable themselves. Eg. when locking the screen with SuperL.
You can also supply a custom user.css
in ~/.config/paperwm/
. This user stylesheet can override the default styles of paperwm (e.g. from ~/.local/share/gnome-shell/extensions/paperwm@hedning:matrix.org/user.css
or /usr/share/gnome-shell/extensions/paperwm@hedning:matrix.org/user.css
), gnome or even other extensions. The same rules as for CSS in the browser apply (i.e. CSS rules are additive). To reload the user.css
(and all other loaded CSS files) you can run Main.loadTheme()
in looking glass (i.e. AltF2 lg
Return). Note that user.css
needs to already be loaded for this to work. So after initially creating the file you might need to restart gnome once.
We also made an emacs package, gnome-shell-mode, to make hacking on the config and writing extensions a more pleasant experience. To support this out of the box we also install a metadata.json
so gnome-shell-mode will pick up the correct file context, giving you completion and interactive evaluation ala. looking glass straight in emacs.
Pressing SuperInsert will assign the active window to a global variable metaWindow
, its window actor to actor
, its workspace to workspace
and its PaperWM style workspace to space
. This makes it easy to inspect state and test things out.
PaperWM provides an extension settings UI to modify many of PaperWM's more prevalent settings. This is available in the gnome-extensions
application.
Note: not all PaperWM user-configurable settings are available in the settings UI.
You can use dconf-editor
to view and modify all PaperWM user settings. You can view all settings by executing the following command from a terminal:
GSETTINGS_SCHEMA_DIR=$HOME/.local/share/gnome-shell/extensions/paperwm@hedning:matrix.org/schemas dconf-editor /org/gnome/shell/extensions/paperwm/
Below is a list of user-configurable settings that are not exposed in the PaperWM settings UI. These can be modified via dconf-editor
.
Note: experimental, incomplete or deprecated settings may not be listed below.
Setting | Description | Input Type | Default value |
---|---|---|---|
animation‑time |
Changes PaperWM animation speed. Lower values means faster animations. | number (should be >= 0) | 0.25 |
Example: speeding up animations
dconf write /org/gnome/shell/extensions/paperwm/animation-time 0.15
Setting | Description | Input Type | Default value |
---|---|---|---|
default‑background |
Sets the (default) background used for PaperWM workspaces. If set will use this background instead of colors defined in workspace-colors . |
absolute path | empty |
Note: you can override this for individual workspaces in the settings UI.
Example:
dconf write /org/gnome/shell/extensions/paperwm/default-background '"/home/user/Wallpaper/mars-sunset-2k.jpg"'
Setting | Description | Reference |
---|---|---|
default‑focus‑mode |
Sets default focus mode used in workspaces. | See Setting the default focus mode. |
Setting | Description | Reference |
---|---|---|
disable‑topbar‑styling |
Disables PaperWM's ability to style the Gnome TopBar. | See Gnome TopBar opacity / styling. |
Setting | Description | Reference |
---|---|---|
show‑focus‑mode‑icon |
Shows/hides the focus mode icon in TopBar. | See Hiding the focus mode icon. |
Setting | Description | Reference |
---|---|---|
show‑window‑position‑bar |
Shows/hides the window position indicator bar in Topbar. | See Window Position Bar. |
Setting | Description | Reference |
---|---|---|
show‑workspace‑indicator |
Shows/hides the workspace indicator element in Topbar. | See The workspace stack & monitors. |
Setting | Description | Input Type | Default value |
---|---|---|---|
use‑workspace‑name |
Use PaperWM workspace name in workspace indicator in the TopBar. Setting to false uses the gnome default name (i.e. Activities ). |
Boolean | true |
Note: this does not disable the workspace indicator, but simply makes it looks like default gnome Activities
button. To show/hide the workspace indicator element use setting show-workspace-indicator
.
Example:
dconf write /org/gnome/shell/extensions/paperwm/use-workspace-name false
Setting | Description | Input Type | Default value |
---|---|---|---|
workspace‑colors |
Sets the workspace background color palette. | String array of colors | ['#314E6C', '#565248', '#445632', '#663822', '#494066', '#826647', '#4B6983', '#807D74', '#5D7555', '#884631', '#625B81', '#B39169', '#7590AE', '#BAB5AB', '#83A67F', '#C1665A', '#887FA3', '#E0C39E'] |
It's possible to set window properties using simple rules that will be applied when placing new windows. Properties can applied to windows identified by their wm_class
or title
. The following properties are currently supported:
Property | Input type | Input example | Description |
---|---|---|---|
scratch_layer |
Boolean | true , false |
if true window will be placed on the scratch layer. |
preferredWidth |
String value with % or px unit |
"50%" , "450px" |
resizes the window width to the preferred width when it's created. Note1: property not applicable to windows on scratch layer. |
Window properties can be added using the Winprops
tab of the PaperWM extension settings:
paperwm-winprops-settings.mp4
Alternatively, you can also define winprops in the user.js
configuration file. Below is a few examples of setting window properties for Spotify and Alacritty. The below examples are best placed in the init
part of user.js
:
Tiling.defwinprop({
wm_class: "Spotify",
title: "Window Title",
scratch_layer: true,
});
Tiling.defwinprop({
wm_class: "firefox",
preferredWidth: "900px",
});
Tiling.defwinprop({
wm_class: /alacritty/i,
preferredWidth: "50%",
});
The wm_class
or title
of a window can be found by using looking glass: AltF2 lg
Return Go to the "Windows" section at the top right and find the window. X11 users can also use the xprop
command line tool (title
is referred as WM_NAME
in xprop
). The match of wm_class
and title
are with an OR condition; and in addition to a plain string matching, a constructed RegExp()
can be used to utilise regex matching.
Note1: Winprops
defined in the PaperWM extension settings take precedence over Winprops
defined using the user.js
method.
Note2: if you use the user.js
method you will need to restart Gnome shell to have them take effect.
If opening a new application window with SuperReturn isn't doing exactly what you want you can create custom functions to fit your needs. Say you want new emacs windows to open the current buffer by default, or have new terminals inherit the current directory:
let App = Extension.imports.app;
App.customHandlers['emacs.desktop'] =
() => imports.misc.util.spawn(['emacsclient', '--eval', '(make-frame)']);
App.customHandlers['org.gnome.Terminal.desktop'] =
(metaWindow, app) => app.action_group.activate_action(
"win.new-terminal",
new imports.gi.GLib.Variant("(ss)", ["window", "current"]));
The app id of a window can be looked up like this:
var Shell = imports.gi.Shell;
var Tracker = Shell.WindowTracker.get_default();
var app = Tracker.get_window_app(metaWindow);
app.get_id();
Available application actions can be listed like this:
app.action_group.list_actions();
Due to limitations in the mutter keybinding API we need to steal some built in Gnome Shell actions by default. Eg. the builtin action switch-group
with the default SuperAbove_Tab keybinding is overridden to cycle through recently used workspaces. If an overridden action has several keybindings they will unfortunately all activate the override, so for instance because AltAbove_Tab is also bound to switch-group
it will be overridden by default. If you want to avoid this, eg. you want AltTab and AltAbove_Tab to use the builtin behavior simply remove the conflicts (ie. SuperTab and SuperAbove_Tab and their Shift variants) from /org/gnome/desktop/wm/keybindings/switch-group
(no restarts required).
Extension.imports.keybindings.bindkey(keystr, name, handler, options)
Option | Values | Meaning |
---|---|---|
activeInNavigator |
true , false |
The keybinding is active when the minimap/navigator is open |
opensMinimap |
true , false |
The minimap will open when the keybinding is invoked |
let Keybindings = Extension.imports.keybindings;
Keybindings.bindkey("<Super>j", "my-favorite-width",
(metaWindow) => {
let f = metaWindow.get_frame_rect();
metaWindow.move_resize_frame(true, f.x, f.y, 500, f.h);
},
{ activeInNavigator: true });
See examples/keybindings.js
for more examples.
#476 added a coloured window position bar to the Gnome Top Bar. This allows users to visually identify the current selected window position of the scrollable viewport in the current workspace. This is demonstrated in the following video:
paperwm-window-position-bar.mp4
The the window position bar can be disabled from PaperWM extension settings
or via dconf
, e.g. by executing the following command in a terminal:
dconf write /org/gnome/shell/extensions/paperwm/show-window-position-bar false
You can style both the coloured position bar and the dimmed "position bar backdrop" by overriding the paperwm-window-position-bar
and paperwm-window-position-bar-backdrop
CSS classes respectively (see user.css
in User configuration & development section for more information). The paperwm-window-position-bar
will also inherit the selection color (same as window borders) from tile-preview
.
Note: PaperWM overrides the default Gnome Top Bar style to be completely transparent so that the dimmed window-position-bar-backdrop
andwindow-position-bar
elements are visible.
#482 added the concept of window focus modes
to PaperWM. A focus mode
controls how windows are "focused". For example, the CENTER
focus mode causes all windows to be centered horizontally on selection, whereas the DEFAULT
focus mode is the traditional PaperWM behaviour.
Focus modes can be toggled by user-settable keybinding (default is Super
+Shift
+c
), or by clicking the new focus-mode button in the topbar:
The default focus mode is the standard PaperWM focus mode (i.e. not centered). This can be changed according to preference by changing the default-focus-mode
setting via dconf
or gsettings
.
To set the default focus mode to CENTER
, execute the following from a terminal:
dconf write /org/gnome/shell/extensions/paperwm/default-focus-mode 1
To undo, or revert to the original PaperWM behaviour, execute the following:
dconf write /org/gnome/shell/extensions/paperwm/default-focus-mode 0
Note: changing this setting during a PaperWM session will set all spaces to the new default focus mode.
Users may also prefer to hide the focus mode icon. You can do so by executing the following command in a terminal:
dconf write /org/gnome/shell/extensions/paperwm/show-focus-mode-icon false
PaperWM by default changes the opacity of the Gnome TopBar. This styling is used for certain PaperWM features. However, this styling may conflict with the TopBar styling of other extensions (that you may prefer have style the TopBar instead).
Users can disable PaperWM's ability to change TopBar styling by executing the following command from a terminal:
dconf write /org/gnome/shell/extensions/paperwm/disable-topbar-styling true
Note1: you will need to restart Gnome shell after changing this setting, e.g. logout then login, or restart in place with an alt-F2
and entering r
(X11 only).
Note2: several PaperWM specific features are dependent on changing the Gnome TopBar to function correctly. If you choose to disable PaperWM's ability to change the TopBar styles (with the setting above), you may also want to disable the Window Position Bar).
See the Winprops section for a way to set the default width of windows identified by their wm_class
window property.
Currently it is not possible to have a default fixed window height. Please check the following issues for progress / info:
There's a few Gnome Shell settings which works poorly with PaperWM. Namely
workspaces-only-on-primary
: Multi monitor support require workspaces spanning all monitorsedge-tiling
: We don't support the native half tiled windowsattach-modal-dialogs
: Attached modal dialogs can cause visual glitching
To use the recommended settings run
set-recommended-gnome-shell-settings.sh
. A "restore previous settings" script is generated so the original settings is not lost.
These extensions are good complements to PaperWM:
- Vertical Overview - brings back vertically stacked workspaces
- Switcher - combined window switcher and launcher
- Dash to Dock - a great dock
A similar idea was apparently tried out a while back: 10/GUI