declare global {
|
/**
|
* Wenn die Bibliothek zur Erweiterung der IDE eingebunden (`ide-lib.js`) wurde,
|
* steht diese globale Variable mit Zugang zur öffentlichen Schnittstelle
|
* zur Verfügung.
|
*/
|
const MC: MathCoach.Api;
|
}
|
|
|
|
/**
|
* Der MathCoach-Namensraum ist die Sammelstelle für alle öffentlichen Schnittstellen.
|
* Somit können auch externe Module (z.B. grafische Editoren) typsicher erstellt werden.
|
*
|
* Als Einstiegspunkt dient das interface `MathCoach.Api` - eine Implementierung dieser Schnittstelle
|
* wird von der IDE (siehe `ide-lib.js`) bereitgestellt und kann über die globale Variable
|
* `MC` zugegriffen werden.
|
*
|
* Beispiel:
|
*
|
* const isReady = await MC.ide.isReady(); // true oder false
|
*/
|
export namespace MathCoach {
|
|
/**
|
* Als Einstiegspunkt dient das interface `MathCoach.Api` - eine Implementierung dieser Schnittstelle
|
* wird von der IDE (siehe `ide-lib.js`) bereitgestellt und kann über die globale Variable
|
* `MC` zugegriffen werden.
|
*
|
*
|
* Beispiel:
|
*
|
* const isReady = await MC.ide.isReady(); // true oder false
|
*/
|
export interface Api {
|
/**
|
* Die Schnittstelle zur Entwicklungsumgebung (IDE) von MathCoach.
|
*/
|
readonly ide: IdeApi;
|
|
/**
|
* Prüft, ob die API einsatzbereit ist. Dies sollte einmalig, beim Start des Werkzeugs,
|
* geprüft werden. Dabei bedeutet der Rückgabewert `true`, dass das Werkzeug durch
|
* die IDE gestartet wurde und die Kommunikation möglich ist. `false` bedeutet, dass
|
* das Werkzeug nicht durch die IDE gestartet wurde.
|
*
|
* Somit wäre es möglich ein Tool offlinefähig zu machen, indem es ggf. eine eigene
|
* Implementierung der MathCoach-API (beispielsweise unter Verwendung des LocalStorage
|
* zum Speichern von Dateien) verwendet.
|
*
|
* Anwendungsbeispiel (Prüft zusätzlich, ob die globale `MC`-Variable verfügbar ist - also
|
* die `ide-lib.js` korrekt eingebunden und geladen wurde):
|
*
|
* let isReady = (typeof MC !== "undefined") ? await MC.isReady() : false;
|
* if(isReady){
|
* // MathCoach-API is ready to use!
|
* }else{
|
* // MathCoach-API is not ready...
|
* }
|
*
|
*
|
*/
|
isReady(): Promise<boolean>;
|
}
|
|
|
/**
|
* Schnittstelle zur IDE von MathCoach
|
*/
|
export interface IdeApi {
|
/**
|
* Gibt den Namen des aktuellen Benutzers zurück, der mit dem Werkzeug arbeitet.
|
*
|
* Anwendungsbeisipiel:
|
*
|
* let user = await MC.ide.getUserName();
|
*
|
*/
|
getUserName(): Promise<string>;
|
/**
|
* Gibt den Verweis auf die Datei zurück, mit der das Entwicklerwerkzeug gestartet wurde.
|
*
|
* Anwendungsbeispiel:
|
*
|
* let file = await MC.ide.getContextFile();
|
* let { owner, path, part } = file;
|
*/
|
getContextFile(): Promise<File>;
|
/**
|
* Einstiegspunkt der Dateisystem-Schnittstelle (z.B. um Dateien zu lesen und zu schreiben)
|
*/
|
readonly fs: FileSystemApi;
|
/**
|
* Einstiegspunkt der Vorschau-Schnittstelle (z.B. um generierte Aufgaben zu starten)
|
*/
|
readonly navigator: NavigatorApi;
|
}
|
/**
|
* Schnittstelle zur Navigation der Vorschau
|
*/
|
export interface NavigatorApi {
|
/**
|
* Navigiert die Vorschau zu einem Link.
|
*
|
* Anwendungsbeispiel:
|
*
|
* await MC.ide.navigator.navigateTo("/mathcoach/www/yourName/readme.html", true)
|
*
|
*
|
* @param link Web URL (z.B. zu einer Datei im WWW-Verzeichnis oder einer MathCoach-Aufgabe)
|
* @param forceOpen `true` um das Anzeigen der Vorschau zu erzwingen, `false` um nur bei bereits geöffneter Vorschau zu navigieren.
|
*/
|
navigateTo(link: string, forceOpen?: boolean): Promise<void>;
|
|
/**
|
* Navigiert die Vorschau zu einer MathCoach-Aufgabe.
|
* Hinweis: Die Datei muss im `vfs`-Teil des Dateisystems liegen und
|
* eine ausführbare MathCoach-Aufgabe sein (z.B. eine groovy-Datei).
|
*
|
* Anwendungsbeispiel:
|
*
|
* let file = { part: "vfs", owner:"yourName", path: "/myExercise.groovy" }
|
* await MC.ide.navigator.navigateToExercise(file)
|
*
|
* @param file Datei-Verweis
|
*/
|
navigateToExercise(file: MathCoach.File, forceOpen?: boolean): Promise<void>
|
}
|
/**
|
* Schnittstelle zum Dateisystem
|
*/
|
export interface FileSystemApi {
|
/**
|
* Liest eine Datei und gibt den Textinhalt zurück.
|
*
|
* Anwendungsbeispiel: Lesen der Datei, mit dem das Werkzeug gestartet wurde
|
*
|
* let file = await MC.ide.getContextFile();
|
* let text = await MC.ide.fs.readFile(file);
|
* // do something with the text, e.g. JSON.parse(text)
|
*
|
* @param file Verweis auf die Datei
|
*/
|
readFile(file: File): Promise<string>;
|
/**
|
* Schreibt Text in eine Datei.
|
*
|
* Anwendungsbeispiel: Schreiben der Datei, mit dem das Werkzeug gestartet wurde
|
*
|
* let file = await MC.ide.getContextFile(); // some file reference
|
* let text = "some text"; // or JSON.stringify(yourDataContainer)
|
* await MC.ide.fs.writeFile(file,text);
|
*
|
* @param file Verweis auf die Datei
|
* @param text Der neue Inhalt der Datei
|
*/
|
writeFile(file: File, text: string): Promise<void>;
|
}
|
/**
|
* Eindeutiger Verweis auf eine Datei.
|
*
|
* Anwendungsbeispiel:
|
*
|
* let user = await MC.ide.getUserName(); // oder von einem anderen File-Objekt abgfragen...
|
* let file = { owner: user, part: "vfs", path:"/myExercise.groovy" }
|
*
|
* Siehe auch: `MC.ide.getContextFile()`
|
*
|
*/
|
export interface File {
|
/**
|
* Name des Besitzers. Hinweis: Der Besitzter kann vom angemeldeten
|
* Benutzer abweichen (z.B. wenn das Teilen von Inhalten zukünftig unterstützt wird)
|
*/
|
owner: string;
|
/**
|
* Liegt die Datei im öffentlichen (www) oder verborgenen (vfs) Dateisystem?
|
*/
|
part: "vfs" | "www";
|
/**
|
* Absoluter Pfad zur Datei. Mmuss immer mit einem Slash beginnen.
|
*/
|
path: string;
|
}
|
}
|
