Introduction
Les objets souris sont obtenus par l'attribut mouse
d'un objet d'affichage tel que scene. Par exemple,
pour obtenir l'entrée souris de la fenêtre par défaut créée par Visual, utilisez
scene.mouse. Pour des exemples simples de manipulation de la souris,
voir Exemple de clic de souris et Exemple de dragage
de souris.
Un objet souris possède un groupe d'attributs correspondant
à l'état courant de la souris. Il a aussi les fonctions getevent()
et getclick(), qui retournent un objet avec des attributs semblables
correspondant à l'état de la souris lors du dernier appui de l'utilisateur sur les boutons de la souris.
Si l'utilisateur n'a encore rien fait avec les boutons de la souris,
getevent() et getclick()
arrêteront l'exécution du programme jusqu'à ce que cela arrive.
Différentes sortes de souris
Les routines de l'objet souris peuvent manipuler des souris à 3 boutons,
avec les boutons "gauche", "droit", et "du milieu". Pour les systèmes avec une souris
à 2 boutons, le bouton "du milieu" est constitué des boutons gauche et droit pressés en même temps.
Pour les systèmes avec une souris à un bouton, le bouton droit est invoqué en maintenant appuyée la touche SHIFT
et le bouton du milieu est invoqué en maintenant appuyée la touche CTRL.
Etat courant de la souris
pos La position courante en 3D
du curseur de la souris; scene.mouse.pos. Visual
choisit toujours un point dans le plan parallèle à l'écran et passant à travers
display.center. (Voir Projection des informations
de la souris sur un plan donné pour d'autres options.)
button = None (pas de bouton pressé),
'left', 'right', 'middle', ou 'wheel' (molette appuyée sur certaines souris Windows).
Exemple: scene.mouse.button == 'left'
est vrai si le bouton gauche de la souris est actuellement appuyé.
pick Le plus proche objet de la scène
qui tombe sous le curseur ou None. Actuellement seuls les sphères,
boîtes, cylindres et objets convexes peuvent être sélectionnés. L'objet sélectionné est scene.mouse.pick.
pickpos Le point 3D sur
la surface de l'objet sélectionné qui tombe sous le curseur, ou None; scene.mouse.pickpos.
camera La position actuelle en lecture seule
de la caméra ainsi positionnée par l'utilisateur, scene.mouse.camera.
Par exemple, mag(scene.mouse.camera-scene.center)
est la distance du centre de la scène à la position courante de
la caméra. Si vous voulez définir la position et la direction de la caméra en le programmant, utilisez
scene.forward et scene.center,
décrit dans Contrôler la fenêtre.
ray Un vecteur unitaire pointant depuis la caméra dans la direction du curseur
de la souris. Les points sous lesquels le curseur sont exactement
{ camera + t*ray pour t>0}.
Les attributs camera
et ray définissent ensemble tous les points 3D sous le curseur de la souris.
project() Projette la position sur un plan.
Voir Projeter la position de la souris sur un plan donné.
alt = 1 si la touche ALT est pressée, sinon 0
ctrl = 1 si la touche CTRL est pressée, sinon 0
(pour une souris à un bouton, a un sens uniquement si les boutons de la souris sont non appuyés)
shift = 1 si la touche SHIFT est pressée, sinon 0
(pour une souris à un bouton, a un sens uniquement si les boutons de la souris sont non appuyés)
Notez que les programmes qui dépendent des modifications des évènements souris
avec les touches CTRL ou SHIFT ne fonctionneront pas correctement avec une souris à un bouton (ainsi pour la
plupart des systèmes Macintosh), car la touche CTRL invoque le bouton "du milieu", et la touche SHIFT
invoque le bouton "droit".
Obtention des évènements
Il y a quatre sortes d'évènements souris: press (pression), click (clic), drag (dragage)
et drop (relachement):
Un évènement press intervient lorsqu'un bouton de la souris est pressé.
Un évènement click intervient lorsque tous les boutons de la souris sont
relâchés avec aucun ou un très léger mouvement de celle-ci.
Notez qu'un évènement click arrive quand le bouton de la souris est relâché.
Voir Exemple de clic de souris.
Un évènement drag intervient lorsque la souris est déplacée
légèrement après un évènement press avec les boutons de la souris encore appuyés.
Ceci peut être utilisé pour signaler le début d'un dragage d'un objet.
Voir Exemple de dragage.
Un évènement drop intervient lorsque les boutons de la souris
sont relachés après un évènement drag.
Entre un évènement drag (début d'un dragage) et un évènement drop (fin
du dragage), il n'y a aucun évènement souris mais vous pouvez examiner continuellement
la position mise à jour de la souris indiquée par scene.mouse.pos.
Voici comment appeler un évènement qui arrive et obtenir les informations à propos de cet évènement:
events Le nombre d'évènements
(press, click, drag, ou drop) qui sont dans la file d'attente; c'est-à-dire
scene.mouse.events.
scene.mouse.events = 0 peut être utilisé pour abandonner toutes les entrées.
Aucune valeur autre que 0 ne peut être assignée.
getevent() Obtient l'évènement souris le plus vieux
et le supprime de la file d'attente d'entrées. Si aucun évènement n'attend dans la file d'attente (c'est-à-dire
si scene.mouse.events
vaut zéro), getevent() attend jusqu'à ce que l'utilisateur entre un évènement souris
(press, click, drag, ou drop). getevent()
retourne un objet avec des attributs semblables à un objet souris: pos,
button, pick, pickpos,
camera, ray,
project(), alt,
ctrl, et shift.
Ces attributs correspondent à l'état de la souris quand l'évènement arrive.
Par exemple, après avoir exécuté mm = scene.mouse.getevent()
vous pouvez visualiser les propriétés changeantes de cet évènement telles que mm.pos,
mm.pick, mm.drag
(voir ci-dessous), etc.
Si vous êtes intéressé par chaque type d'évènement (press, click,
drag, et drop), vous devez utiliser events et getevent().
Si vous n'êtes intéressé que par les évènements de clic gauche (bouton gauche appuyé et relâché sans mouvements
significatifs de la souris), vous pouvez utiliser clicked
et getclick():
clicked Le nombre de clics gauche qui sont dans la file
d'attente; c'est-à-dire scene.mouse.clicked.
Ceci n'inclut pas le nombre d'évènements autres (press, drag, ou drop).
getclick() Obtient l'évènement
clic gauche de la souris le plus vieux (pression du bouton gauche et relâchement de celui-ci dans presque la même position)
et le supprime de la file d'attente d'entrées, se débarassant de tous les évènements press, drag ou drop.
Si aucun clic n'est en attente dans la queue (c'est à dire, si scene.mouse.clicked vaut zéro),
getclick() attend jusqu'à ce que l'utilisateur clique. Autrement,
getclick() est la même chose que getevent().
C'est une technique utile de déboggage que d'insérer scene.mouse.getclick()
dans votre programme à un endroit où vous souhaitez vous arrêter temporairement pour examiner
la scène. Puis cliquez simplement pour continuer.
Informations supplémentaires obtenues avec getevent() ou getclick()
En plus des informations disponibles avec scene.mouse,
getevent() et getclick()
fournissent ces informations supplémentaires:
press = 'left' ou 'right'
ou 'middle' pour un évènement press, ou None
click = 'left' ou 'right'
ou 'middle' pour un évènement click, ou None; dans ce cas, pos
et d'autres attributs correspondent à l'état de la souris
au moment du déclenchement de l'évènement press, ainsi impossible de perdre l'information de la position
initiale. Voir Exemple de clic.
drag = 'left' ou 'right'
ou 'middle' pour un évènement drag, ou None; dans ce cas, pos
et d'autres attributs correspondent à l'état de la souris
au moment du déclenchement de l'évènement press, ainsi impossible de perdre l'information de la position
intiale. Voir Exemple de dragage.
drop = 'left' ou 'right'
ou 'middle' pour un évènement drop, ou None
release = 'left' ou 'right'
ou 'middle' suivant les évènements click et drop, indiquant quel bouton a été relâché, ou None
Normalement, draguer avec le bouton droit ou du milieu représente
une rotation ou un zoom et est traité automatiquement par Visual, si bien que vous pouvez vérifier
les évènements drag du bouton gauche ou drop simplement en vérifiant si drag
ou drop sont vrais (en Python, une chaîne de caractères non vide
telle que 'left' est vraie, None est faux). A moins que vous ne mettiez hors service le zoom par l'utilisateur (scene.userzoom
= 0), click, drag,
et drop avec le bouton du milieu sont invisibles à votre programme.
A moins que vous mettez hors service la rotation par l'utilisateur (scene.userspin
= 0), click, drag,
et drop avec le bouton droit de la souris sont invisibles à votre programme.
Projection de la position de la souris
sur un plan donné
Voici comment obtenir la position de la souris relativement à un plan particulier de l'espace:
temp = scene.mouse.project(normal=(0,1,0), point=(0,3,0))
if temp: # temp vaut None si aucun intersection avec le plan
ball.pos = temp
Ceci projette le curseur de la souris sur un plan qui est perpendiculaire
à la normale spécifiée. Si point n'est pas spécifié,
le plan passe à travers l'origine. Cela retourne une position 3D, ou None si la projection
de la souris manque le plan.
Dans l'exemple montré ci-dessus, l'utilisateur de votre programme sera
capable d'utiliser la souris pour placer la balle dans un plan parallèle au plan xy, à une hauteur de 3 au-dessus
du plan xy, peu importe que l'utilisateur ait ou non modifé le point de vue.
Vous pouvez spécifier à la place une distance perpendiculaire d
de l'origine au plan qui est perpendiculaire à la normale spécifiée.
L'exemple au-dessus est équivalent à
temp = scene.mouse.project(normal=(0,1,0), d=3)
