Carte et points de passage

La carte est dessinée sur une instance de Canvas — la classe JavaFX représentant un « canevas », c.-à-d. une surface sur laquelle il est possible de dessiner — placée dans un panneau de type Pane.

La raison pour laquelle il est nécessaire de placer le canevas dans un panneau est que, contrairement au canevas, le panneau est redimensionné automatiquement lorsqu'il est placé dans certains composants. Cela est utile pour garantir que le panneau (et donc la carte) occupe la totalité de la fenêtre de l'interface.

Sachant que le canevas n'est pas redimensionné automatiquement, il faut utiliser des liens JavaFX (bindings) pour faire en sorte que sa largeur et sa hauteur soient toujours égales à celles du panneau. Pour la largeur, cela peut se faire ainsi :

canvas.widthProperty().bind(pane.widthProperty());

Pour dessiner sur un canevas, il faut obtenir ce que l'on nomme son contexte graphique (graphics context) au moyen de la méthode getGraphicsContext2D. Ce contexte, de type GraphicsContext, possède de nombreuses méthodes permettant de définir les paramètres de dessin (couleur du trait, épaisseur, etc.) et de dessiner.

Pour dessiner la carte, une fois le contexte graphique obtenu, on peut utiliser sa méthode drawImage pour dessiner chacune des tuiles visible au moins partiellement. Ces tuiles sont obtenues du gestionnaire de tuiles, et si ce dernier lève une exception (de type IOException), la tuile correspondante n'est simplement pas dessinée.

La carte doit être redessinée à chaque changement des paramètres de la carte affichée (niveau de zoom ou coin haut-gauche), ainsi qu'à chaque changement des dimensions du canevas.

Le dessin de la carte étant relativement cher, il est important de le retarder autant que possible. Par exemple, si l'utilisateur redimensionne rapidement la fenêtre, il faudrait éviter de redessiner la totalité de la carte au moindre changement.

Pour cela, nous vous proposons une technique qui consiste à retarder le redessin jusqu'au prochain « battement » (pulse) JavaFX. Sans rentrer dans les détails, JavaFX met généralement à jour le dessin de l'interface 60 fois par seconde, si cela est nécessaire. Chacune de ces mises à jour est nommée un « battement ». En retardant le redessin de la carte au prochain battement, on garantit qu'elle n'est pas redessinée plus de 60 fois par seconde.

Retarder ainsi le redessin n'est pas très facile et utilise des notions avancées de JavaFX, donc nous vous offrons ici une solution « clefs en main ». Il vous faut dans un premier temps ajouter à votre classe un attribut booléen nommé redrawNeeded, qui ne sera vrai que si un redessin de la carte est nécessaire. Ensuite, il vous faut y ajouter une méthode privée nommée redrawIfNeeded effectuant le redessin si et seulement si cet attribut est vrai :

private void redrawIfNeeded() {
  if (!redrawNeeded) return;
  redrawNeeded = false;

  // … à faire : dessin de la carte
}

Ensuite, il faut vous assurer que JavaFX appelle bien cette méthode à chaque battement, ce qui se fait au moyen du code ci-dessous, à ajouter au constructeur de votre classe :

canvas.sceneProperty().addListener((p, oldS, newS) -> {
    assert oldS == null;
    newS.addPreLayoutPulseListener(this::redrawIfNeeded);
  });

Finalement, il faut ajouter une méthode privée à votre classe permettant de demander un redessin au prochain battement. Cela se fait en mettant à vrai l'attribut redrawNeeded, et en forçant JavaFX à effectuer le prochain battement, même si de son point de vue cela n'est pas nécessaire :

private void redrawOnNextPulse() {
  redrawNeeded = true;
  Platform.requestNextPulse();
}

Une fois tout cela en place, il ne vous reste plus qu'à appeler la méthode redrawOnNextPulse lorsqu'un redessin est nécessaire.

BaseMapManager doit détecter et gérer trois types d'événements :

1. l'utilisation de la molette de la souris, qui permet de changer le niveau de zoom de la carte,
2. le déplacement de la souris lorsque le bouton gauche est maintenu pressé, qui permet de faire glisser la carte,
3. le clic sur la carte, qui permet d'ajouter un point de passage.

Les deux derniers types d'événements sont similaires puisqu'ils impliquent tous deux un clic, la différence étant que dans un cas la souris bouge entre le moment où le bouton est pressé et celui où il est relâché, alors que dans l'autre cas elle reste stationnaire.

Pour gérer ces types d'événements, il faut installer des gestionnaires sur le panneau contenant la carte, au moyen des méthodes setOnScroll (changement du niveau de zoom), setOnMousePressed, …Dragged, …Released (glissement de la carte) et setOnMouseClicked (ajout d'un point de passage).

Comme tous les gestionnaires d'événements JavaFX, ceux qu'on installe au moyen de ces méthodes reçoivent en argument un événement, de type MouseEvent pour tous les gestionnaires susmentionnés sauf celui passé à setOnScroll, qui reçoit un événement de type ScrollEvent. Ces événements possèdent plusieurs méthodes utiles parmi lesquelles :

• getX() et getY(), qui permettent de connaître la position du curseur de la souris,
• isStillSincePress(), qui permet de savoir si la souris est restée stationnaire depuis le moment où son bouton a été pressé,
• getDeltaY() (ScrollEvent uniquement), qui permet de savoir de combien d'unités la molette de la souris a été tournée.

La valeur retournée par getDeltaY est à ajouter au niveau de zoom courant pour obtenir, après arrondissement à l'entier le plus proche, le nouveau niveau de zoom, qui doit toutefois être limité à la plage allant de 8 à 19. Comme cela a été mentionné plus haut, le point se trouvant sous le pointeur de la souris ne doit pas bouger lorsque le niveau de zoom change.

Les trois gestionnaires d'événements gérant le glissement de la carte doivent déterminer de combien d'unités la souris s'est déplacée le long des deux axes. Un moyen simple de faire cela est de stocker dans une propriété JavaFX la position à laquelle se trouvait la souris lors de l'événement précédent, représentée par une valeur de type Point2D. Cette classe possède des méthodes (add, subtract, etc.) permettant de facilement faire les calculs nécessaires.

En plus de ces gestionnaires d'événements, BaseMapManager doit également mettre en place des auditeurs JavaFX qui détectent les situations dans lesquelles le fond de carte doit être redessiné, et appeler redrawOnNextPulse dans ce cas. Cela se fait facilement en ajoutant un auditeur détectant les changements des paramètres du fond de carte et des dimensions du canevas — c.-à-d. ses propriétés width et height.

Chaque marqueur représentant un point de passage est un groupe JavaFX, de type Group, contenant deux fils, qui sont chacun un chemin SVG de type SVGPath. Les groupes représentant les marqueurs sont les fils directs d'un panneau de type Pane.

Le premier de ces chemins est le contour extérieur du marqueur, et la classe de style pin_outside lui est attachée. Le second de ces chemins est le disque blanc intérieur du marqueur, et la classe de style pin_inside lui est attachée. Finalement, la classe de style pin est attachée au groupe lui-même, de même que la classe first s'il s'agit du premier point de passage, last s'il s'agit du dernier, et middle sinon.

La méthode setContent de SVGPath peut être utilisée pour donner le texte du chemin SVG à un nœud de ce type.

Les chemins SVG des marqueurs ont été construits de manière à ce que leur origine se trouve au bout de leur pointe. Pour les placer correctement sur la carte, il suffit donc de les positionner aux coordonnées du point de passage qui leur correspond.

Ce positionnement doit obligatoirement être fait au moyen des méthodes setLayoutX et setLayoutY, appliquées aux groupes représentant les marqueurs. Les coordonnées à passer à ces méthodes sont exprimées dans le système du panneau contenant tous les marqueurs, qui est identique à celui du panneau montrant la carte car les deux panneaux sont toujours superposés — voir le programme de test de la §3.4 pour un exemple.

WaypointsManager doit détecter et gérer deux types d'événements :

1. le déplacement de la souris lorsque le bouton gauche est maintenu pressé sur un marqueur de point de passage, qui permet de le déplacer,
2. le clic sur un marqueur de point de passage, qui permet de le supprimer.

Les gestionnaires d'événements correspondants doivent être installés sur chacun des groupes représentant un marqueur. Pour éviter que ces gestionnaires n'empêchent ceux du fond de carte d'être activés, il faut impérativement appeler la méthode setPickOnBounds avec false en argument sur le panneau contenant les marqueurs.

Lorsqu'un marqueur est en cours de déplacement, il est effectivement déplacé visuellement, mais le point de passage auquel il correspond ne change pas avant que le bouton de la souris ne soit relâché. À ce moment-là, le nœud le plus proche du pointeur de la souris est recherché dans un cercle de 1000 m de diamètre centré sur lui, et s'il existe, le point de passage est changé. Sinon, une erreur est signalée (voir la section suivante) et le point de passage ne change pas.

En plus de ces gestionnaires d'événements, WaypointsManager doit également mettre en place des auditeurs qui détectent les situations dans lesquelles les marqueurs doivent être recréés et/ou repositionnés, à savoir :

1. un auditeur détectant les changements de la propriété contenant les paramètres du fond de carte et repositionnant les marqueurs,
2. un auditeur détectant les changements de la liste contenant les points de passage et recréant la totalité des marqueurs.

Pour faciliter l'écriture de ces auditeurs, il paraît judicieux de placer le code créant les marqueurs dans une première méthode privée, et le code les positionnant dans une seconde méthode privée.

Lorsqu'un point de passage est ajouté ou déplacé à un endroit donné et qu'aucun nœud ne se trouve proche de cet endroit, une erreur est signalée et l'action est annulée.

Pour pouvoir signaler des erreurs, le constructeur de WaypointsManager reçoit en argument une valeur de type Consumer<String>. L'interface Consumer fait partie de la bibliothèque Java et représente un « consommateur de valeurs » d'un type donné. Sa méthode accept prend justement une valeur et la consomme, dans le sens où elle ne retourne aucun résultat.

Le consommateur passé au constructeur de WaypointsManager prend en argument un message d'erreur, sous la forme d'une chaîne de caractères, et se charge de l'afficher à l'écran pour informer l'utilisateur du problème. Dans le programme de test donné plus bas, ce consommateur se contente d'afficher le message sur la console, mais dans la version finale du projet, le message sera affiché dans l'interface graphique.

Les deux cas dans lesquels WaypointsManager doit signaler une erreur sont :

1. lorsqu'on demande à addWaypoint d'ajouter un point de passage à un endroit qui n'est pas assez proche d'un nœud du graphe,
2. lorsqu'un marqueur de point de passage est déplacé à un endroit qui n'est pas assez proche d'un nœud du graphe.

Dans ces deux cas, le message à passer au consommateur est le même :

Aucune route à proximité !