# Configuração dos Comandos à Distância do KDE

## Introdução

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.

### Requisitos

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 . Caso contrário, aparecerá a cinzento e traçado .

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

## Utilização

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. Configuração do KRemoteControl Listas dos comandos e dos modos e acções configurados

### Comandos à Distância e Modos

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.

Poderá adicionar modos a um comando à distância, seleccionando o comando e usando o botão + 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 -. Adicionar um modo Adicionar um novo modo

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 Música para circular pelos modos do &amarok; e do &juk;, enquanto um botão Vídeo 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. Editar o Comando Editar um comando

### Acções

Depois de seleccionar um comando ou um modo, poderá adicionar acções a ele com o botão + à direita. Existem duas formas diferentes de criar acções: usando um modelo ou navegando no barramento de sessão do D-Bus manualmente. Adicionar uma Acção Adicionar uma acção

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 Gestão de energia que contém modelos para encerrar ou suspender o seu computador. Adicionar uma Acção do Perfil Adicionar uma acção com um modelo

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. Adicionar uma Acção de D-Bus Adicionar uma acção que use o D-Bus

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.

Adicionar Opções à Acção Opções das acções

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. Auto-Preencher Gerar automaticamente as acções com os modelos

Nota: 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.

## Informação Avançada

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.

### Criar um Perfil

#### Introdução

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.

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 ajuste da interface em vez de chamadas de recolha de informações).

#### HowTo de Perfis

1. #### &DBus;

   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 qdbusviewer, 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.

2. #### Passo-a-passo

   Assim que tenha descoberto as funções apropriadas de &DBus;, terá de as descrever num documento `aplicação.profile.xml`. Aqui está um guia rápido sobre como criar esses ficheiros:

   1. Crie primeiro um ficheiro novo que contém os dados abaixo. A marca name define um nome curto e descritivo do perfil. Adicione uma descrição do perfil na marca description. Adicione também o seu nome na marca author e um número de versão na marca version. 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.

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

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

          </profile>

   2. Depois de ter criado o esqueleto do perfil, está na hora de adicionar alguns modelos de acções.

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

              <name>O Meu Perfil</name>
              <version>0.1</version>
              <author>Eu</author>
              <description>Alguma informação descritiva sobre o que o perfil faz</description>

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

                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

      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 button é usado para a função de preenchimento automático. Veja o ficheiro do esquema profile.xsd para obter uma lista completa de todos os nomes de botões disponíveis. O atributo repeat 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 autostart como sendo 'true' (verdadeiro). Os atributos button, repeat e autostart são opcionais. Se o repeat e o autostart não estiverem definidos, serão ambos igual a false (falso).

      Adicione um nome curto à marca name, bem com uma descrição, usando a marca description. A propriedade ifmulti 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: sendtotop (envia a chamada para a instância activada no topo das janelas empilhadas), sendtobottom (envia a chamada para a instância por baixo de todas as outras janelas), sendtoall (envia para todas as instâncias), dontsend (não envia a acção para nenhuma instância) e unique (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 unique.

   3. Depois, defina a função de &DBus; que deverá ser executada na marca prototype:

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

              <name>O Meu Perfil</name>
              <version>0.1</version>
              <author>Eu</author>
              <description>Alguma informação descritiva sobre o que o perfil faz</description>

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

                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

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

   4. 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 profile.xsd. A marca comment 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 default. 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.

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

             <name>O Meu Perfil</name>
              <version>0.1</version>
              <author>Eu</author>
              <description>Alguma informação descritiva sobre o que o perfil faz</description>

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

                <prototype>
                  <serviceName>org.exemplo.aplicacao</serviceName>
                  <node>UmNó</node>
                  <function>funcao</function>

                  <arguments>
                    <argument type="QString">
                      <comment>Comentário adicional</comment>
                      <default>umValor</default>
                    </argument>
                  </arguments>

                </prototype>

                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

#### Instalação

Para testar e usar o perfil, terá de o copiar para a pasta `$(kde_datadir)/profiles` e reiniciar o &kremotecontrol;.

Se quiser contribuir o perfil para o &kde; SC, envie-o por favor para a equipa do 'kdeutils' em kde-utils-devel@kde.org.