Introduction - KanoComputing/kdesk GitHub Wiki

The tool

Kano Desktop Manager, aka kdesk, is a lightweight desktop manager optimized for Kano OS and other Debian-based systems, including the desktop background image, icons, and egl screensaver.

We’ve created the utility from scratch, with inspiration taken from other desktop managers, especially idesk and vdesk.

Features:

  • optimized connection with the notify library for Openbox window manager and others, so the hourglass start-up feature works seamlessly
  • 100% customizable background, icons, screensaver
  • efficient screensaver with low CPU usage

How to install it

Kano OS

kdesk is installed by default in Kano OS.
Package name: kdesk
Binaries:

  • /usr/bin/kdesk
  • /usr/bin/kdesk-eglsaver

Other environments

Follow the development instructions

Manual installation

To replace the default desktop icon manager in LXDE, edit this file /etc/xdg/lxsession/LXDE/autostart by adding @kdesk.

In debug mode, you can save a log of the progress replacing the above line with this: /bin/bash -c "kdesk > /tmp/kdesk.log 2>&1

How it works

Normal kdesk invocation is simply done by running kdesk & from the command line or through the Xinitrc of your choice. kdesk -h will give you a brief help along with 2 more options:

  • kdesk -t: tests and displays your current configuration
  • kdesk -w: draws the desktop wallpaper and quits
  • kdesk -r: refresh the settings

Configuration files

There is a global settings configuration file: .kdeskrc and a kdesktop directory which contains .lnk files, each one defines a desktop icon.

kdeskrc

Configuration of the desktop is handled by the file /usr/share/kano-desktop/kdesk/.kdeskrc. Any or all of these settings can be overriden on a per-user basis by a file of the same name contained in your home directory. Single entries will suffice so for example you can override the background by simply having the key Background.File-4-3 in your homedir .kdeskrc file.

Kdesk will only fail if neither of these files can be found or parsed.

The following keywords allow for extra functionalities in kdesk itself:

  • ScreenSaverTimeout - Time in seconds of user idle time before the screen saver should start. The value 0 disables the screen saver.
  • ScreenSaverProgram - The path to a program to be started as the screen saver. The program should itself watch for further user input and exit.
  • EnableSound - If this flag is set to true, sounds will be enabled
  • SoundWelcome - Path to an mp3 sound file to be played on kdesk startup
  • SoundLaunchApp - Path to an mp3 sound file to be played when the user double clicks on a disabled icon
  • SoundDisabledIcon - Path to an mp3 sound file to be played when the user double clicks and starts an app
  • OneClick - If this flag is set to true, one single mouse click will start the icon apps. Default is false.
  • Background.File-medium - Filename of the wallpaper image used for Medium resolution screens (see ScreenMedResWidth)
  • ScreenMedResWidth - Minimal screen width of the screen in pixels to be considered as high resolution wallpaper mode. If the screen resolution falls below this width, the wallpaper "Background.File-medium" will be displayed. instead of the high resolution ones (background.file-4-3, background.file-16-9). The default is none, which means high resolution.
  • MouseHoverIcon - ID of a mouse pointer to display when mouse moves over each icon. The default is XC_hand1 (#58), a waiting hand icon as defined by the official font icon cursor table, which can be replaced by themes: http://tronche.com/gui/x/xlib/appendix/b/ Please provide the constants in numerical form.
  • Transparency - Applies a transparency level to each icon on the desktop. A value from 1 to 255 can be supplied. 1 is totally transparent, 255 completely opaque. The default is 255.
  • GridWidth and GridHeight - By default the grid size is set to 128x128 pixels for each icon. These settings allow for changing it. This sets the size of the icon boxes, which includes space for the attributes Message, HoverIcon and Caption.
  • GridIconWidth and GridIconHeight - All icons (images) placed inside a grid will be uniformly resized to these attributes. The values need to fall below GridWidth and GridHeight, as they define the containing area.
  • MaximizeSingleton - boolean setting which when set to true will bring your icon's application to the foreground when the icon is clicked. The icon's AppID attribute will be used to find your app's window. By default it is set to false.
  • DefaultDesktopIcon - Specifies a default icon in cases where the lnk files point to missing image files, or when the svg conversion fails for some reason.

Kdesk Refresh

Kdesk provides for a signal handler to refresh its settings. It will reload your configuration and icon files and recreate the desktop. The wallpaper will also be reloaded.

There are 2 ways to achieve this: If you are bound to the XServer display, just do:

$ kdesk -r

If you are outside the display (ssh remote session for example) you can do:

kill -HUP $(pidof kdesk)

kdesktop files

Icons are defined in independent files located under /usr/share/kano-desktop/kdesk/kdesktop directory, and also under homedir/.kdesktop.

The following optional keywords allow for extra functionality applied to each icon on the desktop.

  • Singleton - When this flag is set to true, kdesk will only allow a single running instance of this app
  • AppID - This attribute is used for Singleton applications to decide wether the application is running or not. KDesk uses the application window title and class name (as returned for example by the GNU tool XWinInfo) to match against this attribute.
  • IconHover - Path and filename to a second texture icon that will be drawn when the mouse moves over the icon.
  • HoverXOffest - Number of pixels to displace the second texture icon to the right of the original icon position
  • HoverYOffest - Number of pixels to displace the second texture icon to the bottom from the original icon position
  • HoverTransparent - Wether the second texture icon is blended on top of the original icon during mouse over motions. A value of zero (default) means no blending, 255 meaning strong color blending. Intermediate values in the 100 range create a smooth mix of both blended images.
  • Message - A text literal which is rendered next to the icon. Default is to the right. The icon's width attribute needs to be wide enough for the text to fit. It supports dual-line with the OR character marker |, in this case the text below will be rendered with a font size 2 points smaller.
  • IconStamp - Path and filename to an additional icon which is drawn on top of the first one, centered, and respecting the alpha channel. It is changeable via Icon Hooks so you can animate a frame around the icon, or conversely, change a central icon around a frame, dynamically. IconHover can still be applied even when IconStamp is in effect, and it will be rendered taking the Icon attribute image dimensions.
  • HAlign - Wether the icon should be align the the left or right of the icon box. This is specially useful when using the Message attribute.

It is possible to use svg icons. In this case kdesk will convert them to png files, place them in your home cache directory .cache/kdesk/icons, and replace the paths automatically. The cache directory will be recreated during a normal kdesk load and a refresh as well kdesk -r if it is not found.

##### Icon Grids

Icon Grids enable you ask Kdesk to position the icons on the desktop for you. You can turn it on by putting the following into the icon config file:

Relative-to: grid
X: <grid-location-hint>
Y: <grid-location-hint>

kdesk will try to satisfy the field based on your location hints, but in cases it cannot, it will position the icon automatically. In case you don't care about the position of the icon at all, just set X and Y to 'auto'.

Note that the attributes Width and Height are IGNORED when the icon is put into the grid! Both of them are forced to 128 by default, or by the attributes GridWidth and GridHeight in the .kdeskrc file, so the grid is uniform.

Screensaver

Kdesk-eglsaver

This app is kdesk's default screen saver. It renders three bitmaps on a black background screen which are rotated on a 3D effect in slow motion. It uses the native RaspberryPI Opengl GPU features thus it looks very comfortable to the user, consumes low CPU power and completely hides applications which would draw on the framebuffer, as is the case with Minecraft or omxplayer.

Kfbsaver

Kfbsaver is a framebuffer based screen saver showing a fixed color on top of the desktop. It was developed as a first approach for integrating into Kanux but it is no optimally fitted as it causes flickering effects with framebuffer based apps like Minecraft and omxplayer. It is not being built/packaged.

You should use kdesk-eglsaver instead.

Kdesk Icon Hooks

Introduced in Kdesk version 1.02 is the concept of Icon Hooks. This facility enables you to change visual aspects of the icons at run-time via signals kdesk -a icon_name. Perhaps you want to bring life to an icon to visually tell if Internet is up and change the icon image on the fly? Then this is for you. Here's how it works:

  • Add the key IconHook in .kdeskrc to point to a program of your choice, the icon hook script
  • Start kdesk as you normally would
  • From a terminal type kdesk -a icon where icon is the filename of the desktop icon you want to animate - without the .lnk extension. Names are case insensitive.
  • Kdesk will execute your Icon Hook program giving you the name of your icon, so you can change its appearance

Now, in your Icon Hook script do whatever logic processing you need to decide what visual changes need be applied, and tell kdesk via stdout which flags you want changed, for example:

  • Icon: mynewicon.png will change the icon immediately.
  • Caption: My new title will do the same for the text rendered just below the icon.
  • Message: This is a new icon status will render a text message at either side of the icon (see the new icon flag halign for horizontal alignment).

The Icon Hook script can be written in any language and it uses the standard output to communicate with Kdesk, so it can be anything from a bash script to Python to a C program.

Kdesk Screen Saver Hooks

In the same way kdesk provides for icon hooks, it also delivers hooks for the screen saver. There are 2 hooks in place: ScreenSaverStart and ScreenSaverStop.

The fist one is sent when the inactivity time exceeds the screen saver timeout so it’s time to start it. A return value of 0 means proceed with the screen saver, while any other value means cancel the screen saver. The end user will not notice and change in the UIX desktop, it will be silently cancelled.

The second hook is called when the screen saver is stopped as a result of the user moving the mouse or keyboard. No relevant return code is used in this case.

These 2 hooks are sent to the script specified under IconHook in .kdeskrc with the first parameter being "ScreenSaverStart" or "ScreenSaverStop".

System hourglass support

Kdesk includes a library with a very simple API to provide for a mouse visual feedback when applications are started in the form of a waiting hourglass image. libkdesk-hourglass contains 3 APIs: kdesk_hourglass_start, kdesk_hourglass_start_appcmd and kdesk_hourglass_end.

Clients can load and use the library dynamically, there are source samples in Python and C++ to help you on that. The implementation follows these simple 2 steps:

  • Before starting an application, clients call kdesk_hourglass_start or kdesk_hourglass_start_appcmd providing either the application name or the app's binary filename. The application name is the name as reported by X11 WC_NAME, normally it's the title. You can find it using the xwininfo -tree -root tool. The former API accepts the program name without parameters. It can include the pathname as well.

At this point the mouse pointer will change to an hourglass icon. When the application is responsive the system will automatically change the mouse pointer back to its original state.

  • If for some reason your app fails to start you should call kdesk_hourglass_end to remove the hourglass and restore the original pointer. If you can’t detect this situation and fail to do so the system will do it for you after a timeout of 20 seconds.

  • It is safe to call kdesk_hourglass_start / appcmd with an empty string and remove the hourglass ay any point afterwards before the 20 seconds timeout expires.

Keep in mind that all mouse events are discarded when the hourglass mode is on, this means that your apps will not receive any click or move events until the hourglass is turned off.