JavaScool:DocCreationProgletExemple : Différence entre versions

De Sciencinfolycee
Aller à : navigation, rechercher
m
m
 
(33 révisions intermédiaires par le même utilisateur non affichées)
Ligne 1 : Ligne 1 :
 
[[Catégorie:JavaScoolDev]] __NOTOC__  
 
[[Catégorie:JavaScoolDev]] __NOTOC__  
Cette page a pour but de vous expliquer comment créer une proglet concrètement. Elle présente une proglet d'exemple, affichant simplement un bouton et un label, et permettant à l'utilisateur d'interagir avec ces derniers. Le code est commenté et détaillé, et vous pouvez télécharger :
+
Cette page a pour but d'expliquer comment créer une proglet concrètement. Elle présente une proglet d'exemple, affichant simplement un label, et permettant à l'utilisateur d'interagir avec ce dernier.
  
* [proglets/sources-sampleCode.zip Les sources au format zip]
+
* Le code est commenté et disponible en [http://javascool.gforge.inria.fr/documents/javadoc/javascool-proglet-sampleCode.jar sauvegardant sur le disque] une archive zip, qui peut aussi être exécutée en [http://javascool.gforge.inria.fr/documents/javadoc/javascool-proglet-sampleCode.jar l'ouvrant avec Java].
* [proglets/javascool-proglet-sampleCode.jar L'exécutable au format jar]
+
 
 +
* L'outil de création/complilation de proglets, le [[JavaScool:DocJavaScoolBuilder|Javascoolbuilder]] permet de proposer un modèle de fichier du type ci dessous
 +
 
 +
* La description de la [[JavaScool:DocCreationProglet|spécification]] des proglets donne une description complète des fonctionnalités mises à disposition (en particulier la possibilité de définir des sous-langages et de la complétion automatique dans l'éditeur) non détaillées ici dans un soucis de simplicté.
 +
 
 +
* '''proglets processing''': Pour créer des proglets avec [http://processing.org processing] se référer aussi à la [[JavaScool:ProgletProcessing|documentation spécifique]].
 +
 
 +
* '''utiliser netbeans''': Pour créer des proglets avec [http://fr.netbeans.org netbeans] se référer aussi à la [[JavaScool:UsingNetbeans|documentation spécifique]].
 +
 
 +
* Dans tous les cas quelqu'un qui crée un proglet le fait avec l'aide de l'équipe de Java's Cool :
 +
** ne pas hésiter à [http://javascool.gforge.inria.fr/?page=contact nous contacter].
  
 
= proglet.pml =
 
= proglet.pml =
  
Ce fichier est le coeur de la proglet : il définit la description de la proglet, le nom de son icône et les auteurs
+
Ce fichier donne la description de la proglet, le nom de son icône et les auteurs
  
{proglet
+
<pre>
  title="Exemple de proglet"
+
  title="Exemple de «proglet»"
  author="Guillaume Matheron "
+
  author="Guillaume Matheron <guillaume.quest@gmail.com>"
 
  icon="sample.png"
 
  icon="sample.png"
}
+
</pre>
 +
 
 +
Note: http://www.iconfinder.com est un excellent outil pour trouver des icones, ici de 128x128.
  
 
= sample.png =
 
= sample.png =
Ligne 19 : Ligne 31 :
 
Cette image est le logo de la proglet. Elle peut avoir n'importe quel nom mais celui-ci doit être mentionné dans le fichier proglet.pml
 
Cette image est le logo de la proglet. Elle peut avoir n'importe quel nom mais celui-ci doit être mentionné dans le fichier proglet.pml
  
Note : il est quasi-indispensable que cette image soit au format png transparent. Sans cela il sera très difficile dee l'intégrer sur le site sans affecter son design
+
Note : il est quasi-indispensable que cette image soit au format png transparent. Sans cela il est très difficile de l'intégrer sur le site sans affecter son design.
  
[[Image:sample.png|Logo de la proglet]]
+
Note: la taille maximale de cette image est de <tt>128x128</tt> pour respecter le design.
  
= Panel.java =
+
= help.xml =
  
C'est le fichier central de la proglet, en quelque sorte (ou au moins de son code Java). Il contient la description de la zone de Javascool réservée à la proglet (le 'panel') et le code à exécuter automatiquement au lancement de la proglet (initialiser des variables, créer des listeners, lancer des tâches de fond etc.)
+
Ce fichier définit la documentation pour l'utilisateur. Le fichier est écrit en XML.
 +
L'aide quant à comment rédiger ce fichier est [[JavaScool:DocumentsHml|disponible ici]].
  
La classe Panel doit hériter de la classe JApplet. On créera donc une autre class, ProgletPanel, qui contiendra tous les éléments graphiques de la proglet. On se contentera donc dans la classe Panel d'implémenter la méthode init() de la classe JApplet et d'instancier la class ProgletPanel.
+
Il est possible, de créer plusieurs fichiers d'aide XML, mais ils seront tous convertis au format HTML, dans un fichier d'extension '''.htm'''. Toutes les pages d'aide peuvent être liées les unes aux autres, en utilisant l'extension .'''htm'''.
  
Notes :
+
Note : le nom du fichier help.xml est fixé par les spécifications d'une proglet.
  
* Le nom de la classe Proglet est fixé par les spécifications, mais celui de la classe ProgeltPanel ne l'est pas. En fait, cette classe peut très bien ne pas exister ou être définie comme classe privée dans la classe Panel.
+
= Panel.java =
* La classe Panel doit hériter de la classe java.applet.Applet mais il est en général plus simple de la faire hériter de javax.swing.JApplet. Ceci est autorisé car javax.swing.JApplet hérite elle-même de java.applet.Applet.
 
* On utilise ici la fonction Macros.readString(). Plus d'informations dans la [?page=developers&action=faq#fsfgs FAQ]
 
* Consultez les [?page=developers&action=proglets spécifications d'une proglet]
 
  
Code source du fichier Panel.java
+
C'est le fichier qui contient la description de l'objet graphique qui incarne la proglet.
 +
Cette classe Java implémente le code à exécuterau lancement de la proglet (initialisation des variables, lancer des tâches, etc..).
  
import javax.swing.JApplet;
+
La classe Panel doit hériter d'un composant graphique tel que <tt>javax.swing.JPanel</tt>.
import org.javascool.tools.Macros;
 
 
public class Panel extends JApplet {
 
private static ProgletPanel panel=new ProgletPanel();
 
 
/** Constructeur par défaut */
 
public Panel() {
 
// Affiche panel en tant que panel principal de cette applet
 
setContentPane(panel);
 
}
 
 
/** Récupérer le ProgletPanel affiché */
 
public static ProgletPanel getPanel() {
 
return panel;
 
}
 
 
/** Juste pour montrer que cette méthode peut être implémentée */
 
public void init() {
 
        // On demande un texte à l'utilisateur et on l'affiche en label
 
panel.setText(Macros.readString());
 
}
 
}
 
  
= ProgletPanel.java =
+
Note: le nom Panel.java est fixé par les spécifications
  
Ce fichier définit le panel qui sera affiché dans l'applet. La classe ProgletPanel doit donc étendre la classe java.awt.Panel.
+
Dans notre exemple les éléments clés sont:
 +
<pre>
 +
package org.javascool.proglets.sampleCode;
 +
import javax.swing.JLabel;
  
Lors de sa construction elle crée un label et l'affiche en haut du panel. Elle définit aussi une méthode permettant de changer le texte du label, pour respecter l'encapsulation.
+
public class Panel extends javax.swing.JPanel {
 +
  // Construction de la proglet
 +
  public Panel() {
 +
    // On crée un label
 +
    label = new JLabel("");
 +
    // Et on l'ajoute au panel
 +
    add(label);
 +
  }
 +
  // Ce label sera utilisé par la routine Functions.setMessage()
 +
  JLabel label;
 +
}
 +
</pre>
 +
# La proglet de nom <tt>sampleCode</tt> est définie dans un package de nom <tt>org.javascool.proglets.sampleCode</tt>.
 +
# La classe se nomme bien <tt>Panel.java</tt> et hérite de <tt>javax.swing.JPanel</tt>
 +
# Dans le fichier source il y a aussi une méthode <tt>run()</tt> qui permet de lancer une démo de la proglet (elle n'est pas recopiée ici):
 +
<pre>
 +
  public void run() {
 +
  }
 +
</pre>
 +
Note: ce n'est plus start() mais <tt>run()</tt> qu'il faut utiliser.
  
import java.awt.Panel;
+
Note: La plateforme JavaScool propose:
import java.awt.Label;
+
* Des [http://javascool.gforge.inria.fr/?page=api:/org/javascool/widgets/package-summary.html widgets] pour aider à créer des interfaces graphiques.
import java.awt.BorderLayout;
+
* Des [http://javascool.gforge.inria.fr/?page=api:/org/javascool/macros/package-summary.html macros] et des [http://javascool.gforge.inria.fr/?page=api:/org/javascool/tools/package-summary.html tools] disposer de fonctions utilitaires facilitant l'implémentation.
import java.lang.String;
+
* Un mécanisme d'[http://javascool.gforge.inria.fr/index.php?page=api&api=org/javascool/macros/Macros.html#assertion%28boolean,%20java.lang.String,%20java.lang.Object%29 assertion] aide à débugger le code.
 
public class ProgletPanel extends Panel {
 
/** Correspond au label affiché dans le panel de la proglet */
 
private Label label;
 
 
/** Construit un nouveau panel */
 
public ProgletPanel() {
 
// On crée un label
 
label=new Label("");
 
// Et on l'ajoute au panel
 
add(label,BorderLayout.NORTH);
 
}
 
 
/** Change le texte affiché dans le label */
 
public void setText(String text) {
 
label.setText(text);
 
}
 
}
 
  
 
= Functions.java =
 
= Functions.java =
  
Ce fichier définit les fonctions directement accessibles depuis Java's Cool, et qui permettent donc d'interagir avec la proglet
+
Ce fichier définit les fonctions directement accessibles depuis Java's Cool, et qui permettent donc d'interagir avec la proglet.  
 
 
Dans cet exemple, nous définirons une méthode getText(String) qui permettra de changer le texte affiché dans le panel de la proglet. Toutes les méthodes de Fonctions doivent être statiques pour être accessibles depuis Java's Cool.
 
 
 
import java.lang.String;
 
 
public class Functions {
 
/** Permet de changer le texte affiché sur le panel de la proglet */
 
public static void setText(String text) {
 
Panel.getPanel().setText(text);
 
}
 
}
 
 
 
= help.xml =
 
 
 
Ce fichier définit l'aide à afficher à l'utilisateur. Le fichier est écrit en xml, vous pouvez trouver de l'aide quand à comment rédiger ce fichier dans les [?page=developers&action=doc-xml spécifications des fichiers d'aide]. Il est possible, de créer plusieurs fichiers d'aide, mais ils seront tous convertis au format htm lors de la compilation de la proglet. Pour lier les fichiers entre eux, vous devez donc y référer en tant que fichiers htm.
 
 
 
Note : le nom du fichier help.xml est fixé par les spécifications d'une proglet
 
  
+
Note: le nom Functions.java est fixé par les spécifications.
  
= exercice.xml =
+
Dans cet exemple, nous définissons la méthode <tt>setMessage(String)</tt> qui permet de changer le texte affiché.  
 +
<pre>
 +
package org.javascool.proglets.sampleCode;
 +
import static org.javascool.macros.Macros.*;
  
Ce fichier est un fichier xml : il sera converti en htm et permet de créer une seconde page d'aide. Toutes les pages d'aide peuvent être liées les unes aux autres
+
public class Functions {
 +
  /** Renvoie l'instance de la proglet. */
 +
  private static Panel getPane() {
 +
    return getProgletPane();
 +
  }
 +
  /** Permet de changer le message affiché sur le panel de la proglet */
 +
  public static void setMessage(String text) {
 +
    getPane().label.setText(text);
 +
  }
 +
}
 +
</pre>
 +
# La proglet de nom <tt>sampleCode</tt> est définie dans un package de nom <tt>org.javascool.proglets.sampleCode</tt>.
 +
# La classe se nomme bien <tt>Functions.java</tt> et la fonction <tt>setMessage(String)</tt> est bien publique et statique.
 +
# La construction
 +
#* <tt>private static Panel getPane() { return org.javascool.macros.Macros.getProgletPane(); }</tt>
 +
#* permet de renvoyer l'instance de classe <tt>org.javascool.proglets.sampleCode.Panel</tt> que la plateforme JavaScool utilise afin d'y accéder.
 +
# La classe <tt>org.javascool.macros.Macros</tt> contient des fonctions utiles pour définir des proglets.

Version actuelle datée du 17 août 2012 à 15:21

Cette page a pour but d'expliquer comment créer une proglet concrètement. Elle présente une proglet d'exemple, affichant simplement un label, et permettant à l'utilisateur d'interagir avec ce dernier.

  • L'outil de création/complilation de proglets, le Javascoolbuilder permet de proposer un modèle de fichier du type ci dessous
  • La description de la spécification des proglets donne une description complète des fonctionnalités mises à disposition (en particulier la possibilité de définir des sous-langages et de la complétion automatique dans l'éditeur) non détaillées ici dans un soucis de simplicté.
  • Dans tous les cas quelqu'un qui crée un proglet le fait avec l'aide de l'équipe de Java's Cool :

proglet.pml

Ce fichier donne la description de la proglet, le nom de son icône et les auteurs

 title="Exemple de «proglet»"
 author="Guillaume Matheron <guillaume.quest@gmail.com>"
 icon="sample.png"

Note: http://www.iconfinder.com est un excellent outil pour trouver des icones, ici de 128x128.

sample.png

Cette image est le logo de la proglet. Elle peut avoir n'importe quel nom mais celui-ci doit être mentionné dans le fichier proglet.pml

Note : il est quasi-indispensable que cette image soit au format png transparent. Sans cela il est très difficile de l'intégrer sur le site sans affecter son design.

Note: la taille maximale de cette image est de 128x128 pour respecter le design.

help.xml

Ce fichier définit la documentation pour l'utilisateur. Le fichier est écrit en XML. L'aide quant à comment rédiger ce fichier est disponible ici.

Il est possible, de créer plusieurs fichiers d'aide XML, mais ils seront tous convertis au format HTML, dans un fichier d'extension .htm. Toutes les pages d'aide peuvent être liées les unes aux autres, en utilisant l'extension .htm.

Note : le nom du fichier help.xml est fixé par les spécifications d'une proglet.

Panel.java

C'est le fichier qui contient la description de l'objet graphique qui incarne la proglet. Cette classe Java implémente le code à exécuterau lancement de la proglet (initialisation des variables, lancer des tâches, etc..).

La classe Panel doit hériter d'un composant graphique tel que javax.swing.JPanel.

Note: le nom Panel.java est fixé par les spécifications

Dans notre exemple les éléments clés sont:

package org.javascool.proglets.sampleCode;
import javax.swing.JLabel;

public class Panel extends javax.swing.JPanel {
  // Construction de la proglet
  public Panel() {
    // On crée un label
    label = new JLabel("");
    // Et on l'ajoute au panel
    add(label);
  }
  // Ce label sera utilisé par la routine Functions.setMessage()
  JLabel label;
}
  1. La proglet de nom sampleCode est définie dans un package de nom org.javascool.proglets.sampleCode.
  2. La classe se nomme bien Panel.java et hérite de javax.swing.JPanel
  3. Dans le fichier source il y a aussi une méthode run() qui permet de lancer une démo de la proglet (elle n'est pas recopiée ici):
  public void run() {
  }

Note: ce n'est plus start() mais run() qu'il faut utiliser.

Note: La plateforme JavaScool propose:

  • Des widgets pour aider à créer des interfaces graphiques.
  • Des macros et des tools disposer de fonctions utilitaires facilitant l'implémentation.
  • Un mécanisme d'assertion aide à débugger le code.

Functions.java

Ce fichier définit les fonctions directement accessibles depuis Java's Cool, et qui permettent donc d'interagir avec la proglet.

Note: le nom Functions.java est fixé par les spécifications.

Dans cet exemple, nous définissons la méthode setMessage(String) qui permet de changer le texte affiché.

package org.javascool.proglets.sampleCode;
import static org.javascool.macros.Macros.*;

public class Functions {
  /** Renvoie l'instance de la proglet. */
  private static Panel getPane() {
    return getProgletPane();
  }
  /** Permet de changer le message affiché sur le panel de la proglet */
  public static void setMessage(String text) {
    getPane().label.setText(text);
  }
}
  1. La proglet de nom sampleCode est définie dans un package de nom org.javascool.proglets.sampleCode.
  2. La classe se nomme bien Functions.java et la fonction setMessage(String) est bien publique et statique.
  3. La construction
    • private static Panel getPane() { return org.javascool.macros.Macros.getProgletPane(); }
    • permet de renvoyer l'instance de classe org.javascool.proglets.sampleCode.Panel que la plateforme JavaScool utilise afin d'y accéder.
  4. La classe org.javascool.macros.Macros contient des fonctions utiles pour définir des proglets.