=head1 NOM

Tk::event - Facilités diverses pour la gestion d'événements : définir des
événements virtuels, générer des événements

=head1 SYNOPSIS

I<$widget>-E<gt>B<event>I<Action>(?I<arg>, I<arg>, I<...>?);

=head1 DESCRIPTION

Les méthodes B<event>I<Action> fournissent diverses facilités pour jouer avec
les événements du système de fenêtres, comme définir des événements virtuels
ou synthétiser des événements. Les événements virtuels sont partagés par tous
les widgets de la même B<MainWindow>. Des MainWindows différentes peuvent
avoir des événements virtuels différents.

Les méthodes suivantes sont actuellement supportées :

=over 4

=item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>, I<sequence> ?, I<sequence>, I<...>?) 

Associe l'événement virtuel I<virtual> avec la séquence d'événements physiques
donnée par les arguments I<sequence>, ainsi l'événement virtuel sera déclenché
chaque fois que l'une des I<sequence>s se produit. I<virtual> peut être
n'importe quelle valeur chaîne et I<sequence> peut prendre toutes les valeurs
permises pour l'argument I<sequence> de la méthode bind. Si I<virtual> est
déjà défini, les nouvelles séquences d'événements physiques s'ajoutent aux
séquences existant pour l'événement.

=item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?, I<sequence>, I<sequence>, I<...>?) 

Supprime chaque I<sequence> de celles associées à l'événement virtuel
I<virtual>. I<virtual> peut être n'importe quelle valeur chaîne et I<sequence>
peut prendre toutes les valeurs permises pour l'argument I<sequence> de la
méthode bind.  Toutes les I<sequence>s qui ne sont pas actuellement associées
à I<virtual> sont ignorées.  Si l'on ne fournit aucun argument I<sequence>,
toutes les séquences d'événements physiques sont supprimées de I<virtual>, par
conséquent cet événement virtuel ne sera plus jamais déclenché.

=item I<$widget>-E<gt>B<eventGenerate>(I<event> ?, I<option> =E<gt> I<value>, I<option> =E<gt> I<value>, I<...>?) 

Génère un événement fenêtre et fait en sorte qu'il soit traité comme s'il
provenait du système de fenêtres.  I<$window> est une référence à la fenêtre
pour laquelle l'événement a été généré. I<Event> fournit une description de
base de l'événement, telle que B<E<lt>Shift-Button-2E<gt>> ou
B<E<lt>E<gt>PasteE<gt>E<gt>>. Si I<Window> est vide l'écran entier est
concerné, et les coordonnées sont relatives à l'écran. I<Event> peut avoir
toute forme permise pour l'argument I<sequence> de la méthode bind sauf qu'il
doit consister en un seul motif d'événement et non une séquence.  Des paires
I<Option-value> peuvent être utilisées pour spécifier des attributs
additionnels pour l'événement, tels que les positions x et y de la souris ;
voir "CHAMPS D'UN ÉVÉNEMENT" ci-dessous. Si l'option B<-when> n'est pas
spécifiée, l'événement est traité immédiatement : tous les handlers de
l'événement doivent avoir terminé avant que la méthode B<eventGenerate> ne
rende la main.  Si l'option B<-when> est spécifiée elle détermine le moment où
l'événement sera traité.

=item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>>'?) 

Renvoie l'information associée à l'événement virtuel.  Si l'argument
B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> est omis, la valeur de retour est une
liste de tous les événements virtuels actuellement définis.  Si
B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> est spécifié la valeur de retour est une
liste des séquences d'événements physiques actuellement définis pour
l'événement virtuel ; si l'événement virtuel n'est pas défini B<undef> est
renvoyé.

=back

=head1 CHAMPS D'UN ÉVÉNEMENT

La méthode B<eventGenerate> supporte les options suivantes ; elles
correspondent aux expansions ``%'' permises dans les callbacks de liaison pour
la méthode bind.

=over 4

=item B<-above> =E<gt> I<window> 

I<window> spécifie le champ I<above> de l'événement, soit comme un nom de
chemin de fenêtre soit comme un identifiant de fenêtre. Valide pour les
événements B<Configure>. Correspond à la substitution %a des scripts de
liaison.

=item B<-borderwidth> =E<gt> I<size>

I<size> doit être une distance d'écran ; elle spécifie le champ
I<border_width> de l'événement. Valide pour les événements
B<Configure>. Correspond à la substitution %B des scripts de liaison.

=item B<-button> =E<gt> I<number>

I<number> doit être un entier ; il spécifie le champ I<detail> pour un
événement B<ButtonPress> ou B<ButtonRelease>, écrasant tout numéro de bouton
fourni dans la base de l'argument I<event>. Correspond à la substitution %b
des scripts de liaison.

=item B<-count> => I<number>

I<number> doit être un entier ; il spécifie le champ I<count> de
l'événement. Valide pour les événements B<Expose>. Correspond à la
substitution %c des scripts de liaison.

=item B<-detail> => I<detail>

I<detail> spécifie le champ I<detail> de l'événement et doit être un des
suivants :

  NotifyAncestor   NotifyNonlinearVirtual  NotifyDetailNone
  NotifyPointer    NotifyInferior          NotifyPointerRoot
  NotifyNonlinear  NotifyVirtual

Valide pour les événements B<Enter>, B<Leave>, B<FocusIn> et
B<FocusOut>. Correspond à la substitution %d des scripts de liaison.

=item B<-focus> I<boolean> 

I<boolean> doit être une valeur booléenne ; elle spécifie le champ I<focus>
pour l'événement. Valide pour les événements B<Enter> et B<Leave>. Correspond
à la substitution %f des scripts de liaison.

=item B<-height> I<size>

I<size> doit être une distance d'écran ; elle spécifie le champ I<height> pour
l'événement. Valide pour les événements B<Configure>. Correspond à la
substitution %h des scripts de liaison.

=item B<-keycode> I<number>

I<number> doit être un entier ; il spécifie le champ I<keycode> de
l'événement. Valide pour les événements B<KeyPress> et
B<KeyRelease>. Correspond à la substitution %k des scripts de liaison.

=item B<-keysym> I<name>

I<name> doit être un nom valide de code symbolique de touche, tel que B<g>,
B<space>, ou B<Return> ; la valeur correspondante de code de touche est
utilisée comme champ I<keycode> de l'événement, écrasant tout détail spécifié
dans l'argument de base de I<event>.  Valide pour les événements B<KeyPress>
et B<KeyRelease>. Correspond à la substitution %K des scripts de liaison.

=item B<-mode> I<notify>

I<notify> spécifie le champ I<mode> de l'événement et doit être l'un parmi
B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, ou
B<NotifyWhileGrabbed>. Valide pour les événements B<Enter>, B<Leave>,
B<FocusIn> et B<FocusOut>. Correspond à la substitution %m des scripts de
liaison.

=item B<-override> I<boolean>

I<boolean> doit être une valeur booléenne ; elle spécifie le champ
I<override_redirect> de l'événement. Valide pour les événements B<Map>,
B<Reparent> et B<Configure>. Correspond à la substitution %o des scripts de
liaison.

=item B<-place> I<where>

I<where> spécifie le champ I<place> de l'événement ; sa valeur est
B<PlaceOnTop> ou B<PlaceOnBottom>. Valide pour les événements
B<Circulate>. Correspond à la substitution %p des scripts de liaison.

=item B<-root> I<window>

I<window> est soit un nom de chemin de fenêtre soit un entier identifiant de
fenêtre ; il spécifie le champ I<root> de l'événement. Valide pour les
événements B<KeyPress>, B<KeyRelease>, B<ButtonPress>, B<ButtonRelease>,
B<Enter>, B<Leave> et B<Motion>. Correspond à la substitution %R des scripts
de liaison.

=item B<-rootx> I<coord>

I<coord> doit être une distance d'écran ; elle spécifie le champ I<x_root> de
l'événement. Valide pour les événements B<KeyPress>, B<KeyRelease>,
B<ButtonPress>, B<ButtonRelease>, B<Enter>, B<Leave> et B<Motion>. Correspond
à la substitution %X des scripts de liaison.

=item B<-rooty> I<coord>

I<coord> doit être une distance d'écran ; elle spécifie le champ I<y_root> de
l'événement. Valide pour les événements B<KeyPress>, B<KeyRelease>,
B<ButtonPress>, B<ButtonRelease>, B<Enter>, B<Leave> et B<Motion>. Correspond
à la substitution %Y des scripts de liaison.

=item B<-sendevent> I<boolean>

I<boolean> doit être une valeur booléenne ; elle spécifie le champ
I<send_event> de l'événement. Valide pour tous les événements. Correspond à la
substitution %E des scripts de liaison.

=item B<-serial> I<number>

I<number> doit être un entier ; il spécifie le champ I<serial> de
l'événement. Valide pour tous les événements. Correspond à la substitution %#
des scripts de liaison.

=item B<-state> I<state>

I<state> spécifie le champ I<state> de l'événement. Une valeur entière pour
les événements B<KeyPress>, B<KeyRelease>, B<ButtonPress>, B<ButtonRelease>,
B<Enter>, B<Leave> et B<Motion>. Pour les événements B<Visibility> ce doit
être B<VisibilityUnobscured>, B<VisibilityPartiallyObscured> ou
B<VisibilityFullyObscured>. Cette option outrepasse tout modificateur tel que
B<Meta> or B<Control> qui serait spécifié pour l'I<événement> de
base. Correspond à la substitution %s des scripts de liaison.

=item B<-subwindow> I<window>

I<window> spécifie le champ I<subwindow> de l'événement, soit le nom de chemin
d'un widget Tk soit un identifiant de fenêtre. Valide pour les événements
B<KeyPress>, B<KeyRelease>, B<ButtonPress>, B<ButtonRelease>, B<Enter>,
B<Leave> et B<Motion>. Correspond à la substitution %S des scripts de liaison.

=item B<-time> I<integer>

I<integer> doit être une valeur entière ; elle spécifie le champ I<time> de
l'événement. Valide pour les événements B<KeyPress>, B<KeyRelease>,
B<ButtonPress>, B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion> et
B<Property>. Correspond à la substitution %t des scripts de liaison.

=item B<-warp> I<boolean>

I<boolean> doit être une valeur booléenne ; elle spécifie si le pointeur
d'écran doit être déformé [whether the screen pointer should be warped as
well.] Valide pour les événements B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
B<ButtonRelease> et B<Motion>.

=item B<-width> I<size>

I<size> doit être une distance d'écran ; elle spécifie le champ I<width> de
l'événement. Valide pour les événements B<Configure>. Correspond à la
substitution %w des scripts de liaison.

=item B<-when> I<when>

I<when> détermine le moment où l'événement doit être traité ; il doit avoir
l'une des valeurs suivantes :

=over 8

=item B<now>

Traiter l'événement immédiatement, avant que la commande se termine. C'est le
comportement par défaut lorsque l'option B<-when> est omise.

=item B<tail> 

Place l'événement dans la file d'événements de perl/Tk après tous les
événements déjà programmés pour cette application.

=item B<head>

Place l'événement en tête de la file d'événements de perl/Tk, ainsi il sera
traité avant tout événement se trouvant déjà dans cette file.

=item B<mark>

Place l'événement au début de la file d'événements de perl/Tk's mais après
tout autre événement comportant une B<marque -when>. Cette option est très
utile lorsqu'on génère une série d'événements devant être traités dans l'ordre
mais en tête de la file.

=back

=item B<-x> I<coord>

I<coord> doit être une distance d'écran ; elle spécifie le champ I<x> de
l'événement. Valide pour les événements B<KeyPress>, B<KeyRelease>,
B<ButtonPress>, B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, B<Expose>,
B<Configure>, B<Gravity> et B<Reparent>. Correspond à la substitution %x des
scripts de liaison. Si I<Window> est vide la coordonnée est relative à
l'écran, et cette option correspond à la substitution %X des scripts de
liaison.

=item B<-y> I<coord>

I<coord> doit être une distance d'écran ; elle spécifie le champ I<y> de
l'événement. Valide pour les événements B<KeyPress>, B<KeyRelease>,
B<ButtonPress>, B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>, B<Expose>,
B<Configure>, B<Gravity> et B<Reparent>. Correspond à la substitution %y des
scripts de liaison. Si I<Window> est vide la coordonnée est relative à
l'écran, et cette option correspond à la substitution %Y des scripts de
liaison.

Toute option non spécifiée lors de la génération d'un événement est
initialisée à la valeur 0, sauf I<serial>, qui est initialisée avec le numéro
de série de l'événement X suivant.

=back

=head1 EXEMPLES D'ÉVÉNEMENTS VIRTUELS

Pour qu'un événement virtuel soit déclenché deux choses doivent se
produire. Tout d'abord, l'événement virtuel doit être défini avec la méthode
B<eventAdd>. Ensuite, une liaison doit être créée pour cet événement virtuel
au moyen de la méthode B<bind>. Considérons les définitions suivantes
d'événements virtuels :

  $widget->eventAdd('<<Paste>>' => '<Control-y>'); 
  $widget->eventAdd('<<Paste>>' => '<Button-2>'); 
  $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>'); 
  $widget->eventAdd('<<Save>>' => '<Shift-F12>');

Dans la méthode B<bind>, un événement virtuel peut être lié avec un autre type
d'événement construit de cette manière :

  $entry->bind('Tk::Entry', '<<Paste>>' => sub {
      $entry->Insert($entry->selectionGet) });

"<<" et ">>" sont utilisés pour spécifier qu'on est en train de lier un
événement virtuel. Si l'utilisateur frappe Control-y ou presse le bouton 2, ou
si un événement virtuel B<E<lt>E<lt>PasteE<gt>E<gt>> est synthétisé avec
B<eventGenerate>, la liaison B<E<lt>E<lt>PasteE<gt>E<gt>> sera invoquée.

Si une liaison virtuelle a exactement la même séquence qu'une liaison physique
différente, la liaison physique aura la précédence. Considérons l'exemple
suivant :

  $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>'); 
  $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'}); 
  $mw->bind('Tk::Entry', '<<Paste>>'   => sub{print 'Paste'});

Lorsque l'utilisateur frappe Control-y la liaison B<E<lt>Control-yE<gt>> sera
invoquée, car un événement physique est prioritaire sur un événement virtuel,
toutes choses égales par ailleurs. Toutefois si l'utilisateur frappe
Meta-Control-y la liaison B<E<lt>E<lt>PasteE<gt>E<gt>> sera invoquée, car le
modificateur B<Meta> du motif physique associé à la liaison virtuelle est plus
spécifique que la séquence B<E<lt>Control-yE<gt>> de l'événement physique.

Les liaisons d'un événement virtuel doivent être créées avant que l'événement
virtuel existe. Bien entendu, l'événement virtuel n'a pas besoin d'êre défini,
par exemple sur les plateformes où l'événement virtuel n'aurait pas de sens ou
ne pourrait pas être généré.

Lorsque la définition d'un événement virtuel change au moment du run, toutes
les fenêtres répondent immédiatement à la nouvelle définition. En partant de
l'exemple précédent, si le code suivant est exécuté :

  $entry->bind(ref($entry), '<Control-y>' => undef); 
  $entry->eventAdd('<<Paste>>' => '<Key-F6>');

le comportement changera de deux manières. D'abord, la liaison cachée
B<E<lt>E<lt>PasteE<gt>E<gt>> va émerger. Frapper Control-y n'invoquera plus la
liaison B<E<lt>Control-yE<gt>>, mais plutôt l'événement virtuel
B<E<lt>E<lt>PasteE<gt>E<gt>>. Ensuite, la touche F6 invoquera maintenant la
liaison B<E<lt>E<lt>PasteE<gt>E<gt>>.

=head1 VOIR AUSSI

Tk::bind Tk::callbacks

=head1 MOTS-CLÉS

event, binding, define, handle, virtual event

=head1 TRADUCTION

Jean-Pierre Vidal jeanpierre.vidal@free.fr 

=head1 RELECTURE
Aucune relecture pour le moment.