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

<book id="kremotecontrol" lang="&language;">
  <bookinfo>
    <title
>Configuração dos Controles Remotos 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
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus.gama@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
    </authorgroup>

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

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

    <abstract>
      <para
>Configuração do &kremotecontrol;: A infraestrutura da funcionalidade de controles remotos do &kde;. </para>
    </abstract>
    
    <keywordset>
      <keyword
>KRemoteControl</keyword>
      <keyword
>kcm_remotecontrol</keyword>
      <keyword
>Controle Remoto</keyword>
    </keywordset>

  </bookinfo>

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

    <para
>Este módulo permite-lhe configurar os seus controles remotos. Você poderá atribuir ações que serão executadas quando pressionar no botão. As açõ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;, você terá que configurar uma infraestrutura de controles remotos compatível no seu computador. Neste momento, só existe disponível uma infraestrutura para o LIRC. Se o LIRC estiver devidamente configurado, o ícone do &kremotecontrol; irá acender em vermelho <inlinemediaobject
> <imageobject
> <imagedata fileref="irkick.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. Caso contrário, aparecerá em cinza e tracejado <inlinemediaobject
> <imageobject
> <imagedata fileref="irkickoff.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. </para>

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

    </sect1>
  </chapter>

  <chapter id="usage">
    <title
>Uso</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 ações configuradas para o comando e modo selecionados no 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 ações configurados</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>

    <sect1 id="modes">
      <title
>Controles remotos e modos</title>

      <para
>Cada controle remoto pode ter um número diferente de modos. Ter modos múltiplos permite que os botões executem ações diferentes em situações diferentes. Pense nisso como um controle-remoto multi-função de uma TV/Video/Parabólica/DVD. Em vez de usar controles diferentes para os diversos aplicativos, você pode mudar o comportamento de um controle remoto para adaptá-lo ao aplicativo criando um modo diferente e alternando para ele quando necessário. As ações definidas diretamente para o controle remoto estarão sempre disponíveis, independente do modo que o controle esteja atualmente. Ações definidas em um modo somente são executadas se o controle estiver atualmente definido para aquele modo. Cada controle remoto somente pode estar em um determinado modo por vez. Ele pode também não estar em nenhum modo específico, o que significa que somente as ações sempre disponíveis serão executadas ao se pressionar um botão. Você pode também definir o modo padrão, que será o modo automaticamente atribuído na inicialização. </para>
      <para
>Você poderá adicionar modos a um controle remoto, selecionando o comando e usando o botão <guibutton
>+</guibutton
> ao lado da lista. Ao criar um modo, você terá que indicar um nome para ele. Opcionalmente, poderá atribuir um botão que será usado para ativar o modo, bem como um ícone a usar nas notificações deste modo. Você poderá apagar os modos, selecionando-os e usando o botão <guibutton
>-</guibutton
>. <screenshot>
        <screeninfo
>Adicionar modo</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar um novo modo</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Por padrã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, você 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. Você poderá definir este comportamento nas preferências de um dos comandos, selecionando-o na lista e pressionando o botão de edição. <screenshot>
        <screeninfo
>Editar o controle</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="EditMasterMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Editar um controle</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>

    </sect1>

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

      <para
>Depois de selecionar um controle ou um modo, você poderá adicionar ações a ele com o botão <guibutton
>+</guibutton
> à direita. Existem duas formas diferentes de criar ações: usando um modelo ou navegando no barramento de sessão do D-Bus manualmente. <screenshot>
        <screeninfo
>AddAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma ação</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>A criação das ações com os modelos é simples, mas limitada. Você 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
>Gerenciamento de energia</quote
> que contém modelos para encerrar ou suspender o seu computador. <screenshot>
        <screeninfo
>AddProfileAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddProfileAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma ação usando um modelo</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>A criação de ações, através da navegação pelo D-Bus, apresenta todas as aplicações atualmente em execução. Você 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 você poderá usar mais aplicações e funções diferentes das da lista de modelos. <screenshot>
        <screeninfo
>AddDBusAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddDBusAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Adicionar uma ação que use o D-Bus</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Ao adicionar uma ação, você poderá ajustar mais algumas opções. A primeira define se as ações são executadas de forma repetida, quando mantiver pressionado o botão do controle remoto. Este é um comportamento útil para algumas ações, como o aumento ou diminuição do volume, mas poderão ser indesejados para outras ações, como a pausa/continuação de uma música. A segunda define se a aplicação de destino deverá ser iniciada, caso ainda não esteja, quando pressionar o botão. A terceira e última define qual a instância que deverá receber a ação, caso exista mais que uma instância em execução. Se tiver selecionado uma aplicação que não possa ter várias instâncias em execução, esta opção está desativada. </para>
      <para>
        <screenshot>
        <screeninfo
>AddActionOptions</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddActionOptions.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Opções das ações</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>As açõ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 coleçõ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 pelo perfil em si. O verde significa que todos os modelos têm uma correspondência no seu controle, o amarelo significa que existe uma correspondência parcial e o vermelho corresponde à ausência total de correspondência aos botões do seu controle. Isto não significa que não poderá usar esses modelos. Simplesmente terá de configurá-los um a um, definido você mesmo o botão desejado. <screenshot>
        <screeninfo
>AutoPopulate</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AutoPopulate.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Gerar automaticamente as ações com os modelos</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
><emphasis role="strong"
>Nota:</emphasis
> Se o seu controle remoto não for compatível com nenhum perfil, você poderá não ter configurado o LIRC para usar os espaços de nomes. </para>
    </sect1>
  </chapter>
  <chapter id="advancedInformation">
    <title
>Informações avançadas</title>
    <para
>Este capítulo irá discutir mais algumas informações que poderão ser interessantes para usuários avançados ou programadores. Você irá aprender a criar os seus próprios perfis. </para>

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

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

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

          <step>
            <title
>&DBus;</title>
            <para
>Certifique-se de que a aplicação, para a qual deseja criar o perfil, oferece funções no barramento de sessão do &DBus;. Você poderá verificar isso se tentar adicionar açõ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 ótima 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;, você terá que descrevê-las num documento <filename
>aplicação.profile.xml</filename
>. Aqui está um guia rápido sobre como criar esses arquivos: </para>

            <substeps>
              <step>
                <para
>Crie primeiro um arquivo 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 atualizar 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;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 açõ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;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;Minha Ação&lt;/name&gt;
      &lt;description&gt;O que esta açã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. Ele será usado pelo &kremotecontrol; para corresponder as açõ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 arquivo 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 ação deverá ser executada várias vezes, caso o botão do comando seja mantido pressionado. Se a aplicação deverá ser iniciada quando pressionar um botão, caso não esteja ativa, 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 pressionar um botão. Você poderá usar os seguintes valores para esta propriedade: <quote
>sendtotop</quote
> (envia a chamada para a instância ativada no topo das janelas empilhadas), <quote
>sendtobottom</quote
> (envia a chamada para a instância abaixo de todas as outras janelas), <quote
>sendtoall</quote
> (envia para todas as instâncias), <quote
>dontsend</quote
> (não envia a açã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 padrã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;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;Minha Ação&lt;/name&gt;
      &lt;description&gt;O que esta açã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 argumentos, usando a marca <quote
>function</quote
>. Por exemplo <quote
>comutarPainel</quote
>. </para>
              </step>

              <step>
                <para
>Se a função tiver argumentos, você terá que descrever cada um deles, indicando uma descrição para o usuário, um tipo e, opcionalmente, um valor padrão. Você poderá encontrar uma lista com os tipos suportados no arquivo de esquema <quote
>profile.xsd</quote
>. A marca <quote
>comment</quote
> deverá conter uma descrição amigável sobre o objetivo do argumento. Deverá também declarar um valor padrã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;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;Minha Ação&lt;/name&gt;
      &lt;description&gt;O que é que esta açã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, você terá que copiá-lo para a pasta <filename
>$(kde_datadir)/profiles</filename
> e reiniciar o &kremotecontrol;. </para>
          <para
>Se você quiser contribuir o perfil para o &kde; SC, envie-o por favor para a equipe do 'kdeutils' em <email
>kde-utils-devel@kde.org</email
>. </para>
        </sect2>
    </sect1>
  </chapter>
</book>
