diff options
Diffstat (limited to 'doc/userguide/under-the-hood.docbook')
| -rw-r--r-- | doc/userguide/under-the-hood.docbook | 521 |
1 files changed, 521 insertions, 0 deletions
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 @@ +<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>KDEHOME</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>KDEHOME</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 +kdebindings 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 kwin default +nextDesktop</command></userinput></para> +</step> +</procedure> + +<para>Repeat the above with the <keysym>Prev_Virtual_Screen</keysym> key and +<userinput><command>dcop kwin 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: +--> |