diff options
Diffstat (limited to 'doc/ksnapshot/index.docbook')
| -rw-r--r-- | doc/ksnapshot/index.docbook | 535 |
1 files changed, 535 insertions, 0 deletions
diff --git a/doc/ksnapshot/index.docbook b/doc/ksnapshot/index.docbook new file mode 100644 index 00000000..408ab80d --- /dev/null +++ b/doc/ksnapshot/index.docbook @@ -0,0 +1,535 @@ +<?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: +--> + + + + |