[kde-doc-english] Update for KSnapshot handbook
Brad Hards
bradh at frogmouth.net
Thu Feb 3 07:52:59 CET 2005
Here is another update - do I hold off committing, or put it in
and let people correct it later?
Brad
--- index.docbook 8 Jan 2005 23:46:21 -0000 1.26
+++ index.docbook 3 Feb 2005 06:51:55 -0000
@@ -29,8 +29,16 @@
<address><email>c0029131 at airmail.net</email></address>
</affiliation>
</author>
+<author>
+<firstname>Brad</firstname>
+<surname>Hards</surname>
+<affiliation>
+<address><email>bradh at frogmouth.net</email></address>
+</affiliation>
+</author>
+
<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
@@ -72,36 +80,36 @@
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
-<date>2000-12-12</date>
-<releaseinfo>1.01.00</releaseinfo>
+<date>2005-02-02</date>
+<releaseinfo>1.02.00</releaseinfo>
<abstract>
<para>&ksnapshot; is a simple applet for taking screenshots. It is capable
-of capturing images of either the whole desktop or just a single
-window. The images can then be saved in a variety of formats.</para>
+of capturing images of the whole desktop, a single 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>kdeutils</keyword>
-<keyword>nothing</keyword>
-<keyword>nothing else</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 application for taking screenshots. It is
capable
-of capturing images of either the whole desktop or just a single
-window. The images can then be saved in a variety of formats.</para>
+<para>&ksnapshot; is a simple applet for taking screenshots. It is capable
+of capturing images of the whole desktop, a single 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 bugzilla</ulink></para>
+url="http://bugs.kde.org/wizard.cgi">KDE Bug Tracking System</ulink></para>
</chapter>
<chapter id="using-ksapshot">
@@ -165,31 +173,46 @@ will differ depending on what you have d
</textobject>
</mediaobject>
<para>The snapshot can be saved by clicking on
-the <guibutton>Save As...</guibutton> button. 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
+the <guibutton>Save As...</guibutton> button. 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, enable <guilabel>Only
-grab the window containing the pointer</guilabel> and then take a
-<guibutton>New Snapshot</guibutton>. </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 or you can work with a program until
+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 in 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, uncheck the
-<guilabel>Only grab the window containing the pointer</guilabel>
-option. &ksnapshot; will now capture the entire desktop if you press
+<para>To take a new snapshot of the entire desktop, select the
+<guilabel>Full Screen</guilabel> combo box entry (next to the
+<guilabel>Capture mode:</guilabel> label), 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 (next to the
+<guilabel>Capture mode:</guilabel> label) 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>
+
</sect1>
<sect1 id="additional-features">
<title>Additional Features</title>
@@ -252,8 +275,215 @@ get some more information about &kde; an
</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 interace 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 the
+<literal>grabMode</literal> call, 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 the <literal>setGrabMode</literal>,
+which requires an argument to identify the mode required (as for the
<literal>grabMode</literal>
+call). 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 the <literal>timeout</literal> call, 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
(click on
+capture).
+</para>
+
+<para>You can set the timeout using the <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 the
+<literal>url</literal> call, 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 the <literal>setURL</literal> command,
+which requires a string argument to identify the new path. So you can
+set the path to <literal>file:///home/bradh/snapshot4.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 the
<literal>slotGrab</literal>
+command, 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 call <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
+the <literal>slotCopy</literal> command, 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 the <literal>slotMovePointer</literal> call, 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 the <literal>printSlot</literal> command, 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 the <literal>exit</literal>
+command, 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>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20050203/7ee42c24/attachment.sig
More information about the kde-doc-english
mailing list