summaryrefslogtreecommitdiffstats
path: root/doc/klipper/index.docbook
blob: 71327f14c22409b14acc7e06fcd0e2c17279efbf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" 
"dtd/kdex.dtd" [
  <!ENTITY kappname "&klipper;">
  <!ENTITY package "kdebase">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">
<bookinfo>
<title>The &klipper; Handbook </title>

<authorgroup>
<author>&Philip.Rodrigues; &Philip.Rodrigues.mail;</author>

<othercredit role="developer">
&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;
<!-- <contrib>Developer</contrib> -->
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2000-2003</year>
<holder>&Philip.Rodrigues;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2005-01-31</date>
<releaseinfo>2.92.00</releaseinfo>

<abstract>
<para>&klipper; is the &kde; clipboard cut &amp; paste utility.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Klipper</keyword>
<keyword>kdebase</keyword>
<keyword>clipboard</keyword>
</keywordset>
</bookinfo>
 
<chapter id="introduction">
<title>Introduction</title>
<para>&klipper; is the &kde; clipboard utility. It stores clipboard
history, and allows you to link clipboard contents to application
actions. Please report any problems or feature requests to Esben Mose
Hansen (see <ulink
url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
for contact details).</para>

</chapter>

<chapter id="using-klipper">
<title>Using &klipper;</title>

<sect1 id="basic-usage">
<title>Basic Usage</title>
<screenshot>
<screeninfo>The &klipper; icon.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="screenshot.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The &klipper; icon</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>To display the clipboard history, click on the &klipper; icon in
 the &kde; panel, or press <keycombo
 action="simul">&Ctrl;&Alt;<keycap>V</keycap> </keycombo>. Previous
 clipboard entries are shown at the top of the pop-up menu which
 appears. Selecting one of these copies it to the clipboard, from
 where it can be pasted into any &kde; or X application as
 usual.</para>

<para>You can search through the clipboard history by opening it
(click on &klipper;) and typing your query. The results are updated as
you type. In case you're wondering how to use the accelerator keys in
the &klipper; menu, just press &Alt; and the accelerator you want. For
example, to clear the clipboard history when the &klipper; menu is
open, press <keycombo action="simul">&Alt;<keycap>L</keycap>
</keycombo>.</para>

<para>To remove &klipper;, click on its icon in the System Tray, and from the
menu that appears, select <guimenuitem>Quit</guimenuitem>.</para>

</sect1>

<sect1 id="actions">
<title>Actions</title>

<para>&klipper; can perform actions on the contents of the clipboard,
based on whether they match a particular regular expression. For
example, any clipboard contents starting with <quote>http://</quote> can
be passed to &Netscape; or &konqueror; as &URL;s to open.</para>

<para>To use this feature, just copy a &URL; or filename to the
clipboard. If there is a matching regular expression in &klipper;'s
list, a menu will appear showing you the options you have (&eg; Open
&URL; in &konqueror;, open &URL; in &Netscape;). Use the mouse or
keyboard to select the option you want, and &klipper; will run the
program you have selected, opening the address pointed to by the
clipboard contents.</para>

<para>If you do not want to perform any actions on the clipboard
contents, select <guimenuitem>Do Nothing</guimenuitem> on the pop-up menu
to return to what you were doing before. If you leave the menu, it will
disappear, leaving you to continue your work. You can change the time
that the menu remains for in the <guilabel>Configure Klipper...</guilabel>
dialog, with the option <guilabel>Timeout for action pop-ups</guilabel>
under the <guilabel>General</guilabel> tab.</para>
	  
<para>Actions can be disabled completely by clicking on &klipper; and
selecting <guimenuitem>Actions Enabled</guimenuitem>, or by pressing
<keycombo action="simul">&Ctrl;&Alt;<keycap>X</keycap></keycombo>.</para>

<para>Clipboard contents which match a regular expression can also be
edited before performing an action on them. Select <guimenuitem>Edit contents...</guimenuitem> on the &klipper; pop-up menu, and you can
change the clipboard contents in the dialog which appears, before
clicking the <guibutton>OK</guibutton> button to run the appropriate
action.</para>

<para>Pressing <keycombo
action="simul">&Ctrl;&Alt;<keycap>R</keycap></keycombo> shows the pop-up
menu to repeat the last action which &klipper; performed.</para>

</sect1>

<sect1 id="clipboard-modes">
<title>Clipboard/Selection Behavior</title>

<sect2 id="clipboard-modes-general">
<title>General</title>
<para>
&klipper; can be used to set the behavior of the clipboard and selection in
&kde;. 
</para>

<note><para>The &X-Window; uses two separate clipboard buffers: the
<quote>selection</quote> and the <quote>clipboard</quote>. Text is
placed in the selection buffer by simply selecting it, and can be
pasted with the middle mouse button. To place text in
the clipboard buffer, select it and press
<keycombo>&Ctrl;<keycap>X</keycap> </keycombo> or
<keycombo>&Ctrl;<keycap>C</keycap> </keycombo>. Text from the
clipboard buffer is pasted using <keycombo>&Ctrl;<keycap>V</keycap>
</keycombo> or by selecting
<menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem>
</menuchoice>.</para>
</note>

<!-- &klipper; can be used to set the clipboard mode for the whole of &kde;. The
first mode will be familiar to &Microsoft; &Windows; and &Mac; users: Text is
inserted into the clipboard using an application's cut/copy (or generally
<keycombo>&Ctrl;<keycap>X</keycap></keycombo> and
<keycombo>&Ctrl;<keycap>C</keycap></keycombo> respectively)
function, and the application's paste (or generally 
<keycombo>&Ctrl;<keycap>V</keycap></keycombo>) function pastes the
contents of this clipboard.
</para>
<para>
The second mode will be more familiar to longtime &UNIX; users: Selected text
is copied to this clipboard, and clicking the <mousebutton>middle</mousebutton> 
mouse button pastes the
contents of this clipboard.
-->
</sect2>

<sect2 id="changing-clipboard-modes">
<title>Changing Clipboard/Selection Behavior</title>
<para>
In order to change clipboard/selection behavior, select
<guimenuitem>Configure Klipper...</guimenuitem> from the &klipper; pop-up menu,
and in the dialog box that appears, select the
<guilabel>General</guilabel> tab. Selecting <guilabel>Separate clipboard and
selection</guilabel> makes the clipboard and selection function as completely
separate buffers as described above. With this option set, the option
<guilabel>Ignore selection</guilabel> will prevent &klipper; from
including the contents of the selection in its clipboard history and from
performing actions on the contents of the selection. Selecting
<guilabel>Synchronize contents of the clipboard and the selection</guilabel>
causes the clipboard and selection buffers to always be the same, meaning that
text in the selection can be pasted with either the
<mousebutton>middle</mousebutton> mouse button or the key combination <keycombo>&Ctrl;<keycap>V</keycap>
</keycombo>, and similarly for text in the clipboard buffer.
</para>

 <!-- The
<guilabel>Synchronize contents of the clipboard and the
selection</guilabel> check box determines the clipboard mode. If the box is
selected, the clipboard functions in the &UNIX; mode; if not, the
&Windows;/&Mac; mode is used. -->

</sect2>


</sect1>

</chapter>

<chapter id="preferences">
<title>Configuring Klipper</title>

<sect1 id="viewing-options">

<title>Viewing the Configuration Dialog</title>

<para>To view or change &klipper;'s settings, open the &klipper;
pop-up menu, and select <guimenuitem>Configure Klipper...</guimenuitem>. The &klipper;
configuration dialog will appear. Its contents are described
below.</para>

</sect1>

<sect1 id="general-tab">
<title>General Options</title>

<variablelist>

<varlistentry>
<term><guilabel>Popup menu at mouse-cursor position</guilabel></term>
<listitem><para>Make the &klipper; pop-up menus appear at the position of
the mouse cursor, instead of their default position (in the &kde; Panel).
Useful if you use the mouse more than the keyboard.</para></listitem>
</varlistentry>


<varlistentry>
<term><guilabel>Save clipboard contents on
exit</guilabel></term> <listitem><para>If this option is on, the clipboard
history will be saved when &klipper; exits, allowing you to use it next time
&klipper; starts.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Remove whitespace when executing actions</guilabel></term>
<listitem><para>If selected, any whitespace (spaces, tabs, &etc;) at the
beginning and end of the clipboard contents will be removed before passing the
clipboard contents to an application. This is useful, for example, if the
clipboard contains a &URL; with spaces which, if opened by a web browser, would
cause an error.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Replay actions on an item selected from
history</guilabel></term>
<listitem><para>If this is switched on, selecting an item from the history
causes &klipper; to display the actions pop-up on that item, if 
appropriate.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Prevent empty clipboard</guilabel></term>
<listitem><para>If selected, the clipboard will never be empty: &klipper; will
insert the most recent item from the clipboard history into the clipboard
instead of allowing it to be empty.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Ignore selection</guilabel></term>
<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
</para>
</listitem>
</varlistentry> 


<varlistentry>
<term><guilabel>Synchronize contents of the clipboard and the
selection</guilabel></term>
<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
</para>
</listitem>
</varlistentry> 

<varlistentry>
<term><guilabel>Separate clipboard and selection</guilabel></term>
<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>.
</para>
</listitem>
</varlistentry> 


<varlistentry>
<term><guilabel>Timeout for Action pop-ups</guilabel></term>
<listitem><para>Set the time that a pop-up menu will remain for if you do
nothing with it.</para></listitem>
</varlistentry>

<varlistentry><term><guilabel>Clipboard history
size</guilabel></term>
<listitem><para>Sets the number of items that are stored
in the clipboard history.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="actions-tab">
<title>Actions Options</title>

<variablelist>
<varlistentry>
<term>Editing Expressions/Actions</term>
<listitem><para>On the <guilabel>Actions</guilabel> tab, double-click
the regular expression or action that you want to edit. An in-place text editing
box will appear in which the text can be edited as you wish. Make sure you
press <keysym>Enter</keysym> when you are done.</para></listitem>
</varlistentry>

<varlistentry>
<term>Adding Expressions/Actions</term>
<listitem><para>Click the <guibutton>Add Action</guibutton> button
to add a regular expression for &klipper; to match. &klipper; uses
&Qt;'s <classname>QRegExp</classname>, which understands most regular
expressions as you would use in <application>grep</application> or
<application>egrep</application> for instance.</para>
<para>You can add a description of the regular expression type (&eg;
<quote>HTTP URL</quote>) by <mousebutton>left</mousebutton> clicking in the
<guilabel>Description</guilabel> column.</para>   

<note><para>You can find detailed information about the use of
<classname>QRegExp</classname> regular expressions at <ulink
url="http://doc.trolltech.com/qregexp.html#details">http://doc.trolltech.com/qregexp.html#details</ulink>.
Note that &klipper; does not support the wildcard mode mentioned on this
page.</para></note> 

<para>Edit the regular expression as described above. To add a command
to execute, <mousebutton>right</mousebutton> click, select
<guimenuitem>Add Command</guimenuitem> and edit the command which
appears in the tree under the regular expression.</para>

<para>Note that <token>%s</token> in the command line is replaced with
the clipboard contents, &eg; if your command definition is
<userinput><command>kedit</command> <token>%s</token></userinput> and
your clipboard contents are <filename>/home/phil/textfile</filename>,
the command <userinput><command>kedit</command>
<filename>/home/phil/textfile</filename></userinput> will be run. To
include <token>%s</token> in the command line, escape it with a
backslash, as so: <userinput>\%s</userinput>.</para></listitem>
</varlistentry>

<varlistentry><term><guibutton>Advanced...</guibutton></term>
<listitem><para>Brings up the <guilabel>Disable Actions for windows of type
WM_CLASS</guilabel> dialog.</para>
<para>Some programs, such as &konqueror;,
use the clipboard internally. If you get unwanted &klipper; pop-ups all the time
when using a certain application, do the following:</para>

<orderedlist>
<listitem><para>Open the application.</para></listitem>
<listitem><para>From a terminal, run <userinput><command>xprop</command>
| <command>grep</command> <parameter>WM_CLASS</parameter></userinput>
and then click on the window of the application you are
running.</para></listitem> 
<listitem><para>The first string after the equals sign is the one to
enter.</para></listitem>
</orderedlist>

<para>Once the WM_CLASS is added, no more actions will be generated for
windows of that application.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="shortcuts-tab">
<title>Shortcuts Options</title>

<para>The shortcuts tab allows you to change the keyboard shortcuts
which are used to access &klipper; functions. You can change the
shortcut to one of three things:</para>

<variablelist>
<varlistentry>
<term><guilabel>None</guilabel></term>
<listitem><para>The selected action cannot be accessed directly from the
keyboard</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Default</guilabel></term>
<listitem><para>The selected action uses &klipper;'s default key. These are the
shortcuts referred to in this manual.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Custom</guilabel></term>
<listitem><para>The selected action is assigned to the keys you choose.</para>
<para>To choose a custom key for the action you have selected, click on the
representation of a key in the lower right of the screen to activate it, and
type the desired key combination on your keyboard, as in any &kde; application. 
</para> </listitem>
</varlistentry>
</variablelist>

</sect1>
</chapter>

<chapter id="credits">
<title>Credits and License</title>

<para>
&klipper;
</para>
<para>
Program copyright 1998 Andrew Stanley-Jones <email>asj@cban.com</email>
</para>
<para>
Program copyright 1998-2000 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</para>
<para>
Currently maintained by Esben Mose Hansen. See <ulink
url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink>
for contact details.
</para>

<para>
Documentation copyright 2000-2003, 2005 &Philip.Rodrigues;
&Philip.Rodrigues.mail;</para>

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-klipper">
<title>How to obtain &klipper;</title>

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>
<para>&klipper; should compile and install along with the kdebase
package, and appear on your &kde; panel (&kicker;) when you run &kde;
3. If it does not appear, you can start it by selecting
<menuchoice><guimenu>Panel
Menu</guimenu><guisubmenu>Add</guisubmenu><guisubmenu>Applet</guisubmenu><guimenuitem>Klipper</guimenuitem>
</menuchoice>
in any context menu in &kicker;, the &kde; Panel.</para> 

<screenshot>
<screeninfo>&klipper; icon</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

<!--
<para>To remove &klipper; from your panel, select <guimenuitem>Remove
Klipper</guimenuitem> from the context menu (accessed by left-clicking the
small handle to the left of the &klipper; icon).</para>
-->
<!--
<para>To disable this, simply remove the file 
<filename>$<envar>KDEDIR</envar>/share/autostart/klipper.desktop</filename>
or create a file <filename>$<envar>HOME</envar>/share/autostart/klipper.desktop</filename>
with the following contents:

<programlisting>
[Desktop Entry]
Hidden=true
</programlisting>

The latter will keep the system installation intact and only prevent
&klipper; being started for you, without affecting other users.
</para>
-->
</sect1>
</appendix>

&documentation.index; 

</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step: 0
End:
-->