Author: kmorin Date: 2009-08-26 17:20:21 +0200 (Wed, 26 Aug 2009) New Revision: 1595 Added: trunk/src/site/resources/file.png trunk/src/site/rst/commonTags.rst trunk/src/site/rst/installation.rst Modified: trunk/src/site/resources/guixmodeltree.png trunk/src/site/rst/guixFiles.rst Log: Add doc site Added: trunk/src/site/resources/file.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/file.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/src/site/resources/guixmodeltree.png =================================================================== (Binary files differ) Added: trunk/src/site/rst/commonTags.rst =================================================================== --- trunk/src/site/rst/commonTags.rst (rev 0) +++ trunk/src/site/rst/commonTags.rst 2009-08-26 15:20:21 UTC (rev 1595) @@ -0,0 +1,64 @@ +==================== +Balises universelles +==================== + +Afin de pouvoir générer une même interface graphique sous plusieurs librairies graphiques différentes, il faut pouvoir définir les composants sous un même nom. C'est ce que permet Guix avec les balises suivantes et leur correspondance dans leur langage : + +==================== ======================================= ================================================== + Guix Swing GWT +==================== ======================================= ================================================== +Application javax.swing.JFrame com.google.gwt.user.client.ui.VerticalPanel +Button javax.swing.JButton com.google.gwt.user.client.ui.Button +CheckBox javax.swing.JCheckBox com.google.gwt.user.client.ui.CheckBox +ComboBox javax.swing.JComboBox com.google.gwt.user.client.ui.ListBox +DialogBox javax.swing.JDialog com.google.gwt.user.client.ui.DialogBox +Label javax.swing.JLabel com.google.gwt.user.client.ui.Label +List javax.swing.JList com.google.gwt.user.client.ui.ListBox +MenuBar javax.swing.JMenuBar com.google.gwt.user.client.ui.MenuBar +Menu javax.swing.JMenu com.google.gwt.user.client.ui.MenuBar +MenuItem javax.swing.JMenuItem cette balise n'a pas de classe correspondante mais est quand même générée sous une autre forme +Panel javax.swing.JPanel com.google.gwt.user.client.ui.FlowPanel +PasswordField javax.swing.JPasswordField com.google.gwt.user.client.ui.PasswordTextBox +ProgressBar javax.swing.JProgressBar org.gwtwidgets.client.ui.ProgressBar +RadioButton javax.swing.JRadioButton com.google.gwt.user.client.ui.RadioButton +ScrollPanel javax.swing.JScrollPane com.google.gwt.user.client.ui.ScrollPanel +HorizontalSplitPanel javax.swing.JSplitPane com.google.gwt.user.client.ui.HorizontalSplitPanel +VerticalSplitPanel javax.swing.JSplitPane com.google.gwt.user.client.ui.VerticalSplitPanel +TabPanel javax.swing.JTabbedPane com.google.gwt.user.client.ui.TabPanel +TextArea javax.swing.JTextArea com.google.gwt.user.client.ui.TextArea +TextField javax.swing.JTextField com.google.gwt.user.client.ui.TextBox +ToggleButton javax.swing.JToggleButton com.google.gwt.user.client.ui.ToggleButton +Tree javax.swing.JTree com.google.gwt.user.client.ui.Tree +TreeNode javax.swing.tree.DefaultMutableTreeNode com.google.gwt.user.client.ui.TreeItem +==================== ======================================= ================================================== + +Certains attributs représentant la même chose mais ayant un nom différent ont également été mis en commun dans ces balises (ex: *selected* pour JToggleButton et *down* pour ToggleButton ont été regroupé sous *selected*). + + +Balise Table +------------ +Guix définit également une balise *Table*, qui permet de placer aisément les composants dans la fenêtre, à la manière d'un tableau. + +La balise *Table* ne peut avoir comme balises filles que des balises *Row*, qui ne peuvent elles-même avoir que des balises *Cell*. Les balises *Cell* peuvent contenir n'importe quelle autre balise, mais une seule. + +Pour chacune de ces balises, on peut définir les attributs suivants : + +=================== ======================= ================================ +Attribut Description Valeurs possibles +=================== ======================= ================================ +fill remplissage de l'espace non utilisé de la cellule none, horizontal, vertical, both +horizontalAlignment alignement horizontal dans la cellule left, right, center +verticalAlignment alignement vertical dans la cellule top, bottom, middle +ipadx espace horizontal entre le bord de la cellule et le composant un entier +ipady espace vertical entre le bord de la cellule et le composant un entier +weightx définit comment redistribuer l'espace horizontal supplémentaire entre les cellules un entier positif ou nul +weighty définit comment redistribuer l'espace vertical supplémentaire entre les cellules un entier positif ou nul +insets espace entre le bord de la cellule et le bord des cellules des autres composants un quadruplet d'entiers (ex : "1,2,4,0") +=================== ======================= ================================ + +En Swing, un JPanel sera généré, avec comme layout un GridBagLayout. En GWT, il s'agit d'une FlexTable. + +Balise Tab +---------- +La balise *TabPanel* accepte comme balises filles les balises *Tab*, qui représente les onglets. L'attribut *title* permet de définir le nom de l'onglet. + Modified: trunk/src/site/rst/guixFiles.rst =================================================================== --- trunk/src/site/rst/guixFiles.rst 2009-08-26 15:15:16 UTC (rev 1594) +++ trunk/src/site/rst/guixFiles.rst 2009-08-26 15:20:21 UTC (rev 1595) @@ -1,14 +1,118 @@ +============= Fichiers Guix -------------- +============= Structure ~~~~~~~~~ - - Définition des espaces de nommage (optionnel) - - Commentaires contenant la javadoc de la classe à créer (optionnel) - - Balise racine représentant la superclasse de la classe à créer - - Balises représentant les composants de l'IHM +Un fichier Guix est un fichier XML dont chaque balise représente un composant ou un objet de la classe qui sera générée, dont la classe est le type de la balise. On peut soit écrire le nom entier de la classe (FQN), soit définir des espaces de nommage avec le package et préfixer le nom de la classe, soit simplement mettre le nom de la classe sans le package. Dans le dernier cas, le package utilisé sera le package par défaut (*javax.swing* pour Swing, *com.google.gwt.user.client.ui* pour GWT). -Pour assigner des valeurs aux attributs des composants, il suffit de les définir dans les attributs des balises. +Le type de la balise racine représente la superclasse dont héritera la classe générée. -Des balises *<script>* ou *<style>* peuvent être ajoutées n'importe où dans le fichier. Leur contenu sera attaché à la classe générée. +Les balises filles d'une balise seront générées comme des sous-composants. +:: + + <Panel> + <Label /> + <Button /> + </Panel> + +L'exemple ci-dessus représente un Panel contenant un Label et un Button. + +Les commentaires sont interprétés comme la javadoc de la balise située juste en dessous. + + +Attributs +~~~~~~~~~ + +Attributs des objets +******************** +Pour assigner des valeurs aux attributs des composants, il suffit de les définir dans les attributs des balises. Exemple :: + + <Button text="Bouton" /> + +Attributs spéciaux +****************** +Certains attributs sont des attributs spéciaux de Guix : + - *id* : identifiant de l'objet + - *constructor* : paramètres du constructeur de l'objet + - *javaBean* : si vrai, ajoute un modifieur à l'objet généré (vrai par défaut) + - *styleClass* : la classe de style qui permet de définir certaines propriétés communes grâce au CSS + +Pour les attributs dont le type est une chaîne de caractères, il est inutile de mettre les guillemets dans la valeur de l'attribut, comme dans l'exemple précédent. En revanche, pour le constructeur, il est nécessaire de les mettre :: + + <Button constructor='"Bouton"' /> + +Actions et évènements +********************* +Les attributs des balises permettent également de définir les actions en réponse à des évènements. Il suffit pour celà de définir l'attribut du même nom que l'évènement à écouter et d'écrire le code java à exécuter :: + + <Button onActionPerformed='System.out.println("Hello world")' /> + +Guix se chargera de trouver le bon Listener à ajouter à l'objet. + +Data binding +************ +Derrière ce terme se cache un mécanisme très utile, celui de lier la valeur d'un attribut d'un objet, à la valeur d'un (ou plusieurs) attribut d'un (ou plusieurs) objet. Pour cela, il suffit de mettre la valeur de l'attribut entre accolades. +:: + + <TextField id="textfield" /> + <Label text="Vous avez écrit : {textfield.getText()}" /> +Dans l'exemple ci-dessus, le texte du Label changera dès que l'utilisateur écrira dans *textfield*. + +Le binding permet également de ne pas indiqué la méthode mais l'attribut sur lequel porte le binding. L'exemple précédent donenrait donc :: + + <TextField id="textfield" /> + <Label text="Vous avez écrit : {textfield.text}" /> + +Héritage +******** +Il est possible de faire de l'héritage entre classes générées. Les composants définis dans la classe fille seront ajoutés à la suite des composants de la classe mère. + +Il est possible de surcharger un composant, soit pour ajouter des attributs, soit pour changer la classe de celui-ci, en donnant le même attribut *id* au nouveau composant. Bien sûr, ceci ne fonctionne que si la classe du composant de la classe fille est la même que la classe de celui de la classe mère ou en hérite. + + +Balises spéciales +~~~~~~~~~~~~~~~~~ + +script +****** +Si on veut ajouter du code directement dans la classe générée, on peut ajouter des balises *<script>* n'importe où dans le fichier. On peut soit entrer le code directement à l'intérieur de ces balises, ou alors indiquer l'attribut *source* et indiquer le chemin d'un fichier .script qui contient le code. Ce code sera vérifié et ajouté à la classe générée. + +S'il existe un fichier .script ayant le même nom qu'un fichier .guix, il lui est automatiquement lié. + +Il existe 5 méthodes vides par défaut, que l'utilisateur peut surcharger et qui s'effectueront chacune à un moment précis, dans cet ordre : + - **beforeCreation** s'exécute avant la création des composants + - **beforeSettings** s'exécute avant l'affectation des attributs des composants + - **beforeTree** s'exécute avant la mise en page des composants + - **beforeBinding** s'exécute avant l'application du data binding + - **inTheEnd** s'exécute à la fin, quand l'application est prête + +Pour les surcharger, il suffit qu'il les redéfinisse dans un script. + +style +***** +On peut définir des règles de CSS à appliquer aux composants. Leur ajout fonctionne sur le même principe que pour les balises de script. + +Pour la génération en GWT, les fichiers CSS indiqués en source sont ajoutés à l'application comme des vrais fichiers CSS. + +Pour la génération en Swing, les fichiers CSS sont analysés et chaque règle sera interprétée comme un attribut. On distingue les règles sur les classes java, les règles sur les identifiants et les règles sur les classes de style :: + + /* Règle sur la classe Button */ + Button { + text: "Bouton"; + onActionPerformed: {System.out.println("Hello world")}; + foreground: "Color.BLUE"; + } + + /* Règle sur l'identifiant button */ + #button { + enabled: "false"; + } + + /* Règle sur la classe de style */ + .red { + background: "Color.RED"; + } + + Added: trunk/src/site/rst/installation.rst =================================================================== --- trunk/src/site/rst/installation.rst (rev 0) +++ trunk/src/site/rst/installation.rst 2009-08-26 15:20:21 UTC (rev 1595) @@ -0,0 +1,50 @@ +============ +Installation +============ + +Archetypes Maven +---------------- + +Pour créer un projet Maven 2 utilisant Guix, vous pouvez utiliser un des deux archetypes disponible : + - maven-guix-swing-archetype + - maven-guix-gwt-archetype + +Pour générer du Swing, lancer la commande :: + + mvn archetype:create \ + -DarchetypeGroupId=org.nuiton.guix \ + -DarchetypeArtifactId=maven-guix-swing-archetype \ + -DarchetypeVersion=1.0.0 \ + -DgroupId=<my.groupid> \ + -DartifactId=<my-artifactId> + +Pour générer du GWT, lancer la commande :: + + mvn archetype:create \ + -DarchetypeGroupId=org.nuiton.guix \ + -DarchetypeArtifactId=maven-guix-gwt-archetype \ + -DarchetypeVersion=1.0.0 \ + -DgroupId=<my.groupid> \ + -DartifactId=<my-artifactId> + + +Configuration du pom.xml +------------------------ +Configuration commune aux librairies graphiques +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Les propriétés suivantes du plugin maven-guix-plugin sont communes aux différentes librairies graphiques : + - **guixfilesBaseDir** : le dossier racine de vos packages ("src/main/java" par défaut) + - **guixFilesDir** : le dossier où se trouvent les fichiers Guix à compiler. Si certains de vos fichiers font appels à d'autres fichier Guix qui ne se trouvent pas dans ce dossier mais qui se trouvent dans *guixFilesBaseDir* il ira les chercher quand même ("src/main/java" par défaut) + - **targetDirectory** : dossier où seront générés les fichiers java + - **mainClass** : classe principale de votre application (obligatoire) + - **generationLanguage** : la librairie graphique de génération + +Swing +~~~~~ +Pour Swing, la propriété **launcherName** représente le nom de la classe qui sera générée et qui contiendra la méthode *main*. Si vous la modifiez, il faudra également changer la propriété *maven.jar.main.class*. + +GWT +~~~ +Pour GWT, la propriété **launcherName** représente le fichier .gwt.xml qui sera généré et qui servira de module principal. Si vous la modifiez, il faudra également changer les propriétés *compileTargets* et *runTarget* du plugin *maven-googlewebtoolkit2-plugin*. + +