Une Action peut être créée en utilisant le constructeur :

  action = gtk.Action(name, label, tooltip, stock_id)

... où name est une chaîne employée pour identifier l'Action dans un ActionGroup ou dans des descriptions d'UIManager. Le label et le tooltip sont des chaînes utilisées comme étiquette et infobulle dans des widgets délégués. Si label vaut None alors stock_id doit être une chaîne indiquant un élément de Stock pour en récupérer le label. Si tooltip vaut None, l'Action n'aura pas d'infobulle.

Comme nous le verrons dans la Section 16.1.2, « ActionGroup », il est beaucoup plus facile de créer des objets Action en utilisant les méthodes commodes de ActionGroup :

  actiongroup.add_actions(entries, user_data=None)
  actiongroup.add_toggle_actions(entries, user_data=None)
  actiongroup.add_radio_actions(entries, value=0, on_change=None, user_data=None)

On en reparlera plus loin, mais d'abord, décrivons comment utiliser une Action avec un Button pour illustrer les opérations élémentaires de connection d'une Action à un widget délégué.

La procédure de base pour l'utilisation d'une Action avec un Bouton proxy est illustrée par le programme exemple simpleaction.py. Le Bouton est connecté à l'Action par la méthode :

  action.connect_proxy(proxy)

... où le proxy est un widget élément de menu MenuItem, élément de barre d'outils ToolItem ou un bouton Button.

Une action (Action) possède un signal, le signal "activate" qui est déclenché quand l'Action est activée, normalement par le résultat d'une activation d'un widget proxy (par exemple, on a cliqué sur un bouton de barre d'outils ToolButton). Il faut juste connecter une fonction de rappel à ce signal pour contrôler l'activation de n'importe lequel des widgets délégués (proxy).

Voici le code source pour le programme exemple simpleaction.py :

     1 #!/usr/bin/env python
     2 # -*- coding:utf-8 -*-
     3 import pygtk
     4 pygtk.require('2.0')
     5 import gtk
     6 
     7 class SimpleAction:
     8     def __init__(self):
     9         # Créer la fenêtre de premier niveau
    10         window = gtk.Window()
    11         window.set_size_request(70, 30)
    12         window.connect('destroy', lambda w: gtk.main_quit())
    13 
    14         # Créer un groupe de raccourcis
    15         groupe_rapide = gtk.AccelGroup()
    16         # Ajouter le groupe à la fenêtre de premier niveau
    17         window.add_accel_group(groupe_rapide)
    18 
    19         # Créer une action_quitte pour quitter le programme avec un élément de Stock
    20         action_quitte = gtk.Action('Quitter', None, None, gtk.STOCK_QUIT)
    21         # Connecter une fonction de rappel à l'action
    22         action_quitte.connect('activate', self.fonct_quitte)
    23 
    24         # Créer un ActionGroup appelé ActionSimple
    25         groupe_actions = gtk.ActionGroup('ActionSimple')
    26         # Ajouter l'action à groupe_actions avec un raccourci clavier
    27         # "None" signifie utiliser l'accélérateur de l'élément Stock
    28         groupe_actions.add_action_with_accel(action_quitte, None)
    29 
    30         ## Lier l'action au groupe_rapide
    31         action_quitte.set_accel_group(groupe_rapide)
    32 
    33         # Connecter l'accélérateur à l'action
    34         action_quitte.connect_accelerator()
    35 
    36         # Créer un bouton pour l'utiliser comme autre widget délégué
    37         bouton_quitter = gtk.Button()
    38         # l'ajouter à la fenêtre
    39         window.add(bouton_quitter)
    40 
    41         # Lier l'action à son widget délégué
    42         action_quitte.connect_proxy(bouton_quitter)
    43 
    44         window.show_all()
    45         return
    46 
    47     def fonct_quitte(self, b):
    48         print 'Quitter le programme'
    49         gtk.main_quit()
    50 
    51 if __name__ == '__main__':
    52     sa = SimpleAction()
    53     gtk.main()

L'exemple crée une Action (ligne 20) qui utilise un élément Stock Item pour récupérer le texte de l'étiquette avec un mnémonique, une icône, un raccourci clavier et un domaine de traduction. Si on n'utilise pas de Stock Item, il faut indiquer un label à la place. Ligne 22, on connecte le signal "activate" du paramètre action à la méthode self.quit_cb() afin qu'elle soit appelée quand l'action Action est activée par le bouton quitbutton. L'exemple simpleaction.py utilise pas mal de code (lignes 15, 17, 31 et 34) pour installer le raccourci pour le bouton. La procédure est la même pour les éléments de menu MenuItem, les barres d'outils Toolbar et les éléments de barre d'outilsToolItem.

La Figure 16.1, « Exemple d'Action simple » montre le résultat du programme simpleaction.py

Figure 16.1. Exemple d'Action simple

Dans la section précédente nous avons vu qu'un widget existant pouvait être connecté à une Action comme intermédiaire. Dans cette section nous verrons comment un widget délégué peut être créé par les méthodes d'Action :

  menuitem = action.create_menu_item()

  toolitem = action.create_tool_item()

Le programme basicaction.py montre un élément de menu MenuItem, un bouton de barre d'outils ToolButton et un bouton Button partageant une même Action. Le MenuItem et le ToolButton ont été créés par les méthodes précédentes. Voici le code source du programme basicaction.py :

     1	#!/usr/bin/env python
     2	# -*- coding:utf-8 -*-
     3	import pygtk
     4	pygtk.require('2.0')
     5	import gtk
     6	
     7	class BasicAction:
     8	    def __init__(self):
     9	        # Créer la fenêtre de premier niveau
    10	        window = gtk.Window()
    11	        window.connect('destroy', lambda w: gtk.main_quit())
    12	        vbox = gtk.VBox()
    13	        vbox.show()
    14	        window.add(vbox)
    15	
    16	        # Créer un groupe de raccourcis
    17	        groupe_rapide = gtk.AccelGroup()
    18	        # Ajouter le groupe à la fenêtre de premier niveau
    19	        window.add_accel_group(groupe_rapide)
    20	
    21	        # Créer une action_quitte pour quitter le programme avec un élément de Stock
    22	        action_quitte = gtk.Action('Quitter', '_Quittez moi ! ', 'Quitter le programme',
    23	                            gtk.STOCK_QUIT)
    24	        action_quitte.set_property('short-label', '_Quitter')
    25	        # Connecter une fonction de rappel à l'action
    26	        action_quitte.connect('activate', self.fonct_quitte)
    27	
    28	        # Créer un ActionGroup appelé ActionBasic
    29	        groupe_actions = gtk.ActionGroup('ActionBasic')
    30	        # Ajouter l'action à groupe_actions avec un raccourci clavier
    31	        # "None" signifie utiliser le raccourci de l'élément Stock
    32	        groupe_actions.add_action_with_accel(action_quitte, None)
    33	
    34	        # Lier l'action au groupe_rapide
    35	        action_quitte.set_accel_group(groupe_rapide)
    36	
    37	        # Créer une barre de menu
    38	        barremenu = gtk.MenuBar()
    39	        barremenu.show()
    40	        vbox.pack_start(barremenu, False)
    41	
    42	        # Créer une action "Fichier" et l'élément de menu correspondant
    43	        action_fichier = gtk.Action('Fichier', '_Fichier', None, None)
    44	        groupe_actions.add_action(action_fichier)
    45	        elmenu_fichier = action_fichier.create_menu_item()
    46	        barremenu.append(elmenu_fichier)
    47	
    48	        # Créer le menu Fichier
    49	        menu_fichier = gtk.Menu()
    50	        elmenu_fichier.set_submenu(menu_fichier)
    51	
    52	        # Créer  un élément de menu délégué
    53	        menuitem = action_quitte.create_menu_item()
    54	        menu_fichier.append(menuitem)
    55	
    56	        # Créer une barre d'outils
    57	        barreoutils = gtk.Toolbar()
    58	        barreoutils.show()
    59	        vbox.pack_start(barreoutils, False)
    60	
    61	        # Créer un élément de barre d'outils délégué
    62	        elbarre1 = action_quitte.create_tool_item()
    63	        barreoutils.insert(elbarre1, 0)
    64	
    65	        # Créer et placer l'étiquette
    66	        label = gtk.Label('''
    67	Choisir Fichier->Quittez moi ! ou
    68	cliquer sur le bouton Quitter de la barre d'outils ou
    69	cliquer sur le bouton Quitter du bas ou
    70	taper Control+q
    71	pour sortir.
    72	''')
    73	        label.show()
    74	        vbox.pack_start(label)
    75	
    76	        # Créer un bouton pour l'utiliser comme autre widget délégué
    77	        bouton_quitter = gtk.Button()
    78	        # l'ajouter à la fenêtre
    79	        vbox.pack_start(bouton_quitter, False)
    80	
    81	        # Lier l'action à son widget délégué
    82	        action_quitte.connect_proxy(bouton_quitter)
    83	        # On doit placer l'infobulle après l'ajout de l'élément à la barre d'outils
    84	        action_quitte.set_property('tooltip', action_quitte.get_property('tooltip'))
    85	        les_infobulles = gtk.Tooltips()
    86	        les_infobulles.set_tip(bouton_quitter, action_quitte.get_property('tooltip'))
    87	
    88	        window.show()
    89	        return
    90	
    91	    def fonct_quitte(self, b):
    92	        print 'On quitte le programme'
    93	        gtk.main_quit()
    94	
    95	if __name__ == '__main__':
    96	    ba = BasicAction()
    97	    gtk.main()

Cet exemple introduit un groupe d'actions ActionGroup contenant les Action utilisées dans ce programme. La Section 16.1.2, « ActionGroup » entrera plus dans le détail de l'utilisation des ActionGroup.

Le code des lignes 9-14 crée une fenêtre de premier niveau contenant une boîte VBox. Lignes 16-35, on crée l' Action "Quitter" semblable à celle du programme simpleaction.py et on l'ajoute (ligne 32) avec le raccourci gtk.STOCK_QUIT à l' ActionGroup "BasicAction" créé ligne 29. Noter que, contrairement au programme simpleaction.py, il n'est pas nécessaire d'appeler la méthode connect_accelerator(), celle-ci étant appelée automatiquement quand la méthode create_menu_item() est appelée ligne 53.

Lignes 38-40, on crée une barre de menu MenuBar et on la place dans la VBox. Lignes 43-44, on crée une Action (action_fichier) pour le menu Fichier et on l'ajoute au actiongroup. Les éléments de menu Fichier et Quitter sont créés lignes 45 et 53 et ajoutés à la barre de menu barremenu et au menu menu_fichier en ligne 46 et 54.

De la même manière, on crée une Toolbar et on l'ajoute à la VBox aux lignes 57-59. Le ToolItem délégué est créé et ajouté à la Toolbar barreoutils ligne 62-63. Noter que l'infobulle de l' Action doit être établie (ligne 84) après l'ajout du ToolItem à la Toolbar pour être utilisable. De même l'infobulle du Button doit être ajouté manuellement (lignes 84-86).

La Figure 16.2, « Exemple d'Action élémentaire » montre le programme basicaction.py en action.

Figure 16.2. Exemple d'Action élémentaire

Un widget délégué peut être déconnecté d'une Action par la méthode :

  action.disconnect_proxy(proxy)

Une Action possède un certain nombre de propriétés qui contrôlent l'affichage et le fonctionnement de ses widgets délégués. Parmi celles-ci, les plus importantes sont les propriétés "sensitive" et "visible". La propriété "sensitive" détermine la sensibilité des widgets délégués. Si "sensitive" est FALSE les widgets délégués ne sont pas activables et seront normalement affichés "grisés". De même, la propriété "visible" détermine si les widgets délégués seront visibles. Si la propriété "visible" d'une Action est FALSE, ses widgets délégués seront cachés.

Comme on le verra dans la prochaine section, la sensibilité ou la visibilité d'une Action est également contrôlée par la sensibilité ou la visibilité de l'ActionGroup auquel elle appartient. Par conséquent, pour qu'une Action soit sensible (ou visible), elle-même et son ActionGroup doivent être sensibles (ou visibles) tous les deux. Pour déterminer la sensibilité ou visibilité effective d'une Action, il faut utiliser les méthodes suivantes :

  resultat = action.is_sensitive()

  resultat = action.is_visible()

Le nom assigné à une Action est contenu dans sa propriété "name" qui est établie lors de la création de l'Action. On peut retrouver ce nom par la méthode :

  nom = action.get_name()

Les autres propriétés qui contrôlent l'affichage des widgets délégués d'une Action sont :

Autres propriétés intéressantes :

Noter que le programme d'exemple basicaction.py réécrit l'étiquette du gtk.STOCK_QUIT avec "_Quitter moi !" et définit l'étiquette courte à "_Quitter". L'étiquette courte est utilisée pour le bouton de barre d'outil ToolButton et pour le bouton isolé. L'étiquette compléte est utilisée pour le l'élément de menu MenuItem. Noter aussi que l'infobulle ne peut pas être définie pour un ToolItem tant qu'elle n'est pas ajoutée à la barre d'outils Toolbar.

Une Action a trois méthodes qui peuvent être employées pour établir un accélérateur (raccourci clavier) :

  action.set_accel_group(accel_group)

  action.set_accel_path(accel_path)

  action.connect_accelerator()

Celles-ci, outre la méthode gtk.ActionGroup.add_action_with_accel(), devraient couvrir la plupart des cas de création d'accélérateur.

Il faut toujours définir un AccelGroup pour une Action. La méthode set_accel_path() est appelée par la méthode gtk.ActionGroup.add_action_with_accel(). Si on utilise la méthode set_accel_path(), le chemin de l'accélérateur doit avoir le format par défaut : "<Actions>/nom_du_groupe_actions/nom_de_action". Enfin, la méthode connect_accelerator() est appelée pour compléter la mise en place de l'accélérateur.

Puisque la méthode connect_accelerator() peut être appelée plusieurs fois (par exemple, une fois pour chaque widget délégué), le nombre d'appels est compté, ainsi un nombre égal d'appels à la méthode disconnect_accelerator() doit être réalisé avant d'éliminer l'accélérateur.

Comme illustré dans les programmes d'exemple précédents, un accélérateur d'Action peut être employé par tous les widgets délégués. Une Action doit faire partie d'un ActionGroup afin d'utiliser le chemin d'accélérateur par défaut avec ce format : "<Actions>/nom_du_groupe_actions/nom_de_action". La manière la plus simple d'ajouter un accélérateur est d'utiliser la méthode gtk.ActionGroup.add_action_with_accel() et la procédure générale suivante :

Tous les widgets délégués créés ou connectés à l'Action utiliseront le raccourci.

Comme mentionnée précédemment une action à bascule ToggleAction est une sous-classe d'Action qui peut être basculée entre deux états. Le constructeur pour une ToggleAction prend les mêmes paramètres que pour une Action :

  toggleaction = gtk.ToggleAction(name, label, tooltip, stock_id)

En supplément des méthodes pour Action, les methodes suivantes pour ToggleAction :

  toggleaction.set_active(is_active)
  is_active = toggleaction.get_active()

... spécifient et récupérent la valeur actuelle de toggleaction. Le paramètre is_active contient une valeur booléenne.

On peut se connecter au signal "toggled" en spécifiant une fonction de rappel qui a la forme :

  def toggled_cb(toggleaction, user_data)

Le signal "toggled" est émis lorsque le ToggleAction change d'état.

Le widget délégué MenuItem d'un ToggleAction sera affiché par défaut comme un CheckMenuItem. Pour obtenir l'affichage du MenuItem comme un RadioMenuItem, il faut donner à la propriété "draw-as-radio" la valeur TRUE par la méthode :

  toggleaction.set_draw_as_radio(draw_as_radio)

On peut utiliser la méthode suivante pour déterminer si les éléments MenuItem d'une action ToggleAction seront affichés comme des RadioMenuItem :

  draw_as_radio = toggleaction.get_draw_as_radio()

Une action exclusive RadioAction est une sous-classe d'action ToggleAction qui peut être groupé de manière à ce qu'un seul RadioAction soit actif en même temps. Les widgets délégués correspondants sont le RadioMenuItem pour la barre de menu et le RadioToolButton pour la barre d'outils.

Le constructeur d'un RadioAction accepte les mêmes arguments qu'une Action avec l'ajout d'une valeur entière unique qui permet d'identifier le RadioAction actif dans le groupe :

  radioaction = gtk.RadioAction(name, label, tooltip, stock_id, value)

Le groupe d'un RadioAction peut être créé par la méthode :

  radioaction.set_group(group)

... où group est un autre RadioAction auquel doit se rattacher le radioaction. Le groupe contenant un RadioAction peut être obtenu par la méthode :

  group = radioaction.get_group()

qui renvoit une liste du groupe d'objets RadioAction qui inclut le radioaction.

La valeur de l'élément actuellement actif du groupe peut s'obtenir par la méthode :

  active_value = radioaction.get_current_value()

On peut connecter une fonction de rappel au signal "changed" pour être prévenu lorsque l'élément actif du RadioAction a été modifié. Noter qu'il faut se connecter à un seul des objets RadioAction pour surveiller les changements. La fonction de rappel est :

  def changed_cb(radioaction, current, user_data)

... où current est le RadioAction du groupe qui est actuellement actif.

Le programme exemple actions.py montre l'utilisation d'objets Action, ToggleAction et RadioAction. Figure 16.3, « Exemple avec Actions » illustre le programme en cours de fonctionnement :

Figure 16.3. Exemple avec Actions

Cet exemple est suffisament proche de basicaction.py, une description détaillée est inutile.

On crée un ActionGroup

  actiongroup = gtk.ActionGroup(name)

... où name est un nom unique pour l'ActionGroup. Le nom doit être unique car il est utilisé lors de la création des raccourcis des objets Action qu'il contient.

Le paramètre ActionGroup peut être obtenu par la méthode :

  name = actiongroup.get_name()

ou en récupérant le contenu de la propriété "name".

Comme on l'a montré dans Section 16.1.1, « Actions », une Action préexistante peut être ajoutée à un ActionGroup en utilisant une des méthodes :

  actiongroup.add_action(action)

  actiongroup.add_action_with_accel(action, accelerator)

... où le paramètre actionest l'Action qui doit être ajoutée et le paramètre accelerator est une chaîne précisant un raccourci acceptable pour la fonction gtk.accelerator_parse(). Si accelerator vaut None, l'accélérateur (s'il existe) associé à la propriété "stock-id" du paramètre action sera utilisé. Comme on l'a vu précédemment, il vaut mieux utiliser la méthode add_action_wih_accel() si on souhaite utiliser les raccourcis clavier.

Le groupe ActionGroup offre trois méthodes pour faciliter la création et l'ajout d'objets Action à un groupe ActionGroup :

  actiongroup.add_actions(entries, user_data=None)

  actiongroup.add_toggle_actions(entries, user_data=None)

  actiongroup.add_radio_actions(entries, value=0, on_change=None, user_data=None)

Le paramètre entries est une liste de tuples d'entrée d'action qui fournissent l'information utlisée pour créer les actions ajoutées à l'ActionGroup. Le RadioAction avec la valeur value est réglé au départ comme actif. Le paramètre on_change représente la fonction de rappel connectée au signal "changed" du premier RadioAction du groupe. La signature de on_changed est :

  def on_changed_cb(radioaction, current, user_data)

Les tuples d'entrées pour les objets Action contiennent :

Il faut indiquer au minimum une valeur pour le champ name et une valeur, soit pour l'identificateur stock id, soit pour le champ étiquette label. Si on indique une étiquette, alors, on peut donner une valeur None à l'identificateur de stock si on ne l'utilise pas. Par exemple, la méthode suivant :

  actiongroup.add_actions([('quitter', gtk.STOCK_QUIT, '_Quittter moi !', None, 
                            'Quitter le programme', quit_cb)])

ajoute une action à actiongroup pour quitter un programme.

Les tuples d'entrée pour les objets ToggleAction sont semblables aux tuples d'entrée d'Action mais il y a un champ facultatif flag supplémentaire qui contient une valeur booléenne indiquant si l'action est active.La valeur par défaut pour le champ flag est FALSE. Par exemple, la méthode suivante :

  actiongroup.add_toggle_actions([('volume, None, '_Volume', '<control>v', 
                                   'Niveau de son', mute_cb, True)])

ajoute un ToggleAction à l'actiongroup et l'initialise comme actif.

Les tuples d'entrée pour le RadioAction sont semblables à ceux de Action mais avec un champ value à la place du champ callback :

Par exemple le fragment de code suivant :

  radioactionlist = [('ma', None, 'M_A', '<control>a', 'Mode MA', 0)
                     ('mf', None, 'M_F', '<control>f', 'Mode MF', 1)
                     ('blu', None, 'B_LU', '<control>b', 'Mode BLU', 2)]
  actiongroup.add_radio_actions(radioactionlist, 0, changed_cb)

... crée trois objets RadioAction et fixe l'action active initiale à 'ma' et la fonction de rappel qui est appelée quand l'une de ces actions est activée à changed_cb.

Une Action peut être retrouvée par son nom à partir d'un ActionGroup en utilisant la méthode :

  action = actiongroup.get_action(action_name)

Une liste de tous objets Action contenus dans un ActionGroup peut être recherchée en utilisant la méthode :

  actionlist = actiongroup.list_actions()

La sensibilité et la visibilité de tous les objets Action d'un ActionGroup peuvent être controlées en fixant les valeurs de propriété associées. Les méthodes suivantes récupérent et fixent les propriétés :

  is_sensitive = actiongroup.get_sensitive()
  actiongroup.set_sensitive(sensitive)

  is_visible = actiongroup.get_visible()
  actiongroup.set_visible(visible)

Enfin, il est possible de supprimer une Action d'un ActionGroup par la méthode :

  actiongroup.remove_action(action)

Le programme d'exemple actiongroup.py reprend la barre de menu et la barre d'outils du programme actions.py en utilisant les méthodes d'ActionGroup. En outre le programme fournit des boutons pour controler la sensibilité et la visibilité des éléments du menu et de la barre d'outils. La Figure 16.4, « Exemple avec ActionGroup » montre le programme en fonctionnement :

Figure 16.4. Exemple avec ActionGroup

L'application peut surveiller la connexion et le retrait de widgets délégués aux objets Action dans un ActionGroup en utilisant les signaux "connect-proxy" et "disconnect-proxy". Les fonctions de rappel sont de la forme :

  def connect_proxy_cb(actiongroup, action, proxy, user_params)

  def disconnect_proxy_cb(actiongroup, action, proxy, user_params)

Par exemple, on peut vouloir surveiller ces changements pour effectuer quelques modifications supplémentaires aux propriétés du nouveau widget délégué quand il est connecté ou pour mettre à jour quelque autre partie de l'interface utilisateur quand un widget délégué est déconnecté.

Les signaux "pre-activate" and "post-activate" autorisent l'application à réaliser un traitement additionnel juste avant ou après l'activation d'une action. Les fonctions de rappel sont de la forme :

  def pre_activate_cb(actiongroup, action, user_params)

  def post_activate_cb(actiongroup, action, user_params)

Ces signaux sont surtout utilisés par le UIManager pour fournir une notification globale pour tous les objets Action des objets ActionGroup qu'il utilise.