<chapter id="tinkering-under-the-hood"> <!-- Uncomment the <*info> below and add your name to be --> <!-- credited for writing this section. --> <!-- <chapterinfo> <authorgroup> <author> <firstname>Your First Name here</firstname> <surname>Your Surname here </surname> </author> </authorgroup> </chapterinfo> --> <title>Tinkering Under the Hood of &kde;</title> <sect1 id="hand-editing-config-files"> <sect1info> <author> <personname> <firstname>Nicolas</firstname> <surname>Goutte</surname> </personname> <email>goutte@kde.org</email> </author> </sect1info> <title>Hand-Editing Configuration Files</title> <sect2 id="hand-editing-intro"> <title>Introduction</title> <para>In &kde;, the configuration files are easy to edit with a simple editor like &kate; as the configuration files are text files.</para> <para>An example of a text file:</para> <programlisting>[General] AutoSave=1 LastFile=/var/tmp/test.txt</programlisting> <para>The user-specific configuration files are stored in <filename class="directory">.kde/share/config</filename> (replace <filename>.kde</filename> with your $<envar>TDEHOME</envar> setting) and the global ones are in the <filename class="directory">share/config</filename> sub-directory of &kde;'s installation path. (You can find this path by running the command <command>kde-config --prefix</command>.) Their filenames typically end in rc (without an initial period), for example <filename>kopeterc</filename>.</para> <warning><para> 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.</para></warning> </sect2> <sect2 id="hand-editing-backups"> <title>Backups</title> <para>So the first rule is to make a backup of your file before modifying it. The backup is better stored outside any <filename class="directory">.kde</filename> subdirectory (or the corresponding $<envar>TDEHOME</envar> 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 <filename>kmailrc</filename>). (Such a major failure should not happen but it still can happen.)</para> </sect2> <sect2 id="hand-editing"> <title>Editing</title> <para>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 <filename class="directory">.kde</filename> directory. Perhaps you want to learn more about the depths of &kde;.</para> <para>Anyway, whatever your reason, you want to modify by hand a configuration file.</para> <para>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.</para> <para>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 <quote>utf8</quote>).</para> <para>Now you have a file like:</para> <programlisting>[Group] Key1=Value1 Key2=Value2 Key3=Value3</programlisting> <para>You can now modify it (with care!) and then save it (Be sure that it is as <acronym>UTF-8</acronym> again).</para> <para>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.</para> <itemizedlist> <title>Related Information</title> <listitem><para><xref linkend="kde-for-administrators"/> has more information about &kde;'s directory structure, to help you find the file you need to edit.</para> </listitem> </itemizedlist> </sect2> </sect1> <sect1 id="scripting-the-desktop"> <title>Scripting the Desktop</title> <para>&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.</para> <para>Broadly speaking, each &kde; application provides one or more &DCOP; <firstterm>interfaces</firstterm>, 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 <application>kdcop</application> frontend to the available &DCOP; methods.</para> <para>Run <application>kdcop</application> from a &konsole; or the mini-<acronym>CLI</acronym> (the window which pops up on <keycombo action="simul">&Alt;<keycap>F2</keycap> </keycombo>). The <application>kdcop</application> window shows the applications currently running which provide &DCOP; interfaces, using a tree view. <!-- TODO: Describe the search lineedit thingy --> 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 <quote>(default)</quote> usually contains the most frequently-used functions.</para> <para>To test that the function does what we expect, double-click on the <guilabel>setColor</guilabel> entry. To set the color <varname>c</varname>, click on the color selector button, and choose a color. Set whether the color should be color A with the checkbox. Click <guilabel>OK</guilabel> and the background color is set.</para> <para>To access the &DCOP; method from your favorite scripting language, you can either use &DCOP; bindings, if available in the tdebindings module, or call the <command>dcop</command> command-line application. For simple usage, calling the <command>dcop</command> 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.</para> <para>We specify the application, interface and method in that order, followed by the arguments in the same order that they are shown in <application>kdcop</application>. <command>dcop</command> has plenty of other options: take a look at the output of <userinput><command>dcop</command> <option>--help</option></userinput>.</para> <para>That's enough theory: time for an example:</para> <example> <title>A Background Color Changing Script with &DCOP;</title> <para>With the <command>dcop</command> 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.</para> <para>Firstly, we look for the appropriate method with <application>kdcop</application>. For this example, we'll short circuit the searching, and go straight to it: the method we want is <menuchoice><guimenu>kdesktop</guimenu><guisubmenu>KBackgroundIface</guisubmenu><guimenuitem>setColor</guimenuitem> </menuchoice>. The arguments and return type of the function are shown in the style of the C++ language. For <methodname>setColor</methodname>, the arguments are a color, <varname>c</varname>, which specifies the new background color, and a boolean (true or false) value, <varname>isColorA</varname>, which specifies whether the color is the first or second (this is useful for setting gradients and so on).</para> <para>To use our <methodname>setColor</methodname> method on the command line, we use the following: <screen> <prompt>%</prompt> <userinput><command>dcop</command> kdesktop KBackgroundIface setColor '#ffffff' false</userinput> </screen> </para> <para>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 <token>#</token> from the shell.</para> <para>To find the hexadecimal RGB value of a color, open any color chooser dialog in a &kde; application (for example, in &kcontrolcenter;, <menuchoice><guimenu>Appearance & Themes</guimenu><guimenuitem>Colors</guimenuitem> </menuchoice>), select the color you want, and use the value given in the <guilabel>HTML</guilabel> text box.</para> <para>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: <programlisting> <![CDATA[ $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)); } } ]]> </programlisting> </para> <para>Just run the script with no arguments, and it will cycle the background colour through a slightly muted spectrum until it is killed. <foreignphrase>Voilà</foreignphrase>!</para> </example> <para>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:</para> <example> <title>Setting a background from the Internet</title> <para>The following script gets the main image from the <quote>User Friendly</quote> comic strip and sets it as the desktop wallpaper, using commonly available tools and a little bit of &DCOP;:</para> <programlisting> <![CDATA[ #!/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 ]]> </programlisting> <para>The first line after the #!/bin/sh uses <command>wget</command> 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, <command>dcop</command> sets the downloaded image as wallpaper.</para> </example> <!-- <itemizedlist> <title>Related Information</title> <listitem><para>to be written</para> </listitem> </itemizedlist> --> </sect1> <sect1 id="adding-extra-keys"> <title>Adding Extra Keybindings to &kde;</title> <para>Many modern keyboards contain extra keys that are not by default assigned to any action.</para> <para><quote>Multimedia</quote> 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 <guilabel>Configure Shortcuts</guilabel> has no effect.</para> <para>Some IBM laptops, for instance, have extra keys about the left and right arrows, which look like <guiicon>page left</guiicon> and <guiicon>page right</guiicon>.</para> <procedure> <step><para>Use <command>xev</command> to find the code of the keys. In this case, they are 233 and 234 <!-- TODO: Very briefly how to use xev here --> </para></step> <step><para>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 <filename>/usr/X11R6/include/X11/keysymdef.h</filename> (or its equivalent on your system).</para></step> <step><para>Create a file in your home directory called <filename>.Xmodmap</filename>, and add to it the following:</para> <screen>keycode 233 = Next_Virtual_Screen keycode 234 = Prev_Virtual_Screen</screen> </step> <step><para>Run the command <userinput><command>xmodmap</command> <filename>~/.Xmodmap</filename></userinput></para></step> </procedure> <para>At this point, you should be able to run <command>xev</command> again and see that the keys now generate the keysym that you assigned. You can now simply assign them to any action as normal.</para> <itemizedlist> <title>Related Information</title> <listitem><para>The <command>xev</command> manpage. You can see this by typing <userinput>man:/xev</userinput> into a &konqueror; window or by typing <userinput><command>man</command> xev</userinput> into a terminal.</para></listitem> </itemizedlist> </sect1> <sect1 id="keys-for-scripts"> <title>Adding Keybindings for New Actions</title> <para>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.</para> <para>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 <xref linkend="adding-extra-keys"/> to go to the previous or next virtual desktop, two functions for which you will need DCOP (as discussed in <xref linkend="scripting-the-desktop"/>).</para> <para>This can be achieved easily using the following method:</para> <procedure> <step> <para>Open &kcontrol;, and in the <guilabel>Regional & Accessibility</guilabel> section, select <guilabel>Input Action</guilabel></para> </step> <step> <para>Choose <guibutton>New Action</guibutton></para> </step> <step> <para>Name the new action, ⪚ <userinput>Next Virtual Screen</userinput></para> </step> <step> <para>Select <guilabel>Keyboard shortcut -> Command/URL (simple)</guilabel> for the <guilabel>Action type:</guilabel></para> </step> <step> <para>In the <guilabel>Keyboard Shortcut</guilabel> tab, click the button you wish to use to trigger the command. For this example, you would press the one with the <guiicon>Next Page</guiicon> picture on it. <keysym>Next_Virtual_Screen</keysym> will appear in the key image.</para> </step> <step> <para>In the <guilabel>Command/URL Settings</guilabel> tab, enter the command to run in the field: <userinput><command>dcop twin default nextDesktop</command></userinput></para> </step> </procedure> <para>Repeat the above with the <keysym>Prev_Virtual_Screen</keysym> key and <userinput><command>dcop twin default previousDesktop</command></userinput>.</para> <para>Now pressing the <keysym>Prev_Virtual_Screen</keysym> or <keysym>Next_Virtual_Screen</keysym> will switch you to the previous or next virtual desktop, respectively.</para> <para>Obviously you can assign any free key to any action.</para> <itemizedlist> <title>Related Information</title> <listitem><para>See the <application>KHotKeys</application> documentation by looking it up in &khelpcenter;, or typing <userinput>help:/khotkeys</userinput> in a &konqueror; window.</para></listitem> <listitem><para><xref linkend="adding-extra-keys"/></para></listitem> <listitem><para><xref linkend="scripting-the-desktop"/></para></listitem> </itemizedlist> </sect1> <sect1 id="kdebugdialog"> <sect1info> <authorgroup> <author> <personname> <firstname>Adriaan</firstname> <surname>de Groot</surname> </personname> <email>groot@kde.org</email> </author> </authorgroup> </sect1info> <title>&kdebugdialog; - Controlling &kde;'s Debugging Output</title> <sect2 id="kdebugdialog-basic-usage"> <title>Basic Usage</title> <para>&kdebugdialog; is not in the &kmenu; by default. You will need to run it from the shell or from the mini-CLI <!-- link to CLI, for sure --> with the command <userinput><command>kdebugdialog</command></userinput>. &kdebugdialog; pops up a window with a long list of debugging areas. Each area has a checkbox that you can check or uncheck <!-- perhaps select/deselect --> in order to enable or disable debugging output for that part of &kde;.</para> <para>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 <!-- text-entry ? --> 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 <userinput>k</userinput> does not filter very much at all, but entering <userinput>kont</userinput> <!-- that's "butt" in dutch, haha --> will show you just the &kontact; debugging areas. As an even quicker way of enabling or disabling debugging output, there are also <guibutton>select all</guibutton> and <guibutton>deselect all</guibutton> buttons which will cause &kde; to produce a mountain of debugging output, or very little.</para> </sect2> <sect2 id="kdebugdialog-fullmode"> <title>KDebugDialog in full mode</title> <!-- this text partly taken from the kdebugdialog handbook --> <para>In full mode, which is what you get when you start kdebugdialog as <userinput><command>kdebugdialog</command> <option>--fullmode</option></userinput>, 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 <!-- combo? --> 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:</para> <para>File, in which case you can enter a filename. This file is written into your $<envar>HOME</envar> directory.</para> <para>Message Box. Each debugging message is displayed in an information dialog, which you must <guibutton>OK</guibutton> to continue with the application.</para> <para>Shell, the default entry. Messages are printed to stderr, and will appear either in the shell window where the application was started, or in <filename>.xsession-errors</filename>.</para> <para>Syslog. This sends each debugging message to the system's syslog facility, which can perform its own processing of the message.</para> <para>None. This suppresses the output of this type of message.</para> <para>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 <guilabel>abort on fatal errors</guilabel>, which is checked by default — but you might expect an application to crash (in a messy fashion) if a fatal error is encountered anyway.</para> <!-- Add links to "further reading" here --> <!-- <itemizedlist> <title>Related Information</title> <listitem><para>to be written</para> </listitem> </itemizedlist>--> </sect2> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: xml sgml-omittag:nil sgml-shorttag:nil sgml-namecase-general:nil sgml-general-insert-case:lower sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:0 sgml-indent-data:true sgml-parent-document:("index.docbook" "book" "chapter") sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: -->