Author: sletellier Date: 2010-03-11 12:27:15 +0100 (Thu, 11 Mar 2010) New Revision: 1772 Log: Adding multi and treeTable navigation helper documentations (V2) Added: trunk/src/site/rst/NavigationModel.rst Removed: trunk/src/site/rst/NavigationTreeModel.rst Modified: trunk/src/site/rst/index.rst Copied: trunk/src/site/rst/NavigationModel.rst (from rev 1771, trunk/src/site/rst/NavigationTreeModel.rst) =================================================================== --- trunk/src/site/rst/NavigationModel.rst (rev 0) +++ trunk/src/site/rst/NavigationModel.rst 2010-03-11 11:27:15 UTC (rev 1772) @@ -0,0 +1,228 @@ +--------------- +NavigationModel +--------------- + +.. contents:: + +**WARNING : documentation non à jour...** + +Présentation +============ + +Ajout d'un modèle d'arbre de navigation. + +Le but de cette fonctionnalité est de pouvoir créer un arbre de navigation lié au context de JAXX, de définir des UI +rattachés à chaque noeud. + +Le développement est effectué dans le paquetage *jaxx.runtime.swing.navigation*. + +jaxx.runtime.swing.navigation.NavigationModel +============================================= + +Contract representant le model de l'arbre de navigation. + +Les noeuds présents dans se modèle sont aussi typés en *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*. + +L'idée principale est de pouvoir associer à un noeud précis un chemin depuis la racine, ce que l'on appele *chemin de navigation*. + +Pour obtenir le chemin de navigation d'un noeud donné, on récupère l'enmseble des neoud depuis la racine vers ce noeud +et les concatène en suffixant par le caractère séparateur défini. + +Tout les models suivants implémantent cette interface. + +jaxx.runtime.swing.navigation.NavigationTreeModel +================================================= + +Il s'agit du modèle de l'arbre utilisé, c'est une extension d'un *javax.swing.tree.DefaultTreeModel*. + +jaxx.runtime.swing.navigation.NavigationTreeTableModel +====================================================== + +Il s'agit du modèle de l'arbre tableau (*org.jdesktop.swingx.JXTreeTable*), c'est une extension d'un *org.jdesktop.swingx.treetable.DefaultTreeTableModel*. + +Les noeuds présents dans se modèle sont typés en *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeTableNode* qui +étend *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*. + +NavigationTreeTableNode est abstaite, l'instance doit donc être crée en implementant la méthode createNavigationTreeTableNode +du builder (*jaxx.runtime.swing.navigation.NavigationTreeTableModelBuilder*). + +Les builders +============ + +jaxx.runtime.swing.navigation.NavigationModelBuilder +---------------------------------------------------- + +Les builders sont des classes utilitaires permétant de construire le model et les rendus de l'arbre simplement. +Tous les builders implémentent cette interface. + +jaxx.runtime.swing.navigation.NavigationTreeModelBuilder +-------------------------------------------------------- + +Classe utilitaire pour construire le model (ici un *jaxx.runtime.swing.navigation.NavigationTreeModel*) et décorer un arbre. + +jaxx.runtime.swing.navigation.NavigationTreeTableModelBuilder +------------------------------------------------------------- + +Classe utilitaire pour construire le model (ici un *jaxx.runtime.swing.navigation.NavigationTreeTableModel*) et décorer un arbre tableau. + +Les Handlers +============ + +jaxx.runtime.swing.navigation.NavigationTreeHandler +--------------------------------------------------- + +Cette classe est une implémentation d'un model de sélection pour les arbres de navigations. + +Il y a 2 façons de l'utiliser, soit l'on associe une ui par noeud (*Strategy.PER_NODE*) soit on associe une ui par type de noeud (*Strategy.PER_UI_TYPE*). + +jaxx.runtime.swing.navigation.NavigationTreeHandlerWithCardLayout +----------------------------------------------------------------- + +Extension de *jaxx.runtime.swing.navigation.NavigationTreeHandler* pour l'utilisation de CardLayout (*jaxx.runtime.swing.CardLayout2*). + +jaxx.runtime.swing.navigation.NavigationMultiTreeHandler +-------------------------------------------------------- + +TODO ajouter la strategie de la multiselection + +Extension de *jaxx.runtime.swing.navigation.NavigationTreeHandler* pour ajouter la possibilité d'utiliser la multisélection. + +Définition d'un noeud +===================== + +Le noeud (*jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*) est une extension d'un *javax.swing.tree.DefaultMutableTreeNode*. + +Il apporte les nouvelles propriétés suivantes : + + * *navigationPath* : nom de chemin de navigation de ce noeud. + + * *jaxxClass* : nom qualifié de la classe d'ui associé à ce noeud (doit être obligatoirement un *JAXXObject*) + + * *jaxxActionClass* : nom qualifié de la classe d'handler d'ui associé à ce noeud (doit être obligatoirement un *JAXXAction*). + + * *jaxxContextEntryDef* : définition de l'entrée dans le context JAXX associé à ce noeud. + + * *jaxxContextEntryJXPath* : définition d'une expression JXPath à appliquer sur le bean associé au noeud. + + +Retrouver un noeud à partir du chemin de navigation +*************************************************** + +Il est possible en connaissant le chemin de navigation d'un noued de récupérer le noeud dans l'arbre via la méthode + +:: + + model.findNode("chemin.de.navigation") + +Trouver la valeur associée dans le context JAXX à partir du chemin de navigation +******************************************************************************** + +Il est possible en connaissant le chemin de navigation d'un noued de récupérer la valeur associée dans le context JAXX. + +:: + + model.getJAXXContextValue(myJAXXContext, "chemin.de.navigation")* . + +L'algrotihme est le suivant : + + * récupération du noeud associé au chemin de navigation + + * recherche du premier noeud (dans les noeuds qui remontent vers la racine de l'arbre) dont la propriété *jaxxContextEntry* est non nulle, il s'agit du point d'entré dans le context JAXX. + + * redescendre à partir de ce noeud vers le noeud d'origine (si ce noeud était différent) et en descendant conjointement dans l'objet du context JAXX : + + - on utilise l'expression JXPath pour obtenir l'objet associé au noeud + +Exemple : + +:: + + "$root" + <-- la racine de l'abre + | + + "string" <-- attaché au context JAXX <java.lang.String,"string"> + | + + "liste" + <-- attaché au context JAXX <java.util.List.class,"liste"> + | | + | + "0" <-- le premier élément de la liste + | | + | + "1" <-- le second élément de la liste + | | + | + "2" <-- le troisième élément de la liste + | + + "locale" + <-- attaché au context JAXX <java.util.Locale> + | + + country + | + + language + + // preparation du context + java.util.List myList = java.util.Arrays.asList("one","two","three"); + java.util.Locale myLocale = java.util.Locale.FRENCH; + context.setContextValue(myList, "liste"); + context.setContextValue("stringValue","string"); + context.setContextValue(myLocale); + + + // récupération des valeurs dans le context à partir de chemin de navigation + assert model.getJAXXContextValue(context, "$root") == null; + assert model.getJAXXContextValue(context, "$root.string") == "stringValue"; + assert model.getJAXXContextValue(context, "$root.liste") == myList; + assert model.getJAXXContextValue(context, "$root.liste.0") == "one"; + assert model.getJAXXContextValue(context, "$root.liste.1") == "two"; + assert model.getJAXXContextValue(context, "$root.liste.2") == "three"; + assert model.getJAXXContextValue(context, "$root.locale") == myLocale; + assert model.getJAXXContextValue(context, "$root.locale.country") == myLocale.getCountry(); + assert model.getJAXXContextValue(context, "$root.locale.language") == myLocale.getLanguage(); + +TODO mettre à jour cet exemple suite à l'utilisation de JXPath pour naviguer dans les objets. + +A noter qu'une seconde méthode de récupération de valeur du context JAXX est disponible pour pouvoir récupérer cette +valeur en connaissant le noeud : + +:: + + model.getJAXXContextValue(context, myNode); + +jaxx.runtime.swing.navigation.NavigationTreeSelectionAdapter +============================================================ + +Il s'agit d'un listener sur la sélection d'un noeud dans l'arbre de navigation basé sur notre modèle de navigation. Il +étend *javax.swing.event.TreeSelectionListener*. + +Ce listener contient la gestion de passage d'un noeud à un autre avec interaction avec le context JAXX et affichage automatique de l'ui associé au noeud sélectionné. + +**Attention : la mécanique ne fonctionne que pour un arbre à selection unique.** + +Algorithme +********** + +Voici l'algorithme utilisé lors de la sélection d'un nouveau noeud : + + * *closeUI* : tentative de fermeture de l'ui lié au noeud précédemment selectionné, si cela n'aboutit pas on retourne sur le noeud précédent. + + * *attachBeanFromNodeToContext* : injection dans le context JAXX de la valeur associée au nouveau noeud + + * *createUI* : création de la nouvelle ui (si elle n'existe pas) + + * *openUI* : ouverture de la nouvelle ui + +Si une erreur survient lors de ces opérations, on entre dans la méthode *goBackToPreviousNode* qui est abstraite et permet de notifier les erreur de retourner au noeud précdent. + +jaxx.runtime.swing.navigation.NavigationTreeSelectionAdapterWithCardLayout +************************************************************************** + +Il s'agit d'une implantation du listener précédent qui suppose que les uis associées aux noeuds sont affichées dans un +unique container en utilisant le layout *jaxx.runtime.swing.CardLayout2*. + +La contrainte de chaque ui sera extactement le chemin de navigation du noeud associé. + +Il possède deux méthodes abstraites : + + * *getContentContainer* : qui indique le container d'ui. + + * *getContentLayout* : qui indique le layout utilisé. + +Pour pouvoir utilisé cet *adapter*, il vous suffit de définir la méthode suivante (en plus des deux méthodes abstraites) : + + * *goBackToPreviousNode* : comment gérer les erreurs et retourner au noeud précedent. + Property changes on: trunk/src/site/rst/NavigationModel.rst ___________________________________________________________________ Added: svn:mergeinfo + Deleted: trunk/src/site/rst/NavigationTreeModel.rst =================================================================== --- trunk/src/site/rst/NavigationTreeModel.rst 2010-03-11 11:12:44 UTC (rev 1771) +++ trunk/src/site/rst/NavigationTreeModel.rst 2010-03-11 11:27:15 UTC (rev 1772) @@ -1,221 +0,0 @@ -------------------- -NavigationTreeModel -------------------- - -.. contents:: - -**WARNING : documentation non à jour...** - -Présentation -============ - -Ajout d'un modèle d'arbre de navigation. - -Le but de cette fonctionnalité est de pouvoir créer un arbre de navigation lié au context de JAXX, de définir des UI -rattachés à chaque noeud. - -Le développement est effectué dans le paquetage *jaxx.runtime.swing.navigation*. - -jaxx.runtime.swing.navigation.NavigationTreeModel -================================================= - -Il s'agit du modèle de l'arbre utilisé, c'est une extension d'un *javax.swing.tree.DefaultTreeModel*. - -Les noeuds présents dans ce modèle sont aussi typés en *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*. - -L'idée principale est de pouvoir associer à un noeud précis un chemin depuis la racine, ce que l'on appele *chemin de navigation*. - -Pour obtenir le chemin de navigation d'un noeud donné, on récupère l'enmseble des neoud depuis la racine vers ce noeud -et les concatène en suffixant par le caractère séparateur défini. - -jaxx.runtime.swing.navigation.NavigationTreeTableModel -====================================================== - -Il s'agit du modèle de l'arbre tableau (*org.jdesktop.swingx.JXTreeTable*), c'est une extension d'un *org.jdesktop.swingx.treetable.DefaultTreeTableModel*. - -Les noeuds présents dans ce modèle sont typés en *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeTableNode* qui -étend *jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*. - -Cette implmentation est abstaite, l'instance doit -donc être crée en implementant la méthode createNavigationTreeTableNode du builder (*jaxx.runtime.swing.navigation.NavigationTreeTableModelBuilder*). - -Les builders -============ - -jaxx.runtime.swing.navigation.NavigationModelBuilder ----------------------------------------------------- - -Les builders sont des classes utilitaires permetant de construire le model et les rendus de l'arbre simplement. -Tous les builders implémentes cette interface. - -jaxx.runtime.swing.navigation.NavigationTreeModelBuilder --------------------------------------------------------- - -Classe utilitaire pour construire le model (ici un *jaxx.runtime.swing.navigation.NavigationTreeModel*) et décorer un arbre. - -jaxx.runtime.swing.navigation.NavigationTreeTableModelBuilder -------------------------------------------------------------- - -Classe utilitaire pour construire le model (ici un *jaxx.runtime.swing.navigation.NavigationTreeTableModel*) et décorer un arbre tableau. - -Les Handlers -============ - -jaxx.runtime.swing.navigation.NavigationTreeHandler ---------------------------------------------------- - -Cette classe est une implémentation d'un model de sélection pour les arbres de navigations. - -Il y a 2 façons de l'utiliser, soit l'on associe une ui par noeud (*Strategy.PER_NODE*) soit on associe une ui par type de noeud (*Strategy.PER_UI_TYPE*). - -jaxx.runtime.swing.navigation.NavigationTreeHandlerWithCardLayout ------------------------------------------------------------------ - -Extension de *jaxx.runtime.swing.navigation.NavigationTreeHandler* pour l'utilisation de CardLayout (*jaxx.runtime.swing.CardLayout2*). - -jaxx.runtime.swing.navigation.NavigationMultiTreeHandler --------------------------------------------------------- - -TODO ajouter la strategie de la multiselection - -Extension de *jaxx.runtime.swing.navigation.NavigationTreeHandler* pour ajouter la possibilité d'utiliser la multiselection. - -Définition d'un noeud -===================== - -Le noeud (*jaxx.runtime.swing.navigation.NavigationTreeModel.NavigationTreeNode*) est une extension d'un *javax.swing.tree.DefaultMutableTreeNode*. - -Il apporte les nouvelles propriétés suivantes : - - * *navigationPath* : nom de chemin de navigation de ce noeud. - - * *jaxxClass* : nom qualifié de la classe d'ui associé à ce noeud (doit être obligatoirement un *JAXXObject*) - - * *jaxxActionClass* : nom qualifié de la classe d'handler d'ui associé à ce noeud (doit être obligatoirement un *JAXXAction*). - - * *jaxxContextEntryDef* : définition de l'entrée dans le context JAXX associé à ce noeud. - - * *jaxxContextEntryJXPath* : définition d'une expression JXPath à appliquer sur le bean associé au noeud. - - -Retrouver un noeud à partir du chemin de navigation -*************************************************** - -Il est possible en connaissant le chemin de navigation d'un noued de récupérer le noeud dans l'arbre via la méthode - -:: - - model.findNode("chemin.de.navigation") - -Trouver la valeur associée dans le context JAXX à partir du chemin de navigation -******************************************************************************** - -Il est possible en connaissant le chemin de navigation d'un noued de récupérer la valeur associée dans le context JAXX. - -:: - - model.getJAXXContextValue(myJAXXContext, "chemin.de.navigation")* . - -L'algrotihme est le suivant : - - * récupération du noeud associé au chemin de navigation - - * recherche du premier noeud (dans les noeuds qui remontent vers la racine de l'arbre) dont la propriété *jaxxContextEntry* est non nulle, il s'agit du point d'entré dans le context JAXX. - - * redescendre à partir de ce noeud vers le noeud d'origine (si ce noeud était différent) et en descendant conjointement dans l'objet du context JAXX : - - - on utilise l'expression JXPath pour obtenir l'objet associé au noeud - -Exemple : - -:: - - "$root" + <-- la racine de l'abre - | - + "string" <-- attaché au context JAXX <java.lang.String,"string"> - | - + "liste" + <-- attaché au context JAXX <java.util.List.class,"liste"> - | | - | + "0" <-- le premier élément de la liste - | | - | + "1" <-- le second élément de la liste - | | - | + "2" <-- le troisième élément de la liste - | - + "locale" + <-- attaché au context JAXX <java.util.Locale> - | - + country - | - + language - - // preparation du context - java.util.List myList = java.util.Arrays.asList("one","two","three"); - java.util.Locale myLocale = java.util.Locale.FRENCH; - context.setContextValue(myList, "liste"); - context.setContextValue("stringValue","string"); - context.setContextValue(myLocale); - - - // récupération des valeurs dans le context à partir de chemin de navigation - assert model.getJAXXContextValue(context, "$root") == null; - assert model.getJAXXContextValue(context, "$root.string") == "stringValue"; - assert model.getJAXXContextValue(context, "$root.liste") == myList; - assert model.getJAXXContextValue(context, "$root.liste.0") == "one"; - assert model.getJAXXContextValue(context, "$root.liste.1") == "two"; - assert model.getJAXXContextValue(context, "$root.liste.2") == "three"; - assert model.getJAXXContextValue(context, "$root.locale") == myLocale; - assert model.getJAXXContextValue(context, "$root.locale.country") == myLocale.getCountry(); - assert model.getJAXXContextValue(context, "$root.locale.language") == myLocale.getLanguage(); - -TODO mettre à jour cet exemple suite à l'utilisation de JXPath pour naviguer dans les objets. - -A noter qu'une seconde méthode de récupération de valeur du context JAXX est disponible pour pouvoir récupérer cette -valeur en connaissant le noeud : - -:: - - model.getJAXXContextValue(context, myNode); - -jaxx.runtime.swing.navigation.NavigationTreeSelectionAdapter -============================================================ - -Il s'agit d'un listener sur la sélection d'un noeud dans l'arbre de navigation basé sur notre modèle de navigation. Il -étend *javax.swing.event.TreeSelectionListener*. - -Ce listener contient la gestion de passage d'un noeud à un autre avec interaction avec le context JAXX et affichage automatique de l'ui associé au noeud sélectionné. - -**Attention : la mécanique ne fonctionne que pour un arbre à selection unique.** - -Algorithme -********** - -Voici l'algorithme utilisé lors de la sélection d'un nouveau noeud : - - * *closeUI* : tentative de fermeture de l'ui lié au noeud précédemment selectionné, si cela n'aboutit pas on retourne sur le noeud précédent. - - * *attachBeanFromNodeToContext* : injection dans le context JAXX de la valeur associée au nouveau noeud - - * *createUI* : création de la nouvelle ui (si elle n'existe pas) - - * *openUI* : ouverture de la nouvelle ui - -Si une erreur survient lors de ces opérations, on entre dans la méthode *goBackToPreviousNode* qui est abstraite et permet de notifier les erreur de retourner au noeud précdent. - -jaxx.runtime.swing.navigation.NavigationTreeSelectionAdapterWithCardLayout -************************************************************************** - -Il s'agit d'une implantation du listener précédent qui suppose que les uis associées aux noeuds sont affichées dans un -unique container en utilisant le layout *jaxx.runtime.swing.CardLayout2*. - -La contrainte de chaque ui sera extactement le chemin de navigation du noeud associé. - -Il possède deux méthodes abstraites : - - * *getContentContainer* : qui indique le container d'ui. - - * *getContentLayout* : qui indique le layout utilisé. - -Pour pouvoir utilisé cet *adapter*, il vous suffit de définir la méthode suivante (en plus des deux méthodes abstraites) : - - * *goBackToPreviousNode* : comment gérer les erreurs et retourner au noeud précedent. - Modified: trunk/src/site/rst/index.rst =================================================================== --- trunk/src/site/rst/index.rst 2010-03-11 11:12:44 UTC (rev 1771) +++ trunk/src/site/rst/index.rst 2010-03-11 11:27:15 UTC (rev 1772) @@ -43,7 +43,7 @@ * BeanValidator_ - * NavigationTreeModel_ + * NavigationModel_ Who use JAXX ? -------------- @@ -75,4 +75,4 @@ .. _BeanValidator: BeanValidator.html -.. _NavigationTreeModel: NavigationTreeModel.html +.. _NavigationModel: NavigationModel.html