<?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 % Portuguese "INCLUDE"
> <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title
>Manual do &ksnapshot;</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
>Revisão</contrib>
</othercredit>

<othercredit role="developer"
><firstname
>Richard</firstname
> <othername
>J</othername
> <surname
>Moore</surname
> <affiliation
> <address
>&Richard.J.Moore.mail;</address>
</affiliation>
<contrib
>Desenvolvimento</contrib>
</othercredit>

<othercredit role="developer"
><firstname
>Matthias</firstname
> <surname
>Ettrich</surname
> <affiliation
> <address
>&Matthias.Ettrich.mail;</address>
</affiliation>
<contrib
>Desenvolvimento</contrib>
</othercredit>

<othercredit role="translator"
><firstname
>Nuno</firstname
><surname
>Donato</surname
><affiliation
><address
><email
>nunodonato@iol.pt</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</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
>2010-01-07</date>
<releaseinfo
>0.8.1</releaseinfo>

<abstract>
<para
>0 &ksnapshot; é uma 'applet' simples para capturar imagens do ecrã. É capaz de capturar imagens do ecrã inteiro, de apenas uma janela ou de uma região seleccionada. As imagens podem ser gravadas numa variedade de formatos.</para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>KSnapshot</keyword>
<keyword
>kdegraphics</keyword>
<keyword
>captura do ecrã</keyword>
<keyword
>imagem do ecrã</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Introdução</title>

<para
>0 &ksnapshot; é uma 'applet' simples para capturar imagens do ecrã. É capaz de capturar imagens do ecrã inteiro, de apenas uma janela ou de uma região seleccionada. As imagens podem ser gravadas numa variedade de formatos.</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
>Usar o &ksnapshot;</title>

<para
>Este capítulo descreve a utilização do &ksnapshot; para capturar imagens do ecrã.</para>

<sect1 id="starting">
<title
>Iniciando o &ksnapshot;</title>

<para
>O &ksnapshot; pode ser iniciado por uma das várias maneiras descritas de seguida.</para>

<itemizedlist>
<listitem>
<para
>Pode iniciar o &ksnapshot;, seleccionando para tal a opção <menuchoice
> <guimenu
>Aplicações</guimenu
><guisubmenu
>Gráficos</guisubmenu
> <guimenuitem
>Programa de Captura do Ecrã &ksnapshot;</guimenuitem
></menuchoice
>. </para
></listitem>
<listitem>
<para
>Pode iniciar o &ksnapshot; introduzindo o seguinte comando numa linha de comandos:</para>
<screen width="40"
><prompt
>%</prompt
> <command
>ksnapshot &amp;</command
>
</screen>
</listitem>
<listitem
><para
>A mini linha de comandos (invocada com <keycombo action="simul"
>&Alt;<keycap
>F2</keycap
></keycombo
>) também pode ser usada para iniciar o &ksnapshot;</para
></listitem>
</itemizedlist>

<para
>Logo que o &ksnapshot; esteja a correr irá ver uma janela como a seguinte: <mediaobject>
<imageobject>
<imagedata fileref="window.png" format="PNG"/>
</imageobject>
<textobject
><phrase
>Janela do &ksnapshot;</phrase>
</textobject>
</mediaobject>
</para>

</sect1>

<sect1 id="taking-snapshot">
<title
>Capturando uma Imagem</title>

<para
>O &ksnapshot; captura uma imagem do ecrã inteiro imediatamente após ter sido iniciado, mas antes de aparecer no ecrã. Isto permite-lhe criar rapidamente imagens do ecrã inteiro.</para>

<para
>A imagem capturada pelo &ksnapshot; é mostrada na janela de antevisão, que está localizada na parte central superior da janela do &ksnapshot; Em baixo está um exemplo da janela de pré-visualização do &ksnapshot;. A sua imagem será diferente dependendo do que está no seu ecrã.</para>

<mediaobject>
<imageobject>
<imagedata fileref="preview.png" format="PNG"/>
</imageobject>
<textobject
><phrase
>Janela do &ksnapshot;</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
>Dependendo da sua configuração do <guilabel
>Atraso da fotografia</guilabel
> você poderá obter uma cruz como cursor do rato (para o <guilabel
>Sem atraso</guilabel
>) ou poderá lidar com um programa até que o atraso termine e seja tirada uma fotografia.</para>

<para
>Com o <guilabel
>Sem atraso</guilabel
>, a imagem é extraída imediatamente logo que você carregar numa janela.</para>

<para
>O &ksnapshot; irá mostrar a nova imagem na área de antevisão, e nessa altura você poderá optar por gravar a nova imagem (ao carregar em <guibutton
>Gravar Como...</guibutton
>) ou por capturar uma nova, ao carregar no botão <guibutton
>Nova Fotografia</guibutton
>.</para>

<para
>Para capturar uma nova imagem do ecrã inteiro, active a opção <guilabel
>Ecrã Completo</guilabel
> e depois carregue no botão <guibutton
>Nova Fotografia</guibutton
>. O &ksnapshot; irá agora capturar o ecrã inteiro quando carregar no botão <guibutton
>Nova Fotografia</guibutton
>.</para>

<para
>Da mesma forma, para tirar uma fotografia de uma região, seleccione o item da lista <guilabel
>Região</guilabel
> (a seguir ao texto <guilabel
>Modo de captura</guilabel
>) e configurar o <guilabel
>Atraso da fotografia</guilabel
> como <guilabel
>Sem atraso</guilabel
>, carregando então no botão <guibutton
>Nova Fotografia</guibutton
>. O cursor do rato irá então mudar para uma cruz, onde poderá usar o rato para seleccionar a região que deseja capturar. Para tirar a fotografia, carregue na tecla &Enter; ou então em &Esc; para sair.</para>

<para
>Para tirar uma nova fotografia de uma secção da janela, seleccione o item <guilabel
>Secção da Janela</guilabel
> da lista e carregue depois no botão <guibutton
>Nova Fotografia</guibutton
>. Com o <guilabel
>Sem atraso</guilabel
>, irá obter como cursor do rato uma vez, onde terá de carregar uma vez com o &LMB; na janela. A secção da janela, sob o cursor do rato, ficará realçada com um contorno vermelho. Mova o rato para a secção desejada e carregue no &LMB; para capturar a fotografia. </para>

<para
>Se tiver vários ecrãs, o <guilabel
>Ecrã Actual</guilabel
> captura o ecrã que contém o cursor do rato, na altura em que é retirada a captura.</para>
</sect1>

<sect1 id="additional-features">
<title
>Funcionalidades Adicionais</title>

<sect2 id="delay">
<title
>Atraso da Fotografia</title>

<para
>O campo de <guilabel
>Atraso da Fotografia</guilabel
> permite-lhe introduzir uma espera de tempo, em segundos, entre o momento em que pressiona o botão <guibutton
>Nova Fotografia</guibutton
> e o momento em que a imagem é capturada.</para>

<para
>Quando um tempo de espera é definido, não tem que carregar com o rato para capturar a imagem. Isto permite-lhe, por exemplo, abrir um menu, e capturar uma imagem dele.</para>

</sect2>

<sect2 id="window-decoration">
<title
>Excluir as Decorações das Janelas</title>

<para
><guilabel
>Incluir as decorações das janelas</guilabel
> está activo por omissão no modo <guilabel
>Janela Sob o Cursor</guilabel
>.</para>

<para
>Quando você só quiser capturar a aplicação em si sem a decoração envolvente da janela, desactive esta opção e tire uma nova fotografia.</para>

</sect2>
<!-- not in 4.1
<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
>Copiar para a Área de Transferência</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
>Botões</title>

<para
>Há ainda mais dois botões localizados no fundo da janela do &ksnapshot;. As suas funções estão descritas em baixo.</para>

<variablelist>
<varlistentry>
<term
><guibutton
>Ajuda</guibutton
></term>
<listitem
><para
>Aparece-lhe um menu onde você poderá abrir o <guimenuitem
>Manual do &ksnapshot;</guimenuitem
>, relatar um erro ou obter algumas informações <guimenuitem
>Acerca do &kde;</guimenuitem
> e <guimenuitem
>Acerca do &ksnapshot;</guimenuitem
>. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><guibutton
>Sair</guibutton
></term>
<listitem
><para
>Fecha a aplicação &ksnapshot;.</para
></listitem>
</varlistentry>
</variablelist>

</sect2>
</sect1>
</chapter>

<chapter id="dcop">

<title
>A Interface de &DBus;</title>

<para
>O &ksnapshot; poderá ser programado a partir da sua interface &DBus;.</para>

<para
>Existem duas formas de usar a interface de &DBus;: a &GUI; do &Qt; <application
>qdbusviewer</application
> e o utilitário da linha de comandos <application
>qdbus</application
>. </para>

<para
>Exemplos: <itemizedlist mark='opencircle'>

<listitem
><para
>O <prompt
>&percnt;</prompt
> <command
>qdbus</command
> irá mostrar todos os serviços disponíveis. </para
></listitem>

<listitem
><para
>O <prompt
>&percnt;</prompt
> <command
>qdbus</command
> <option
>org.kde.ksnapshot-`pidof -s ksnapshot`</option
> irá mostrar a interface &DBus; do &ksnapshot;. </para
></listitem>

<listitem
><para
>O <prompt
>&percnt;</prompt
> <command
>qdbus</command
> <option
>org.kde.ksnapshot-`pidof -s ksnapshot` /KSnapshot</option
> irá mostrar os métodos que controlam o &ksnapshot;. </para
></listitem>

</itemizedlist>
</para>

<para
>Para mais informações, vá por favor ao <ulink url="http://techbase.kde.org/Development/Tutorials/D-Bus/Introduction"
>tutorial sobre &DBus;</ulink
>. </para>

<!--
kdedev@rebutia:~/svn$ qdbus org.kde.ksnapshot-10484
/
/KDebug
/KSnapshot
/MainApplication
kdedev@rebutia:~/svn$ qdbus org.kde.ksnapshot-10484 /
method QString org.freedesktop.DBus.Introspectable.Introspect()

kdedev@rebutia:~/svn$ qdbus org.kde.ksnapshot-10484 /KSnapshot
method void org.kde.ksnapshot.slotGrab()
method void org.kde.ksnapshot.slotOpen(QString application)
method void org.kde.ksnapshot.slotSave()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()

kdedev@rebutia:~/svn$ qdbus org.kde.ksnapshot-10484 /MainApplication
method void org.kde.KApplication.quit()
method void org.kde.KApplication.reparseConfiguration()
method void org.kde.KApplication.updateUserTimestamp()
method void org.kde.KApplication.updateUserTimestamp(int time)
property readwrite int com.trolltech.Qt.QApplication.cursorFlashTime
property readwrite int com.trolltech.Qt.QApplication.doubleClickInterval
property readwrite QSize com.trolltech.Qt.QApplication.globalStrut
property readwrite int com.trolltech.Qt.QApplication.keyboardInputInterval
property readwrite bool com.trolltech.Qt.QApplication.quitOnLastWindowClosed
property readwrite int com.trolltech.Qt.QApplication.startDragDistance
property readwrite int com.trolltech.Qt.QApplication.startDragTime
property readwrite QString com.trolltech.Qt.QApplication.styleSheet
property readwrite int com.trolltech.Qt.QApplication.wheelScrollLines
property readwrite QString com.trolltech.Qt.QCoreApplication.applicationName
property readwrite QString com.trolltech.Qt.QCoreApplication.applicationVersion
property readwrite QString com.trolltech.Qt.QCoreApplication.organizationDomain
property readwrite QString com.trolltech.Qt.QCoreApplication.organizationName
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()

kdedev@rebutia:~/svn$ qdbus org.kde.ksnapshot-10484 /KDebug
method void org.kde.KDebug.notifyKDebugConfigChanged()
method void org.kde.KDebug.printBacktrace()
method QDBusVariant org.freedesktop.DBus.Properties.Get(QString interface_name, QString property_name)
method void org.freedesktop.DBus.Properties.Set(QString interface_name, QString property_name, QDBusVariant value)
method QString org.freedesktop.DBus.Introspectable.Introspect()
-->
<!-- dbus-launch ksnapshot-->
<!-- ksnapshot qdbus org.kde.ksnapshot-20985-->
<!--
<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
>Créditos e Licença</title>

<para
>Copyright do programa</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
>Documentação baseada no original, copyright 1997-2000 &Richard.J.Moore; &Richard.J.Moore.mail;</para>
<para
>Tradução de Nuno Donato <email
>nunodonato@iol.pt</email
></para
> 
&underFDL; &underGPL; </chapter>

&documentation.index;
</book>

<!--
Local Variables:
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->




