Chalklet Tutorial

Inhaltsverzeichnis

• Für wen ist dieses Tutorial?
• Was sind Chalklets?
• Voraussetzungen
• Entwicklung
• Beispiele

Für wen ist dieses Tutorial ?

Dieses Tutorial richtet sich an Entwickler, die Interesse an der Entwicklung eines Chalklets für E-Kreide haben. Etwas Erfahrung bei der Entwicklung von Java Programmen ist empfehlenswert, da grundlegende Kenntnisse im Umgang mit den Java typischen APIs, Jar-Dateien und dem Klassenpfad vorausgesetzt werden.

Was sind Chalklets ?

Die E-Kreide API ist eine Java Programmierschnittstelle, mit deren Hilfe Entwickler in der Lage sind, sogenannte Chalklet-Programme zu entwickeln, die direkt mit der Tafel des E-Kreide Systems kommunizieren können.

Die zu Grunde liegende Idee ist einfach: Chalklets melden sich als Abonnenten für einen bestimmten Tafelbereich an und erhalten dann vom Tafelsystem alle Linienzüge die durch den Benutzer, innerhalb dieses Bereichs gezeichnet wurden. Zusätzlich dürfen die Programme eigene Linienzüge auf dem vorgegebenen Bereich erzeugen. Diese einfache Art der Interaktion mit dem Tafelsystem eröffnet dem Entwickler interessante Möglichkeiten. So kann ein Chalklet zum Beispiel direkt auf die Eingabe eines Linienzuges durch den Benutzer reagieren, oder selbstständig Zeichnungen anfertigen. Chalklets werden in eigenen Jar-Archiven ausgeliefert, die alle notwendigen Klassen enthalten und in E-Kreide, wie in der Benutzerdokumentation unter Lesenzeichen für Chalklets editieren... beschrieben, eingebunden werden können.

Es wurden bereits eine Reihe von Chalklets, im Rahmen verschiedener Bachelor-, Studien- oder Diplomarbeiten entwickelt. Unter Beispiele sind verschiedene Chalklets aufgeführt.

In diesem Tutorial soll die Entwicklung eines Chalklets an einem konkreten Beispiel beschrieben werden. Es wird ein einfaches Chalklet entwickelt, das eingegebene Linienzüge des Benutzers in einer zufälligen Farbe nachzeichnet. Der Benutzer soll dabei auch die Möglichkeit haben falsche Linienzüge über die UNDO-Taste zu korrigieren.

Voraussetzungen

Um ein Chalklet zu entwickeln und zu testen, benötigt man eine funktionierende E-Kreide Installation und die E-Kreide API. Die aktuelle Version von E-Kreide kann hier heruntergeladen werden.
Die für die Entwicklung notwendigen Klassen der Chalklet API werden bei der Installation von E-Kreide im Installationsverzeichnis unter "lib/echalk.jar" abgelegt. Um ein Chalklet zu kompilieren, müssen diese Klassen im Classpath der virtuellen Maschine vorhanden sein.
Die Dokumentation der Klassen ist im Installationsverzeichnis unter "doc/echalkapi/index.html" zu finden.

Entwicklung

Chalklets werden von E-Kreide über Codereflection gefunden, das heißt E-Kreide sucht in dem Jar-Archiv des Chalklets nach festgelegten Klassen und verwendet diese für die Initialisierung und Ausführung des Chalklets.
Damit ein Chalklet korrekt funktioniert, müssen die zwei folgenden Klassen unbedingt vorhanden sein:

• Eine Klasse die von "de.echalk.util.ChalkletKit" erbt - das ChalkletKit wird von E-Kreide erwendet um festzulegen welche Parameter das Chalklet bekommt und diese beim Start zu übergeben
• Eine Klasse die das Interface "de.echalk.util.Chalklet" implementiert - diese Klasse stellt das eigentliche Chalklet dar

1. Das ChalkletKit (Quellcode)

	 1 package chalkletexample;
	 2 
	 3 import de.echalk.util.*;
	 4 import java.awt.Dimension;
	 5 import java.util.Locale;
	 6

	 7 public class ExampleChalkletKit extends ChalkletKit{
	

	 8  private static final KitSetupInfo KIT_INFO = new ExampleChalkletKitSetupInfo();
	

	 9  private ExampleChalkletKit() {}
	10
	

	11  public static KitSetupInfo getKitSetupInfo() {
	12      return KIT_INFO;
	13  }
	14

	15  public static Chalklet getChalklet( ChalkletContext aContext, 
                                                String[] aStrings ) {
	16     if ( aStrings.length != 1 )
	17        throw new IllegalArgumentException("One argument expected but "+
                                                aStrings.length+" found. ");
	18     final long _delay = Long.parseLong( aStrings[0] );
	19     if ( _delay <= 0 )
	20         throw new IllegalArgumentException( "delay is not positive: "+_delay );
	21     return new ExampleChalklet(aContext,_delay);
	22  }
	23
	

	24  public static Dimension getMinimumChalkletSize( String[] aStrings ) {
	25     return new Dimension(200, 100);
	26  }
	27
	

	28  public static String getChalkletName( Locale aLocale ) {
	29     return Txt.get("Example Chalklet", aLocale);
	30  }
	31
	

	32  private static final class ExampleChalkletKitSetupInfo 
	33                       extends KitSetupInfo {
	34
	

	35     public String getDescription( Locale aLocale ) {
	36       return Txt.get( "A Simple Chalklet Example...\n", aLocale );
	37      }
	38
	

• BooleanParam - boolscher Parameter, kann die Werte wahr oder falsch annehmen.
• EnumParam - Klasse für einen Auswahl Parameter aus einer übergebenen Liste.
• FileParam - Klasse für Dateinamen.
• LongParam - Klasse für einen Long Parameter
• PasswordParam - Bei der Eingabe bleibt das Passwort verborgen. Es wird allerdings lokal unverschlüsselt gespeichert (nicht Zugriffsgesichert gegen lokale Nutzer).
• StringParam - Zeichenketten, ohne Zeilenumbrüche.
• TextParam - Mehrzeilige Texte, in denen Zeilenumbrüche erlaubt sind.

	39     public ParamInfo[] getParamInfo( Locale aLocale ) {
	40         final String _aDelayName  = Txt.get( "Delay", aLocale );
	41         final String _aDelayDescription = Txt.get( 
                                                     "Delay for strokes moves in ms.",
                                                     aLocale );
	42         final ParamInfo _aDelayParam =
	43                new LongParam( _aDelayName, _aDelayDescription, 
                                         new Long(1), new Long(1), null);
	44         return new ParamInfo[] { _aDelayParam };
	45    }
	46  } // End of ExampleChalkletSetupInfo
	47} //end of ExampleChalkletKit
	

2. Das Chalklet (Quellcode)

	 1 package chalkletexample;
	 2
	 3 import de.echalk.util.*;
	 4 import java.awt.Color;
	 5 import java.util.LinkedList;
	 6 import java.util.*;
	 7
	

	 8 public class ExampleChalklet implements Chalklet {
	

	 9  private final ChalkletContext aContext_; // Chalklet drawing context
	10  private final long aDelay_;  // time the chalklets waits after a stroke
	11  private boolean aliveFlag_;  // chalklet still alive?
	12  private LinkedList strokeBuffer_; // list of all strokes drawn so far (for undo)
	

	13  public ExampleChalklet(ChalkletContext aContext, long aDelay) {
	14  aContext_=aContext;
	15  aDelay_=aDelay;
	16  strokeBuffer_= new LinkedList();
	17  aliveFlag_=true;
	18  }
	19
	

	20 /**
	21   * endChalklet
	22   */
	23 public void endChalklet() {
	24   aliveFlag_=false;
	25  }
	26
	

	27  /**
	28    * pushStroke
	29    *
	30    * @param boardStroke BoardStroke
	31    */
	32 public void pushStroke(BoardStroke boardStroke) {
	33   try {
	34    Thread.sleep(aDelay_); // wait delay
	35   }
	36   catch (InterruptedException ex) { }
	37   BoardStroke bs;
	38
	39   // run color is red
	40   if(boardStroke.getColor().equals(Color.red)){
	41    Iterator iter = strokeBuffer_.iterator();
	42   while (iter.hasNext()) {
	43     if(!aliveFlag_) return; // only react if still alive
	44     bs = (BoardStroke)iter.next();
	45     // redraw stroke in random color
	46     // note that strokes are drawn in "earlier ending strokes first" order
	47     aContext_.sendStroke(new BoardStroke(bs,
	48                  0,0,
	49                  0,
	50                  0,
	51                  0,
	52                  new Color((float)Math.random(),
	53                                (float)Math.random(),
	54                                (float)Math.random())));
	55    }
	56  }
	57
	58   strokeBuffer_.add(boardStroke); // add stroke to buffer for later removal
	59 }
	60
	

	61  /**
	62    * removeLastStroke
	63    */
	64 public void removeLastStroke() {
	65   if(strokeBuffer_.isEmpty() || !aliveFlag_) return;
	66   // remove stroke from queue, so that it is not redrawn
	67   strokeBuffer_.removeLast();
	68 }
	69} // end of ExampleChalklet
	

Beispiele