/vertical-workspaces

V-Shell is a GNOME Shell extension that allows you to customize the layout and behavior of the Shell UI.

Primary LanguageJavaScriptGNU General Public License v3.0GPL-3.0

V-Shell (Vertical Workspaces)

A GNOME Shell extension that lets you customize your GNOME Shell UX to suit your workflow, whether you like horizontally or vertically stacked workspaces.

Currently supported GNOME versions: 42 - 46

Custom Overview Layout

Features

  • Supports both vertically and horizontally stacked workspaces
  • Customizable overview layout, appearance, behavior, shortcuts
  • Customizable secondary monitor overview
  • Static overview modes minimize screen content movement
  • Customizable app grid and app folders - icon size, dimensions, sorting, active folder previews
  • Customizable dash - icon size, appearance and behavior, workspace isolation, click and scroll actions
  • Customizable search - results width, number of results, improved searching
  • Customizable workspace switcher - static background
  • Notification and OSD positions and behavior
  • Window attention handler behavior
  • Hot corner/edge position
  • Customizable Super key behavior
  • Keyboard and mouse shortcuts allow advanced workspace and window control
  • 4 predefined and fully customizable profiles
  • Supports Dash to Dock / Ubuntu Dock / Dash to Panel

Added functionality

This section explains some of the less obvious or less visible additions to the Shell's behavior.

Overview - keyboard and mouse shortcuts

Shortcut Description
Shift + click on app icon in dash Move all windows of the application to the current workspace
Secondary mouse click on the activities indicator Open app grid
Shift + Scroll, Shift + Page Up/Down Reorder current workspace
Shift + Ctrl + Space Open V-Shell Settings window
Space Activate window search with all open windows if WSP (Window Search Provider) is installed and enabled
Ctrl + Space Activate extensions search with all installed extensions if ESP (Extensions Search Provider) is installed and enabled
Alt + Space Focus dash so you can use arrow keys to select app icon and Space/Enter to activate it

New buttons

Button Description
Close button in workspace thumbnail Close all windows on the workspace. Default setting requires double-click
Trash button in app folder Remove folder - move all icons to the main grid. Requires double-click

Active icons in app folder previews

To enhance the efficiency of the application menu, V-Shell offers the 'Active Icons in Folder Preview' option. When enabled, icons in the folder preview (folder icon) behave like regular app icons, allowing users to interact with them without opening the folder. V-Shell allows you to increase the number of icons in the preview from 4 to 9, as well as adjust the size of the app grid icons. This feature enables the folder icons to divide the main app grid into sections, with the most frequently used apps readily accessible while others remain hidden deeper within folders.

Custom Overview Layout

Open all apps in the folder at once

Simply drag-and-drop folder onto a workspace thumbnail to open all containing applications.

Known issues

Workspace navigation shortcuts

The default GNOME Shell configuration includes predefined shortcuts for workspaces oriented in both axis: (Shift)+Ctrl+Alt+ Arrow Keys and for horizontal only: (Shift)+Super+PageUp/Down

The default GNOME Settings application only offers options to configure keyboard shortcuts for horizontally oriented workspaces. However, the gSettings configuration scheme provides keys for shortcuts for vertically oriented workspaces as well. You can access and configure these shortcuts using the dconf Editor.

When V-Shell is configured to use vertically stacked workspaces, the (Shift)+Super+PageUp/Down shortcuts for switching workspaces stop working. V-Shell provides the option Override Page Up/Down Shortcuts to automatically switch the default Super+PageUp/Down and Shift+Super+PageUp/Down shortcuts for the current workspace orientation. If enabled, this option will move the shortcuts between following gSettings keys:

Horizontal orientation Vertical orientation
switch-to-workspace-left switch-to-workspace-up
switch-to-workspace-right switch-to-workspace-down
move-to-workspace-left move-to-workspace-up
move-to-workspace-right move-to-workspace-down

Note that unlike the GNOME Settings application, dconf Editor allows you to add more than one keyboard shortcut to each action. V-Shell preserves all other shortcuts, only moves following strings between related gSetting keys:

  • <Super>Page_Up
  • <Super>Page_Down
  • <Super><Shift>Page_Up
  • <Super><Shift>Page_Down

The key order follows the order in which GNOME Settings stores the shortcuts. If you add the same shortcut but with a different key order, V-Shell will not recognize it, and you might end up with the same shortcut assigned to two actions.

Stuttering overview animations

On weaker hardware, you may experience stuttering in overview animations. This usually occurs due to blur effect transitions. In this scenario, you should avoid configurations where blur transitions are needed. Here are some tips on how to use the blur effect without affecting overview animations:

  • Enable Show Workspace Preview Background, which removes the need for blur transitions between desktop view and overview.
  • Set the same amount of blur for Window Picker View and App Grid
  • If your configuration requires blur transitions, keep the Smooth Blur Transitions option disabled

Compatibility with other extensions

V-Shell overrides parts of the GNOME Shell's UI code, and many extensions do the same, so conflicts are inevitable. V-Shell tries to mitigate the consequences of conflicts with the most popular extensions, which includes disabling its own modules. This means that some of V-Shell's settings may not function when conflicting extensions are enabled. V-Shell also provides manual control over its modules so the user can disable problematic ones if needed.

Please, report any incompatibility, you encounter while using V-Shell.

Incompatible extensions

  • Search Light - You can achieve similar behavior by switching V-Shell to the Static Workspace Overview mode

V-Shell modules automatically disabled when conflicting extensions are detected

Module Extensions causing module to disable
Dash Dash to Dock, Ubuntu Dock, Dash to Panel, Dash2Dock Animated
Panel Dash to Panel, Hide Top Bar
Layout Dash to Panel, CHC-E,
WorkspaceSwitcherPopup WSM (Workspace Switcher Manager)

Extensions causing V-Shell to automatically delay its activation

to prevent crashes upon GNOME Shell starting up:

  • Dash to Dock
  • Ubuntu Dock
  • Dash to Panel
  • Dash2Dock Animated

You can enable this option manually if needed, using the Delay at Startup option on the Misc tab of the Settings window.

Extensions whose functionality is included in V-Shell

and should be disabled or restricted by the user:

  • Partially Blur My Shell - V-Shell provides a basic settings for the overview background, including brightness and blur effects. If you want to use Blur My Shell, consider disabling its options for the overview, including app folders, to prevent visual glitches and inconsistency during transitions between overview states.
  • Alphabetical App Grid - V-Shell provides much more options than alphabetical sorting
  • Grand Theft Focus and other extensions preventing showing notification instead of immediately focusing the window that demands attention
  • Hot Edge - V-Shell provides this functionality as an option of the Hot Corner Position setting
  • Some of the Just Perfection options including notifications/OSD positions, hiding main panel, animation speed, dash icon size and more
  • Impatience and extensions adjusting animation speed
  • Click to close overview - V-Shell provides the Click Empty Space To Close option

Changelog

See what's changed in recent versions CHANGELOG.md

Installation

Installation from extensions.gnome.org

The easiest way to install the latest stable release of V-Shell: go to extensions.gnome.org and toggle the switch.

Installation from the latest Github release

Download the latest release archive using following command:

wget https://github.com/G-dH/vertical-workspaces/releases/latest/download/vertical-workspaces@G-dH.github.com.zip

Install the extension (--force switch needs to be used only if some version of the extension is already installed):

gnome-extensions install --force vertical-workspaces@G-dH.github.com.zip

Installation from GitHub repository

The most recent version in the repository is the one I'm currently using and developing on my own systems, problems may occur, but usually nothing serious. The repository version may change often and doesn't updates automatically on your system. If you want to help me, use this latest version and report bugs. You may need to install git, make, gettext and glib2.0 for successful installation. Navigate to the directory you want to download the source code and execute following commands in the terminal:

GNOME 45+:

git clone https://github.com/G-dH/vertical-workspaces.git
cd vertical-workspaces
make install

GNOME 42 - 44:

git clone https://github.com/G-dH/vertical-workspaces.git
cd vertical-workspaces
git checkout gnome-42-44
make install

If you get Can't recursively copy directory error, take a look at issue #51.

Enabling the extension

After installation you need to enable the extension and access its settings.

  • First restart GNOME Shell (ALt + F2, r, Enter, or Log Out/Log In if you use Wayland)
  • Now you should see Vertical Workspaces extension in Extensions application (re-open the app if needed to load new data), where you can enable it and access its Preferences window by pressing Settings button.

Credits

V-Shell contains modified GNOME Shell source code and was originally based on parts of Vertical Overview extension.

Contribution

If you want to help with V-Shell development, please provide feedback, whether it's positive, negative, a bug report, or a feature request. Even if I don't agree with you, it can help improve V-Shell.

Donations

If you enjoy using my extensions, you can help me with my coffee expenses:

"Buy Me A Coffee"

Any support is greatly appreciated!

License

This program is distributed under the terms of the GNU General Public License, version 3 or later. See LICENSE file for details.