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

<book id="kremotecontrol" lang="&language;">
  <bookinfo>
    <title
>Configuració del comandament a distància al KDE</title>

    <authorgroup>
      <author
><firstname
>Michael</firstname
> <surname
>Zanetti</surname
> <affiliation
> <address
><email
>michael_zanetti@gmx.net</email
></address>
        </affiliation>
      </author>
    &traductor.Antoni.Bella; 
    </authorgroup>

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

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

    <abstract>
      <para
>Configuració de &kremotecontrol;: La infraestructura per a la funcionalitat del comandament a distància per a &kde;. </para>
    </abstract>
    
    <keywordset>
      <keyword
>KRemoteControl</keyword>
      <keyword
>kcm_remotecontrol</keyword>
      <keyword
>Comandament a distància</keyword>
    </keywordset>

  </bookinfo>

  <chapter id="introduction">
    <title
>Introducció</title>

    <para
>Aquest mòdul us permet configurar els comandaments a distància. Podeu assignar accions que s'executaran en prémer cada botó. Les accions poden iniciar aplicacions, controlar-les o executar ordres del sistema, com apagar l'ordinador. </para>

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

      <para
>Per usar &kremotecontrol; haureu de tenir instal·lat un dorsal compatible per a comandaments a distància. Actualment només n'hi ha disponible un per a LIRC. Si LIRC està correctament instal·lat, la icona de &kremotecontrol; a la safata del sistema estarà il·luminada en vermell <inlinemediaobject
> <imageobject
> <imagedata fileref="irkick.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. Si no, estarà en gris i tatxada.<inlinemediaobject
> <imageobject
> <imagedata fileref="irkickoff.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. </para>

      <para
>Per a més informació sobre LIRC, visiteu la seva pàgina web a http://www.lirc.org. </para>

    </sect1>
  </chapter>

  <chapter id="usage">
    <title
>Ús</title>

    <para
>El mòdul de configuració consisteix en dues llistes. La llista de l'esquerra mostra els comandaments a distància disponibles i els seus modes. La llista de la dreta mostra totes les accions configurades per als comandaments a distància seleccionats actualment. <screenshot>
      <screeninfo
>Configuració de KRemoteControl</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="kcmremotecontrol.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase
>Llista de comandaments a distància i els modes i accions configurats.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>

    <sect1 id="modes">
      <title
>Comandaments a distància i modes</title>

      <para
>Cada comandament a distància disposa de diversos modes diferents. El tenir múltiples modes permet que els botons executin diferents acciones en situacions diferents. Penseu en ells com a comandaments a distància multi-propòsit per a TV/Vídeo/Satèl·lit/DVD. En comptes d'usar diferents comandaments a distància per a diferents aplicacions, podeu canviar el comportament d'un comandament a distància per adaptar-lo a una aplicació creant diferents modes i alternant entre ells quan sigui necessari. Les accions definides directament en el comandament a distància sempre estaran disponibles, sense importar en quin mode està funcionant actualment el comandament. Cada comandament a distància pot estar funcionant en un únic mode a la vegada. Podeu no estar en cap mode, significant que només s'executaran les accions sempre disponibles en prémer cada botó. També podeu definir un mode per omissió, que serà el que se li assignarà de manera predeterminada a l'inici. </para>
      <para
>Podeu afegir modes a un comandament a distància seleccionant el comandament i utilitzant el botó <guibutton
>+</guibutton
> situat al costat de la llista. Quan creeu un mode, haureu de proporcionar-li un nom. Opcionalment, li podeu assignar un botó que s'utilitzarà per activar el modo i una icona que s'utilitzarà per a les notificacions per aquest mode. Podeu eliminar modes seleccionant-los i utilitzant el botó <guibutton
>-</guibutton
>. <screenshot>
        <screeninfo
>Afegeix mode</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Afegeix un nou mode</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Per omissió, si existeixen múltiples modes amb el mateix botó assignat, el botó s'utilitzarà per a canviar d'un a altre, en seqüència. D'aquesta manera, podeu agrupar els modes. Per exemple, podríeu assignar un botó anomenat <quote
>Música</quote
> per a recórrer els modes per a &amarok; i &juk;, mentre que un botó anomenat <quote
>Vídeo</quote
> podria recórrer als modes per a &dragon; o KMplayer. Si preferiu tenir un botó per a recórrer tots els modes i un segon per a fer-ho en ordre invers, podeu configurar aquest comportament en les preferències del comandament seleccionant-lo i prement el botó d'edició. <screenshot>
        <screeninfo
>EditRemote</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="EditMasterMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Editar un comandament a distància</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>

    </sect1>

    <sect1 id="actions">
      <title
>Accions</title>

      <para
>Després de seleccionar un comandament o un mode, li podeu afegir accions utilitzant el botó <guibutton
>+</guibutton
> a la dreta. Hi ha dues formes diferents en les que es poden crear accions. Utilitzant una plantilla o explorant el bus de sessió D-Bus manualment. <screenshot>
        <screeninfo
>AddAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Afegir una acció</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>El crear accions utilitzant plantilles és més fàcil, però limitat. Podeu trobar plantilles per a les aplicacions més comuns, com &amarok; o el llançador de programes de &kde;, i ordres del sistema per apagar l'ordinador. Aquestes plantilles es recullen en perfils, que les agrupen en tasques similars. Per exemple, hi ha un perfil anomenat <quote
>Gestor d'energia</quote
> que conté plantilles per apagar o suspendre l'ordinador. <screenshot>
        <screeninfo
>AddProfileAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddProfileAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Afegir una acció utilitzant una plantilla</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>El crear accions explorant el D-Bus llista totes les aplicacions que estan actualment en funcionament. Podeu explorar-les junt amb les seves funcions. Això requereix una comprensió bàsica de com funciona D-Bus, però podeu utilitzar més aplicacions i funcions de les que hi ha a la llista de plantilles. <screenshot>
        <screeninfo
>AddDBusAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddDBusAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Afegir una acció utilitzant D-Bus</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Quan s'afegeix una acció, podeu ajustar unes poques opcions més. La primera defineix si l'acció s'executarà repetidament quan es manté premut el botó del comandament a distància. Aquest comportament és útil per accions com augmentar o disminuir el volum, però pot no ser desitjable per accions com reprodueix/pausa en un reproductor multimèdia. La segona defineix si l'aplicació de destinació hauria d'iniciar-se quan es prem el botó, en el cas que encara no estigués en funcionament. Per exemple, no tindria sentit per accions que haurien de tancar una aplicació per iniciar-la. La tercera i última opció per a les accions defineix quina instància de l'aplicació ha de rebre l'acció, si n'hi ha més d'una en funcionament. Si heu seleccionat una aplicació que no es pot iniciar múltiples vegades alhora, l'opció restarà deshabilitada. </para>
      <para>
        <screenshot>
        <screeninfo
>AddActionOptions</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddActionOptions.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Opcions per a les accions</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Les accions també es poden generar automàticament utilitzant el botó de l'assistent. Això significa que &kremotecontrol; pot intentar emparellar botons amb funcions. El diàleg d'auto-genera mostra totes les col·leccions de plantilles disponibles amb una bandera. Depenent del color de la bandera, el vostre comandament a distància estarà totalment, parcialment o no admès per aquest perfil. El verd significa que totes les plantilles incloses es poden emparellar amb el comandament a distància; el groc, que algunes de les accions coincideixen; i el vermell, que cap de les plantilles es pot associar als botons del comandament. Això no significa que no les podeu utilitzar. Només que les haureu de configurar una per una, establint el botó desitjat. <screenshot>
        <screeninfo
>AutoPopulate</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AutoPopulate.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Generar accions automàticament utilitzant plantilles</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
><emphasis role="strong"
>Nota:</emphasis
> Si el comandament a distància no és compatible amb cap perfil, potser no heu configurat LIRC utilitzant espais de nom. </para>
    </sect1>
  </chapter>
  <chapter id="advancedInformation">
    <title
>Informació avançada</title>
    <para
>Aquest capítol tractarà alguna informació que pot ser interessant per a usuaris més avançats o per a desenvolupadors. Aprendreu com crear els vostres propis perfils. </para>

    <sect1 id="profileCreation">
      <title
>Crear un perfil</title>

      <sect2>
        <title
>Introducció</title>
        <para
>Gairebé totes les aplicacions compatibles amb &DBus; es poden utilitzar amb &kremotecontrol; sense cap acció posterior. De tota manera, per a proporcionar una configuració amigable per a l'usuari i deixar que l'aplicació aparegui en el diàleg d'auto-generar, potser voldreu crear un perfil. </para>
        <para
>Un perfil li indica a &kremotecontrol; (i a l'usuari!) què fan les diferents crides de &DBus;. Essencialment, és una espècie de documentació per a les crides de &DBus;. No les haureu d'incloure totes, només les que creieu que beneficiaran més als usuaris finals (normalment, crides a l'<quote
>ajustament de la interfície</quote
> més que no pas les crides a la <quote
>recollida d'informació</quote
>). </para>
      </sect2>

      <sect2>
        <title
>Com es fa per als perfils</title>
        <procedure>

          <step>
            <title
>&DBus;</title>
            <para
>Assegureu-vos que l'aplicació per a la que voleu crear el perfil proporciona funcions per al bus de sessió de &DBus;. Ho podeu comprovar intentant afegir accions per a aquesta aplicació utilitzant el mètode manual en &kremotecontrol;. <quote
>qdbusviewer</quote
>, una aplicació que ve amb la vostra instal·lació de Qt4, també es molt bona eina per esbrinar les capacitats &DBus; de les aplicacions. </para>
          </step>

          <step>
            <title
>Pas a pas</title>
            <para
>Una vegada trobades les funcions apropiades de &DBus;, necessitareu descriure-les en un document <filename
>nom_aplicació.profile.xml</filename
>. Aquí teniu una guia ràpida de com crear aquests fitxers: </para>

            <substeps>
              <step>
                <para
>Primer creeu un nou fitxer que inclogui el contingut de a sota. L'etiqueta <quote
>name</quote
> defineix un nom curt descriptiu del perfil. Afegiu-li una descripció en l'etiqueta <quote
>description</quote
>. Afegiu també el vostre nombre en l'etiqueta <quote
>author</quote
>, i un número de versió en l'etiqueta <quote
>version</quote
>. El número de versió és important per actualitzar el perfil. &kremotecontrol; usarà el que tingui el número més alt si troba múltiples versions d'aquest perfil en el 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;El meu perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Jo&lt;/author&gt;
    &lt;description&gt;Alguna informació descriptiva quant al que fa el perfil&lt;/description&gt;
    &lt;action&gt;
        &lt;--  Aquesta etiqueta s'explica en el següent pas. --&gt;
    &lt;action&gt;

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

              <step>
                <para
>Una vegada creat l'esquelet del perfil, és hora d'afegir algunes plantilles d'acció. </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;El meu perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Jo&lt;/author&gt;
    &lt;description&gt;Alguna informació descriptiva quant al que fa el perfil&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;La meva acció&lt;/name&gt;
      &lt;description&gt;Què és el que fa aquesta acció&lt;/description&gt;
      &lt;prototype&gt;
        &lt;--  Aquesta etiqueta s'explica en el següent pas. --&gt;
      &lt;prototype&gt;
      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;
    
&lt;/profile&gt;
                </programlisting>
               <para
>Primer definiu un identificador únic. Aquest l'utilitzarà &kremotecontrol; per emparellar accions existents a la plantilla, per exemple, per a llegir la descripció. Aquest identificador haurà de ser únic en tot el perfil. L'atribut de <quote
>button</quote
> s'utilitza per a la funció d'auto-generar. Mireu l'esquema de <quote
>profile.xsd</quote
> per a una llista completa dels noms de botó disponibles. L'atribut <quote
>repeat</quote
> indica si l'acció s'ha d'executar múltiples vegades si el botó del comandament a distància es manté premut. Si l'aplicació s'ha d'iniciar si no està funcionant quan premeu un botó, establiu <quote
>autostart</quote
> a <quote
>true</quote
>. Els atributs <quote
>button</quote
>, <quote
>repeat </quote
> i <quote
>autostart</quote
> són opcionals. Si <quote
>repeat </quote
> i <quote
>autostart</quote
> no estan definits, s'establiran per omissió a <quote
>false</quote
>. </para>
                 
               <para
>Afegiu un nom curt a l'etiqueta <quote
>name</quote
> i una descripció, utilitzant l'etiqueta <quote
>description</quote
>. La propietat <quote
>ifmulti</quote
> especifica què hauria de fer &kremotecontrol; si hi ha múltiples instàncies del programa en funcionament quan es prem un botó. Podeu utilitzar els següents valors per a aquesta propietat: <quote
>sendtotop</quote
> (envia la crida a la instància situada a la part superior de la pila de finestres), <quote
>sendtobottom</quote
> (envia la crida a la instància situada a la part inferior de la pila de finestres), <quote
>sendtoall</quote
> (l'envia a totes les instàncies), <quote
>dontsend</quote
> (no envia l'acció a cap instància) i <quote
>unique</quote
> (aquesta aplicació no permet múltiples instàncies). Si aquesta etiqueta no està definida, &kremotecontrol; suposa que les aplicacions no es poden executar múltiples vegades alhora, creant per omissió aquesta etiqueta. </para>
              </step>

              <step>
                <para
>Després, definiu la funció de &DBus; que s'ha d'executar en l'etiqueta <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;El meu perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Jo&lt;/author&gt;
    &lt;description&gt;Alguna informació descriptiva quant al que fa el perfil&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;La neva acció&lt;/name&gt;
      &lt;description&gt;Què és el que fa aquesta acció&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.exemple.aplicació&lt;/serviceName&gt;
        &lt;node&gt;Algun/Node&lt;/node&gt;
        &lt;function&gt;funció&lt;/function&gt;
      &lt;/prototype&gt;

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

&lt;/profile&gt;
                </programlisting>
                <para
><quote
>servicename</quote
> conté el nom del servei de &DBus; per a l'aplicació; &ead; <quote
>org.kde.plasma-desktop</quote
>. <quote
>node</quote
> conté el node de &DBus; respectiu, com <quote
>App</quote
>. Afegiu el nom de la funció sense valor de retorn i arguments utilitzant l'etiqueta <quote
>function</quote
>. Per exemple, <quote
>toggleDashboard</quote
>. </para>
              </step>

              <step>
                <para
>Si la funció té arguments, necessitareu descriure cadascun proporcionant una descripció per a l'usuari, un tipus i, opcionalment, un valor per omissió. Es pot trobar una llista de tipus admesos en el fitxer d'esquema <quote
>profile.xsd</quote
>. L'etiqueta <quote
>comment</quote
> hauria de contenir una bona descripció amigable per a l'usuari sobre per a què s'usa l'argument. També hauríeu de declarar un valor per omissió per a cada argument entre les etiquetes <quote
>default</quote
>. Tingueu en compte que les plantilles que contenen un botó necessiten subministrar un valor per omissió per a tots els arguments, o la funció d'auto-generar presentarà funcions defectuoses. </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;El meu perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Jo&lt;/author&gt;
    &lt;description&gt;Alguna informació descriptiva quant al que fa el perfil&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;La meva acció&lt;/name&gt;
      &lt;description&gt;Què és el que fa aquesta acció&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.exemple.aplicació&lt;/serviceName&gt;
        &lt;node&gt;AlgunNode&lt;/node&gt;
        &lt;function&gt;funció&lt;/function&gt;

        &lt;arguments&gt;
          &lt;argument type="QString"&gt;
            &lt;comment&gt;Comentari addicional&lt;/comment&gt;
            &lt;default&gt;algunValor&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
>Instal·lació</title>
          <para
>Per a provar i usar el perfil, necessitareu copiar-lo a <filename
>$(kde_datadir)/profiles</filename
> i reiniciar &kremotecontrol;. </para>
          <para
>Si voleu contribuir amb el perfil a &kde; SC, si us plau, envieu-lo a l'equip de kdeutils a <email
>kde-utils-devel@kde.org</email
>. </para>
        </sect2>
    </sect1>
  </chapter>
</book>
