From 84da08d7b7fcda12c85caeb5a10b4903770a6f69 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/kdeaddons@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/kicker-applets/Makefile.am | 4 + doc/kicker-applets/index.docbook | 113 +++++++++ doc/kicker-applets/kolourpicker.docbook | 56 +++++ doc/kicker-applets/ktimemon.docbook | 429 ++++++++++++++++++++++++++++++++ 4 files changed, 602 insertions(+) create mode 100644 doc/kicker-applets/Makefile.am create mode 100644 doc/kicker-applets/index.docbook create mode 100644 doc/kicker-applets/kolourpicker.docbook create mode 100644 doc/kicker-applets/ktimemon.docbook (limited to 'doc/kicker-applets') diff --git a/doc/kicker-applets/Makefile.am b/doc/kicker-applets/Makefile.am new file mode 100644 index 0000000..085981d --- /dev/null +++ b/doc/kicker-applets/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kicker-applets/index.docbook b/doc/kicker-applets/index.docbook new file mode 100644 index 0000000..82a61a8 --- /dev/null +++ b/doc/kicker-applets/index.docbook @@ -0,0 +1,113 @@ + + + + KTimemon"> + KolourPicker"> + +]> + + + +The &kicker; Applets Handbook + + + + + +
+
 + + + + + +2001-05-12 +2.20.00 + + +2001 + + + +&FDLNotice; + + + +This is the handbook for the addon applets for &kicker;, &kde;'s panel. + + + + +KDE +kdeaddons +Kicker +Applets + + + + + +&kicker; applets + + +Applets are small applications running inside of &kicker;. Almost +everything besides the application starter buttons are applets. They can +be added from the context menu or from the submenu +Configure Panel by choosing +Add and the Applet. + + + +More information on the use of &kicker; and on the base set of applets +that come with &kicker;, can be found in the &kicker; handbook. + + + +The Applets described in this handbook are: + + + + +&kolourpicker; + + +&ktimemon; + + + + + +&doc-kolourpicker; +&doc-ktimemon; + + +Credits and License + + +Copyrights for each applet is listed in the applicable chapter. + + +&underFDL; +&underGPL; + + + + +Installation + + +To be written + + + + + + + + diff --git a/doc/kicker-applets/kolourpicker.docbook b/doc/kicker-applets/kolourpicker.docbook new file mode 100644 index 0000000..fcbd730 --- /dev/null +++ b/doc/kicker-applets/kolourpicker.docbook @@ -0,0 +1,56 @@ + + + +&kolourpicker; + + + + + + +
+ + + + + + +To be written + + + +KDE +color +selector + + + +Introduction + + +The &kicker; plugin Kolourpicker currently has no +documentation. If you are interested in rectifying that situation, +please contact the kde-doc-english mailing list, which you can reach at + +http://master.kde.org/mailman/listinfo/kde-doc-english +. + + + +Thanks and Acknowledgments + + + +&underGPL; + + + + + + diff --git a/doc/kicker-applets/ktimemon.docbook b/doc/kicker-applets/ktimemon.docbook new file mode 100644 index 0000000..b7ce2d5 --- /dev/null +++ b/doc/kicker-applets/ktimemon.docbook @@ -0,0 +1,429 @@ + + + +&ktimemon; + + + +Martin +Maierhofer + +
m.maierhofer@tees.ac.uk
+ + + + +2001-11-29 +0.03.01 + +&ktimemon; is a system monitor for the K Desktop Environment + + +KDE +ktimemon +system monitor +timemon + + + +Introduction + +&ktimemon; is a small program to keep track of your computer's system +usage. It can display bar graphs containing information about +CPU, memory, and swap usage as well as disk usage and +context switch activity. In keeping with the spirit of KDE, it supports configuration via a +graphical user interface. It also supports docking, +&ie; it can display information in the system panel tray. + + +Currently, &ktimemon; only supports a limited number of systems: +&Linux; based installations with the /proc file +system, &Solaris; based installations with the +kstat library, and Digital &UNIX; (formerly +DEC/OSF1) based installations with the +table(2) system call. Help with +porting it to other platforms is most welcome. + + + + +&ktimemon; can be started from the command line or from the &kde; +start menu (in the Utilities +submenu). If you choose to start from the command line, &ktimemon; +honors the usual &X-Window; program flags such as +. &ktimemon; is +session-aware, &ie; it keeps track of the current +state (colors, &etc;) and restores it in the user's next session. + + + +Onscreen Fundamentals + + +After starting &ktimemon; a small window will appear displaying +information gathered from the operating system. If you move the mouse +pointer over the &ktimemon; window and let it rest for a small amount of +time, a tool-tip (&ie; a small transient window) +will appear. The tool-tip contains numeric information about the system +parameters displayed by the bar graphs. Tool-tips can be disabled (refer +to Configuration). + + + +Display Modes + + +&ktimemon; can display two different sets of system information. As +explained in the Configuration chapter, +mouse buttons can be bound to various actions. Per default, the left +mouse button is bound to the mode switch action, &ie; by clicking the +&LMB; mouse button anywhere in the &ktimemon; window, the displayed +information switches from Normal Mode (the default) +to Extended Mode, and vice versa. + + + +Normal Mode + +After starting &ktimemon; for the first time, it will show +information about the current CPU activity, as well as memory and swap +usage. Three bar graphs are used to show this information; they are +updated regularly (the default sample interval is 0.5s, but it can be +changed, see Configuration). The three bar +graphs represent (from left to right): + + +CPU usage. + +&ktimemon; shows the bar in three different colors, representing +CPU time spent in various modes. From bottom to top +they are: kernel mode, user mode, and user mode with lowered priority +(nice) - since &Solaris; does not seem to support +statistics for nice mode, the topmost part of the bar represents time +spent in the wait state on such systems. The gap +from the top of the bar to the top of the window represents the +percentage the CPU idle time. + + + +Memory usage. + +Similar to the CPU usage bar, this bar is +composed of three sub fields, representing (from bottom to top): +memory allocated by processes, memory used for I/O buffering, and +memory used for file caching. For Digital &UNIX; based systems, the +middle section represents inactive memory (&ie; memory +allocated and not used for a certain amount of time), and for +&Solaris; based systems, the middle section of the bar is not used, +and the topmost section represents the amount of memory used by the +kernel. Again, the gap from the top of the bar to the top of the +window represents free memory. + + + +Swap usage. + +This bar consists of a single field representing +the current swap usage relative to the system's total amount of swap +space. + + + + + +Clicking the mouse button bound to mode switch in +the &ktimemon; window switches to Extended Mode. + + + + +Extended Mode + +In this mode, the three bar graphs are used to display a different +set of system information. Again from left to right, they show: + + + +Paging activity. + +This bar consists of two parts, the lower half +of which shows the number of memory pages written to secondary +storage in the last sample interval. Similarly, the upper half +indicates the number of pages read from secondary storage. + + + +Swapping activity. + +The second bar displays the analog +information for swap activity. + + + +Context switches. + +Again, this bar graph consists of a single +field which indicates the number of context switches in the last +sample interval. + + + + +Since there is no natural way of scaling the +information shown in Extended Mode, by default +&ktimemon; uses autoscaling (explained in the +Common Questions Section). There +is, however, the possibility of specifying the scaling information, +see the Configuration section. + +Note that the two sets of bar graphs share the same colors, &ie; +the colors setup for Normal Mode is also used for +displaying information in Extended Mode (see also Configuration on how to change the color +scheme). + + + + + +Menu Structure + + +By default, the &RMB; mouse button is bound to the menu +pop-up action, &ie; clicking the right mouse button anywhere in +the &ktimemon; window brings up a menu, which is discussed in the +following sections. + + + +<guimenuitem>Settings...</guimenuitem> + +The Settings... menu item is used to +pop up the configuration dialog. Configuration options are discussed in +section Configuration. + + + + +<guimenuitem>Docked In Panel</guimenuitem> + + +By selecting the Docked In Panel menu item, +&ktimemon; switches between its standard display (&ie; a normal window) +and the panelized state, where the &ktimemon; window disappears and a +smaller version is displayed in the system panel. Apart from the +reduction in size, the panelized &ktimemon; behaves +exactly like its big brother. + + + + +<guimenu>Help</guimenu> + +&help.menu.documentation; + + + + +<guimenuitem>Horizontal Bars</guimenuitem> + +By selecting the Horizontal Bars menu +entry, &ktimemon; switches from vertical bars to horizontal bars and +vice versa. Not very useful, but it was easy to implement ;-) + + + + +<guimenuitem>Quit</guimenuitem> + + +The Quit menu item - surprise, surprise +-- is used to terminate &ktimemon;. It will save the current state +(⪚ the color scheme, window size, whether it is displayed in the +panel) and restore the state in the next invocation. + + + +The configuration information is saved in the file +$HOME/.kde/share/config/ktimemonrc, +where $HOME refers +to the user's home folder. If this file is deleted, &ktimemon; will +start in its default state in the next invocation. + + + + + +Configuration + + +&ktimemon; can be configured via a straight-forward dialog (see also the +discussion of the Configuration +Menu). On the General page, the sample +interval can be specified as well as scaling information (see also the +discussion of the extended mode). If the +Autoscaling check box is ticked (autoscaling is +explained in the FAQ section), the +scaling factors cannot be edited, since &ktimemon; determines them +automatically. + + + +The Colors page can be used to tailor the colors of +the bar graph to individual preferences. A small sample bar graph gives +immediate feedback. + + + +In the Interaction page, mouse bindings can be +adapted. Clicking a mouse button on the &ktimemon; window can be +ignored, trigger a mode switch (see also Modes), invoke the context menu (see also Menu), or invoke an external process. The command +line specified for external processes is interpreted by the standard +shell, &ie; shell commands, environment variables, redirection &etc; can +be used. + +The Interaction page also contains a check +box which can be used to disable to automatic appearance of tool-tips +with numeric information about the bar graphs (compare Onscreen Fundamentals). + + + +Common Questions and Answers + + + + +Which operating systems does &ktimemon; support? + + + +&ktimemon; supports &Linux; based systems with the /proc file system, &Solaris; based +systems with the kstat library, and Digital +&UNIX; (formerly DEC/OSF1) systems with the +table(2) system call interface. Only the &Linux; +version has been thoroughly tested, if you experience any problems +with the &Solaris;/Digital &UNIX; port, please do not hesitate to +contact me. + + + +Also, contributions to &ktimemon; to adapt it to other platforms are +most welcome. Please contact me at +m.maierhofer@tees.ac.uk if you intend to port &ktimemon; +to other flavors of &UNIX;. + + + + + + + + +How does autoscaling work? + + + + +Glad you asked. Since there is no sensible predetermined scaling factor +for paging/swapping operations and context switches (unlike ⪚ memory +utilization, where you can take the total memory size as baseline), +&ktimemon; uses a semi-intelligent (well, ...) autoscaling +mechanism. Autoscaling works as follows: + + + + + +Each of the three bar graphs as described in the extended mode section has an associated +scaling factor. The initial values of these factors are set to some +predetermined value. + + + + +Each time a new sample is displayed, the respective value is tentatively +scaled with the corresponding factor. If the value can be displayed in +the scale chosen by the factor, no change occurs (&ie; small changes in +the activity are reflected by a changing height of the bar). + + + + +If the scaled value would be either too large or too small to be +displayed with the current scaling factor, the scaling is adjusted so +that the new value displayed is roughly halfway up the bar graph. Thus, +subsequent changes should have a good chance of getting displayed +relative to the current value, without having to change the scale again. + + + + + + + + + +Why does a message box with diagnostic output from child +command pop up? + + + + +If you bind a mouse button to an external command as described in the +Configuration chapter, &ktimemon; does +not check for a valid command name. Instead a command shell is invoked +to execute the statement, so shell commands, environment variables and +more can be used. To allow some feedback to the user, &ktimemon; +monitors the stderr output of the command +shell, and reports it in this message box. + + + +While this scheme can be helpful in case a command is not found, it can +be quite annoying if the invoked command prints harmless diagnostic +information on stderr. A simple and elegant +solution to this problem is to add 2>/dev/null +at the end of the command specification. This redirects diagnostic +messages to message nirvana, and stops the message box popping up. + + + + + + + + +Thanks and Acknowledgments + +&ktimemon; is based on an Xt version by my brother. + +Thanks to Tobe Toben, +ttoben@artis.uni-oldenburg.de, Cristian Tibirna +ctibirna@gch.ulaval.ca, Dirk A. Mueller +dmuell@rhrk.uni-kl.de, Mark Krischer +krischem@amp.com, and Lubos Lunak +l.lunak@sh.cvut.cz for bug reports, patches, comments, +suggestions. + + + + +&underGPL; + + + + + + -- cgit v1.2.1