You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
536 lines
16 KiB
536 lines
16 KiB
<?xml version="1.0" ?>
|
|
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
|
<!ENTITY kappname "&ksnapshot;">
|
|
<!ENTITY package "kdegraphics">
|
|
<!ENTITY % addindex "IGNORE">
|
|
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
|
|
]>
|
|
|
|
<book lang="&language;">
|
|
|
|
<bookinfo>
|
|
<title>The &ksnapshot; Handbook</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Richard</firstname>
|
|
<othername>J.</othername>
|
|
<surname>Moore</surname>
|
|
<affiliation>
|
|
<address>&Richard.J.Moore.mail;</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Robert</firstname>
|
|
<othername>L.</othername>
|
|
<surname>McCormick</surname>
|
|
<affiliation>
|
|
<address>&Robert.L.McCormick.mail;</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Brad</firstname>
|
|
<surname>Hards</surname>
|
|
<affiliation>
|
|
<address>&Brad.Hards.mail;</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<othercredit role="reviewer">
|
|
<firstname>Lauri</firstname>
|
|
<surname>Watts</surname>
|
|
<affiliation>
|
|
<address>&Lauri.Watts.mail;</address>
|
|
</affiliation>
|
|
<contrib>Reviewer</contrib>
|
|
</othercredit>
|
|
|
|
<othercredit role="developer">
|
|
<firstname>Richard</firstname>
|
|
<othername>J</othername>
|
|
<surname>Moore</surname>
|
|
<affiliation>
|
|
<address>&Richard.J.Moore.mail;</address>
|
|
</affiliation>
|
|
<contrib>Developer</contrib>
|
|
</othercredit>
|
|
|
|
<othercredit role="developer">
|
|
<firstname>Matthias</firstname>
|
|
<surname>Ettrich</surname>
|
|
<affiliation>
|
|
<address>&Matthias.Ettrich.mail;</address>
|
|
</affiliation>
|
|
<contrib>Developer</contrib>
|
|
</othercredit>
|
|
|
|
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
|
</authorgroup>
|
|
|
|
<copyright>
|
|
<year>1997-2000</year>
|
|
<holder>&Richard.J.Moore;</holder>
|
|
</copyright>
|
|
|
|
<copyright>
|
|
<year>2000</year>
|
|
<holder>&Matthias.Ettrich;</holder>
|
|
</copyright>
|
|
|
|
<legalnotice>&FDLNotice;</legalnotice>
|
|
|
|
<date>2006-07-05</date>
|
|
<releaseinfo>0.7</releaseinfo>
|
|
|
|
<abstract>
|
|
<para>&ksnapshot; is a simple applet for taking screenshots. It is capable
|
|
of capturing images of the whole desktop, a single window, a section of a window or a selected
|
|
region. The images can then be saved in a variety of formats.</para>
|
|
</abstract>
|
|
|
|
<keywordset>
|
|
<keyword>KDE</keyword>
|
|
<keyword>KSnapshot</keyword>
|
|
<keyword>kdegraphics</keyword>
|
|
<keyword>screen capture</keyword>
|
|
<keyword>screen grab</keyword>
|
|
</keywordset>
|
|
|
|
</bookinfo>
|
|
|
|
<chapter id="introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>&ksnapshot; is a simple applet for taking screenshots. It is capable
|
|
of capturing images of the whole desktop, a single window a section of a window or a selected
|
|
region. The images can then be saved in a variety of formats.</para>
|
|
|
|
<para>Please report any problems or feature requests to the <ulink
|
|
url="http://bugs.kde.org/wizard.cgi">&kde; Bug Tracking System</ulink></para>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="using-ksapshot">
|
|
<title>Using &ksnapshot;</title>
|
|
|
|
<para>This chapter describes the use of &ksnapshot; for capturing screen
|
|
images.</para>
|
|
|
|
<sect1 id="starting">
|
|
<title>Starting &ksnapshot;</title>
|
|
|
|
<para>&ksnapshot; may be started by one of several ways as described
|
|
below.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You may start &ksnapshot; by selecting it from the <menuchoice>
|
|
<guimenu>K-Menu</guimenu><guisubmenu>Graphics</guisubmenu>
|
|
<guimenuitem>&ksnapshot; (Screen Capture Program)</guimenuitem></menuchoice>.
|
|
</para></listitem>
|
|
<listitem>
|
|
<para>You may start &ksnapshot; by entering the following at the command
|
|
prompt:</para>
|
|
<screen width="40">
|
|
<prompt>%</prompt> <command>ksnapshot &</command>
|
|
</screen>
|
|
</listitem>
|
|
<listitem><para>The mini command line (invoked with
|
|
<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>) may
|
|
also be used to start &ksnapshot;</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Once &ksnapshot; starts, you will see a window like the following:
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="window.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject><phrase>&ksnapshot; Preview Window</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="taking-snapshot">
|
|
<title>Taking A Snapshot</title>
|
|
|
|
<para> &ksnapshot; grabs an image of your entire desktop immediately after it is
|
|
started, but before it displays itself on screen. This allows you to quickly
|
|
create full-desktop screenshot images.</para>
|
|
|
|
<para>The snapshot taken by &ksnapshot; is displayed in the preview window,
|
|
which is located in the upper left of the &ksnapshot; application window.
|
|
Below is an example of the preview window from &ksnapshot;. Your preview
|
|
will differ depending on what you have displayed on the desktop.</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="preview.png" format="PNG"/>
|
|
</imageobject>
|
|
<textobject><phrase>&ksnapshot; Preview Window</phrase>
|
|
</textobject>
|
|
</mediaobject>
|
|
|
|
<para>The snapshot can be saved by clicking on
|
|
the <guibutton>Save As...</guibutton> button. This opens the standard &kde; save dialog,
|
|
where you can choose the filename, the folder location, and the format that your snapshot
|
|
will be saved in. If multiple snapshots are taken, the
|
|
filename is automatically incremented to prevent you from overwriting previous
|
|
snapshots. You may however edit the filename to anything you wish, including the name
|
|
of a previously saved snapshot. </para>
|
|
|
|
<para>To take a snapshot of a single window, select the <guilabel>Window
|
|
Under Cursor</guilabel> combo box entry (next to the <guilabel>Capture mode:</guilabel>
|
|
label), and then click on the <guibutton>New Snapshot</guibutton> button.</para>
|
|
|
|
<para>Depending on your <guilabel>Snapshot delay:</guilabel> settings you
|
|
get either a cross as the mouse pointer (for <guilabel>No delay</guilabel>),
|
|
or a standard mouse cursor which you can use to work with a program until
|
|
the delay is over and a snapshot is taken.</para>
|
|
|
|
<para>With <guilabel>No delay</guilabel>, the snapshot is taken immediately when you
|
|
click into a window.</para>
|
|
|
|
<para>&ksnapshot; will display the new snapshot in the preview
|
|
area, at which time you can choose to save the new image (by pressing
|
|
<guibutton>Save As...</guibutton>)
|
|
or to grab a new one, by pressing the
|
|
<guibutton>New Snapshot</guibutton> button.</para>
|
|
|
|
<para>To take a new snapshot of the entire desktop, select the
|
|
<guilabel>Full Screen</guilabel> combo box entry and then click on the
|
|
<guibutton>New Snapshot</guibutton> button.
|
|
&ksnapshot; will now capture the entire desktop if you press
|
|
<guibutton>New Snapshot</guibutton>.</para>
|
|
|
|
<para>Similarly, to take a snapshot of a region, select the
|
|
<guilabel>Region</guilabel> combo box entry and set the
|
|
<guilabel>Snapshot delay</guilabel> to <guilabel>No delay</guilabel>,
|
|
and then click on the <guibutton>New Snapshot</guibutton> button. The
|
|
mouse cursor will then change into a cross, and you can then use the
|
|
mouse to select the region you want to capture. </para>
|
|
|
|
<para>To take a new snapshot of a section of a window, select the
|
|
<guilabel>Section of Window</guilabel> combo box entry and then click on the
|
|
<guibutton>New Snapshot</guibutton> button. With <guilabel>No delay</guilabel>
|
|
you get a cross as the mouse pointer and you have to click once with the &LMB; into
|
|
the window. The section of the window under the mouse cursor is now highlighted
|
|
with a red border. Move the mouse to the wanted section and click the &LMB;
|
|
to capture the screenshot.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="additional-features">
|
|
<title>Additional Features</title>
|
|
|
|
<sect2 id="delay">
|
|
<title>Snapshot Delay</title>
|
|
|
|
<para>The <guilabel>Snapshot Delay:</guilabel> box allows you to enter an
|
|
arbitrary time delay, in seconds, between the time that you press the
|
|
<guibutton>New Snapshot</guibutton> button and the time that the snapshot is
|
|
taken.</para>
|
|
|
|
<para>When a delay time has been set, you do not have to click the mouse
|
|
button to capture a screenshot. This enables you to open a drop down menu,
|
|
and take a picture of it.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="window-decoration">
|
|
<title>Exclude Window decorations</title>
|
|
|
|
<para><guilabel>Include window decorations</guilabel> is enabled by default.</para>
|
|
|
|
<para>When you only want to capture the application itself without the surrounding
|
|
window decoration, disable this option and take a new snapshot.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="print-snapshot">
|
|
<title>Print</title>
|
|
|
|
<para>When you want to print your snapshot from the preview, just click
|
|
<guibutton>Print...</guibutton> and you get the standard &kde; Print dialog, from
|
|
where you can directly print your snapshot.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="copy-snapshot">
|
|
<title>Copy to Clipboard</title>
|
|
|
|
<para>When you want to edit your snapshot in a graphics application without saving
|
|
the snapshot, just click <guibutton>Copy to Clipboard</guibutton> and insert the image
|
|
into a viewer or graphics application.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="bottom-buttons">
|
|
<title>Buttons</title>
|
|
|
|
<para>There are two further buttons located at the bottom of the
|
|
&ksnapshot; window. There function is described below.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guibutton>Help</guibutton></term>
|
|
<listitem><para>Gives you a menu where you can open the
|
|
<guimenuitem>&ksnapshot; Handbook</guimenuitem>, report a bug or
|
|
get some more information <guimenuitem>About &ksnapshot;</guimenuitem>
|
|
and <guimenuitem>About &kde;</guimenuitem>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><guibutton>Quit</guibutton></term>
|
|
<listitem><para>Quits the &ksnapshot; application.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="dcop">
|
|
|
|
<title>&DCOP; Interface</title>
|
|
|
|
<para>&ksnapshot; can be scripted using its &DCOP; interface. This
|
|
chapter explains the various &DCOP; calls that you can use, and
|
|
provides some examples of how you can use them.</para>
|
|
|
|
<para>As with all &DCOP; calls, you need to specify the application
|
|
you want to interface with, and the particular interface. With &ksnapshot;
|
|
you need to identify which particular application, which is
|
|
<literal>ksnapshot-</literal> followed by the process number.</para>
|
|
|
|
<para>To start &ksnapshot; and obtain the right argument, use
|
|
<command>dcopstart ksnapshot</command>, which returns the
|
|
argument (such as <computeroutput>ksnapshot-20594</computeroutput>) on
|
|
standard output.</para>
|
|
|
|
<para>You can get a list of the available &DCOP; interfaces, use
|
|
the right arguments, as shown in this example:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop `dcopstart ksnapshot` interface</command><computeroutput>
|
|
QCStringList interfaces()
|
|
QCStringList functions()
|
|
QString url()
|
|
void slotGrab()
|
|
void slotPrint()
|
|
void slotSave()
|
|
bool save(QString filename)
|
|
void slotSaveAs()
|
|
void slotCopy()
|
|
void setTime(int newTime)
|
|
int timeout()
|
|
void setURL(QString newURL)
|
|
void setGrabMode(int grab)
|
|
int grabMode()
|
|
void slotMovePointer(int x,int y)
|
|
void exit()
|
|
</computeroutput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
In the examples following, the process is always
|
|
<computeroutput>ksnapshot-23151</computeroutput>.
|
|
</para>
|
|
|
|
<sect1 id="dcop-settings">
|
|
|
|
<title>&DCOP; Access to Settings</title>
|
|
|
|
<para>For each of the settings that you can control with the
|
|
&GUI;, you can both obtain the current status of that setting,
|
|
and modify the setting, using &DCOP;.
|
|
</para>
|
|
|
|
<para>You can obtain the current capture mode using
|
|
<literal>grabMode</literal>, as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface grabMode</command>
|
|
</screen>
|
|
This will return <computeroutput>0</computeroutput> for full-screen capture,
|
|
<computeroutput>1</computeroutput> for window capture, and <computeroutput>2</computeroutput>
|
|
for region capture.
|
|
</para>
|
|
|
|
<para>You can set the capture mode using <literal>setGrabMode</literal>,
|
|
which requires an argument to identify the mode required (as for <literal>grabMode</literal>).
|
|
So you can set window capture mode (<command>1</command>), using:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface setGrabMode 1</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>You can obtain the current timeout setting (the <guilabel>Snapshot delay:</guilabel>
|
|
GUI item) using <literal>timeout</literal>, as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface timeout</command>
|
|
</screen>
|
|
This will return the timeout setting in seconds, or zero if there is no delay
|
|
(capture on click).
|
|
</para>
|
|
|
|
<para>You can set the timeout using <literal>setTime</literal>,
|
|
which requires an argument to identify the timeout duration. So you can
|
|
set a delay of 4 seconds using:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface setTime 4</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>You can obtain the path that the snapshot will be saved to using
|
|
<literal>url</literal>, as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt><command>dcop ksnapshot-23151 interface url</command>
|
|
</screen>
|
|
This will return the filename, as a &URL; (eg as
|
|
<computeroutput>file:///home/bradh/test2.png</computeroutput>).
|
|
</para>
|
|
|
|
<para>You can set the path using <literal>setURL</literal>,
|
|
which requires a string argument to identify the new path. So you can
|
|
set the path to <literal>file:///home/bradh/snapshot.jpg</literal>
|
|
using:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface setURL file:///home/bradh/snapshot.jpg</command>
|
|
</screen>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="dcop-snapshot">
|
|
<title>Taking Screenshots with &DCOP;</title>
|
|
|
|
<para>
|
|
The key to taking screenshots with &DCOP; is use of <literal>slotGrab</literal>,
|
|
as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface slotGrab</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
This will take a snapshot using the current snapshot mode and timeout settings
|
|
(as described above). If you want to save the snapshot image, there are a
|
|
number of calls you can use. If you just want to save the image to the current
|
|
path (as returned by <literal>url</literal> or changed by
|
|
<literal>setURL</literal>), you can use <literal>slotSave</literal>, as shown
|
|
below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface slotSave</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If you want the user to be able to specify a filename (and path), you can use
|
|
<literal>slotSaveAs</literal>, which will bring up a standard &kde; file
|
|
save dialog.</para>
|
|
|
|
<para>
|
|
If you want to save the image to a different name (or path) without
|
|
changing the path with <literal>setURL</literal>, you can use
|
|
<literal>save</literal>, providing the &URL; to save to as an argument. So if you
|
|
want to save the snapshot to <filename>file:///tmp/tempshot.png</filename>, you
|
|
can do the following:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface save file:///tmp/tempshot.png</command>
|
|
</screen>
|
|
Note that this will return true if the snapshot was successfully saved, and false
|
|
otherwise. Also, you should be aware that if the file already exists, the user
|
|
will get a standard &kde; dialog that requires the user to decide whether to overwrite
|
|
or not.
|
|
</para>
|
|
|
|
<para>
|
|
In addition to saving the snapshot, you can also copy it to the clipboard, using
|
|
<literal>slotCopy</literal>, as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface slotCopy</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
If you need to select a window that may not be under the mouse cursor, you
|
|
can use <literal>slotMovePointer</literal>, passing the x position
|
|
(in screen pixels) and the y position (also in screen pixels) as arguments.
|
|
So to move the mouse to the top left hand corner of the screen (0,0), you
|
|
can do the following:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface slotMoveMouse 0 0</command>
|
|
</screen>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="dcop-print">
|
|
<title>Printing Screenshots with &DCOP;</title>
|
|
|
|
<para>
|
|
You can print the current screenshot (which may or may not have been saved)
|
|
using <literal>printSlot</literal>, as shown below:
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface slotPrint</command>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Note that this will bring up the normal &kde; print dialog, which may require
|
|
user interaction.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="dcop-exit">
|
|
<title>&DCOP; Application control</title>
|
|
|
|
<para>
|
|
You can cause &ksnapshot; to exit by using <literal>exit</literal>,
|
|
as shown below.
|
|
<screen width="60">
|
|
<prompt>$</prompt> <command>dcop ksnapshot-23151 interface exit</command>
|
|
</screen>
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="credits">
|
|
|
|
<title>Credits and License</title>
|
|
|
|
<para>Program copyright</para>
|
|
<itemizedlist>
|
|
<listitem><para>1997-2000 &Richard.J.Moore; &Richard.J.Moore.mail;</para></listitem>
|
|
<listitem><para>2000 &Matthias.Ettrich; &Matthias.Ettrich.mail;</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Documentation based on the original, copyright 1997-2000 &Richard.J.Moore;
|
|
&Richard.J.Moore.mail;</para>
|
|
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
|
|
|
&underFDL;
|
|
&underGPL;
|
|
|
|
</chapter>
|
|
|
|
&documentation.index;
|
|
</book>
|
|
|
|
<!--
|
|
Local Variables:
|
|
sgml-minimize-attributes: nil
|
|
sgml-general-insert-case: lower
|
|
End:
|
|
-->
|
|
|
|
|
|
|
|
|