# Tinkering Under the Hood of &kde;

Nicolas Goutte goutte@kde.org

## Hand-Editing Configuration Files

### Introduction

In &kde;, the configuration files are easy to edit with a simple editor like &kate; as the configuration files are text files.

An example of a text file:

    [General]
    AutoSave=1
    LastFile=/var/tmp/test.txt

The user-specific configuration files are stored in `.kde/share/config` (replace `.kde` with your $`KDEHOME` setting) and the global ones are in the `share/config` sub-directory of &kde;'s installation path. (You can find this path by running the command `kde4-config --prefix`.) Their filenames typically end in rc (without an initial period), for example `kopeterc`.

Editing configuration files by hand can risk the stability of your &kde; installation. Applications usually do not check what they read from the configuration files. This means that they can be disturbed by what they get as configuration and might even crash.

### Backups

So the first rule is to make a backup of your file before modifying it. The backup is better stored outside any `.kde` subdirectory (or the corresponding $`KDEHOME` directory). Backups are anyway a good idea in case of a major failure of &kde; that would destroy important configuration files (for example your &kmail; settings, which are in the file `kmailrc`). (Such a major failure should not happen but it still can happen.)

### Editing

So why would you want to touch the configuration files at all? Well, first you need it when you want to enforce the KIOSK mode. Perhaps a developer has asked you to add an entry to help him to solve a problem with the application. Perhaps you want to recover from a problem without having to remove all the `.kde` directory. Perhaps you want to learn more about the depths of &kde;.

Anyway, whatever your reason, you want to modify by hand a configuration file.

When planning to edit such a file, make sure that the application using it is not running. If it is one of the basic configuration files, consider editing the file while &kde; is not running at all.

Ready? So make a backup of the file (Did I tell you this already?), start you favorite editor (let us assume it is &kate;), load the file (Be careful to load as UTF-8, &kate; displays it as utf8).

Now you have a file like:

    [Group]
    Key1=Value1
    Key2=Value2
    Key3=Value3

You can now modify it (with care!) and then save it (Be sure that it is as UTF-8 again).

Now you can test the application and if the application does not run correctly anymore, close the application and restore the backup of the configuration file.

### Related Information

- kde-for-administrators has more information about &kde;'s directory structure, to help you find the file you need to edit.

## Scripting the Desktop

&kde; provides a powerful interprocess communication system in &DCOP;, the Desktop COmmunication Protocol. Using &DCOP;, you can control a wide range of functions in &kde; from the command line or from a script written in your favorite scripting language. You can also get information out of &kde; applications: for example, several &kde; media players provide methods to query the player for information about the currently-playing track.

Broadly speaking, each &kde; application provides one or more &DCOP; interfaces, which in turn provide methods (or, if you prefer, functions) that another application can call. So, the first step in using &DCOP; is to find the appropriate method for the task. The easiest way to do this is using the kdcop frontend to the available &DCOP; methods.

Run kdcop from a &konsole; or the mini-CLI (the window which pops up on &Alt;F2 ). The kdcop window shows the applications currently running which provide &DCOP; interfaces, using a tree view. In general, finding the correct method requires a little bit of searching through the tree view, but a useful hint is that the interface marked (default) usually contains the most frequently-used functions.

To test that the function does what we expect, double-click on the setColor entry. To set the color `c`, click on the color selector button, and choose a color. Set whether the color should be color A with the checkbox. Click OK and the background color is set.

To access the &DCOP; method from your favorite scripting language, you can either use &DCOP; bindings, if available in the kdebindings module, or call the `dcop` command-line application. For simple usage, calling the `dcop` command-line application is sufficient. To call a &DCOP; method on the command line, we need to specify the application and interface owning the method, the method itself, and the arguments, in a form suitable for the shell.

We specify the application, interface and method in that order, followed by the arguments in the same order that they are shown in kdcop. `dcop` has plenty of other options: take a look at the output of ``dcop` `--help``.

That's enough theory: time for an example:

### A Background Color Changing Script with &DCOP;

With the `dcop` command-line application and a little bit of Perl, we're going to make a simple script which slowly cycles the desktop background through the spectrum.

Firstly, we look for the appropriate method with kdcop. For this example, we'll short circuit the searching, and go straight to it: the method we want is kdesktop KBackgroundIface setColor . The arguments and return type of the function are shown in the style of the C++ language. For `setColor`, the arguments are a color, `c`, which specifies the new background color, and a boolean (true or false) value, `isColorA`, which specifies whether the color is the first or second (this is useful for setting gradients and so on).

To use our `setColor` method on the command line, we use the following:

    % dcop kdesktop KBackgroundIface setColor '#ffffff' false

To specify the color, we used the hexadecimal RGB value, as used in &HTML;. Note that it is enclosed in single quotes to protect the # from the shell.

To find the hexadecimal RGB value of a color, open any color chooser dialog in a &kde; application (for example, in &kcontrolcenter;, Appearance & Themes Colors ), select the color you want, and use the value given in the HTML text box.

So, that's all we need from &DCOP;; now it's just a case of writing a script around it. Here's a (very!) rough implementation:

    $min=49;  # Minimum value of R, G, or B colour
    $max=174; # Maximum value of R, G, or B colour
    $step=5;  # Amount to step colour by on each step
    $sleeptime=15; # Interval in seconds between each step

    @start = ($max, $min, $min);
    @colour = @start;

    while (1) {
    	foreach (0..5) {
    		my $which = $_ % 3; # Which colour (R, G or B) to change
    		my $updown = $_ % 2; # Whether to increase or decrease the colour value
    		do {
    			if ($updown == 0) { $colour[$which]+=$step; }
    			if ($updown == 1) { $colour[$which]-=$step; }
    			my $dcopcall=sprintf "dcop kdesktop KBackgroundIface setColor '#%x%x%x' true\n", @colour;
    			system($dcopcall);
    			sleep $sleeptime;
    			} while (($colour[$which] >= $min) and ($colour[$which] <= $max));
    		}
    }

Just run the script with no arguments, and it will cycle the background colour through a slightly muted spectrum until it is killed. Voilà!

Of course, Perl isn't the only language you can use to write scripts with &DCOP;—if you prefer shell scripting, that's available too:

### Setting a background from the Internet

The following script gets the main image from the User Friendly comic strip and sets it as the desktop wallpaper, using commonly available tools and a little bit of &DCOP;:

    #!/bin/sh
    COMICURL=`wget -qO - http://www.userfriendly.org/static/index.html | \
              grep Latest | sed -e "s,.*SRC=\",," -e "s,\">.*,,"`
    TMPFILE=`mktemp /tmp/$0.XXXXXX` || exit 1
    wget -q -O $TMPFILE $COMICURL
    dcop kdesktop KBackgroundIface setWallpaper $TMPFILE 1

The first line after the #!/bin/sh uses `wget` and some regular expression magic to extract the image location from the main page's &HTML; source. The second and third lines download the image, and finally, `dcop` sets the downloaded image as wallpaper.

## Adding Extra Keybindings to &kde;

Many modern keyboards contain extra keys that are not by default assigned to any action.

Multimedia keys often generate a signal, and can simply be chosen as a keybinding within an application just like choosing any other key. Some keys however, are not detected and pressing them in a Configure Shortcuts has no effect.

Some IBM laptops, for instance, have extra keys about the left and right arrows, which look like page left and page right.

1. Use `xev` to find the code of the keys. In this case, they are 233 and 234

2. Choose key symbols. There are quite a range of these that are not used by default, so many are free. You can find the list in `/usr/X11R6/include/X11/keysymdef.h` (or its equivalent on your system).

3. Create a file in your home directory called `.Xmodmap`, and add to it the following:

       keycode 233 = Next_Virtual_Screen
       keycode 234 = Prev_Virtual_Screen

4. Run the command ``xmodmap` `~/.Xmodmap``

At this point, you should be able to run `xev` again and see that the keys now generate the keysym that you assigned. You can now simply assign them to any action as normal.

## Related Information

- The `xev` manpage. You can see this by typing `man:/xev` into a &konqueror; window or by typing ``man` xev` into a terminal.

## Adding Keybindings for New Actions

Most actions in either the desktop or in applications are readily available to assign a keybinding to. If the action you want a shortcut for is something you wrote yourself, or is otherwise not available, you can still assign a shortcut.

To bring together the two previous sections, perhaps you want to assign an otherwise unused key on your keyboard to a script or dcop command. Our example here will be to assign the two keys we added in adding-extra-keys to go to the previous or next virtual desktop, two functions for which you will need DCOP (as discussed in scripting-the-desktop).

This can be achieved easily using the following method:

1. Open &kcontrol;, and in the Regional & Accessibility section, select Input Action

2. Choose New Action

3. Name the new action, ⪚ `Next Virtual Screen`

4. Select Keyboard shortcut -> Command/URL (simple) for the Action type:

5. In the Keyboard Shortcut tab, click the button you wish to use to trigger the command. For this example, you would press the one with the Next Page picture on it. Next_Virtual_Screen will appear in the key image.

6. In the Command/URL Settings tab, enter the command to run in the field: ``dcop kwin default nextDesktop``

Repeat the above with the Prev_Virtual_Screen key and ``dcop kwin default previousDesktop``.

Now pressing the Prev_Virtual_Screen or Next_Virtual_Screen will switch you to the previous or next virtual desktop, respectively.

Obviously you can assign any free key to any action.

## Related Information

- See the KHotKeys documentation by looking it up in &khelpcenter;, or typing `help:/khotkeys` in a &konqueror; window.

- adding-extra-keys

- scripting-the-desktop

## &kdebugdialog; - Controlling &kde;'s Debugging Output

### Basic Usage

&kdebugdialog; is not in the &kmenu; by default. You will need to run it from the shell or from the mini-CLI with the command ``kdebugdialog``. &kdebugdialog; pops up a window with a long list of debugging areas. Each area has a checkbox that you can check or uncheck in order to enable or disable debugging output for that part of &kde;.

The list of debugging areas is sorted numerically, not alphabetically, so kio (127) comes before artskde (400). The numbers go up to 200000 or so, but there are really only 400 areas. You don't have to scroll through the entire list to find the area you need, though. There is a line edit box at the top of the dialog where you can enter a part of the name of the area you want. The list of entries that is displayed is filtered to include only those debug areas that contain the text you have entered. ⪚ entering `k` does not filter very much at all, but entering `kont` will show you just the &kontact; debugging areas. As an even quicker way of enabling or disabling debugging output, there are also select all and deselect all buttons which will cause &kde; to produce a mountain of debugging output, or very little.

### KDebugDialog in full mode

In full mode, which is what you get when you start kdebugdialog as ``kdebugdialog` `--fullmode``, the same list of debugging areas as in plain mode is available, but you can select only one at a time from a drop-down box. You may then independently set the output for various types of messages: Information, Warning, Error and Fatal Error. For each of these types, you can choose where the messages are sent. The choices are:

File, in which case you can enter a filename. This file is written into your $`HOME` directory.

Message Box. Each debugging message is displayed in an information dialog, which you must OK to continue with the application.

Shell, the default entry. Messages are printed to stderr, and will appear either in the shell window where the application was started, or in `.xsession-errors`.

Syslog. This sends each debugging message to the system's syslog facility, which can perform its own processing of the message.

None. This suppresses the output of this type of message.

For messages generated by fatal errors, it is generally a bad idea to choose None or Syslog, since in both cases you most likely will not see the message and the application that encounters the fatal error will vanish without leaving a clue as to why it vanishes. Whether or not the application will vanish on fatal errors can be controlled by the checkbox abort on fatal errors, which is checked by default — but you might expect an application to crash (in a messy fashion) if a fatal error is encountered anyway.