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
