? snapshot-2005-02-06.patch Index: index.docbook =================================================================== RCS file: /home/kde/kdegraphics/doc/ksnapshot/index.docbook,v retrieving revision 1.26 diff -u -4 -p -r1.26 index.docbook --- index.docbook 8 Jan 2005 23:46:21 -0000 1.26 +++ index.docbook 5 Feb 2005 23:44:45 -0000 @@ -29,8 +29,16 @@
c0029131@airmail.net
+ +Brad +Hards + +
bradh@frogmouth.net
+ + + Lauri Watts @@ -72,36 +80,36 @@ &FDLNotice; -2000-12-12 -1.01.00 +2005-02-02 +1.02.00 &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. +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. KDE KSnapshot -kdeutils -nothing -nothing else +kdegraphics +screen capture +screen grab Introduction -&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. +&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. Please report any problems or feature requests to the KDE bugzilla +url="http://bugs.kde.org/wizard.cgi">KDE Bug Tracking System @@ -165,31 +173,46 @@ will differ depending on what you have d The snapshot can be saved by clicking on -the Save As... 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 Save As... 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. -To take a snapshot of a single window, enable Only -grab the window containing the pointer and then take a -New Snapshot. +To take a snapshot of a single window, select the Window +Under Cursor combo box entry (next to the Capture mode: +label), and then click on the New Snapshot button. + Depending on your Snapshot delay: 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 No delay), +or a standard mouse cursor which you can use to work with a program until the delay is over and a snapshot is taken. + With No delay, the snapshot is taken immediately when you click in a window. + &ksnapshot; will display the new snapshot in the preview area, at which time you can choose to save the new image (by pressing Save As...) or to grab a new one, by pressing the New Snapshot button. -To take a new snapshot of the entire desktop, uncheck the -Only grab the window containing the pointer -option. &ksnapshot; will now capture the entire desktop if you press +To take a new snapshot of the entire desktop, select the +Full Screen combo box entry (next to the +Capture mode: label), and then click on the +New Snapshot button. +&ksnapshot; will now capture the entire desktop if you press New Snapshot. +Similarly, to take a snapshot of a region, select the +Region combo box entry (next to the +Capture mode: label) and set the +Snapshot delay to No delay, +and then click on the New Snapshot 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. + Additional Features @@ -252,8 +275,215 @@ get some more information about &kde; an + + +&DCOP; Interface + +&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. + +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 +ksnapshot- followed by the process number. + +To start &ksnapshot; and obtain the right argument, use +dcopstart ksnapshot, which returns the +argument (such as ksnapshot-20594) on +standard output. + +You can get a list of the available &DCOP; interfaces, use +the right arguments, as shown in this example: + +$ dcop `dcopstart ksnapshot` interface +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() + + + + + +In the examples following, the process is always +ksnapshot-23151. + + + + +&DCOP; Access to Settings + +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;. + + +You can obtain the current capture mode using the +grabMode call, as shown below: + +$ dcop ksnapshot-23151 interface grabMode + +This will return 0 for full-screen capture, +1 for window capture, and 2 +for region capture. + + +You can set the capture mode using the setGrabMode, +which requires an argument to identify the mode required (as for the grabMode +call). So you can set window capture mode (1), using: + +$ dcop ksnapshot-23151 interface setGrabMode 1 + + + +You can obtain the current timeout setting (the Snapshot delay: +GUI item) using the timeout call, as shown below: + +$ dcop ksnapshot-23151 interface timeout + +This will return the timeout setting in seconds, or zero if there is no delay (click on +capture). + + +You can set the timeout using the setTime, +which requires an argument to identify the timeout duration. So you can +set a delay of 4 seconds using: + +$ dcop ksnapshot-23151 interface setTime 4 + + + +You can obtain the path that the snapshot will be saved to using the +url call, as shown below: + +$ dcop ksnapshot-23151 interface url + +This will return the filename, as a URL (eg as +file:///home/bradh/test2.png). + + +You can set the path using the setURL command, +which requires a string argument to identify the new path. So you can +set the path to file:///home/bradh/snapshot4.jpg +using: + +$ dcop ksnapshot-23151 interface setURL file:///home/bradh/snapshot.jpg + + + + + + +Taking Screenshots with &DCOP; + + +The key to taking screenshots with &DCOP; is use of the slotGrab +command, as shown below: + +$ dcop ksnapshot-23151 interface slotGrab + + + + +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 url) or changed by +setURL), you can call slotSave, as shown +below: + +$ dcop ksnapshot-23151 interface slotSave + + + + +If you want the user to be able to specify a filename (and path), you can use +slotSaveAs, which will bring up a standard &kde; file +save dialog. + + +If you want to save the image to a different name (or path) without +changing the path with setURL, you can use +save, providing the URL to save to as an argument. So if you +want to save the snapshot to file:///tmp/tempshot.png, you +can do the following: + +$ dcop ksnapshot-23151 interface save file:///tmp/tempshot.png + +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. + + + +In addition to saving the snapshot, you can also copy it to the clipboard, using +the slotCopy command, as shown below: + +$ dcop ksnapshot-23151 interface slotCopy + + + + +If you need to select a window that may not be under the mouse cursor, you +can use the slotMovePointer 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: + +$ dcop ksnapshot-23151 interface slotMoveMouse 0 0 + + + + + +Printing Screenshots with &DCOP; + + +You can print the current screenshot (which may or may not have been saved) +using the printSlot command, as shown below: + +$ dcop ksnapshot-23151 interface slotPrint + + + + +Note that this will bring up the normal &kde; print dialog, which may require +user interaction. + + + + + +&DCOP; Application control + + +You can cause &ksnapshot; to exit by using the exit +command, as shown below. + +$ dcop ksnapshot-23151 interface exit + + + + + + + Credits and License