← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to doc/klipper/index.docbook

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

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