runtime/doc/kcontrol/kcmnotify/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
   3 "dtd/kdex.dtd" [
   4 <!ENTITY % addindex "IGNORE">
   5 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
   6 ]>
   7
   8 <article lang="&language;">
   9 <articleinfo>
  10
  11 <authorgroup>
  12 <author>&Mike.McBride; &Mike.McBride.mail;</author>
  13 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  14 </authorgroup>
  15
  16 <date>2005-03-04</date>
  17 <releaseinfo>3.4.0</releaseinfo>
  18
  19 <keywordset>
  20 <keyword>KDE</keyword>
  21 <keyword>KControl</keyword>
  22 <keyword>system notification</keyword>
  23 <keyword>notification</keyword>
  24 </keywordset>
  25 </articleinfo>
  26
  27 <sect1 id="sys-notify">
  28 <title>System Notification Settings</title>
  29
  30 <para>&kde;, like all applications, needs to inform the user when a
  31 problem occurs, a task is completed, or something has happened.  &kde;
  32 uses a set of <quote>System Notifications</quote> to keep the user
  33 informed on what is happening.</para>
  34
  35 <para>Using this module, you can determine what &kde; does to communicate
  36 each event.</para>
  37
  38 <para>The panel consists of a large list of specific events which need
  39 to be communicated to the user.  This list is organized into groups by applications.</para>
  40
  41 <para>To configure a notification, simply select the application from the drop down box at the top
  42 of the dialog labeled <guilabel>Event source:</guilabel>.  This will lead to a list of
  43 all configurable notifications for the application. The list of notifications includes 6 columns to
  44 the left of the notification name.  These columns (from left to right) are:</para>
  45
  46 <variablelist>
  47 <varlistentry>
  48 <term><guiicon>Execute a program</guiicon></term>
  49 <listitem><para>If an icon is present in this column, a separate program will be executed when this notification is performed.  This can be used to execute a program to help restore data, shutdown a potentially compromised system or email another user to alert them to a problem.</para></listitem>
  50 </varlistentry>
  51
  52 <varlistentry>
  53 <term><guiicon>Print to standard error output</guiicon></term>
  54 <listitem><para>If an icon is present in this column, &kde; will send a message to the computers standard output.</para></listitem>
  55 </varlistentry>
  56
  57 <varlistentry>
  58 <term><guiicon>Display a message box</guiicon></term>
  59 <listitem><para>If an icon is present in this column, &kde; will open a message box and inform the user of the notification.  This is probably the most commonly selected option for alerting users to an error.</para></listitem>
  60 </varlistentry>
  61
  62 <varlistentry>
  63 <term><guiicon>Log to a file</guiicon></term>
  64 <listitem><para>If an icon is present in this column, &kde; will write certain information to a file on disk for later retrieval.  This is useful for tracking problems or important system changes.</para></listitem>
  65 </varlistentry>
  66
  67 <varlistentry>
  68 <term><guiicon>Play a sound</guiicon></term>
  69 <listitem><para>This does exactly what you think it does.  If an icon is present in this column, &kde; will play a specific sound over the speakers.  This is commonly used by games in &kde; for starting a new game, or other action within the game.</para></listitem>
  70 </varlistentry>
  71
  72 <varlistentry>
  73 <term><guiicon>Flash the taskbar entry</guiicon></term>
  74 <listitem><para>If an icon is present in this column, &kde; will cause the taskbar to flash until the user has clicked the taskbar entry.  This is most useful when you want the user to look at the program (such as a new email message was received, or the users name was said on an IRC channel).</para></listitem>
  75 </varlistentry>
  76 </variablelist>
  77
  78 <sect2><title>Change a single notification</title>
  79 <para>To make a change to a notification, click on the name of the notification once with the &LMB;.  The notification will be highlighted.
  80 Now click on the button labeled
  81 <guibutton>More options</guibutton> so you can see all the checkboxes.  </para>
  82
  83 <tip><para>You can have more than one event triggered by a single notification. As an example, it is easy to have a sound played and
  84 a message box appear in response to a system notification.  One notification does not prevent other notifications from operating.</para></tip>
  85 <para>The following list details each of the notification types and how to use them. </para>
  86
  87 <variablelist>
  88 <varlistentry>
  89 <term><guilabel>Play a sound</guilabel></term>
  90 <listitem><para>If a mark is in this checkbox, &kde; will play a sound everytime this notification is initiated. To specify the sound, use the text box to the right of the checkbox to enter the folder location of the sound file you want &kde; to play.  You can use the folder button (located to the far right of the dialog box) to browse your directory tree.  To hear a test of your sound, simply click on the play button (small button directly to the right of <guilabel>Play a sound</guilabel>.)</para></listitem>
  91 </varlistentry>
  92
  93 <varlistentry>
  94 <term><guilabel>Log to a file</guilabel></term>
  95 <listitem><para>If a mark is in this checkbox, &kde; will write certain information to a file on disk for later retrieval.  To specify the log file to use, enter the pathname in the text box to the right of the checkbox.  You can use the folder button (located to the far right of the dialog box) to browse your directory tree.  </para></listitem>
  96 </varlistentry>
  97
  98 <varlistentry>
  99 <term><guilabel>Execute a program</guilabel></term>
 100 <listitem><para>If a mark is in this checkbox, a separate program will be executed when this notification is performed.  To specify the program to execute, enter the pathname in the text box to the right of the checkbox.  You can use the folder button (located to the far right of the dialog box) to browse your directory tree.  </para></listitem>
 101 </varlistentry>
 102
 103 <varlistentry>
 104 <term><guilabel>Show a message in a pop up window</guilabel></term>
 105 <listitem><para>If a mark is in this checkbox, &kde; will open a message box and inform the user of the notification.  The text of the box can not be changed from this dialog.  If you place a mark in the checkbox labeled <guilabel>Use a passive window that does not interrupt other work</guilabel>, &kde; will open the message box, but it will not change desktops and the message box will not appear until the user returns to the program sending the notification.  If that box is left empty, the user must respond to the message box even if it means they have to stop working on another program.</para></listitem>
 106 </varlistentry>
 107
 108 <varlistentry>
 109 <term><guilabel>Print a message to standard error output</guilabel></term>
 110 <listitem><para>If a mark is in this checkbox, &kde; will send a message to the computer's standard output.</para></listitem>
 111 </varlistentry>
 112
 113 <varlistentry>
 114 <term><guilabel>Mark taskbar entry</guilabel></term>
 115 <listitem><para>If a mark is in this checkbox, &kde; will cause the taskbar of the program sending the notification to flash until the user has clicked the taskbar entry.</para></listitem>
 116 </varlistentry>
 117 </variablelist>
 118
 119 <tip><para>You can use the icon columns (located to the left of the notifications) to quickly select or deselect the options. Clicking in the column with the &LMB; will toggle the notification on and off.</para></tip>
 120
 121 </sect2>
 122 <sect2><title>Change all notifications in all &kde; applications</title>
 123 <para>You can alter more than one notification at a time by using the section of the dialog labeled <guilabel>Quick Controls</guilabel>.</para>
 124 <para>The first item in this section is a checkbox labeled <guilabel>Apply to all applications</guilabel>.  If there is a mark in this checkbox, any changes made in the <guilabel>Quick Controls</guilabel> area are applied to all applications (not just the selected application).  If there is no mark in this checkbox, any changes are limited to the application selected at the top of the dialog.</para>
 125 <para>The next line consists of a button and a drop down box.  This is used to enable every notification of a single type. Simply select the notification type from the drop down box (on the right) and click the button labeled <guibutton>Turn On All</guibutton>.  This will enable all notifications of that type.</para>
 126 <para>The bottom line operates the same, but when you select the button labeled <guibutton>Turn Off All</guibutton>, all the notifications of the selected type will be disabled.</para>
 127 </sect2>
 128 <sect2><title>Change sound player options</title>
 129 <para>If you click the button labeled <guibutton>Player settings</guibutton>, a small dialog box will appear with three radio buttons:</para>
 130 <variablelist>
 131 <varlistentry>
 132 <term><guilabel>Use the &kde; sound system</guilabel></term>
 133 <listitem><para>If a mark is in this radio button, &kde; will play all sound notifications through the &kde; sound system (&arts;).  You can adjust the volume of system notifications using the slider.</para>
 134 <note><para>The slider only affects &kde; system notifications.  Changes to this slider will not affect other sounds on your computer.</para></note></listitem>
 135 </varlistentry>
 136 <varlistentry>
 137 <term><guilabel>Use external player</guilabel></term>
 138 <listitem><para>If a mark is in this radio button, &kde; will not use the &kde; sound system to play the sound.  This is a good choice if the sound format you want to use is not supported by the &kde; notification system or if you don't use the &arts; sound daemon. After checking the radio box, enter the full path and name of the program you want to use into the text field.  You can use the folder button (located along the right side) to browse the directory tree.</para></listitem>
 139 </varlistentry>
 140 <varlistentry>
 141 <term><guilabel>No audio output</guilabel></term>
 142 <listitem><para>Disables all sound notifications.</para></listitem>
 143 </varlistentry>
 144 </variablelist>
 145 <para>When you have made your selection, click <guibutton>Apply</guibutton> to save changes but keep the dialog box open.  Click
 146 <guibutton>OK</guibutton> to save changes and close dialog box.  Click <guibutton>Cancel</guibutton> to close the dialog box without
 147 making any changes.</para>
 148 </sect2>
 149 </sect1>
 150
 151 </article>