From 4aed2c8219774f5d797760606b8489a92ddc5163 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/userguide/under-the-hood.docbook | 521 +++++++++++++++++++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 doc/userguide/under-the-hood.docbook (limited to 'doc/userguide/under-the-hood.docbook') diff --git a/doc/userguide/under-the-hood.docbook b/doc/userguide/under-the-hood.docbook new file mode 100644 index 000000000..094a01d63 --- /dev/null +++ b/doc/userguide/under-the-hood.docbook @@ -0,0 +1,521 @@ + + + + + + +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 +kde-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 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 + + + 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 +. + +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 +kdesktopKBackgroundIfacesetColor +. 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 & ThemesColors +), 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) 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;: + + +.*,,"` +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. + + +Use xev to find the code of the keys. In +this case, they are 233 and 234 + +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). +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 + +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 to go to the previous or +next virtual desktop, two functions for which you will need DCOP (as discussed in +). + +This can be achieved easily using the following method: + + + +Open &kcontrol;, and in the Regional & Accessibility +section, select Input Action + + +Choose New Action + + +Name the new action, ⪚ Next Virtual +Screen + + +Select Keyboard shortcut -> Command/URL (simple) +for the Action type: + + +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. + + +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. + + + + + + + + + + + +Adriaan +de Groot + +groot@kde.org + + + + +&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 +, 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. + + + + + + + + + + + -- cgit v1.2.3