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

<book id="kremotecontrol" lang="&language;">
  <bookinfo>
    <title
>Configuración de mandos a distancia para 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
>Kira</firstname
><surname
>J. Fernández</surname
><affiliation
><address
><email
>kirajfdez@gmail.com</email
></address
></affiliation
><contrib
>Traductora</contrib
></othercredit
> 
    </authorgroup>

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

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

    <abstract>
      <para
>Configuración de &kremotecontrol;: la infraestructura de la funcionalidad de mando a distancia para &kde;. </para>
    </abstract>
    
    <keywordset>
      <keyword
>KRemoteControl</keyword>
      <keyword
>kcm_remotecontrol</keyword>
      <keyword
>Mando a distancia</keyword>
    </keywordset>

  </bookinfo>

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

    <para
>Este módulo le permite configurar sus mandos a distancia. Puede asignar acciones que se ejecutan al presionar cada botón. Las acciones pueden iniciar aplicaciones, controlarlas o ejecutar órdenes del sistema, como apagar su equipo. </para>

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

      <para
>Para usar &kremotecontrol; debe haber instalado un motor compatible para mandos a distancia en su equipo. Actualmente solo hay disponible un motor para LIRC. Si LIRC está correctamente instalado, el icono de &kremotecontrol; en la bandeja del sistema estará iluminado en rojo <inlinemediaobject
> <imageobject
> <imagedata fileref="irkick.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. Si no, estará en gris y tachado.<inlinemediaobject
> <imageobject
> <imagedata fileref="irkickoff.png" format="PNG"/> </imageobject
> </inlinemediaobject
>. </para>

      <para
>Para más información sobre LIRC, visite su página web en http://www.lirc.org. </para>

    </sect1>
  </chapter>

  <chapter id="usage">
    <title
>Uso</title>

    <para
>El módulo de configuración consiste en dos listas. La lista de la izquierda muestra los mandos a distancia disponibles y sus modos. La lista de la derecha muestra todas las acciones configuradas para los mandos a distancia seleccionados actualmente. <screenshot>
      <screeninfo
>Configuración de KRemoteControl</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="kcmremotecontrol.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase
>Lista de mandos a distancia y modos y acciones configurados.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>

    <sect1 id="modes">
      <title
>Mandos a distancia y modos</title>

      <para
>Cada mandoa distancia tiene varios modos diferentes. Tener múltiples modos permite que los botones ejecuten diferentes acciones en situaciones distintas. Piense en ellos como mandos a distancia múltiples para TV/video/satélite. En lugar de usar diferentes mandos a distancia para diferentes aplicaciones, usted puede cambiar el comportamiento de un mando a distancia para adaptarlo a una aplicación creando diferentes modos y alternando entre ellos cuando sea necesario. Las acciones definidas directamente en el mando a distancia están siempre disponibles, sin importar en qué modo está funcionando actualmente el mando. Cada mando a distancia puede estar funcionando en un solo modo a la vez. Puede no estar en ningún modo, significando que solo se ejecutarán las acciones siempre disponibles al apretar cada botón. También puede definir un modo por defecto, que es el que se le asignará de manera predeterminada al inicio. </para>
      <para
>Puede añadir modos a un mandoa distancia seleccionando el mando y usando el botón <guibutton
>+</guibutton
> situado junto a la lista. Cuando cree un modo, tendrá que proporcionarle un nombre. Opcionalmente, puede asignar un botón que se utilizará para activar el modo y un icono que se use para las notificaciones para este modo. Puede eliminar modos seleccionándolos y usando el botón <guibutton
>-</guibutton
>. <screenshot>
        <screeninfo
>Añadir modo</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Añadir un modo nuevo</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>De forma predeterminada, si existen múltiples modos con el mismo botón asignado, el botón se usará para cambiar de uno a otro, en secuencia. De esta forma, puede agrupar sus modos. Por ejemplo, podría asignar un botón llamado <quote
>Música</quote
> para recorrer los modos para &amarok; y &juk;, mientras que un botón llamado <quote
>Vídeo</quote
> podría recorrer los modos para &dragon; o KMplayer. Si prefiere tener un botón para recorrer todos los modos y un segundo botón para recorrerlos en orden inverso, puede configurar este comportamiento en las preferencias del mando seleccionándolo y apretando el botón de edición. <screenshot>
        <screeninfo
>EditRemote</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="EditMasterMode.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Editar un mando a distancia</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>

    </sect1>

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

      <para
>Después de seleccionar un mando o un modo, puede añadirle acciones usando el botón <guibutton
>+</guibutton
> a la derecha. Hay dos formas diferentes en las que se pueden crear acciones: usando una plantilla o explorando el bus de sesión D-Bus manualmente. <screenshot>
        <screeninfo
>AddAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Añadir una acción</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Crear acciones usando plantillas es más fácil, pero limitado. Puede encontrar plantillas para las aplicaciones más comunes, como &amarok; o el lanzador de programas de &kde;, y órdenes del sistema para apagar su equipo. Esas plantillas se recogen en perfiles, qu elas agrupan en tareas similares. Por ejemplo, hay un perfil llamado <quote
>Gestor de energía</quote
> que contiene plantillas para apagar o suspender el equipo. <screenshot>
        <screeninfo
>AddProfileAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddProfileAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Añadir una acción usando una plantilla</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Crear acciones explorando el D-Bus lista todas las aplicaciones que están actualmente en funcionamiento. Puede explorarlas junto con sus funciones. Esto requiere una comprensión básica de cómo funciona D-Bus, pero puede usar más aplicaciones y funciones que las que están en la lista de plantillas. <screenshot>
        <screeninfo
>AddDBusAction</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddDBusAction.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Añadir una acción usando D-Bus</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Cuando añada una acción, puede ajustar unas pocas acciones más. La primera de ellas define si la acción se ejecuta repetidamente cuando el botón del mando a distancia se mantiene pulsado. Este comportamiento es útil para acciones como aumentar o disminuir el volumen, pero puede no ser deseable para acciones como activar o desactivar la pausa en un reproductor multimedia. La segunda define si la aplicación objetivo debería iniciarse cuando se pulsa el botón, en caso de que aún no estuviera en marcha. Por ejemplo, no tendría sentido para acciones que debieran cerrar una aplicación para iniciarla. La tercera y última opción para las acciones es definir qué instancia de la aplicación debería recibir la acción, si hay más de una en marcha. Si ha seleccionado una aplicación que no puede iniciarse varias veces al mismo  tiempo, la opción estará deshabilitada. </para>
      <para>
        <screenshot>
        <screeninfo
>AddActionOptions</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AddActionOptions.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Opciones para las acciones</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
>Las acciones también pueden generarse automáticamente usando el botón del asistente. Esto significa que &kremotecontrol; puede intentar emparejar botones con funciones por usted. El diálogo de autogenerar muestra todas las colecciones de plantillas disponibles con una bandera. Dependiendo del color de la bandera, su mando a distancia estará totalmente, parcialmente o no admitido por ese perfil. El verde significa que todas las plantillas incluidas se pueden emparejar con su mando a distancia; el amarillo, que algunas de las acciones contenidas coinciden; y el rojo, que ninguna de las plantillas se pueden asociar a los botones de su mando. Esto no significa que no pueda usar esas plantillas. Solo tiene que configurarlas una por una, estableciendo el botón deseado usted mismo. <screenshot>
        <screeninfo
>AutoPopulate</screeninfo>
          <mediaobject>
            <imageobject>
              <imagedata fileref="AutoPopulate.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase
>Generar acciones automáticamente utilizando plantillas</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </para>
      <para
><emphasis role="strong"
>Nota:</emphasis
> Si su mando a distancia no es compatible con ningún perfil, puede que no haya configurado LIRC usando espacios de nombres. </para>
    </sect1>
  </chapter>
  <chapter id="advancedInformation">
    <title
>Información avanzada</title>
    <para
>Este capítulo tratará de una información que puede ser interesante para usuarios más avanzados o para desarrolladores. Usted aprenderá cómo crear sus propios perfiles. </para>

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

      <sect2>
        <title
>Introducción</title>
        <para
>Casi todas las aplicaciones compatibles con &DBus; se pueden usar con &kremotecontrol; sin ninguna acción posterior.Sin embargo, para proporcionar una configuración amigable para el usuario y dejar que la aplicación aparezca en el diálogo de autogenerar, puede que desee crear un perfil para ella. </para>
        <para
>Un perfil le dice a &kremotecontrol; (¡y al usuario!) qué hacen las diferentes llamadas a &DBus;. Esencialmente, es una especie de documentación para las llamadas a &DBus;. No tiene que incluir todas las llamadas a &DBus;, solo las que usted crea que más van a beneficiar a los usuarios finales (normalmente, llamadas al <quote
>ajuste de la interfaz</quote
> más que llamadas a la <quote
>recogida de información</quote
>). </para>
      </sect2>

      <sect2>
        <title
>Tutorial de perfiles</title>
        <procedure>

          <step>
            <title
>&DBus;</title>
            <para
>Asegúrese de que la aplicación para la que quiere crear el perfil proporciona funciones para el bus de sesión de &DBus;. Puede comprobarlo intentando añadir acciones para esa aplicación usando el método manual en &kremotecontrol;. <quote
>qdbusviewer</quote
>, una aplicación que se envía con su instalación de Qt4, también es muy buena herramienta para averiguar las capacidades de aplicaciones de &DBus;. </para>
          </step>

          <step>
            <title
>Paso a paso</title>
            <para
>Una vez haya encontrado las funciones apropiadas de &DBus;, necesitará describirlas en un documento <filename
>appname.profile.xml</filename
>. Aquí tiene una guía rápida de cómo crear esos archivos: </para>

            <substeps>
              <step>
                <para
>Primero cree un archivo nuevo que incluya el contenido de abajo. La etiqueta <quote
>name</quote
> define un nombre corto descriptivo del perfil. Añada una descripción del perfil en la etiqueta <quote
>description</quote
>. Añada también su nombre en la etiqueta <quote
>author</quote
>, y un número de versión en la etiqueta <quote
>version</quote
>. El número de versión es importante para actualizar su perfil. &kremotecontrol; usará el que tenga el número más alto si encuentra múltiples versiones de su 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;Mi perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Yo&lt;/author&gt;
    &lt;description&gt;Alguna información descriptiva de lo que hace el perfil&lt;/description&gt;
    &lt;action&gt;
        &lt;--  Esta etiqueta se explicará en el siguiente paso--&gt;
    &lt;action&gt;

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

              <step>
                <para
>Después de que haya creado el esqueleto del perfil, es hora de añadir algunas plantillas de acción. </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;Mi perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Yo&lt;/author&gt;
    &lt;description&gt;Alguna información descriptiva de lo que hace el perfil&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;Mi acción&lt;/name&gt;
      &lt;description&gt;Lo que hace esta acción&lt;/description&gt;
      &lt;prototype&gt;
        &lt;--  Esta etiqueta se explicará en el siguiente paso--&gt;
      &lt;prototype&gt;
      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;
    
&lt;/profile&gt;
                </programlisting>
               <para
>Primero defina un identificador único. Esto será utilizado por &kremotecontrol; para emparejar acciones existentes a la plantilla, por ejemplo para leer la descripción. Este idenficador debe ser único en todo el perfil. el atributo de <quote
>button</quote
> se usa para la función de autogenerar. Mire el esquema de <quote
>profile.xsd</quote
> para una lista completa de los nombres de botón disponibles. El atributo <quote
>repeat</quote
> dice si la acción debe ser ejecutada múltiples veces si el botón del mando a distancia se mantiene pulsado. Si la aplicación debe comenzar si no está ya en marcha cuando se pulse un botón, establezca <quote
>autostart</quote
> a <quote
>true</quote
>. Los atributos <quote
>button</quote
>, <quote
>repeat </quote
> y <quote
>autostart</quote
> son opcionales. Si <quote
>repeat </quote
> y <quote
>autostart</quote
> no están definidos, se establecerán por omisión en <quote
>false</quote
>. </para>
                 
               <para
>Añada un nombre corto a la etiqueta <quote
>name</quote
> y una descripción, usando la etiqueta <quote
>description</quote
>. La propiedad <quote
>ifmulti </quote
> especifica qué debería hacer &kremotecontrol; si hay múltiples instancias del programa en marcha cuando se aprieta un botón. Puede usar los siguientes valores para esta propiedad: <quote
>sendtotop</quote
> (envía la llamada a la instancia situada en la parte superior de la pila de ventanas), <quote
>sendtobottom</quote
> (envía la llamada a la instancia situada en la parte inferior de la pila de ventanas), <quote
>sendtoall</quote
> (la envía a todas las instancias), <quote
>dontsend</quote
> (no envía la acción a ninguna instancia) y <quote
>unique</quote
> (esta aplicación no permite múltiples instancias). Si esta etiqueta no está definida, &kremotecontrol; supone que las aplicaciones no pueden funcionar varias veces a la vez, haciendo que esta etiqueta funcione por omisión como <quote
>unique</quote
>. </para>
              </step>

              <step>
                <para
>Después, defina la función de &DBus; que debe ejecutarse en la 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;Mi perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Yo&lt;/author&gt;
    &lt;description&gt;Información descriptiva sobre lo que hace el perfil&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;Mi acción&lt;/name&gt;
      &lt;description&gt;Lo que hace esta acción&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.example.application&lt;/serviceName&gt;
        &lt;node&gt;Some/Node&lt;/node&gt;
        &lt;function&gt;function&lt;/function&gt;
      &lt;/prototype&gt;

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

&lt;/profile&gt;
                </programlisting>
                <para
><quote
>servicename</quote
> contiene el nombre de servicio de &DBus; para la aplicación; &eg; <quote
>org.kde.plasma-desktop</quote
>. <quote
>node</quote
> contiene el nodo de &DBus; respectivo, como <quote
>App</quote
>. Añada el nombre de la función sin valor de retorno y argumentos usando la etiqueta <quote
>function</quote
>. Por ejemplo, <quote
>toggleDashboard</quote
>. </para>
              </step>

              <step>
                <para
>Si la función tiene argumentos, necesitará describir cada uno de ellos proporcionando una descripción para el usuario, un tipo y, opcionalmente, un valor predeterminado. Se puede encontrar una lista de tipos admitidos en el archivo de esquema <quote
>profile.xsd</quote
>. La etiqueta <quote
>comment</quote
> debería contener una buena descripción amigable para el usuario sobre para qué se usa el argumento. También debería declarar un valor predeterminado para cada argumento entre las etiquetas <quote
>default</quote
>. Tenga en cuenta que las plantillas que contienen un botón necesitan suministrar un valor predeterminado para todos los argumentos, o la función de autogenerar producirá funciones defectuosas. </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;Mi perfil&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Yo&lt;/author&gt;
    &lt;description&gt;Información descriptiva sobre lo que hace la plantilla&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;Mi acción&lt;/name&gt;
      &lt;description&gt;Lo que hace esta acción&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.example.application&lt;/serviceName&gt;
        &lt;node&gt;SomeNode&lt;/node&gt;
        &lt;function&gt;función&lt;/function&gt;

        &lt;arguments&gt;
          &lt;argument type="QString"&gt;
            &lt;comment&gt;Comentarios adicionales&lt;/comment&gt;
            &lt;default&gt;someValue&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
>Instalación</title>
          <para
>Para probar y usar el perfil, necesita copiarlo en <filename
>$(kde_datadir)/profiles</filename
> y reiniciar &kremotecontrol;. </para>
          <para
>Si desea contribuir con el perfil a &kde; SC, por favor envíelo al equipo de kdeutils a <email
>kde-utils-devel@kde.org</email
>. </para>
        </sect2>
    </sect1>
  </chapter>
</book>
