workspace/doc/klipper/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
   3 "dtd/kdex.dtd" [
   4   <!ENTITY kappname "&klipper;">
   5   <!ENTITY package "kdebase">
   6   <!ENTITY % addindex "IGNORE">
   7   <!ENTITY % English "INCLUDE" > <!-- change language only here -->
   8 ]>
   9
  10 <book lang="&language;">
  11 <bookinfo>
  12 <title>The &klipper; Handbook </title>
  13
  14 <authorgroup>
  15 <author>&Philip.Rodrigues; &Philip.Rodrigues.mail;</author>
  16
  17 <othercredit role="developer">
  18 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;
  19 <!-- <contrib>Developer</contrib> -->
  20 </othercredit>
  21
  22 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  23
  24 </authorgroup>
  25
  26 <copyright>
  27 <year>2000-2003</year>
  28 <holder>&Philip.Rodrigues;</holder>
  29 </copyright>
  30
  31 <legalnotice>&FDLNotice;</legalnotice>
  32
  33 <date>2005-01-31</date>
  34 <releaseinfo>2.92.00</releaseinfo>
  35
  36 <abstract>
  37 <para>&klipper; is the &kde; clipboard cut &amp; paste utility.</para>
  38 </abstract>
  39
  40 <keywordset>
  41 <keyword>KDE</keyword>
  42 <keyword>Klipper</keyword>
  43 <keyword>kdebase</keyword>
  44 <keyword>clipboard</keyword>
  45 </keywordset>
  46 </bookinfo>
  47
  48 <chapter id="introduction">
  49 <title>Introduction</title>
  50 <para>&klipper; is the &kde; clipboard utility. It stores clipboard
  51 history, and allows you to link clipboard contents to application
  52 actions. Please report any problems or feature requests to Esben Mose
  53 Hansen (see <ulink
  54 url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
  55 for contact details).</para>
  56
  57 </chapter>
  58
  59 <chapter id="using-klipper">
  60 <title>Using &klipper;</title>
  61
  62 <sect1 id="basic-usage">
  63 <title>Basic Usage</title>
  64 <screenshot>
  65 <screeninfo>The &klipper; icon.</screeninfo>
  66 <mediaobject>
  67 <imageobject>
  68 <imagedata fileref="screenshot.png" format="PNG" />
  69 </imageobject>
  70 <textobject>
  71 <phrase>The &klipper; icon</phrase>
  72 </textobject>
  73 </mediaobject>
  74 </screenshot>
  75
  76 <para>To display the clipboard history, click on the &klipper; icon in
  77  the &kde; panel, or press <keycombo
  78  action="simul">&Ctrl;&Alt;<keycap>V</keycap> </keycombo>. Previous
  79  clipboard entries are shown at the top of the popup menu which
  80  appears. Selecting one of these copies it to the clipboard, from
  81  where it can be pasted into any &kde; or X application as
  82  usual.</para>
  83
  84 <para>You can search through the clipboard history by opening it
  85 (click on &klipper;) and typing your query. The results are updated as
  86 you type. In case you're wondering how to use the accelerator keys in
  87 the &klipper; menu, just press &Alt; and the accelerator you want. For
  88 example, to clear the clipboard history when the &klipper; menu is
  89 open, press <keycombo action="simul">&Alt;<keycap>L</keycap>
  90 </keycombo>.</para>
  91
  92 <para>To remove &klipper;, click on the handle next to it (a small
  93 black triangle), and from the menu that appears, select
  94 <guimenuitem>Remove Klipper</guimenuitem>.</para>
  95
  96 </sect1>
  97
  98 <sect1 id="actions">
  99 <title>Actions</title>
 100
 101 <para>&klipper; can perform actions on the contents of the clipboard,
 102 based on whether they match a particular regular expression. For
 103 example, any clipboard contents starting with <quote>http://</quote> can
 104 be passed to &Netscape; or &konqueror; as &URL;s to open.</para>
 105
 106 <para>To use this feature, just copy a &URL; or filename to the
 107 clipboard. If there is a matching regular expression in &klipper;'s
 108 list, a menu will appear showing you the options you have (&eg; Open
 109 &URL; in &konqueror;, open &URL; in &Netscape;). Use the mouse or
 110 keyboard to select the option you want, and &klipper; will run the
 111 program you have selected, opening the address pointed to by the
 112 clipboard contents.</para>
 113
 114 <para>If you do not want to perform any actions on the clipboard
 115 contents, select <guimenuitem>Do Nothing</guimenuitem> on the pop-up menu
 116 to return to what you were doing before. If you leave the menu, it will
 117 disappear, leaving you to continue your work. You can change the time
 118 that the menu remains for in the <guilabel>Configure Klipper...</guilabel>
 119 dialog, with the option <guilabel>Timeout for action pop-ups</guilabel>
 120 under the <guilabel>General</guilabel> tab.</para>
 121
 122 <para>Actions can be disabled completely by clicking on &klipper; and
 123 selecting <guimenuitem>Actions Enabled</guimenuitem>, or by pressing
 124 <keycombo action="simul">&Ctrl;&Alt;<keycap>X</keycap></keycombo>.</para>
 125
 126 <para>Clipboard contents which match a regular expression can also be
 127 edited before performing an action on them. Select <guimenuitem>Edit contents...</guimenuitem> on the &klipper; pop-up menu, and you can
 128 change the clipboard contents in the dialog which appears, before
 129 clicking the <guibutton>OK</guibutton> button to run the appropriate
 130 action.</para>
 131
 132 <para>Pressing <keycombo
 133 action="simul">&Ctrl;&Alt;<keycap>R</keycap></keycombo> shows the pop-up
 134 menu to repeat the last action which &klipper; performed.</para>
 135
 136 </sect1>
 137
 138 <sect1 id="clipboard-modes">
 139 <title>Clipboard/Selection Behavior</title>
 140
 141 <sect2 id="clipboard-modes-general">
 142 <title>General</title>
 143 <para>
 144 &klipper; can be used to set the behavior of the clipboard and selection in
 145 &kde;.
 146 </para>
 147
 148 <note><para>The &X-Window; uses two separate clipboard buffers: the
 149 <quote>selection</quote> and the <quote>clipboard</quote>. Text is
 150 placed in the selection buffer by simply selecting it, and can be
 151 pasted with the middle mouse button. To place text in
 152 the clipboard buffer, select it and press
 153 <keycombo>&Ctrl;<keycap>X</keycap> </keycombo> or
 154 <keycombo>&Ctrl;<keycap>C</keycap> </keycombo>. Text from the
 155 clipboard buffer is pasted using <keycombo>&Ctrl;<keycap>V</keycap>
 156 </keycombo> or by selecting
 157 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem>
 158 </menuchoice>.</para>
 159 </note>
 160
 161 <!-- &klipper; can be used to set the clipboard mode for the whole of &kde;. The
 162 first mode will be familiar to &Microsoft; &Windows; and &Mac; users: Text is
 163 inserted into the clipboard using an application's cut/copy (or generally
 164 <keycombo>&Ctrl;<keycap>X</keycap></keycombo> and
 165 <keycombo>&Ctrl;<keycap>C</keycap></keycombo> respectively)
 166 function, and the application's paste (or generally
 167 <keycombo>&Ctrl;<keycap>V</keycap></keycombo>) function pastes the
 168 contents of this clipboard.
 169 </para>
 170 <para>
 171 The second mode will be more familiar to longtime &UNIX; users: Selected text
 172 is copied to this clipboard, and clicking the <mousebutton>middle</mousebutton>
 173 mouse button pastes the
 174 contents of this clipboard.
 175 -->
 176 </sect2>
 177
 178 <sect2 id="changing-clipboard-modes">
 179 <title>Changing Clipboard/Selection Behavior</title>
 180 <para>
 181 In order to change clipboard/selection behavior, select
 182 <guimenuitem>Configure Klipper...</guimenuitem> from the &klipper; pop-up menu,
 183 and in the dialog box that appears, select the
 184 <guilabel>General</guilabel> tab. Selecting <guilabel>Separate clipboard and
 185 selection</guilabel> makes the clipboard and selection function as completely
 186 separate buffers as described above. With this option set, the option
 187 <guilabel>Ignore selection</guilabel> will prevent &klipper; from
 188 including the contents of the selection in its clipboard history and from
 189 performing actions on the contents of the selection. Selecting
 190 <guilabel>Synchronize contents of the clipboard and the selection</guilabel>
 191 causes the clipboard and selection buffers to always be the same, meaning that
 192 text in the selection can be pasted with either the
 193 <mousebutton>middle</mousebutton> mouse button or the key combination <keycombo>&Ctrl;<keycap>V</keycap>
 194 </keycombo>, and similarly for text in the clipboard buffer.
 195 </para>
 196
 197  <!-- The
 198 <guilabel>Synchronize contents of the clipboard and the
 199 selection</guilabel> check box determines the clipboard mode. If the box is
 200 selected, the clipboard functions in the &UNIX; mode; if not, the
 201 &Windows;/&Mac; mode is used. -->
 202
 203 </sect2>
 204
 205
 206 </sect1>
 207
 208 </chapter>
 209
 210 <chapter id="preferences">
 211 <title>Configuring &klipper;</title>
 212
 213 <sect1 id="viewing-options">
 214
 215 <title>Viewing the Configuration Dialog</title>
 216
 217 <para>To view or change &klipper;'s settings, open the &klipper;
 218 pop-up menu, and select <guimenuitem>Configure Klipper...</guimenuitem>. The &klipper;
 219 configuration dialog will appear. Its contents are described
 220 below.</para>
 221
 222 </sect1>
 223
 224 <sect1 id="general-tab">
 225 <title>General Options</title>
 226
 227 <variablelist>
 228
 229 <varlistentry>
 230 <term><guilabel>Popup menu at mouse-cursor position</guilabel></term>
 231 <listitem><para>Make the &klipper; popup menus appear at the position of
 232 the mouse cursor, instead of their default position (in the &kde; Panel).
 233 Useful if you use the mouse more than the keyboard.</para></listitem>
 234 </varlistentry>
 235
 236
 237 <varlistentry>
 238 <term><guilabel>Save clipboard contents on
 239 exit</guilabel></term> <listitem><para>If this option is on, the clipboard
 240 history will be saved when &klipper; exits, allowing you to use it next time
 241 &klipper; starts.</para>
 242 </listitem>
 243 </varlistentry>
 244
 245 <varlistentry>
 246 <term><guilabel>Remove white space when executing actions</guilabel></term>
 247 <listitem><para>If selected, any white space (spaces, tabs, &etc;) at the
 248 beginning and end of the clipboard contents will be removed before passing the
 249 clipboard contents to an application. This is useful, for example, if the
 250 clipboard contains a &URL; with spaces which, if opened by a web browser, would
 251 cause an error.</para>
 252 </listitem>
 253 </varlistentry>
 254
 255 <varlistentry>
 256 <term><guilabel>Replay actions on an item selected from
 257 history</guilabel></term>
 258 <listitem><para>If this is switched on, selecting an item from the history
 259 causes &klipper; to display the actions pop-up on that item, if
 260 appropriate.</para>
 261 </listitem>
 262 </varlistentry>
 263
 264 <varlistentry>
 265 <term><guilabel>Prevent empty clipboard</guilabel></term>
 266 <listitem><para>If selected, the clipboard will never be empty: &klipper; will
 267 insert the most recent item from the clipboard history into the clipboard
 268 instead of allowing it to be empty.</para></listitem>
 269 </varlistentry>
 270
 271 <varlistentry>
 272 <term><guilabel>Ignore selection</guilabel></term>
 273 <listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
 274 </para>
 275 </listitem>
 276 </varlistentry>
 277
 278
 279 <varlistentry>
 280 <term><guilabel>Synchronize contents of the clipboard and the
 281 selection</guilabel></term>
 282 <listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
 283 </para>
 284 </listitem>
 285 </varlistentry>
 286
 287 <varlistentry>
 288 <term><guilabel>Separate clipboard and selection</guilabel></term>
 289 <listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
 290 </para>
 291 </listitem>
 292 </varlistentry>
 293
 294
 295 <varlistentry>
 296 <term><guilabel>Timeout for Action pop-ups</guilabel></term>
 297 <listitem><para>Set the time that a popup menu will remain for if you do
 298 nothing with it.</para></listitem>
 299 </varlistentry>
 300
 301 <varlistentry><term><guilabel>Clipboard history
 302 size</guilabel></term>
 303 <listitem><para>Sets the number of items that are stored
 304 in the clipboard history.</para></listitem>
 305 </varlistentry>
 306
 307 </variablelist>
 308
 309 </sect1>
 310
 311 <sect1 id="actions-tab">
 312 <title>Actions Options</title>
 313
 314 <variablelist>
 315 <varlistentry>
 316 <term>Editing Expressions/Actions</term>
 317 <listitem><para>On the <guilabel>Actions</guilabel> tab, double-click
 318 the regular expression or action that you want to edit. An in-place text editing
 319 box will appear in which the text can be edited as you wish. Make sure you
 320 press <keysym>Enter</keysym> when you are done.</para></listitem>
 321 </varlistentry>
 322
 323 <varlistentry>
 324 <term>Adding Expressions/Actions</term>
 325 <listitem><para>Click the <guibutton>Add Action</guibutton> button
 326 to add a regular expression for &klipper; to match. &klipper; uses
 327 &Qt;'s <classname>QRegExp</classname>, which understands most regular
 328 expressions as you would use in <application>grep</application> or
 329 <application>egrep</application> for instance.</para>
 330 <para>You can add a description of the regular expression type (&eg;
 331 <quote>HTTP URL</quote>) by <mousebutton>left</mousebutton> clicking in the
 332 <guilabel>Description</guilabel> column.</para>
 333
 334 <note><para>You can find detailed information about the use of
 335 <classname>QRegExp</classname> regular expressions at <ulink
 336 url="http://doc.trolltech.com/qregexp.html#details">http://doc.trolltech.com/qregexp.html#details</ulink>.
 337 Note that &klipper; does not support the wildcard mode mentioned on this
 338 page.</para></note>
 339
 340 <para>Edit the regular expression as described above. To add a command
 341 to execute, <mousebutton>right</mousebutton> click, select
 342 <guimenuitem>Add Command</guimenuitem> and edit the command which
 343 appears in the tree under the regular expression.</para>
 344
 345 <para>Note that <token>%s</token> in the command line is replaced with
 346 the clipboard contents, &eg; if your command definition is
 347 <userinput><command>kedit</command> <token>%s</token></userinput> and
 348 your clipboard contents are <filename>/home/phil/textfile</filename>,
 349 the command <userinput><command>kedit</command>
 350 <filename>/home/phil/textfile</filename></userinput> will be run. To
 351 include <token>%s</token> in the command line, escape it with a
 352 backslash, as so: <userinput>\%s</userinput>.</para></listitem>
 353 </varlistentry>
 354
 355 <varlistentry><term><guibutton>Advanced...</guibutton></term>
 356 <listitem><para>Brings up the <guilabel>Disable Actions for windows of type
 357 WM_CLASS</guilabel> dialog.</para>
 358 <para>Some programs, such as &konqueror;,
 359 use the clipboard internally. If you get unwanted &klipper; pop-ups all the time
 360 when using a certain application, do the following:</para>
 361
 362 <orderedlist>
 363 <listitem><para>Open the application.</para></listitem>
 364 <listitem><para>From a terminal, run <userinput><command>xprop</command>
 365 | <command>grep</command> <parameter>WM_CLASS</parameter></userinput>
 366 and then click on the window of the application you are
 367 running.</para></listitem>
 368 <listitem><para>The first string after the equals sign is the one to
 369 enter.</para></listitem>
 370 </orderedlist>
 371
 372 <para>Once the WM_CLASS is added, no more actions will be generated for
 373 windows of that application.</para>
 374 </listitem>
 375 </varlistentry>
 376 </variablelist>
 377
 378 </sect1>
 379
 380 <sect1 id="shortcuts-tab">
 381 <title>Shortcuts Options</title>
 382
 383 <para>The shortcuts tab allows you to change the keyboard shortcuts
 384 which are used to access &klipper; functions. You can change the
 385 shortcut to one of three things:</para>
 386
 387 <variablelist>
 388 <varlistentry>
 389 <term><guilabel>None</guilabel></term>
 390 <listitem><para>The selected action cannot be accessed directly from the
 391 keyboard</para></listitem>
 392 </varlistentry>
 393 <varlistentry>
 394 <term><guilabel>Default</guilabel></term>
 395 <listitem><para>The selected action uses &klipper;'s default key. These are the
 396 shortcuts referred to in this manual.</para></listitem>
 397 </varlistentry>
 398 <varlistentry>
 399 <term><guilabel>Custom</guilabel></term>
 400 <listitem><para>The selected action is assigned to the keys you choose.</para>
 401 <para>To choose a custom key for the action you have selected, click on the
 402 representation of a key in the lower right of the screen to activate it, and
 403 type the desired key combination on your keyboard, as in any &kde; application.
 404 </para> </listitem>
 405 </varlistentry>
 406 </variablelist>
 407
 408 </sect1>
 409 </chapter>
 410
 411 <chapter id="credits">
 412 <title>Credits and License</title>
 413
 414 <para>
 415 &klipper;
 416 </para>
 417 <para>
 418 Program copyright 1998 &Andrew.Stanley-Jones; <email>asj@cban.com</email>
 419 </para>
 420 <para>
 421 Program copyright 1998-2000 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</para>
 422 <para>
 423 Currently maintained by Esben Mose Hansen. See <ulink
 424 url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
 425 for contact details.
 426 </para>
 427
 428 <para>
 429 Documentation copyright 2000-2003, 2005 &Philip.Rodrigues;
 430 &Philip.Rodrigues.mail;</para>
 431
 432 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 433 &underFDL;
 434 &underGPL;
 435
 436 </chapter>
 437
 438 <appendix id="installation">
 439 <title>Installation</title>
 440
 441 <sect1 id="getting-klipper">
 442 <title>How to obtain &klipper;</title>
 443
 444 &install.intro.documentation;
 445
 446 </sect1>
 447
 448 <sect1 id="compilation">
 449 <title>Compilation and Installation</title>
 450 <para>&klipper; should compile and install along with the kdebase
 451 package, and appear on your &kde; panel (&kicker;) when you run &kde;
 452 3. If it does not appear, you can start it by selecting
 453 <guimenuitem>Add Applet to Panel...</guimenuitem>
 454 in any context menu in &kicker;, the &kde; Panel
 455 and choosing <guilabel>Klipper</guilabel> in the dialog.</para>
 456
 457 <screenshot>
 458 <screeninfo>&klipper; icon</screeninfo>
 459         <mediaobject>
 460           <imageobject>
 461             <imagedata fileref="screenshot.png" format="PNG"/>
 462           </imageobject>
 463           <textobject>
 464             <phrase>Screenshot</phrase>
 465           </textobject>
 466         </mediaobject>
 467 </screenshot>
 468
 469 <!--
 470 <para>To remove &klipper; from your panel, select <guimenuitem>Remove
 471 Klipper</guimenuitem> from the context menu (accessed by left-clicking the
 472 small handle to the left of the &klipper; icon).</para>
 473 -->
 474 <!--
 475 <para>To disable this, simply remove the file
 476 <filename>$<envar>KDEDIR</envar>/share/autostart/klipper.desktop</filename>
 477 or create a file <filename>$<envar>HOME</envar>/share/autostart/klipper.desktop</filename>
 478 with the following contents:
 479
 480 <programlisting>
 481 [Desktop Entry]
 482 Hidden=true
 483 </programlisting>
 484
 485 The latter will keep the system installation intact and only prevent
 486 &klipper; being started for you, without affecting other users.
 487 </para>
 488 -->
 489 </sect1>
 490 </appendix>
 491
 492 &documentation.index;
 493
 494 </book>
 495 <!--
 496 Local Variables:
 497 mode: sgml
 498 sgml-minimize-attributes: nil
 499 sgml-general-insert-case: lower
 500 sgml-indent-step: 0
 501 End:
 502 -->
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512