<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kremotecontrol "<application
>KRemoteControl</application
>">
  
  <!ENTITY % Portuguese "INCLUDE"
> <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book id="kremotecontrol" lang="&language;">
  <bookinfo>
    <title
>Configuração dos Comandos à Distância do KDE</title>

    <authorgroup>
      <author
><firstname
>Michael</firstname
> <surname
>Zanetti</surname
> <affiliation
> <address
><email
>michael_zanetti@gmx.net</email
></address>
        </affiliation>
      </author>
    <othercredit role="translator"
><firstname
>José</firstname
><surname
>Pires</surname
><affiliation
><address
><email
>zepires@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
    </authorgroup>

    <date
>2010-03-05</date>
    <releaseinfo
>1.0</releaseinfo>

    <copyright>
      <year
>2010</year>
      <holder
>Michael Zanetti</holder>
    </copyright>

    <abstract>
      <para
>Configuração do &kremotecontrol;: A infra-estrutura da funcionalidade de Comandos à Distância do &kde;. </para>
    </abstract>
    
    <keywordset>
      <keyword
>KRemoteControl</keyword>
      <keyword
>kcm_remotecontrol</keyword>
      <keyword
>Controlo Remoto</keyword>
    </keywordset>

  </bookinfo>

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

    <para
>Este módulo permite-lhe configurar os seus comandos à distância. Poderá atribuir acções que serão executadas quando carregar no botão. As acções poderão iniciar as aplicações, controlá-las ou executar comandos do sistema, como por exemplo encerrar o seu computador. </para>

    <sect1 id="requirements">
      <title
>Requisitos</title>

      <para
>Para usar o &kremotecontrol;, terá de configurar uma infra-estrutura de comandos à distância compatível no seu computador. Neste momento, só existe disponível uma infra-estrutura para o LIRC. Se o LIRC estiver devidamente configurado, o ícone do &kremotecontrol; irá acender a vermelho <inlinemediaobject
> <imageobject
> <imagedata fileref="irkick.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. Caso contrário, aparecerá a cinzento e traçado <inlinemediaobject
> <imageobject
> <imagedata fileref="irkickoff.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. </para>

      <para
>Para mais informações acerca do LIRC, vá à página Web respectiva em http://www.lirc.org. </para>

    </sect1>
  </chapter>

  <chapter id="usage">
    <title
>Utilização</title>

    <para
>O módulo de configuração consiste em duas listas. A lista da esquerda mostra os comandos disponíveis e os seus modos. A lista à direita mostra todas as acções configuradas para o comando e modo seleccionados de momento. <screenshot>
      <screeninfo
>Configuração do KRemoteControl</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="kcmremotecontrol.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase
>Listas dos comandos e dos modos e acções configurados</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>

    <sect1 id="modes">
      <title
>Comandos à Distância e Modos</title>

      <para
>Cada comando à distância poderá ter um conjunto de modos diferentes. O facto de ter vários modos permite que os botões executem acções diferentes para situações igualmente distintas. Pense nisto como um comando universal para a TV/vídeo/satélite, etc. Em vez de usar diferentes comandos para as diferentes aplicações, poderá mudar o comportamento de um dado comando de modo a que se adapte uma aplicação, criando modos distintos e mudando-os de acordo com as necessidades. As acções definidas directamente no comando à distância estão sempre disponíveis, independentemente do modo em que o comando se encontra actualmente. As acções definidas num modo só são executadas se o comando estiver configurado de momento par esse modo. Cada comando só poderá estar num dado modo de cada vez. Poderá também não estar em modo algum de todo, o que significa que só as acções sempre disponíveis é que serão executadas ao carregar num botão. Poderá também definir um modo predefinido, o qual será o modo atribuído automaticamente no arranque. </para>
      <para
>Poderá adicionar modos a um comando à distância, seleccionando o comando e usando o botão <guibutton
>+</guibutton
> ao lado da lista. Ao criar um modo, terá de indicar um nome para ele. Opcionalmente, poderá atribuir um botão que será usado para activar o modo, bem como um ícone a usar nas notificações deste modo. Poderá apagar os modos, seleccionando-os e usando o botão <guibutton
>-</guibutton
>. <screenshot>
        <screeninfo
>Adicionar um modo</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar um novo modo</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Por omissão, se existirem vários modos com o mesmo botão atribuído, este é usado para circular pelos vários modos. Desta forma, poderá agrupar os seus modos. Por exemplo, poderá atribuir um botão chamado <quote
>Música</quote
> para circular pelos modos do &amarok; e do &juk;, enquanto um botão <quote
>Vídeo</quote
> poderia circular pelos modos do &dragon; ou do KMplayer. Se preferir, por outro lado, ter um botão para circular por todos os modos, assim como um segundo para circular na ordem inversa pelos modos, poderá definir este comportamento nas preferências de um dos comandos, seleccionando-o na lista e carregando no botão de edição. <screenshot>
        <screeninfo
>Editar o Comando</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="EditMasterMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Editar um comando</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>

    </sect1>

    <sect1 id="actions">
      <title
>Acções</title>

      <para
>Depois de seleccionar um comando ou um modo, poderá adicionar acções a ele com o botão <guibutton
>+</guibutton
> à direita. Existem duas formas diferentes de criar acções: usando um modelo ou navegando no barramento de sessão do D-Bus manualmente. <screenshot>
        <screeninfo
>Adicionar uma Acção</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma acção</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>A criação das acções com os modelos é simples, mas limitada. Poderá encontrar modelos para as aplicações mais comuns, como o &amarok; ou o lançador de programas do &kde;, ou ainda para alguns comandos do sistema, como o encerramento do seu computador. Estes modelos estão recolhidos em perfis que os agrupam em tarefas semelhantes. Por exemplo, existe um perfil chamado  <quote
>Gestão de energia</quote
> que contém modelos para encerrar ou suspender o seu computador. <screenshot>
        <screeninfo
>Adicionar uma Acção do Perfil</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddProfileAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma acção com um modelo</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>A criação de acções, navegando para tal no D-Bus, apresenta todas as aplicações actualmente em execução. Poderá navegar em todas elas e nas suas funções. Isto necessita de uma compreensão básica de como funciona o D-Bus, mas poderá usar mais aplicações e funções diferentes das da lista de modelos. <screenshot>
        <screeninfo
>Adicionar uma Acção de D-Bus</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddDBusAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma acção que use o D-Bus</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Ao adicionar uma acção, poderá ajustar mais algumas opções. A primeira define se as acções são executadas de forma repetida, quando mantiver pressionado o botão do comando à distância. Este é um comportamento útil para algumas acções, como o aumento ou diminuição do volume, mas poderão ser indesejados para outras acções, como a pausa/continuação de uma música. A segunda define se a aplicação de destino deverá ser iniciada, caso não o esteja, quando carregar no botão. A terceira e última define qual a instância que deverá receber a acção, caso exista mais que uma instância em execução. Se tiver seleccionado uma aplicação que não possa ter várias instâncias em execução, esta opção está desactivada. </para>
      <para>
        <screenshot>
        <screeninfo
>Adicionar Opções à Acção</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddActionOptions.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Opções das acções</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>As acções também poderão ser preenchidas automaticamente com o botão do assistente. Isto significa que o &kremotecontrol; poderá tentar fazer uma correspondência dos botões às funções por si. A janela de preenchimento automático mostra todas as colecções de modelos disponíveis com uma bandeira. Dependendo da cor da bandeira, o seu comando poderá ser suportado por completo, parcialmente ou não suportado de todo pelo perfil em si. O verde significa que todos os modelos têm uma correspondência no seu comando, o amarelo significa que existe uma correspondência parcial e o vermelho corresponde à ausência total de correspondência aos botões do seu comando. Não significa que não poderá usar esses modelos. Simplesmente terá de os configurar um a um, definido você mesmo o botão desejado. <screenshot>
        <screeninfo
>Auto-Preencher</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AutoPopulate.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Gerar automaticamente as acções com os modelos</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
><emphasis role="strong"
>Nota:</emphasis
> Se o seu comando à distância não for compatível com nenhum perfil, poderá não ter configurado o LIRC para usar os espaços de nomes. </para>
    </sect1>
  </chapter>
  <chapter id="advancedInformation">
    <title
>Informação Avançada</title>
    <para
>Este capítulo irá discutir mais algumas informações que poderão ser interessantes para utilizadores avançados ou programadores. Irá aprender a criar os seus próprios perfis. </para>

    <sect1 id="profileCreation">
      <title
>Criar um Perfil</title>

      <sect2>
        <title
>Introdução</title>
        <para
>Poderá usar praticamente todas as aplicações com suporte para &DBus; no &kremotecontrol;, sem quaisquer outras acções. Contudo, para oferecer uma configuração amigável e para que a aplicação apareça na janela de preenchimento automático, poderá criar um perfil para ela. </para>
        <para
>Um perfil diz ao &kremotecontrol; (e ao utilizador!) o que é que as várias chamadas de &DBus; fazem. Essencialmente, é um tipo de documentação para as chamadas de &DBus;. Não tem de incluir todas as chamadas de &DBus; - apenas as que acha que os utilizadores poderão tirar algum benefício (normalmente chamadas de <quote
>ajuste da interface</quote
> em vez de chamadas de <quote
>recolha de informações</quote
>). </para>
      </sect2>

      <sect2>
        <title
>HowTo de Perfis</title>
        <procedure>

          <step>
            <title
>&DBus;</title>
            <para
>Certifique-se que a aplicação, para a qual deseja criar o perfil, oferece funções no barramento de sessão do &DBus;. Poderá verificar isso se tentar adicionar acções para essa aplicação, usando o método manual no &kremotecontrol;. O <quote
>qdbusviewer</quote
>, uma aplicação que vem com a sua instalação do Qt4, também é uma óptima ferramenta para descobrir as capacidades de &DBus; das aplicações. </para>
          </step>

          <step>
            <title
>Passo-a-passo</title>
            <para
>Assim que tenha descoberto as funções apropriadas de &DBus;, terá de as descrever num documento <filename
>aplicação.profile.xml</filename
>. Aqui está um guia rápido sobre como criar esses ficheiros: </para>

            <substeps>
              <step>
                <para
>Crie primeiro um ficheiro novo que contém os dados abaixo. A marca <quote
>name</quote
> define um nome curto e descritivo do perfil. Adicione uma descrição do perfil na marca <quote
>description</quote
>. Adicione também o seu nome na marca <quote
>author</quote
> e um número de versão na marca <quote
>version</quote
>. O número de versão é importante quando actualizar o seu perfil. O &kremotecontrol; irá usar o perfil com o maior número de versão, caso existam várias versões disponíveis no seu sistema. </para>
                <programlisting
>&lt;xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

    &lt;name&gt;O Meu Perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Eu&lt;/author&gt;
    &lt;description&gt;Alguma informação descritiva sobre o que o perfil faz&lt;/description&gt;
    &lt;action&gt;
        &lt;--  Esta marca será explicada no próximo passo --&gt;
    &lt;action&gt;

&lt;/profile&gt;
                </programlisting>
              </step>

              <step>
                <para
>Depois de ter criado o esqueleto do perfil, está na hora de adicionar alguns modelos de acções. </para>

                <programlisting
>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

    &lt;name&gt;O Meu Perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Eu&lt;/author&gt;
    &lt;description&gt;Alguma informação descritiva sobre o que o perfil faz&lt;/description&gt;

    &lt;action id="umIdUnico"  repeat="true|false" button="umBotao"&gt;
      &lt;name&gt;A Minha Acção&lt;/name&gt;
      &lt;description&gt;O que esta acção faz&lt;/description&gt;
      &lt;prototype&gt;
        &lt;-- Esta marca será explicada no passo seguinte --&gt;
      &lt;/prototype&gt;

      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;

&lt;/profile&gt;
                </programlisting>
               <para
>Defina primeiro um identificador único. Este será usado pelo &kremotecontrol; para corresponder as acções existentes ao modelo, por exemplo para ler a descrição. Este identificador deverá ser único em todo o perfil. O atributo <quote
>button</quote
> é usado para a função de preenchimento automático. Veja o ficheiro do esquema <quote
>profile.xsd</quote
> para obter uma lista completa de todos os nomes de botões disponíveis. O atributo <quote
>repeat</quote
> diz se a acção deverá ser executada várias vezes, caso o botão do comando seja mantido pressionado. Se a aplicação deverá ser iniciada quando carregar num botão, caso não esteja activa, configure o <quote
>autostart</quote
> como sendo 'true' (verdadeiro). Os atributos <quote
>button</quote
>, <quote
>repeat</quote
> e <quote
>autostart</quote
> são opcionais. Se o <quote
>repeat</quote
> e o <quote
>autostart</quote
> não estiverem definidos, serão ambos igual a <quote
>false</quote
> (falso). </para>
                 
               <para
>Adicione um nome curto à marca <quote
>name</quote
>, bem com uma descrição, usando a marca <quote
>description</quote
>. A propriedade <quote
>ifmulti</quote
> define o que o &kremotecontrol; deverá fazer, caso existam várias instâncias em execução, quando carregar num botão. Poderá usar os seguintes valores para esta propriedade: <quote
>sendtotop</quote
> (envia a chamada para a instância activada no topo das janelas empilhadas), <quote
>sendtobottom</quote
> (envia a chamada para a instância por baixo de todas as outras janelas), <quote
>sendtoall</quote
> (envia para todas as instâncias), <quote
>dontsend</quote
> (não envia a acção para nenhuma instância) e <quote
>unique</quote
> (Esta aplicação não permite a execução de várias instâncias). Se esta marca não estiver definida, o &kremotecontrol; assume que as aplicações não podem ser executadas várias vezes, sendo o valor por omissão igual a <quote
>unique</quote
>. </para>
              </step>

              <step>
                <para
>Depois, defina a função de &DBus; que deverá ser executada na marca <quote
>prototype</quote
>: </para>
                <programlisting
>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

    &lt;name&gt;O Meu Perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Eu&lt;/author&gt;
    &lt;description&gt;Alguma informação descritiva sobre o que o perfil faz&lt;/description&gt;

    &lt;action id="umIdUnico"  repeat="true|false" button="umBotao"&gt;
      &lt;name&gt;A Minha Acção&lt;/name&gt;
      &lt;description&gt;O que esta acção faz&lt;/description&gt;
      &lt;prototype&gt;
        &lt;serviceName&gt;org.exemplo.aplicacao&lt;/serviceName&gt;
        &lt;node&gt;Um/Nó&lt;/node&gt;
        &lt;function&gt;funcao&lt;/function&gt;
      &lt;/prototype&gt;

      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;

&lt;/profile&gt;
                </programlisting>
                <para
>O <quote
>servicename</quote
> contém o nome do serviço de &DBus; para a aplicação, &eg; <quote
>org.kde.plasma-desktop</quote
>. O <quote
>node</quote
> contém o nó respectivo de &DBus;, como por exemplo <quote
>Aplicação</quote
>. Adicione o nome da função, sem o valor de retorno nem os argumento, usando a marca <quote
>function</quote
>. Por exemplo <quote
>comutarPainel</quote
>. </para>
              </step>

              <step>
                <para
>Se a função tiver argumentos, terá de descrever cada um deles, indicando uma descrição para o utilizador, um tipo e, opcionalmente, um valor por omissão. Poderá encontrar uma lista com os tipos suportados no ficheiro de esquema <quote
>profile.xsd</quote
>. A marca <quote
>comment</quote
> deverá conter uma descrição amigável sobre o objectivo do argumento. Deverá também declarar um valor por omissão para cada argumento, dentro das marcas <quote
>default</quote
>. Lembre-se que os modelos que contêm um botão terão de indicar um valor por omissão para todos os argumentos, caso contrário a função de preenchimento automático irá produzir funções inválidas. </para>
      
                  <programlisting
>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

   &lt;name&gt;O Meu Perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Eu&lt;/author&gt;
    &lt;description&gt;Alguma informação descritiva sobre o que o perfil faz&lt;/description&gt;

    &lt;action id="umIdUnico"  repeat="true|false" button="umBotao"&gt;
      &lt;name&gt;A Minha Acção&lt;/name&gt;
      &lt;description&gt;O que é que esta acção faz&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.exemplo.aplicacao&lt;/serviceName&gt;
        &lt;node&gt;UmNó&lt;/node&gt;
        &lt;function&gt;funcao&lt;/function&gt;

        &lt;arguments&gt;
          &lt;argument type="QString"&gt;
            &lt;comment&gt;Comentário adicional&lt;/comment&gt;
            &lt;default&gt;umValor&lt;/default&gt;
          &lt;/argument&gt;
        &lt;/arguments&gt;

      &lt;/prototype&gt;

      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;

&lt;/profile&gt;
                  </programlisting>
              </step>
            </substeps>
          </step>
        </procedure>
      </sect2>
      <sect2>
        <title
>Instalação</title>
          <para
>Para testar e usar o perfil, terá de o copiar para a pasta <filename
>$(kde_datadir)/profiles</filename
> e reiniciar o &kremotecontrol;. </para>
          <para
>Se quiser contribuir o perfil para o &kde; SC, envie-o por favor para a equipa do 'kdeutils' em <email
>kde-utils-devel@kde.org</email
>. </para>
        </sect2>
    </sect1>
  </chapter>
</book>
