<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="tooltip.py" xml:lang="es">

  <info>

  <title type="text">Consejo (Python)</title>

    <link type="guide" xref="beginner.py#misc"/>

    <link type="seealso" xref="toolbar.py"/>

    <link type="next" xref="toolbar_builder.py"/>

    <revision version="0.1" date="2012-08-20" status="draft"/>

    <credit type="author copyright">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2012</years>

    </credit>

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

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Daniel Mustieles</mal:name>

      <mal:email>daniel.mustieles@gmail.com</mal:email>

      <mal:years>2011 - 2017</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Nicolás Satragno</mal:name>

      <mal:email>nsatragno@gmail.com</mal:email>

      <mal:years>2012 - 2013</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Jorge González</mal:name>

      <mal:email>jorgegonz@svn.gnome.org</mal:email>

      <mal:years>2011</mal:years>

    </mal:credit>

  </info>

  <title>Consejo</title>

  <media type="image" mime="image/png" src="media/tooltip.png"/>

  
Una barra de herramientas con un consejo (con una imagen) para un botón.

  <note>
Esto construye el ejemplo de <link xref="toolbar.py">Toolbar</link>.
</note>

  <links type="section"/>

  <section id="code">

  <title>Código usado para generar este ejemplo</title>

    from gi.repository import Gtk

from gi.repository import Gdk

from gi.repository import Gio

import sys

class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):

        Gtk.Window.__init__(

            self, title="Toolbar with Tooltips Example", application=app)

        self.set_default_size(400, 200)

        grid = Gtk.Grid()

        toolbar = self.create_toolbar()

        toolbar.set_hexpand(True)

        toolbar.show()

        grid.attach(toolbar, 0, 0, 1, 1)

        self.add(grid)

        undo_action = Gio.SimpleAction.new("undo", None)

        undo_action.connect("activate", self.undo_callback)

        self.add_action(undo_action)

        fullscreen_action = Gio.SimpleAction.new("fullscreen", None)

        fullscreen_action.connect("activate", self.fullscreen_callback)

        self.add_action(fullscreen_action)

    def create_toolbar(self):

        toolbar = Gtk.Toolbar()

        toolbar.get_style_context().add_class(Gtk.STYLE_CLASS_PRIMARY_TOOLBAR)

        # button for the "new" action

        new_button = Gtk.ToolButton.new_from_stock(Gtk.STOCK_NEW)

        # with a tooltip with a given text

        new_button.set_tooltip_text("Create a new file")

        new_button.set_is_important(True)

        toolbar.insert(new_button, 0)

        new_button.show()

        new_button.set_action_name("app.new")

        # button for the "open" action

        open_button = Gtk.ToolButton.new_from_stock(Gtk.STOCK_OPEN)

        # with a tooltip with a given text in the Pango markup language

        open_button.set_tooltip_markup("Open an <i>existing</i> file")

        open_button.set_is_important(True)

        toolbar.insert(open_button, 1)

        open_button.show()

        open_button.set_action_name("app.open")

        # button for the "undo" action

        undo_button = Gtk.ToolButton.new_from_stock(Gtk.STOCK_UNDO)

        # with a tooltip with an image

        # set True the property "has-tooltip"

        undo_button.set_property("has-tooltip", True)

        # connect to the callback function that for the tooltip

        # with the signal "query-tooltip"

        undo_button.connect("query-tooltip", self.undo_tooltip_callback)

        undo_button.set_is_important(True)

        toolbar.insert(undo_button, 2)

        undo_button.show()

        undo_button.set_action_name("win.undo")

        # button for the "fullscreen/leave fullscreen" action

        self.fullscreen_button = Gtk.ToolButton.new_from_stock(

            Gtk.STOCK_FULLSCREEN)

        self.fullscreen_button.set_is_important(True)

        toolbar.insert(self.fullscreen_button, 3)

        self.fullscreen_button.set_action_name("win.fullscreen")

        return toolbar

    # the callback function for the tooltip of the "undo" button

    def undo_tooltip_callback(self, widget, x, y, keyboard_mode, tooltip):

        # set the text for the tooltip

        tooltip.set_text("Undo your last action")

        # set an icon fot the tooltip

        tooltip.set_icon_from_stock("gtk-undo", Gtk.IconSize.MENU)

        # show the tooltip

        return True

    def undo_callback(self, action, parameter):

        print("You clicked \"Undo\".")

    def fullscreen_callback(self, action, parameter):

        is_fullscreen = self.get_window().get_state(

        ) & Gdk.WindowState.FULLSCREEN != 0

        if not is_fullscreen:

            self.fullscreen_button.set_stock_id(Gtk.STOCK_LEAVE_FULLSCREEN)

            self.fullscreen()

        else:

            self.fullscreen_button.set_stock_id(Gtk.STOCK_FULLSCREEN)

            self.unfullscreen()

class MyApplication(Gtk.Application):

    def __init__(self):

        Gtk.Application.__init__(self)

    def do_activate(self):

        win = MyWindow(self)

        win.show_all()

    def do_startup(self):

        Gtk.Application.do_startup(self)

        new_action = Gio.SimpleAction.new("new", None)

        new_action.connect("activate", self.new_callback)

        app.add_action(new_action)

        open_action = Gio.SimpleAction.new("open", None)

        open_action.connect("activate", self.open_callback)

        app.add_action(open_action)

    def new_callback(self, action, parameter):

        print("You clicked \"New\".")

    def open_callback(self, action, parameter):

        print("You clicked \"Open\".")

app = MyApplication()

exit_status = app.run(sys.argv)

sys.exit(exit_status)

  </section>

  <section id="methods">

  <title>Métodos útiles para un widget de consejo</title>

    
set_tooltip_text(text) y set_tooltip_markup(text) pueden usarse para añadir un consejo o texto plano (o texto en el lenguaje de marcado de Pango) a un widget.

    
Para consejos más complejos, por ejemplo para un consejo con una imagen:

    <steps>

      <item>
Establezca la propiedad "has-tooltip" del widget a True; 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.
</item>

      <item>
Conecte a la señal "query-tooltip". 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 set_icon(). Hay funciones para establecer el texto marcado del consejo (set_markup(text)), una imagen desde un icono del almacén (set_icon_from_stock(stock_id, size)), o incluso poner un widget personalizado (set_custom(widget)).
</item>

      <item>
Devuelva True de su manejador de «query-tooltip». Esto hace que el consejo se muestre. Si devuelve False, no se mostrará.
</item>

    </steps>

    
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í:

    <steps>

      <item>
Establezca "has-tooltip" y conecte con "query-tooltip" como antes.
</item>

      <item>
Use set_tooltip_window() en el widget para establecer una GtkWindow creada como ventana del consejo.
</item>

      <item>
En la devolución de llamada "query-tooltip" puede acceder a su ventana usando get_tooltip_window() y manipularla como quiera. La semántica del valor de retorno es exactamente la misma que antes, devuelva True para mostrar el widget o False para no hacerlo.
</item>

    </steps>

  </section>

  <section id="references">

  <title>Referencias de la API</title>

    
En este ejemplo se usa lo siguiente:

    <list>

      <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkTooltip.html">GtkTooltip</link>
</item>

      <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkToolbar.html">GtkToolbar</link>
</item>

      <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkWidget.html">GtkWidget</link>
</item>

      <item>
<link href="http://developer.gnome.org/gtk3/stable/gtk3-Stock-Items.html">Elementos del almacén</link>
</item>

    </list>

  </section>

</page>