Documentation on displays

docs/display/index.rst

@@ -3,13 +3,6 @@ Gestion de l'affichage
 
 .. _curses: https://docs.python.org/3/howto/curses.html
 
-L'intégralité de l'affichage du jeu est géré grâce à la bibliothèque native de
-Python curses_.
-
-
-.. warning::
-  Plus de documentation à venir.
-
 
 .. toctree::
    :maxdepth: 3
@@ -19,3 +12,51 @@ Python curses_.
    map
    stats
    logs
+
+L'intégralité de l'affichage du jeu est géré grâce à la bibliothèque native de Python curses_.
+
+Initialisation du terminal
+--------------------------
+
+Au lancement du jeu, le terminal est initialisé, les caractères spéciaux sont traduits en abstraction curses, les
+caractères tapés par l'utilisateur ne sont plus affichés sur le terminal, on envoie les touches tapées à curses en
+permanence sans avoir à taper sur Entrée, le curseur est rendu invisible, on active le support des couleurs et enfin
+on déclare vouloir attraper tous les clics de souris. Tout cela est fait dans un contexte Python, qui permet
+d'effectuer les opérations inverses lors de la fermeture du programme, même en cas de crash, afin de retrouver un
+terminal utilisable.
+
+
+Pads
+----
+
+Chaque morceau d'affichage est géré dans un *pad*. Un pad est un objet défini par curses, représentant une sous-fenêtre,
+qui a l'avantage d'être un peu plus flexible qu'une simple fenêtre. Un pad peut en effet dépasser de l'écran, et on
+peut choisir où placer le coin avant gauche et quelle partie du pad il faut dessiner sur la fenêtre.
+
+Ce projet implémente une couche d'abstraction supplémentaire, afin d'avoir des objets plus utilisables. Chaque partie
+d'affichage est réprésentée dans une classé étendant ``Display``. Chaque ``Display`` contient un (ou plusieurs) pads,
+et propose une surcouche de certaines fonctions de curses.
+
+L'affichage de texte par exemple sur un pad est plus sécurisée que celle proposée par curses. Le comportement par défaut
+est d'afficher un message à partir d'une position donnée avec des attributs (gras, couleur, ...) donnés sous
+forme numérique. Cette implémentation permet de passer les attributs voulus sous forme de paramètres booléens, de
+choisir la couleur de front/de fond sans définir de paire curses, mais surtout de tronquer le texte à la place
+disponible, afin de ne pas avoir à se soucier d'avoir un message trop grand et éviter des crashs non désirés.
+
+Les ``Display`` sont gérés par un ``DisplayManager``. C'est lui qui décide, en fonction de l'état actuel du jeu,
+d'afficher les bons ``Display`` aux bons endroits et de les redimensionner correctement en fonction de la taille du
+terminal. C'est aussi lui qui propage l'information de modifier les attributs d'un ``Display``, si par exemple
+l'inventaire du joueur a été mis à jour.
+
+Il s'occupe enfin de tout redimensionner si jamais le terminal a changé de taille, après une intervention
+de l'utilisateur.
+
+
+Interactions avec la souris
+---------------------------
+
+Le jeu attrape les clics de souris. C'est le ``DisplayManager``, connaissant l'état du jeu et ce qui est affiché à
+quel endroit, qui va chercher sur quel ``Display`` on a cliqué. L'information est propagée au bon ``Display``, en
+adaptant les coordonnées.
+
+Tout ``Display`` qui contient un menu procède de la même façon pour propager l'information au bon menu.