<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="tooltip.py" xml:lang="es">
  <info>
  <title type="text">MenuButton</title>
    <link type="guide" xref="beginner.py#misc"/>
    <link type="seealso" xref="toolbar.py"/>
    <revision version="0.1" date="2012-08-20" status="draft"/>

    <credit type="author copyright">
      <name>Marta Maria Casetti</name>
      <email>mmcasetti@gmail.com</email>
      <years>2012</years>
    </credit>

    <desc>Añadir consejos a sus widgets</desc>
  </info>

  <title>Consejo</title>
  <media type="image" mime="image/png" src="media/tooltip.png"/>
  <p>Una barra de herramientas con un consejo (con una imagen) para un botón.</p>

  <links type="section"/>
    
  <section id="code">
  <title>Código usado para generar este ejemplo</title>
    <code mime="text/x-csharp" style="numbered"><xi:include href="samples/tooltip.py" parse="text"><xi:fallback/></xi:include></code>
  </section>

  <section id="methods">
  <title>Métodos útiles para un widget de consejo</title>
    <p><code>set_tooltip_text(text)</code> y <code>set_tooltip_markup(text)</code> pueden usarse para añadir un consejo o texto plano (o texto en el lenguaje de marcado de Pango) a un widget.</p>
    <p>Para consejos más complejos, por ejemplo para un consejo con una imagen:</p>
    <steps>
      <item><p>Establezca la propiedad <code>"has-tooltip"</code> del widget a <code>True</code>; esto hará que GTK+ monitorice el widget en busca de movimiento y eventos relacionados que se necesitan para determinar cuándo y dónde mostrar un consejo.</p></item>
      <item><p>Conecte a la señal <code>"query-tooltip"</code>. Esta señal se emitirá cuando se deba mostrar un widget. Uno de los argumentos que se le pasan al manejador de señales es un objeto GtkTooltip. Este es el objeto que se va a mostrar como un consejo, y puede manipularse en su retorno de llamada usando funciones como <code>set_icon()</code>. Hay funciones para establecer el texto marcado del consejo (<code>set_markup(text)</code>), una imagen desde un icono del almacén (<code>set_icon_from_stock(stock_id, size)</code>), o incluso poner un widget personalizado (<code>set_custom(widget)</code>).</p></item>
      <item><p>Devuelva <code>True</code> de su manejador de «query-tooltip». Esto hace que el consejo se muestre. Si devuelve <code>False</code>, no se mostrará.</p></item>
    </steps>

    <p>En el probablemente raro caso en el que quiera tener aún más control sobre el consejo que se va a mostrar, puede establecer su propia GtkWindow que se usará como ventana del consejo. Esto funciona así:</p>
    <steps>
      <item><p>Establezca <code>"has-tooltip"</code> y conecte con <code>"query-tooltip"</code> como antes.</p></item>
      <item><p>Use <code>set_tooltip_window()</code> en el widget para establecer una GtkWindow creada como ventana del consejo.</p></item>
      <item><p>En la devolución de llamada <code>"query-tooltip"</code> puede acceder a su ventana usando <code>get_tooltip_window()</code> y manipularla como quiera. La semántica del valor de devolución es exactamente la misma que antes, devuelva <code>True</code> para mostrar el widget o <code>False</code> para no hacerlo.</p></item>
    </steps>

  </section>
  
  <section id="references">
  <title>Referencias de la API</title>
    <p>En este ejemplo se usa lo siguiente:</p>
    <list>
      <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkTooltip.html">GtkTooltip</link></p></item>
      <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkToolbar.html">GtkToolbar</link></p></item>
      <item><p><link href="http://developer.gnome.org/gtk3/stable/GtkWidget.html">GtkWidget</link></p></item>
      <item><p><link href="http://developer.gnome.org/gtk3/stable/gtk3-Stock-Items.html">Stock Items</link></p></item>
    </list>
  </section>
</page>
