Documentation - dangvd/ksmoothdock GitHub Wiki

Table of Contents
1. What is KSmoothDock
2. How to install
3. Initial set-up
4. Programs
5. Set the panel position on the screen
6. Panel visibility
7. Settings
8. Application menu
9. Pager
10. Set different wallpapers for different desktops
11. Show Running Tasks
12. Clock
13. Multiple panels (Multiple docks)
14. Multi-screen
15. Config location
16. Troubleshooting
17. FAQs

1. What is KSmoothDock

KSmoothDock is a cool desktop panel with parabolic zooming effect for KDE Plasma 5, with the focus on smooth zooming effect and being simple and easy to use.

KSmoothDock is written in C++ and depends on Qt 5 and KDE Frameworks 5.

Historical note: Versions 1.x to 4.x were written for KDE 3.

2. How to install

You can either install from a binary package or from the source code package. The latest packages are available from the Download link on the homepage.

Option 1. (Preferably) Download and install from a binary package: Currently there is a DEB package for the Debian distribution and its derivatives (Ubuntu, Mint etc).

To install the DEB package, use dpkg/apt command, or, simply click on the DEB package from the file manager to launch the default package installer (e.g. QApt)
After the installation, KSmoothDock can be launched from the Application Menu (Utilities category), or from the command line by running:
$ ksmoothdock

Option 2. If you want to install from the source code (for example, if a package for your Linux distribution is not available), download the source code package and follow the steps below:

First, make sure you have the required Qt 5 and KDE Frameworks 5 development packages installed. On Debian-based distributions, they can be installed by running:
$ sudo apt install gettext extra-cmake-modules qtbase5-dev libkf5activities-dev libkf5config-dev libkf5coreaddons-dev libkf5dbusaddons-dev libkf5i18n-dev libkf5iconthemes-dev libkf5xmlgui-dev libkf5widgetsaddons-dev libkf5windowsystem-dev

To build, extract the ksmoothdock-6.1.tar.gz file, then, from within the extracted ksmoothdock-6.1 directory, run:
$ cmake src
$ make

You can now start the program by running the ksmoothdock binary created in that directory, i.e.:
$ ./ksmoothdock

You can also install the program by running:
$ sudo make install

After the installation, KSmoothDock can be launched from the Application Menu (Utilities category), or from the command line:
$ ksmoothdock

To uninstall, run:
$ sudo make uninstall

3. Initial set-up

When KSmoothDock runs for the first time, a welcome dialog will be displayed. Select the components and the initial position of your first panel to start.

4. Programs

The programs are combined launchers/tasks:

If there's no rounded square background around the icon, no current task (instance) of the program is running. You can left click on the icon to launch a new instance.
If there's a rounded square background around the icon, some instances of the program are running. You can shift left click on the icon to launch a new instance. Left clicking will active the instances, and cycle through them in case of multiple instances.
The active program has a brighter rounded square background.
You can pin a running task to make it a launcher on the dock, i.e. the icon will be there even if no instance is running.
You can unpin a program to make it disappear if no instance is running.

KSmoothDock initially creates a set of default launchers. To edit them, right click on the KSmoothDock panel and select "Edit Launchers". The Edit Launchers dialog will be displayed and you can add/remove/edit launchers (in addition to the quick pin/unpin options). The dialog supports a variety of options for launchers, including special ones such as show desktop, links to folders, lock the screen, separators and more.

Drag and drop: You can use drag and drop within the launcher list to reorder the launchers, or drag and drop from an external source such as K Menu to create new launchers.

5. Set the panel position on the screen

To set the panel position, right click on the panel and select Panel Settings then "Position".

6. Panel Visibility

To set the panel visibility, right click on the panel and select Panel Settings then "Visibility".

There are 4 visibility options: Always Visible, Auto Hide, Windows Can Cover and Windows Go Below:

Always Visible: the dock is always visible and reserves part of the screen for itself.
Auto Hide: the dock hides itself when the user leaves it and shows itself when the user moves the mouse on the edge of the screen that the dock resides.
Windows Can Cover (i.e. Intellihide): allows maximized windows to cover a dock panel. If covered, the dock panel will show itself when the user moves the mouse to the edge of the screen that the dock resides.
Windows Go Below: doesn't reserve screen space but maximized windows will go below a dock, unless the window is set to "Keep Above Others"

7. Appearance Settings

To edit the appearance settings, right click on the panel and select Panel Settings then "Appearance Settings". A settings dialog will be displayed and you can change various settings such as minimum/maximum icon size, background color etc. The appearance settings will apply to all the dock panels.

8. Application Menu

This is enabled by default, but to enable/disable it, right click on the panel and select Panel Settings then "Optional Features" then "Application Menu".

Features:

Traditional cascading application menu, organized by categories
Special menus/items such as Session, Power and Search (using krunner)
Consistent look with the dock
Automatically reserve screen space when showing to improve menu readability with translucent effect (this behaviour can be turned on/off)
Supporting drag action (dragging the menu items from the application menu to other destinations)
Automatically updating itself when the desktop entries have changed

To configure the application menu, right click on the dock and select "Application Menu Settings". You can then set the name, the icon and whether to reserve screen space when showing.

9. Pager

To enable the pager, right click on the panel and select Panel Settings then "Optional Features" then "Pager".

Pager features:

Can be turned on/off from KSmoothDock's context menu
Clicking on a desktop icon switches to that virtual desktop, or, if it's already the current desktop, shows/hides the desktop
Can set different wallpapers for different desktops and different screens (this requires Plasma desktop widgets to stay unlocked)
If individual wallpapers are set, the icons will be the mini version of the wallpapers

10. Set different wallpapers for different desktops

Right click on a desktop icon on the pager, and select "Set Wallpaper for Desktop X" and choose the image for the wallpaper. If you have multiple screens, you can set different wallpapers for different screens for each desktop as well.

Note: This requires Plasma desktop widgets to stay unlocked. It's because KDE Plasma 5 doesn't support setting different wallpapers for different desktops (see the bug entry), so KSmoothDock has to get around it by changing the wallpaper whenever the user changes their virtual desktop. And KDE Plasma 5 only allows the wallpaper to be changed programmatically if the desktop widgets are unlocked.

11. Show Running Tasks

To enable the task manager, right click on the panel and select Panel Settings then "Optional Features" then "Show Running Tasks".

12. Clock

To enable the clock, right click on the panel and select Panel Settings then "Optional Features" then "Clock".

Clock features:

Can be turned on/off from KSmoothDock's context menu
Left click on the clock shows calendar
Right click on the clock shows clock's context menu with 24/12 clock format option, date&time and font size settings

13. Multiple Panels

You can add/clone/remove a panel from KSmoothDock's context menu.

The panels share the same appearance settings (e.g. background color, icon min/max sizes) but can be configured individually otherwise (e.g. the components, the launchers, position, visibility).

14. Multi-screen

To set the screen that the panel resides on, right click on the panel and select "Screen".

15. Config location

KSmoothDock's config directory is $HOME/.ksmoothdock

16. Troubleshooting

Autostart KSmoothDock in KDE Plasma desktop

When autostart KSmoothDock in the KDE Plasma desktop, you have to delay the autostart a bit so that the desktop is fully started. For example, use the following command in Autostart settings: sleep 3 && ksmoothdock

Having problems running KSmoothDock in Plasma 5.10+ on the side of the screen?

Turning off Touch Screen support's edge swipe gesture (introduced in Plasma 5.10) should fix it.

Shaky animation when switching virtual desktops?

Go to System Settings -> Desktop Behavior -> Desktop Effects -> Switching Animation and select Fade Desktop.

17. FAQs

Please visit FAQs