NOM

Tk::bind - Invoquer des callbacks à partir d'événements X


SYNOPSIS

Récupérer des liaisons :

$widget->bind

$widget->bind(tag)

$widget->bind(sequence)

$widget->bind(tag,sequence)

Créer et détruire des liaisons :

$widget->bind(sequence,callback)

$widget->bind(tag,sequence,callback)


DESCRIPTION

La méthode bind associe les callbacks avec les événements X. Si callback est spécifié, bind fera en sorte que callback sera évalué chaque fois que le ou les événements décrits par sequence se produiront dans la (ou les) fenêtre(s) identifiée(s) par $widget ou tag. Si callback est une chaîne vide alors la liaison courante pour sequence est détruite, laissant sequence sans lien. Dans tous les cas où un argument callback est fourni, bind renvoie une chaîne vide.

Si sequence est spécifiée sans callback, alors le callback lié actuellement à sequence est renvoyé, ou bien undef s'il n'y a pas de liaison pour sequence. Si sequence et callback ne sont pas spécifiées, alors la valeur de retour est une liste dont les éléments sont toutes les séquences pour lesquelles il existe des liaisons pour tag.

Si aucun tag n'est spécifié alors bind se réfère à $widget. Si tag est spécifié il s'agit typiquement d'un nom de classe et bind se réfère à toutes les instances de classe associées à $widget sur MainWindow. (tag peut être un autre ``objet widget'' mais cette pratique est désapprouvée). La méthode de Perl ref($object) est là pour retrouver le nom de classe de n'importe quel objet. Chaque fenêtre a une liste de tags associée, et une liaison s'applique à une fenêtre particulière si ses tag font partie de ceux spécifiés pour la fenêtre. Bien que la méthode bindtags puisse être utilisée pour assigner un ensemble arbitraire de tags de liaison à une fenêtre, les tags de liaison par défaut fournissent le comportement suivant :

Si un tag est le nom d'une fenêtre interne la liaison s'applique à cette fenêtre ;

Si le tag est le nom d'une fenêtre toplevel la liaison s'applique à la fenêtre toplevel et à toutes ses fenêtres internes ;

Si le tag est le nom d'une classe de widgets, comme Tk::Button, la liaison s'applique à tous les widgets de cette classe ;

Si tag a la valeur all, la liaison s'applique à toutes les fenêtres descendantes de la MainWindow de l'application.


MOTIFS D'ÉVÉNEMENTS

L'argument sequence spécifie une séquence de un ou plusieurs motifs d'événement, avec des caractères 'espace' optionnels entre les motifs. Chaque motif d'événement peut prendre trois formes. Le cas le plus simple est un simple caractère ASCII, tel que a ou [. Ce caractère ne peut pas être l'espace ni le caractère <. Cette forme de motif relie un événement KeyPress à ce caractère particulier. La deuxième forme est plus longue mais plus générale. Elle a la syntaxe suivante :

  '<modificateur-modificateur-type-detail>'

Le motif d'événement est encadré par '<' et '>', et doit normalement être entre quotes, car '<' et '>' sont des caractères spéciaux de perl. Entre '<' et '>' on trouve zéro modificateurs ou davantage, un type d'événement, et une information supplémentaire (detail) qui identifie un bouton particulier ou un code symbolique de touche. N'importe quel champ peut être omis, pouvu qu'au moins type ou detail soit présent. Les champs doivent être séparés par des espaces ou des tirets.

La troisième forme de motif est utilisée pour spécifier un événement virtuel nommé défini par l'utilisateur ; voir Tk::event pour les détails. Il a la syntaxe suivante :

  <<name>>

Le motif d'événement virtuel est écrit entre '<<' et '>>'. Entre '<<' et '>>' se trouve le nom (défini par l'utilisateur) de l'événement virtuel. Les modificateurs, tels que Shift ou Control, ne doivent pas être combinés avec un événement virtuel pour le modifier. Les liaisons sur un événement virtuel doivent être créées avant que l'événement virtuel soit défini, et si la définition de l'événement virtuel change dynamiquement, toutes les fenêtres liées à cet événement virtuel répondent immédiatement à la nouvelle définition.


MODIFICATEURS

Les modificateurs sont énumérés ci-après :

    Control        Mod2, M2 
    Shift          Mod3, M3 
    Lock           Mod4, M4 
    Button1, B1    Mod5, M5 
    Button2, B2    Meta, M 
    Button3, B3    Alt
    Button4, B4    Double
    Button5, B5    Triple
    Mod1, M1       Quadruple

Lorsque plusieurs valeurs sont listées, séparées par une virgule, les valeurs sont équivalentes. La plupart des modificateurs ont une signification X évidente. Par exemple, Button1 demande à ce que le bouton 1 soit enfoncé pour que l'événement se produise. Pour qu'une liaison corresponde à un événement donné, les modificateurs de l'événement doivent inclure tous ceux spécifiés dans le motif d'événement. Un événement peut contenir des modificateurs additionnels non spécifiés dans la liaison. Par exemple, si le bouton 1 est pressé alors que les touches shift et control sont enfoncées, le motif <Control-Button-1> correspondra à l'événement, mais <Mod1-Button-1> ne correspondra pas. Si aucun modificateur n'est spécifié, alors n'importe quelle combinaison de modificateurs peut être présente dans l'événement.

Meta et M se réfèrent à n'importe quel modificateur depuis M1 jusqu'à M5, associé à une (ou plusieurs) touche(s) meta du clavier (codes symboliques de touche Meta_R et Meta_L). S'il n'y a pas de touche meta, ou si elles ne sont pas associées à un modificateur, Meta et M ne correspondront à aucun événement. De manière similaire, le modificateur Alt se réfère à tout modificateur associé à la touche alt du clavier (codes symboliques de touche Alt_L and Alt_R).

Les modificateurs Double, Triple et Quadruple sont une commodité pour spécifier les double click souris ainsi que d'autre événements répétés. Ils font en sorte qu'un motif d'événement doit être répété 2,3 ou 4 fois, et imposent aussi une contrainte de temps et d'espace dans le séquence : pour qu'une séquence d'événements correspondent à un motif Double, Triple ou Quadruple, tous les événements doivent être proches dans le temps et sans déplacement excessif de la souris entre eux. Par exemple, <Double-Button-1> est équivalent à <Button-1><Button-1> avec une contrainte supplémentaire de temps et d'espace.


TYPES D'ÉVÉNEMENT

Le champ type peut être l'un quelconque des types d'événement X standard, avec quelques abréviations supplémentaires. Ci-dessous une liste de tous le types valides ; lorsque deux noms apparaissent ensemble, séparés par une virgule, ils sont synonymes.

  Activate             Destroy           Map
  ButtonPress, Button  Enter             MapRequest
  ButtonRelease        Expose            Motion
  Circulate            FocusIn           MouseWheel
  CirculateRequest     FocusOut          Property
  Colormap             Gravity           Reparent
  Configure            KeyPress, Key     ResizeRequest
  ConfigureRequest     KeyRelease        Unmap
  Create               Leave             Visibility
  Deactivate

La plupart de ces événements ont les mêmes champs et signification que les événements du système de fenêtre X. Vous trouverez une description plus détaillée de ces événements dans tous les livres de programmation X Window. Deux de ces événements représentent une extension du système d'événement X afin de répondre aux fonctionnalités des plate-formes Macintosh et Windows. Voici quelques détails supplémentaires sur ces événements. Il s'agit de :

  Activate
  Deactivate

Ces deux événements sont envoyés à toutes les fenêtres filles d'une toplevel lorsque leur état change. Outre la notion de ``de fenêtre ayant le focus'', les plate-formes Macintosh et Windows ont la notion de ``fenêtre active'' (qui a, le plus souvent, le focus, mais ce n'est pas requis). Sur le Macintosh, les widgets de la fenêtre active ont une apparence différente des widgets des fenêtres désactivées. L'événement Activate est envoyé à toute fenêtre fille d'un toplevel lorsque son état passe d'inactif à actif. De la même manière, l'événement Deactivate est envoyé lorsque la fenêtre passe de l'état activée à l'état désactivée. [There are no use- ful percent substitutions you would make when binding to these events.]

    MouseWheel

Les souris des plate-formes Windows comportent souvent une roulette utilisée pour faire défiler les documents sans utiliser les barres de défilement. Lorsqu'on utilise cette roulette, le système génère des événements MouseWheel que l'application peut utiliser pour faire défiler les documents. Tout comme les événements clavier, cet événement est toujours redirigé vers la fenêtre qui a actuellement le focus. Lorsque vous recevez l'événement vous pouvez utiliser la substitution %D pour obtenir le champ déplacement (delta) de l'événement qui est une valeur entière de la distance dont la roulette de la souris s'est déplacée. La plus petite valeur que le système puisse rapporter est définie par l'OS. Sur les machines Windows 95 & 98 cette valeur doit être au moins de 120 avant qu'elle soit rapportée. Toutefois, des périphériques de plus haute résolution seront sans doute disponibles dans le futur. Le signe de la valeur détermine la direction dans laquelle votre widget doit se déplacer. Les valeurs positives sont associées à des déplacements vers le haut et les valeurs négatives à des déplacements vers le bas.

La dernière partie de la spécification d'un long événement est detail. Dans le cas d'un événement ButtonPress ou ButtonRelease, c'est le numéro du bouton (1-5). Si un numéro de bouton est fourni, seul un événement sur ce bouton particulier correspondra ; si aucun numéro de bouton n'est fourni, un événement correspondra sur n'importe quel bouton. Note : donner un numéro de bouton spécifique est différent de spécifier un modificateur de bouton ; dans le premier cas, on se réfère au bouton pressé ou relâché, dans le deuxième on se réfère à n'importe quel autre bouton qui est encore pressé lorsque survient l'événement en correspondance. Si un numéro de bouton est fourni type peut être omis : ce sera ButtonPress par défaut. Par exemple, le spécificateur <1> est équivalent à <ButtonPress-1>.

Si le type d'événement est KeyPress ou KeyRelease, alors detail doit être spécifié dans la forme d'un code symbolique de touche X. Les codes symboliques de touche sont des spécifications textuelles de touches particulières du clavier ; elles comprennent tous les caractères alphanumériques ASCII (par exemple ``a'' est le code symbolique du caractère ASCII ``a''), plus des descriptions pour les caractères non-alphanumériques (``comma'' est le code symbolique du caractère ``virgule''), plus des descriptions pour toutes les touches non-ASCII du clavier (``Shift_L'' est le code symbolique de la touche shift gauche, et ``F1'' est le code symbolique de la touche de fonction F1, si elle existe). La liste complète des codes symboliques n'est pas présentée ici ; elle est disponible dans d'autres documentations X et peut varier d'un système à l'autre. Si nécessaire, vous pouvez utiliser la notation 'K' décrite ci-dessous pour imprimer le nom de code symbolique d'une touche particulière. Si detail est fourni pour un code symbolique de touche, le champ type peut être omis ; sa valeur par défaut sera KeyPress. Par exemple, <Control-comma> est équivalent à <Control-KeyPress-comma>.


LIAISON DES CALLBACKS ET SUBSTITUTIONS

L'argument callback de bind est un callback perl/Tk qui sera exécuté chaque fois que la séquence donnée se présentera. (Voir Tk::callbacks pour une description des formes possibles). callback sera associé à la même MainWindow associée au $widget utilisé pour invoquer la méthode bind, et sera exécuté comme si l'appel provenait de MainLoop. Si callback contient n'importe quel appel Ev(%), chaque ``callback imbriqué'' Ev(%) sera évalué lors de l'occurrence de l'événement pour former les arguments à passer au callback principal. Le remplacement dépend du caractère %, comme défini dans la liste ci-dessous. Sauf indication contraire, la chaîne de remplacement est la valeur numérique (décimale) du champ considéré pour l'événement courant. Perl/Tk a mis un peu en valeur ce mécanisme, en comparaison du mécanisme semblable de Tcl/Tk. Les mises en valeur ne sont pas toutes reflétées dans la liste ci-dessous. Quelques substitutions sont valides uniquement pour certains types d'événement ; si on les utilise pour d'autres types d'événement la valeur substituée est indéfinie (ce qui n'est pas la même chose que undef !).

'#'
Le numéro de la dernière requête client traitée par le serveur (le champ serial de l'événement). Valide pour tous les types d'événement.

'a'
Le champ above de l'événement, formaté comme un nombre hexadécimal. Valide uniquement pour les événements Configure.

'b'
Le nombre de boutons pressés ou relâchés. Valide seulement pour les événements ButtonPress et ButtonRelease.

'c'
Le champ count de l'événement. Valide uniquement pour les événements Expose.

'd'
Le champ detail de l'événement. Le 'd' est remplacé par une chaîne identifiant le détail. Pour les événements Enter, Leave, FocusIn et FocusOut, la chaîne sera l'une de celles-ci :
  NotifyAncestor    NotifyNonlinearVirtual  NotifyDetailNone
  NotifyPointer     NotifyInferior          NotifyPointerRoot
  NotifyNonlinear   NotifyVirtual

Pour les événements ConfigureRequest, la chaîne sera l'une parmi :

  Above      Opposite
  Below      None
  BottomIf    TopIf

Pour les événements autres que ceux-là, la chaîne substituée est indéfinie. (Notez que ceci n'est pas la même chose que la partie Detail de la séquence utilisée pour spécifier l'événement.)

'f'
Le champ focus de l'événement (0 ou 1). Valide seulement pour les événements Enter et Leave.

'h'
Le champ height de l'événement. Valide seulement pour les événements Configure, ConfigureRequest, Create, Expose, et ResizeRequest.

'k'
Le champ keycode de l'événement. Valide seulement pour les événements KeyPress et KeyRelease.

'm'
Le champ mode de l'événement. La chaîne de substitution est une de celles-ci : NotifyNormal, NotifyGrab, NotifyUngrab ou NotifyWhileGrabbed. Valide uniquement pour les événements Enter, FocusIn, FocusOut et Leave.

'o'
Le champ override_redirect de l'événement. Valide seulement pour les événements Map, Reparent et Configure.

'p'
Le champ place de l'événement, substitué par une des chaînes PlaceOnTop ou PlaceOnBottom. Valide seulement pour les événements Circulate et CirculateRequest.

's'
Le champ state de l'événement. Pour les événements ButtonPress, ButtonRelease, Enter, KeyPress, KeyRelease, Leave et Motion, une chaîne décimale est substituée. Pour Visibility, une des chaînes VisibilityUnobscured, VisibilityPartiallyObscured ou VisibilityFullyObscured est substituée.

't'
Le champ time de l'événement. Valide seulement pour les événements qui contiennent un champ time.

'w'
Le champ width de l'événement. Valide uniquement pour les événements Configure, ConfigueRequest, Create, Expose et ResizeRequest.

'x'
Le champ x de l'événement. Valide seulement pour les événements contenant un champ x.

'y'
Le champ y de l'événement. Valide seulement pour les événements contenant un champ y.

'@'
La chaîne ``@x,y'' où x et y sont comme ci-dessus. Valide seulement pour les événements contenant les champs x et y. Ce format est utilisé par des méthodes de Tk::Text et de widgets similaires.

'A'
Substitue le caractère UNICODE correspondant à l'événement, ou la chaîne vide si l'événement ne correspond pas à un caractère UNICODE (par exemple la touche shift a été pressée). XmbLookupString effectue tout le travail de traduction entre l'événement et le caractère UNICODE. Valide seulement pour les événements KeyPress et KeyRelease.

'B'
Le champ border_width de l'événement. Valide seulement pour les événements Configure, ConfigureRequest et Create.

'D'
Il s'agit de la valeur de déplacement (delta) d'un événement MouseWheel. La valeur de déplacement indique de combien la roulette a tourné. Sur les systèmes Windows 95 & 98 la plus petite valeur est de 120. Les systèmes futurs fourniront une meilleure résolution. Le signe indique la direction dans laquelle la roulette a été tournée (valeur positive = déplacement vers le haut).

'E'
Le champ send_event de l'événement. Valide pour tous les types d'événement.

'K'
Une chaîne texte représentant le code de touche symbolique correspondant à l'événement. Valide seulement pour les événements KeyPress et KeyRelease.

'N'
Un nombre décimal représentant le code de touche symbolique correspondant à l'événement. Valide seulement pour les événements KeyPress et KeyRelease.

'R'
L'identificateur de fenêtre root de l'événement. Valide seulement pour les événements contenant un champ root.

'S'
L'identificateur de fenêtre subwindow de l'événement, en tant qu'objet si c'est un, sinon un nombre hexadécimal. Valide seulement pour les événements contenant un champ subwindow.

'T'
Le champ type de l'événement. Valide pour tous les types d'événement.

'W'
La fenêtre à laquelle on a notifié l'événement (le champ $widget de l'événement) - en tant qu'objet Perl//Tk. Valide pour tous les types d'événement.

'X'
Le champ x_root de l'événement. Si l'on utilise un gestionnaire de fenêtres racines virtuelles, il s'agit de la coordonnée x dans la fenêtre virtuelle. Valide seulement pour les événements ButtonPress, ButtonRelease, KeyPress, KeyRelease et Motion.

'Y'
Le champ y_root de l'événement. Si l'on utilise un gestionnaire de fenêtres racines virtuelles, il s'agit de la coordonnée y dans la fenêtre virtuelle. Valide seulement pour les événements ButtonPress, ButtonRelease, KeyPress, KeyRelease et Motion.


CORRESPONDANCES MULTIPLES

Il peut arriver que plusieurs liaisons correspondent à un événement X donné. Si les liaisons sont associées à différents tags, alors chaque liaison sera exécutée, dans l'ordre. Par défaut, une liaison de classe sera exécutée en premier, suivie par une liaison de widget, une liaison de sa toplevel, et une liaison all. La méthode bindtags peut être utilisée pour changer cet ordre pour une fenêtre particulière ou pour associer des liaisons additionnelles à la fenêtre.

return et Tk->break peuvent être utilisées dans un callback pour contrôler le traitement des callbacks en correspondance. Si return est invoquée, alors le callback courant est terminé mais Tk continuera de traiter les callbacks associés aux autres tag. Si Tk->break est invoqué dans un callback, le callback termine et aucun autre callback ne sera invoqué pour l'événement. (Tk->break est implémentée via die (de perl) avec une valeur spéciale qui est ``interceptée'' par le ``code de collage'' de perl/Tk.)

Si plus d'une liaison correspond à un événement particulier et qu'elles ont le même tag, la liaison la plus spécifique est choisie et son callback évalué. Les tests suivants sont appliqués, dans l'ordre, pour déterminer quelle est la séquence de correspondance la plus spécifique :

(a)
un motif d'événement qui spécifie une touche ou un bouton particulier sera plus spécifique qu'un autre ;

(b)
une séquence longue (en termes de nombre d'événements en correspondance) sera plus spécifique qu'une séquence courte ;

(c)
si les modificateurs spécifiés dans un motif sont un sous-ensemble des modificateurs d'un autre motif, le motif comportant le plus de modificateurs sera le plus spécifique ;

(d)
un événement virtuel dont le motif physique correspond à la séquence est moins spécifique que le même motif physique qui ne serait pas associé à un événement virtuel ;

(e)
étant donnée une séquence qui correspond à deux ou plusieurs événements virtuels, l'un des événements virtuels sera choisi, mais l'ordre est indéfini.

Si les séquences en correspondance contiennent plus d'un événement, les tests (c)-(e) seront appliqués dans l'ordre, du plus récent au moins récent des événements des séquences. Si ces tests ne permettent pas de désigner un vainqueur, la séquence enregistrée le plus récemment sera choisie.

S'il existe deux événements virtuels (ou plus) déclenchés par la même séquence, et que ces événements virtuels sont lié au même tag de fenêtre, seulement un des événements virtuels sera déclenché, aléatoirement :

  $widget->eventAdd('<<Paste>>' => '<Control-y>'); 
  $widget->eventAdd('<<Paste>>' => '<Button-2>'); 
  $widget->eventAdd('<<Scroll>>' => '<Button-2>'); 
  $widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'}); 
  $widget->bind('Tk::Entry','<<Scroll>>', sub {print 'Scroll'});

Si l'utilisateur frappe Control-y, la liaison <<Paste>> sera invoquée, mais si l'utilisateur presse le bouton 2 alors l'une des deux liaisons <<Paste>> ou <<Scroll>> sera invoquée, sans qu'on puisse savoir laquelle.

Si un événement X ne correspond à aucune liaison existante, l'événement est ignoré. Un événement non lié n'est pas considéré comme étant une erreur.


SEQUENCES MULTI-ÉVÉNEMENT ET ÉVÉNEMENTS IGNORÉS

Lorsqu'une sequence spécifiée dans une méthode bind contient plus d'un motif d'événement, son callback est exécuté même si les événements récents (jusqu'à l'événement courant et y compris ce dernier) correspondent à la séquence donnée. Cela signifie, par exemple, que si le button 1 est clické de façon répétitive la séquence <Double-ButtonPress-1> ne correspondra que la première fois. Si des événements étrangers capables de prévenir une correspondance surgissent au milieu d'une séquence d'événements ils sont alors ignorés sauf si ce sont ces événements KeyPress ou ButtonPress. Par exemple, <Double-ButtonPress-1> correspondra à une séquence de bouton 1 pressé plusieurs fois, même s'il existe des événements ButtonRelease (et peut-être aussi des événemenst Motion) entre les événements ButtonPress. De plus, un événement KeyPress peut être précédé par n'importe quel nombre d'autres événements KeyPress pour les touches de modification sans que les touches de modification annulent la correspondance. Par exemple, la séquence d'événement aB correspondra à un KeyPress de la touche a, un Keyrelease de la touche a, l'appui de la touche Shift et un appui de la touche b : presser sur Shift est ignoré parce qu'il s'agit d'une touche modificatrice. Finalement, si plusieurs événements Motion arrivent à la suite les uns de autres, seul le dernier sera considéré pour établir la correspondance des séquences de liaison.


ERREURS

Si une erreur se produit lorsqu'on exécute le calback d'une liaison le mécanisme Tk::Error est utilisé pour rapporter l'erreur. Le mécanisme Tk::Error sera exécuté au même niveau d'appel, et associé avec la même MainWindow qui a invoqué le callback.


AVERTISSEMENTS

Notez que pour le widget Canvas, l'appel de bind doit être pleinement qualifié. Ceci parce qu'il existe toujours une méthode de liaison pour le widget Canvas, qui lie individuellement chaque tag du canevas.

$canvas->Tk::bind


VOIR AUSSI

Tk::Error Tk::callbacks Tk::bindtags


MOTS-CLÉS

Event, binding


TRADUCTION

Jean-Pierre Vidal jeanpierre.vidal@free.fr


RELECTURE

Aucune relecture pour le moment.