<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="fr">

  <info>

  <title type="text">Tooltip (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>Ajouter des infobulles à vos éléments graphiques</desc>

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

      <mal:name>Luc Rebert,</mal:name>

      <mal:email>traduc@rebert.name</mal:email>

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

    </mal:credit>

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

      <mal:name>Alain Lojewski,</mal:name>

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

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

    </mal:credit>

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

      <mal:name>Luc Pionchon</mal:name>

      <mal:email>pionchon.luc@gmail.com</mal:email>

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

    </mal:credit>

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

      <mal:name>Bruno Brouard</mal:name>

      <mal:email>annoa.b@gmail.com</mal:email>

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

    </mal:credit>

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

      <mal:name>Luis Menina</mal:name>

      <mal:email>liberforce@freeside.fr</mal:email>

      <mal:years>2014</mal:years>

    </mal:credit>

  </info>

  <title>Infobulle</title>

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

  
Une barre d'outil avec une infobulle (une image) pour un bouton.

  <note>
This example builds on the <link xref="toolbar.py">Toolbar</link> example.
</note>

  <links type="section"/>

  <section id="code">

  <title>Code utilisé pour générer cet exemple</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éthodes utiles pour un élément graphique infobulle (Tooltip)</title>

    
Les fonctions set_tooltip_text(text) et set_tooltip_markup(text) peuvent être utilisées pour ajouter une infobulle textuelle (ou un texte dans le langage de balisage Pango) à un élément graphique.

    
Pour des infobulles plus complexes, par exemple pour une infobulle sous la forme d'image :

    <steps>

      <item>
Attribuez la valeur True (vrai) à la propriété "has-tooltip" de l'élément graphique ; de cette façon GTK+ surveille les événements liés aux mouvements de la souris et tous ceux qui sont nécessaires afin de déterminer quand et où afficher une infobulle.
</item>

      <item>
Connectez le signal "query-tooltip". Ce signal est émis lorsqu'une infobulle doit s'afficher. Un des arguments transmis au gestionnaire de signaux est un objet GtkTooltip. C'est l'objet que nous allons afficher comme infobulle et qui peut être manipulé dans votre fonction de rappel (callback) en utilisant des fonctions comme set_icon(). Ce sont des fonctions servant à paramétrer le balisage de l'infobulle (set_markup(text)), à définir une image à partir de la collection d'icônes (set_icon_from_stock(stock_id, size)), ou même à positionner un élément graphique personnalisé (set_custom(widget)).
</item>

      <item>
Renvoyez la valeur True à partir de votre gestionnaire query-tooltip. Cela provoque l'affichage de l'infobulle. Si vous renvoyez False, elle n'est pas affichée.
</item>

    </steps>

    
Dans le cas peut probable où vous voulez avoir plus de contrôle sur l'infobulle qui est sur le point d'être affichée, vous pouvez définir votre propre GtkWindow qui sera utilisée comme fenêtre d'infobulle. Cela fonctionne comme ceci :

    <steps>

      <item>
Paramétrez "has-tooltip" et connectez le à "query-tooltip" comme auparavant.
</item>

      <item>
Utilisez set_tooltip_window() sur l'élément graphique pour définir un GtkWindow créé par vos soins comme fenêtre d'infobulle.
</item>

      <item>
Dans la fonction de rappel "query-tooltip" vous pouvez accéder à votre fenêtre en utilisant get_tooltip_window() et la manipuler comme bon vous semble. La sémantiques pour la valeur retournée est exactement comme ci-dessus, renvoyez True pour afficher la fenêtre, False dans le cas contraire.
</item>

    </steps>

  </section>

  <section id="references">

  <title>Références API</title>

    
Dans cet exemple, les éléments suivants sont utilisés :

    <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">Stock Items</link>
</item>

    </list>

  </section>

</page>