From 1b6c123de102f0152d296fba8771d348329ba95c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sl=C3=A1vek=20Banko?= Date: Tue, 17 Nov 2020 19:52:37 +0100 Subject: Move the khelpcenter guides to the directory level in which they are installed. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Slávek Banko --- doc/userguide/under-the-hood.docbook | 470 ----------------------------------- 1 file changed, 470 deletions(-) delete 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 deleted file mode 100644 index 0f7dbe111..000000000 --- a/doc/userguide/under-the-hood.docbook +++ /dev/null @@ -1,470 +0,0 @@ - - -Tinkering Under the Hood of &tde; - - - -Hand-Editing Configuration Files - - -Introduction -In &tde;, 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 $TDEHOME setting) and -the global ones are in the share/config sub-directory of &tde;'s -installation path. (You can find this path by running the command -tde-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 -&tde; 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 $TDEHOME directory). Backups are anyway -a good idea in case of a major failure of &tde; 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 &tde;. - -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 &tde; 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. - - - - - - - - -Scripting the Desktop - -&tde; provides a powerful interprocess communication system in -&DCOP;, the Desktop COmmunication Protocol. Using &DCOP;, you can -control a wide range of functions in &tde; from the command line or -from a script written in your favorite scripting language. You can -also get information out of &tde; applications: for example, several -&tde; media players provide methods to query the player for -information about the currently-playing track. - -Broadly speaking, each &tde; 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 -tdebindings 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 &tde; 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 &tde; - -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 twin default -nextDesktop - - - -Repeat the above with the Prev_Virtual_Screen key and -dcop twin 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. - - - - - - - - -&tdedebugdialog; - Controlling &tde;'s Debugging Output - - -Basic Usage - -&tdedebugdialog; is not in the &kmenu; by default. You will need to run -it from the shell or from the mini-CLI with -the command tdedebugdialog. -&tdedebugdialog; 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 &tde;. - -The list of debugging areas is sorted numerically, not alphabetically, -so tdeio (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 &tde; to produce a mountain of debugging output, or -very little. - - - -TDEDebugDialog in full mode - - - -In full mode, which is what you get when you start tdedebugdialog as -tdedebugdialog -, 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.1