Index: topia/doc/UI.rst
diff -u /dev/null topia/doc/UI.rst:1.1
--- /dev/null	Fri Oct  8 13:08:01 2004
+++ topia/doc/UI.rst	Fri Oct  8 13:07:56 2004
@@ -0,0 +1,382 @@
+======================================
+Implantation des interfaces graphiques
+======================================
+
+:author: Benjamin Poussin <poussin@codelutin.com>
+:date: 20041007
+
+Concept
+=======
+
+L'utilisateur écrit ces interfaces en XML très simple, l'extension des
+fichiers sont .suix (Simple User Interface Xml).
+
+Les fichiers .suix ne contiennent aucune information de présentation, il ne
+contient que des groupes et des widgets fonctionnels. Le style (couleur,
+font, position, ...) est décrit dans un fichier séparer de style CSS.
+
+Topia lit la description .suix pour généré une interface permettant de
+récupérer simplement des éléments graphiques décrit dans cette interface,
+cela est utile pour ne pas avoir à caster les objets retournés.
+
+Les callbacks sont écrit directement dans des classes Java. Ces classes
+contiennent des méthodes respectant une certaine signature ce qui permet par
+introspection de les enregistrer en tant que listener sur les bons objets.
+
+Un moteur de rendu graphique lit les fichiers .suix pour créer l'interface
+graphique à l'exécution. Sur l'objet qui gère l'interface lu depuis le
+fichier .suix, on peut enregistrer des objets contenants les méthodes de
+callback, ajouter des objets gérants le style des objets. Il permet aussi de
+récupérer un objet de l'interface graphique par son nom. Le type d'objet
+retourné est Object.
+
+Un proxy répondant à l'interface généré par topia et encapsulant un moteur
+de rendu graphique peut-être utilisé pour simplifier l'utilisation de
+l'interface graphique. De cette façon on n'a plus à caster les Object qui
+nous sont retourné.
+
+Les fichiers .suix
+==================
+
+Les fichiers .suix sont des fichiers xml contenant seulement la description
+des widgets que l'on souhaite. Un ensemble de widgets prédéfinis existent, et
+permettent une portabilité entre différente librairie graphique. Il est aussi
+possible d'utiliser des objets très spécifique à une librairie graphique ou
+un langage, dans ce cas, la description XML ne sera utilisable que dans la
+cible choisie.
+
+Si seul les composants prédéfini sont utilisé, alors la description XML
+est portable d'une librairie à une autre (HTML, Swing/Java, AWT/Java,
+SWT/Java, .NET, ...)
+
+Les widgets prédéfinis
+----------------------
+
+Tous les widgets prédéfinis sont des objets que l'on trouve dans la
+librairie lutinwidget pour l'implantation Swing/Java, ces widgets ont été
+choisi car ils répondent le mieux possible au besoin des interfaces graphiques
+utilisateur. Certaine fois il s'agit simplement d'un héritage d'un widget
+de la librairie Swing.
+
+Tous les widgets prédéfinis ont des caractéristiques commune comme la
+possibilité de les rendre inactif (disable), ou de leur demander la valeur
+qu'il contiennent, ou de modifier leur valeur courante.
+
+Les widgets prédéfinis sont des widgets que l'on retrouve dans la plupart
+des librairies d'interface utilisateur. On y trouve:
+
+label
+  pour afficher un texte ou un icône
+
+fieldtext
+  pour l'entrer d'une zone texte sur une seul ligne, un mask de saisie peut
+  lui être défini
+
+textarea
+  pour l'entrer d'une zone de texte sur plusieurs lignes.
+
+list
+  pour le choix d'un ou plusieurs élément dans une liste. Une liste à un
+  modèle qui permet de définir les objets à afficher dans la liste
+
+combo
+  pour le choix d'un élement dans une liste déroulante. Elle contient un
+  modèle qui permet de définir les objets à afficher dans la liste.
+  On peut aussi indiquer que la combo est éditable
+ 
+table
+  une table permet d'afficher un ensemble de cellule contenant des
+  informations. Un modèle permet d'indiquer les objets à afficher dans la
+  table.
+
+tree
+  Un tree permet d'afficher sous forme d'arbre de l'information. Un modèle
+  permet de définir la structure de l'arbre est les objets à afficher
+
+button
+  Un bouton peut avoir une image et ou un texte.
+
+statusBar (progressBar, ...)
+  La status bar, permet d'afficher un message d'information pour
+  l'utilisateur, elle contient aussi une progressBar pour que l'utilisateur
+  sache ou en est la commande qu'il a exécuté, ...
+  D'autre petit élément peuvent être ajouté comme, l'heure, la mémoire, la
+  charge cpu, ... (ceci peut aussi être demandé au travers des CSS.)
+
+Slider
+  Un slider permet de sélectionner une valeur parmi d'autre en modifiant la
+  possition d'un curseur sur une ligne. Un modèle permet de définir les
+  valeur possible pour le slider.
+
+Spinner
+  Un spinner permet de sélectionner une valeur numérique soit en la
+  saisissant directement dans une zone de texte, soit en utilisant deux
+  petites flèches (vers le haut, vers le bas) qui permettent de modifier
+  la valeur simplement. Un modèle permet de définir les valeurs acceptables.
+
+checkbox
+  Une checkbox permet de saisir une valeur booléenne (vrai/faux), elle
+  contient un label ou une image.
+
+radioButton
+  Un radionButton est la même chose que la checkBox, mais il fait parti d'un
+  groupe. Dans un groupe un seul radioButton peut être séletionné à la fois,
+  et au moins un doit être sélectionné.
+
+datePicker
+  Un datePicker permet de saisir/choisir une date simplement. La date
+  peut-être soit: un jour et une heure, un jour ou une heure.
+
+Aucun widget de placement existe car tout le placement des composants se
+fait grâce au CSS.
+
+Les éléments XML
+----------------
+
+Chaque widget prédéfini est un élément XML. Les autres éléments sont:
+
+group
+  permet de définir des groupes de widget devant aller ensemble
+
+unknown
+  permet d'ajouter des widgets non prédéfini. Dans ce cas, le fichier
+  .suix devient dépendant de la librairie utilisé pour ce widget.
+
+include
+  permet d'inclure un autre fichier XML dans le fichier.
+
+Exemple de fichier .suix
+------------------------
+
+Dans cette exemple on à simplement une interface permettant de décrire une
+personne::
+
+  <suix version="1.0">
+    <group id="person">      
+      <group class="data" title="Person">
+        <label>Veuillez saisir la nouvelle personne</label>
+        <textfield   id="firstname" title="firstname"/>
+        <textfield   id="name"      title="name"/>
+        <radiobutton id="male"      title="male"   group="sexe"/>
+        <radiobutton id="female"    title="female" group="sexe"/>
+        <datepicker  id="birthday"  titble="birthday"/>
+        <spinner     id="height"    title="height"/>
+        <spinner     id="weight"    title="weight"/>
+        <textfield   id="address"   title="address"/>
+        <combobox    id="zipcode"   title="zipcode"/>
+        <textfield   id="city"      title="city"/>
+        <combobox    id="country"   title="country"/>
+        <unknown     id="map"       type="com.bbn.OpenMap"/>
+      </group>
+      <group class="data" id="other">
+        <include     file="car.suix"/>
+        <include     file="house.suix"/>
+      </group>
+      <group class="action">
+        <button id="save" title="Save">
+        <button id="cancel" title="Cancel">
+      </group>
+    </group>
+  </suix>
+
+La gestion des styles
+=====================
+
+Les styles permettent de modifier entièrement l'interface graphique
+utilisateur. Il est possible de modifier la possition des widgets, la
+couleur, les fonts, la visibilité, la classe de renderer, ...
+
+Le fichier contenant ces informations est un fichier de style CSS.
+
+Ce fichier est donc spécifique suivant la librairie graphique choisie. Par
+exemple le fichier ne sera pas le même si on utilise une interface HTML ou
+une interface Swing.
+
+Il est possible d'appliquer plusieurs CSS sur un même fichier .suix ce qui
+permet si certaine librairie recouvre les mêmes concepts (couleurs, fonts,
+...) de conserver les mêmes fichiers pour plusieurs librairies (Swing/Java,
+AWT/Java)
+
+Pseudo élément
+--------------
+
+Chaque widget peut avoir un attribut *title*. Si on veut modifier le style
+d'un titre il faut utiliser le pseudo élément #title.
+
+Un autre pseudo element est aussi cree pour l'objet racine de l'arbre des
+widgets. Ce pseudo element est nomé root.
+
+Exemple de CSS
+--------------
+
+::
+
+  /* on affiche l'interface dans une frame */
+  #root {
+    display: frame;
+  }
+
+  .data {
+    background-color: cyan;
+    font: arial;
+  }
+  
+  /* Tous les titres dans des groupes de classe data seront rose */
+  .data > #title {
+    foreground-color: pink;
+    position: left;
+  }
+  
+  /* On modifie spécifiquement le titre de firstname */
+  #firstname #title {
+    position: top; 
+    font-style: bold;
+    color: red;
+  }
+
+Gestion en Java des CSS
+-----------------------
+
+Les fichiers CSS sont lu en Java par une classe spécifique. Il est possible
+plutôt que de lire un fichier CSS d'écrire de façon programmatique ce que
+l'on souhaite. Les fichiers CSS ne sont donc qu'une façon plus souple de géré
+les styles, et permet de modifier l'apparence de l'interface sans
+recompilation.
+
+Exemple d'utilisation de la classe Style
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+  Style style = new Style();
+  style.load("person.jss");
+  style.addStyle("#name #title", "color", "yellow");
+
+On remarque que la méthode addStyle ne prend que des String en paramètre, il
+sera sans doute possible d'avoir des choses du style::
+
+  style.addStyle("#name #title", Style.COLOR, Color.yellow);
+  
+Le problème est pour widget *unknown*, il ne sera pas forcement possible de
+passer par autre chose que des chaines pour le type du style à modifier. La
+valeur elle peut très bien être un Object plutôt qu'une chaine, cela est même
+sans doute obligatoire.
+
+Liste non exhautive des possibilités par widget
+-----------------------------------------------
+
+Renderer de list, combo, tree, table
+Editor de tree, table
+
+label, radioButton, button, checkBox: permet de possitionner le texte par
+rapport au texte.
+
+radioButton, checkBox: permet de définir la position du texte et de l'image
+par rapport au widget (au dessus, à droite, ...)
+
+La gestion callbacks
+====================
+
+Les callbacks sont simplement codé dans une classe. Les méthodes implantées
+dans cette classe ayant un certain type de nom sont pris en compte comme des
+méthodes de callback. Si une méthode qui devrait être un callback ne peut
+être affecté à un objet alors une erreur est reporté. Selon le mode de
+lancement de l'application, soit cela arrête l'application soit seulement un
+message est loggé.
+
+Struture du nom de la méthode
+-----------------------------
+
+Le nom de la méthode commence par *on_*, puis on ajoute le nom de l'objet
+sur lequel on veut mettre le callback, et enfin on met le nom de callback.
+Par exemple pour prendre en compte le clique sur un bouton::
+
+  on_monButton_mouseClick
+  
+Argument de la méthode de callback
+----------------------------------
+
+La méthode de callback peut prendre entre zéro et deux arguments. 
+
+Le premier argument peut être l'interface généré par topia ou bien la classe
+du moteur de rendu. Dans ce cas si on détecte ce type d'argument lors de
+l'appel du callback l'objet Proxy ou l'instance du moteur sera passé en
+argument.
+
+Le deuxième argument peut-être l'event du callback, si on detecte sa
+présence, alors il sera passé au callback en argument. L'utilisation de
+cet argument fait que la méthode de callback n'est plus portable d'une
+librairie à une autre.
+
+Bonne pratique de développement
+-------------------------------
+
+Une bonne façon de faire une application ayant le moins possible de
+dépendance sur une librairie graphique est de découper en deux classes les
+callback. La première classe reçoit les callbacks avec les arguments events.
+Cette classe est donc spécifique à la librairie. Son role est d'extraire de
+l'event toutes les informations dont l'application à besoin pour faire le
+traitement. Une fois les informations extraite elle délègue le travail à une
+classe portable d'une librairie à une autre.
+
+De cette façon le plus gros du traitement peux être récupérer lorsque l'on
+change de librairie.
+
+Par exemple pour la gestion de la souris on pourrait avoir::
+
+  class Dependante {
+    protected Independante indep;    
+    public Dependante(Independante indep){
+      this.indep = indep;
+    }
+    public void on_monBouton_mousePressed(MouseEvent e){
+      int x = e.getX();
+      int y = e.getY();
+      indep.monBoutonPressed(x, y);
+    }
+  }
+  
+  class Independante {
+    public void monBoutonPressed(int x, int y){
+      // ... traitement ...
+    }
+  }
+
+Le moteur de rendu graphique
+============================
+
+Le moteur de rendu permet d'interpréter le fichier .suix pour générer
+l'interface graphique. Une fois l'interface chargé, il est possible de
+lui ajouter des objets de callback, des objets de style, une interface qui
+sera utilisé pour passé au callback si les callback attende une interface
+plutôt que directement le moteur graphique.
+
+:remarque: Il y a quelques problèmes lorsque l'utilisateur ajouter des
+  composants durant l'execution de l'application directement en utilisant
+  les méthodes swing *add* sur les containers, car les styles ne leur seront
+  sans doute pas appliqués.
+
+Implantation
+------------
+
+Chaque widget prédéfini à un mapping en dure dans le moteur (ou bien un
+fichier de configuration). Une instance de chaque widget demandé en créée et
+conservé dans une Map qui a comme cle l'identifiant de l'objet et comme
+valeur l'instance du widget.
+
+Le tag group correspond à un panel, chaque widget d'un group est placé dans
+le panel qui le contient, les widgets sans id ne sont ajouté qu'au panel et
+ne seront pas dans la Map.
+
+On a alors un arbre de widget qui commence toujours par un panel.
+
+Le Proxy de simplification
+==========================
+
+Le proxy de simplification est la pour permettre à l'utilisateur de
+simplifier l'utilisation du moteur de rendu en évitant les casts.
+
+Le proxy de simplification est créé en utilisant une méthode spéciale du
+moteur de rendu. Cette méthode prend en argument une interface et retourne
+un proxy respectant cette interface. Le proxy encapsule le moteur de rendu,
+et le moteur de rendu utilise le proxy pour les callbacks qui en ont besoin.