État observable

La vue de la carte (map view) est la partie de l'interface portant le numéro 1 sur la figure 1 et montrant la carte de la Suisse sur laquelle la partie se déroule. Cette carte est constituée d'un fond, une image fixe présentée ci-dessous, au-dessus duquel les routes sont ensuite dessinées.

Une route est représentée par un nombre de cases égal à sa longueur. Chaque case est un rectangle coloré de la couleur de la route — ou en gris si la route n'a pas de couleur. Ce rectangle est entouré d'un trait plein s'il s'agit d'une route en surface, traitillé s'il s'agit d'un tunnel.

Lorsqu'une route appartient à l'un des joueurs, chacune des cases qui la compose est recouverte d'un rectangle de la couleur du joueur et de deux disques, symbolisant un wagon du propriétaire.

Nous appellerons vue des pioches (decks view) la partie de l'interface portant le numéro 2 sur la figure 1 et montrant, de haut en bas, la pioche des billets, les cinq cartes disposées face visible, et la pioche des cartes.

Les deux pioches sont représentées par de simples boutons intitulés Billets et Cartes. Sous chacun de ces intitulés figure une jauge donnant une idée du nombre de cartes restant dans la pioche. Le niveau de cette jauge est toujours relatif au nombre total de cartes dans le jeu : 46 pour les billets, 110 pour les cartes.

La figure ci-dessous montre par exemple le bouton représentant la pioche des billets en début de partie. Étant donné que 10 billets sur 46 ont déjà été distribués à ce stade, la jauge montre un taux de remplissage de 36/46, soit environ 78%.

Nous appellerons vue de la main (hand view) la partie de l'interface portant le numéro 3 sur la figure 1 et montrant les billets et les cartes que le joueur auquel correspond l'interface a en main.

Dans la partie gauche de cette vue se trouve la liste des billets, qui sont chacun représentés textuellement de la manière décrite à la §2.4.5 de l'étape 1.

À droite de la liste des billets se trouvent les cartes wagon/locomotive. Elles apparaissent dans l'ordre utilisé dans l'énumération Card : wagon noir, puis wagon violet, puis wagon bleu, et ainsi de suite jusqu'à locomotive.

L'image représentant un type de carte donné n'est visible que lorsque le joueur en possède au moins une dans sa main. S'il en possède au moins deux, leur nombre apparaît de plus superposé à l'image de la carte. La figure ci-dessous montre un exemple d'une main contenant un total de six cartes.

Pour clarifier la manière dont les différentes propriétés doivent être créées et gérées par ObservableGameState, cette section présente plus en détail le cas des propriétés contenant les cartes disposées face visible.

Pour commencer, étant donné que nous avons ici affaire à un groupe de (cinq) propriétés, celles-ci ne sont pas stockées comme des attributs individuels. Au lieu de cela, elles sont placées dans une collection, ici une liste, qui est elle stockée dans un attribut. Ce dernier peut être déclaré et initialisé ainsi :

private final List<ObjectProperty<Card>> faceUpCards =
  createFaceUpCards();

où createFaceUpCards est une méthode statique privée retournant une liste de cinq propriétés qui sont des instances de SimpleObjectProperty<Card>. Bien entendu, ce code d'initialisation pourrait aussi être placé dans le constructeur.

Dans la méthode setState, le contenu de ces cinq propriétés est mis à jour en fonction du nouvel état reçu, que l'on suppose stocké dans newGameState :

for (int slot : FACE_UP_CARD_SLOTS) {
  Card newCard = newGameState.cardState().faceUpCard(slot);
  faceUpCards.get(slot).set(newCard);
}

Finalement, une méthode permet d'obtenir la propriété correspondant à un emplacement donné :

public ReadOnlyObjectProperty<Card> faceUpCard(int slot) {
  return faceUpCards.get(slot);
}

Notez que cette méthode est déclarée comme retournant une valeur de type ReadOnlyObjectProperty<Card> alors qu'elle retourne en fait une valeur de type ObjectProperty<Card>. Cela est valide car le second type est un sous-type du premier, et a l'avantage d'indiquer clairement à l'utilisateur de la méthode que la propriété n'est pas destinée à être modifiée.

Bien entendu, il est toujours possible de faire un « cast » de la valeur retournée en ObjectProperty<Card> puis de modifier son contenu, mais la probabilité de faire cela par erreur est infime. Sachant que notre but est d'éviter les erreurs involontaires, et pas les attaques d'utilisateurs malintentionnés, celui-ci semble atteint.

Faites bien attention au fait que les propriétés JavaFX sont des objets observables, ce qui implique qu'ils doivent être créés une fois pour toutes au moment de la création de la classe. Ensuite, la valeur contenue dans ces propriétés doit être mise à jour à chaque appel de setState, mais les propriétés elles-mêmes doivent rester identiques.

JavaFX définit plusieurs hiérarchies de classes représentant chacune une propriété contenant une valeur d'un type donné. Par exemple, une propriété contenant un objet de type T est représenté par une hiérarchie de classes qui inclut, entre autres, les classes :

• ReadOnlyObjectProperty<T>, représentant une propriété (abstraite) en lecture seule,
• ObjectProperty<T>, représentant une propriété (abstraite) en lecture/écriture,
• SimpleObjectProperty<T>, représentant une propriété concrète.

Ces classes sont données ici de haut en bas, c-à-d que chaque classe hérite, directement ou indirectement, des classes apparaissant avant elle.

Comme l'exemple de la section précédente l'illustre, il est conseillé d'utiliser :

• le type en lecture seule (ReadOnly…) comme type de retour de la méthode d'accès, afin que l'appelant ne puisse modifier le contenu de la propriété par erreur,
• le type « de base » dans le type de l'attribut,
• la classe concrète (Simple…) pour créer l'instance.

En plus de ObjectProperty, JavaFX définit d'autres hiérarchies de classes représentant des propriétés spécialisées contenant des valeurs de type spécifique. Pour ObservableGameState, les hiérarchies suivantes sont utiles :

• ReadOnly-, Simple- et BooleanProperty, pour les propriétés contenant une valeur booléenne, et
• ReadOnly-, Simple- et IntegerProperty, pour les propriétés contenant un entier.

De plus, l'interface ObservableList, qui représente une liste observable, est utile pour stocker la liste des billets du joueur. Il est possible d'en créer une instance en utilisant la méthode observableArrayList de FXCollections.

Une partie du graphe de scène de la vue de la carte est représentée sur la figure 5 plus bas. Chaque rectangle blanc représente un nœud JavaFX, et certains d'entre eux sont accompagnés d'annotations colorées qui donnent :

• en vert, les feuilles de style CSS à attacher au nœud en modifiant la liste retournée par getStylesheets,
• en rouge, l'identité des nœuds, à définir au moyen de la méthode setId,
• en bleu, les classes de style à associer au nœud en modifiant la liste retournée par getStyleClass.

Comme cette image l'illustre, la vue de la carte est une instance de Pane.

Son premier fils est une instance de ImageView contenant le fond de carte. L'image que ce nœud affiche est déterminée par une règle du fichier map.css, et createMapView n'a donc rien à faire d'autre que le créer et le placer dans le graphe de scène.

Chacun des fils suivants — seul le premier est montré ici — est un groupe représentant une route. L'identité de ce groupe est celle de la route, p.ex. AT1_STG_1 dans la figure ci-dessous. Cette route, qui relie Saint-Gall à l'Autriche, est la première définie dans la classe ChMap.

Une route est composée à son tour de plusieurs groupes, un par case de la route. L'identité de chacun de ces groupes est constituée de l'identité de la route suivi d'un caractère souligné (_) puis du numéro de la case, qui va de 1 à la longueur de la route. Par exemple, la première case de la route AT1_STG_1, visible dans la figure ci-dessous, porte l'identité AT1_STG_1_1.

Chacune des cases est composée de la « voie » — le rectangle coloré visible lorsque personne ne s'est encore emparé de la route — et du wagon, le rectangle orné de deux disques blancs visible lorsqu'un joueur s'est emparé de la route. Notez que le wagon est toujours présent dans le graphe de scène, mais n'est visible que lorsque l'identité d'un joueur y est attachée, comme décrit à la section suivante.

Les dimensions et positions des différentes formes géométriques du graphe de scène donné ci-dessus sont les suivantes :

• les deux rectangles ont une largeur de 36 unités, et une hauteur de 12 unités,
• les deux cercles ont un rayon de 3 unités, sont centrés verticalement dans le rectangle, et placés horizontalement à 6 unités de chaque côté de son centre.

Notez que lorsque vous créez les instances de Circle représentant les cercles, la position du centre que vous devez spécifier est relative au groupe. Dès lors, pour les placer comme demandé, il faut centrer le premier en (12, 6), le second en (24, 6).

Les groupes représentant les routes sont positionnés par la feuille de style map.css, qui contient par exemple la règle suivante :

#AT1_STG_1_1 {
    -fx-translate-x: 947;
    -fx-translate-y: 204;
    -fx-rotate: 20
}

Cette règle spécifie la position et l'orientation de la case donnée en exemple sur la figure 5. Cela implique que createMapView ne doit pas positionner ces éléments graphique, il lui suffit de les créer et de les placer dans le graphe de scène.

Lorsqu'un joueur s'empare d'une route, la classe correspondant à l'identité du joueur — PLAYER_1 pour le premier joueur, PLAYER_2 pour le second — doit être ajoutée au groupe représentant la route. Par exemple, si le second joueur s'emparait de la route d'identité AT1_STG_1, la classe PLAYER_2 devrait être ajoutée aux trois que le nœud Group portant la même identité dans la figure 5 possède déjà, à savoir route, UNDERGROUND et NEUTRAL.

Une manière simple de faire cela consiste à attacher un auditeur à la propriété de l'état de jeu observable contenant le propriétaire de la route. Dès que son contenu devient différent de null, la classe correspondant au propriétaire de la route est attachée au nœud. Sachant que le propriétaire d'une route ne peut pas changer, il n'est pas nécessaire de gérer le cas où la route aurait déjà un propriétaire.

Finalement, le groupe représentant une route ne doit être « activé » — selon la terminologie JavaFX — que lorsque le joueur a la possibilité de s'emparer de la route. Le fait qu'un nœud JavaFX soit activé signifie qu'il reçoit les événements comme les clics de la souris, qui sont justement utilisés par les joueurs pour s'emparer d'une route, comme expliqué à la section suivante.

Pour désactiver le groupe représentant une route lorsque le joueur ne peut pas s'en emparer, il suffit de lier sa propriété disableProperty à une propriété qui n'est vraie que lorsque :

1. la propriété passée en argument à createMapView et contenant le gestionnaire d'action à utiliser lorsque le joueur désire s'emparer d'une route contient null, ou
2. le joueur ne peut pas s'emparer de la route.

La méthode isNull de ObjectProperty, ainsi que les méthodes not et or de BooleanProperty permettent d'exprimer cela élégamment ainsi :

Group routeGroup = …;
routeGroup.disableProperty().bind(
  claimRouteHP.isNull().or(gameState.claimable(route).not()));

où claimRouteHP est la propriété contenant le gestionnaire d'action à utiliser lorsque le joueur désire s'emparer d'une route, gameState est l'état observable du jeu, et la méthode claimable permet d'obtenir la propriété booléenne associée à la route et ne contenant vrai que si le joueur peut actuellement s'en emparer.

Lorsqu'un joueur clique sur un élément quelconque d'un groupe représentant une route, cela signifie qu'il désire s'en emparer — ou tenter de le faire dans le cas d'un tunnel.

Pour gérer cela, un gestionnaire de clic de souris doit être attaché, au moyen de setOnMouseClicked, au groupe représentant une route. Ce gestionnaire utilise la méthode possibleClaimCards de l'état de jeu observable pour déterminer la liste des ensembles de cartes que le joueur a la possibilité d'utiliser pour s'emparer de la route.

Si cette liste contient un seul ensemble de cartes, cela signifie que le joueur n'a pas le choix des cartes à utiliser pour s'emparer de la route, et la méthode onClaimRoute du gestionnaire d'action passé à createMapView peut être appelée avec la route et l'ensemble de cartes.

Par contre, si la liste contient plus d'un ensemble de cartes, alors le sélectionneur de cartes passé en argument à createMapView doit être utilisé pour choisir lequel de ces ensembles utiliser. Ce n'est que lorsque le joueur a fait son choix que la méthode onClaimRoute peut être appelée avec la route et l'ensemble de cartes choisi.

Le code à écrire pour gérer cette seconde situation est court mais non trivial, et il vous est donc donné ici pour faciliter votre travail :

// ci-dessous, cardChooser est le sélectionneur de cartes
Route route = …;
List<SortedBag<Card>> possibleClaimCards = …;
ClaimRouteHandler claimRouteH = …;
ChooseCardsHandler chooseCardsH =
  chosenCards -> claimRouteH.onClaimRoute(route, chosenCards);
cardChooser.chooseCards(possibleClaimCards, chooseCardsH);

Ce code fonctionne ainsi :

1. la méthode chooseCards du sélectionneur de cartes est appelé par la dernière ligne, ce qui, dans la version finale du programme, provoquera l'apparition d'un dialogue demandant au joueur de choisir l'ensemble de cartes qu'il désire utiliser pour (tenter de) s'emparer de la route,
2. lorsque le joueur aura fait son choix, le sélectionneur de cartes appellera la méthode onChooseCards du gestionnaire qu'on lui a passé en argument, qui est ici contenu dans la variable chooseCardsH,
3. cette méthode, dont le code est celui de la lambda de l'avant-dernière ligne, appellera la méthode onClaimRoute du gestionnaire d'action utilisé lorsque le joueur désire s'emparer d'une route, contenu ici dans la variable claimRouteH,
4. le gestionnaire d'action contenu dans claimRouteH fera le nécessaire pour que le joueur (tente de) s'emparer de la route.

Ne vous en faites pas si cela n'est pas encore clair pour vous, la rédaction de la prochaine étape devrait vous permettre de mieux comprendre le mécanisme utilisé.

Le graphe de scène de la vue de la main est présenté dans la figure 6 ci-dessous.

La vue de la main elle-même est une instance de HBox dont le premier fils est l'instance de ListView montrant les billets.

Les fils suivants, au nombre de 9, sont chacun une instance de StackPane montrant les cartes d'une couleur donnée que le joueur a en main. Ces fils sont ordonnés dans le même ordre que l'énumération Card et sont identiques à un détail près : l'une des deux classes attachées à l'instance de StackPane correspond à la couleur de la carte, et varie donc. Le seul fils présenté ci-dessous est celui correspondant au premier type de carte, le wagon noir. Les cartes locomotive n'étant pas colorées, la classe NEUTRAL est attachée au dernier fils.

Les trois rectangles de la figure ci-dessus représentent les trois composantes du dessin d'une carte wagon/locomotive. De haut en bas il s'agit de :

1. le rectangle représentant la partie extérieure de la carte — le cadre arrondi —, qui a une largeur de 60 unités et une hauteur de 90 unités,
2. le rectangle représentant la partie intérieure — colorée — de la carte, qui a une largeur de 40 unités et une hauteur de 70 unités,
3. le rectangle contenant l'image du wagon ou de la locomotive, qui a les mêmes dimensions que le précédent.

Le graphe de scène de la vue des pioches est présenté dans la figure ci-dessous. Seule la première des cinq cartes face visible y est présentée. Le graphe de scène de ces cartes est identique à celui utilisé pour les cartes de la vue de la main, mais sans le compteur. Là aussi, la classe correspondant à la couleur de la carte – ou NEUTRAL pour les locomotives — est attachée à l'instance de StackPane à la racine de la portion du graphe de scène représentant la carte. Dans la figure ci-dessous, nous avons fait l'hypothèse que la première carte disposée face visible était rouge.

Les boutons représentant les deux pioches sont accompagnés d'une jauge. Cette dernière est constituée d'un petit graphe de scène, présenté à la figure 8, attaché au bouton au moyen de la méthode setGraphic.

Les deux rectangles représentant la jauge ont initialement une largeur de 50 unités et une hauteur de 5 unités. Bien entendu, la largeur du rectangle représentant l'avant-plan de la jauge — à droite sur la figure — varie en fonction du nombre de cartes présentes dans la pioche correspondante.

La portion du graphe de scène de la vue de la main correspondant à un type de carte donné ne doit être visible que si le joueur possède au moins une carte de ce type en main. Pour ce faire, il suffit de lier la propriété visibleProperty du nœud à la racine de cette portion du graphe de scène à une propriété qui n'est vraie que si le nombre de cartes de ce type en possession du joueur est supérieur à 0. Une telle propriété s'obtient très facilement au moyen de la méthode greaterThan de Bindings :

ReadOnlyIntegerProperty count = …;
StackPane card = …;
card.visibleProperty().bind(Bindings.greaterThan(count, 0));

L'instance de Text donnant la valeur du compteur doit toujours montrer la représentation textuelle du nombre de cartes du type donné présent dans la main du joueur — count dans l'extrait de programme ci-dessus. Pour ce faire, il suffit de lier la propriété textProperty de Text à une propriété contenant la représentation textuelle du nombre de cartes, qui s'obtient très facilement au moyen de la méthode convert de Bindings.

Finalement, cette instance de Text ne doit être visible que si le compteur est strictement supérieur à 1. Pour cela, il suffit de lier sa propriété visibleProperty à une propriété obtenue une fois encore au moyen de greaterThan.

La classe de style représentant la couleur d'une des cinq cartes face visible doit bien entendu changer lorsque la carte en question change. Cela peut se faire en attachant, au moyen de la méthode addListener, un auditeur à la propriété de l'état du jeu observable correspondant à l'emplacement. Lorsque cet auditeur est informé d'un changement, il modifie la classe de style du nœud afin de refléter le changement du type de carte.

Les boutons représentant les deux pioches, de même que les groupes représentant les cartes disposées face visible, ne doivent être activés que lorsque le joueur peut tirer des billets ou des cartes. Pour cela, il suffit de lier la propriété disableProperty de ces éléments à une propriété qui n'est vraie que si la propriété contenant le gestionnaire d'action correspondant contient null. Une fois encore, cela peut se faire au moyen de la méthode isNull offerte par ObjectProperty.

Finalement, la jauge attachée à chacune des pioches doit toujours avoir une taille proportionnelle au pourcentage des cartes qu'elle contient. La classe ObservableGameState offre des propriétés contenant ce pourcentage, sous la forme d'un entier compris entre 0 et 100, et il suffit donc d'ajuster la largeur de l'avant-plan de la jauge en fonction.

Sachant que la largeur maximale de l'avant-plan de la jauge est de 50 unités, la largeur correspondant à un pourcentage donné s'obtient en multipliant ce pourcentage par 50 puis en divisant le résultat par 100. Les propriétés JavaFX contenant des nombres, comme IntegerProperty, offrent des méthodes permettant d'obtenir des propriétés dérivées en effectuant un calcul sur leur contenu. Grâce à ces méthodes — multiply et divide ci-dessous — il est très facile d'ajuster la taille de la jauge :

Rectangle gaugeForeground = …;
ReadOnlyIntegerProperty pctProperty = …;
gaugeForeground.widthProperty().bind(
  percentageProperty.multiply(50).divide(100));

Lorsque le joueur clique sur le bouton représentant la pioche des billets, cela signifie qu'il désire tirer des billets. Il faut alors appeler la méthode onDrawTickets du gestionnaire d'action à utiliser pour le tirage de billets.

Lorsque le joueur clique sur l'une des cartes dont la face est visible, ou sur le bouton représentant la pioche des cartes, cela signifie qu'il désire tirer une carte de l'emplacement correspondant. Il faut alors appeler la méthode onDrawCards du gestionnaire d'action à utiliser pour le tirage de cartes, en lui passant le numéro de l'emplacement (ou -1 pour la pioche) en argument.