| NewGraph2D() | Konstruktor eines JsGraph Objektes |
| Redraw() | Veranlasst das Neuzeichnen der Grafik |
| Clear() | Löscht die Grafik eines JsGraph Objektes |
| Reset() | Setzt alle Attribute und Transformationen zurück |
| AddEventHandler() | Insatlliert einen beliebigen Event Handler für das Canvas Objekt |
| MakeSnapshot() | Speichert die aktuelle Grafik in einem Snapshot |
| DrawSnapshot() | Zeichnet einen Snapshot |
| SetDrawFunc() | Weist einem JSG-Objekt eine Draw-Funktion zu |
| SetDeferedDrawFunc() | Weist einem JSG-Objekt eine DeferedDraw-Funktion zu |
| SetBeforeResetFunc() | Weits einem JSG-Objekt eine Funktion zu, die gerufen wird, bevor die Grafik vor einem Draw gelöscht wird. |
| BeginDrawing() EndDrawing() | Funktionen zur Synchronisation des Zeichnens mit Resize-Ereignissen |
| IsDrawing() | Abfrage, ob mindestens ein BeginDrawing() noch offen ist |
| IsInvalidDrawing() | Abfrage, ob der Zeichenbereich durch ein Resize ungültig geworden ist |
| IsDrawPending() | Abfrage, ob ein Draw in der Warteschleife ist (z.B. nach Resize-Event) |
| CancelPendingDraws() | Löscht die Draw-Warteschleife |
JsGraph.Redraw( )
Veranlasst das Neuzeichnen der Grafik, indem die installierten Funktionen DrawFunc und DeferedDrawFunc aufgerufen werden.
Die DrawFunc wird unmittelbar gerufen, während die DeferedDrawFunc frühestens nach der Zeit DeferedDrawTime (Default = 50 ms) gerufen wird, nachdem die Funktion Redraw beendet ist. Wiederholtes Aufrufen von Redraw in kürzeren Zeitabständen bewirkt, dass DeferedDrawFunc erst nach einer entsprechenden Pause nur einmal aufgerufen wird. Aufwändige Beschriftungen der Grafik werden also am besten in eine Defered-Funktion gepackt.
Wenn AutoReset true ist, wird vor dem Aufruf der DrawFunc die Funktion Reset() gerufen. Wenn zusätzlich AutoClear true ist (default), wird in Reset() die Funktion Clear() auch noch aufgerufen. Vor dem Aufruf von Reset() wird eine allenfalls installierte BeforeResetFunc gerufen.
JsGraph.Clear( )
Löscht die Grafik des Canvas innerhalb des aktuellen Clipping-Bereiches. Um den Clipping-Bereich auf den Canvas zurückzusetzen und zusätzlich die Attribute auf ihre Standardwerte zu setzen, verwendet man am Besten die Funktion Reset(). Der Clippingbereich kann mit der Funktion SetClipping() auf den Viewport oder Canvas gesetzt werden.
Diese Funktion kann auch implizit von der Funktion Reset() gerufen werden, welche dann aber immer den ganzen Canvas löscht. Wenn AutoReset und AutoClear true sind, wird Clear() automatisch vor dem Aufruf der DrawFunc ausgeführt.
Anstelle von Clear kann das Canvas mit der Funktion DrawSnapshot() mit einem vorher gezeichneten Bild initialisiert werden. Ein Snapshot kann mit der Funktion MakeSnapshot() erstellt werden. In diesem Fall macht es Sinn, AutoClear auf false zu setzen und Clear() explizit aufzurufen, wenn DrawSnapshot() false zurückgibt.
JsGraph.Reset( clear )
Setzt den Zustand des JsGraph Objektes zurück auf den Anfangszustand. Insbesondere wird die Grafik mit Clear() gelöscht (wenn clear = true ist), es werden alle internen Positionen zurückgesetzt, der Pen in den Zustand up versetzt, alle offenen Pfade geschlossen und gelöscht, die Windows-Transformation angewählt, alle Transformationen neu initialisiert, der Clipping-Bereich auf canvas gesetzt und alle Attribute auf ihre Startwerte zurückgesetzt.
Die Funktion Reset wird intern vor dem Aufruf einer installierten Draw Callback-Funktion gerufen, wenn AutoReset true ist (default). Die Draw-Funktion wird bei einem Resize des Canvas aufgerufen. Wenn ein Canvas animiert werden soll, muss Reset explizit am Anfang der Draw-Funktion gerufen werden, um den Zeichenbereich für das nächste Bild zu löschen. Wenn Reset in der Draw-Funktion gerufen wird, kann AutoReset false gesetzt werden, um etwas Rechenzeit zu sparen.
Diese Funktion ist als erster Aufruf in einer Draw-Funktion sinnvoll, wenn man Grafik-Animationen erstellen will. Dabei ist zu beachten, dass gezeichnete Grafik erst sichtbar wird, wenn alle JavaScripts fertig ausgeführt sind. Solange also noch gezeichnet wird, wird nichts dargestellt. Um Grafik zu animieren, muss man daher die Zeichenfunktionen per requestAnimationFrame aufrufen.
var jsg = NewGraph2D( {
Width: 600, Height: 400, DrawFunc: DrawGraph, AutoReset: false
} );
function DrawGraph( g ) {
g.Reset();
// draw some graph here...
requestAnimationFrame( function(){ jsg.Redraw(); } );
}
Das Beispiel funktioniert auch, wenn AutoReset nicht false gesetzt wird und der Aufruf von Reset() nicht gemacht würde, da Reset() dann automatisch vor dem Aufruf von DrawGraph() aufgerufen wird.
JsGraph.AddEventHandler( EventType, EventHandler, Capture )
Installiert einen beliebigen Event Handler für das Canvas Element. Es können mehrere Handler nacheinander für denselben EventType installiert werden. Die Reigenfolge der Aufrufe ist nicht definiert.
Achtung: Der Funktion EventHandler wird nicht das native JavaScript Event Objekt übergeben, sondern das Browser-Unabhängige xEvent Objekt (siehe Modul x.js). Als zweites Argument wird ihr dieses JsGraph Objekt übergeben, damit der Handler Zugriff auf dieses Objekt hat, zum Beispiel um die Koordinaten der Maus in Window-Koordinaten zu transformieren und etwas zu zeichnen.
Verwende die Funktionen TransCnvsWinX() und TransCnvsWinY() um die Mauskoordinaten von Canvas- in Window-Koordinaten zu transformieren.
Event Handler lassen sich auch per Parameter EventHandlers der Funktion NewGraph2D() installieren.
Hinweis: Ein 'click' Event Handler kann auch bei NewGraph2D() im Parameter OnClick definiert werden.
JsGraph.MakeSnapshot( id, x, y, w, h )
JsGraph.MakeSnapshot( id )
JsGraph.MakeSnapshot( id, 'viewport' )
Erstellt von einem wählbaren Bereich des Canvas einen Snapshot und speichert diesen intern unter der id ab. Der Snapshot kann später mit der Funktion DrawSnapshot() wieder auf den Canvas kopiert werden.
Mit der zweiten Aufrufvariante wird ein Snapshot des ganzen Canvas gemacht. Mit der dritten Variante wird ein Snapshot des aktuellen Viewportbereiches gemacht.
Sinn der Funktionen MakeSnapshot() und DrawSnapshot() ist es, bei animierten Canvas statische Grafiken nicht bei jedem Frame neu zu zeichnen, sondern in einem wiederverwendbaren Snapshot zu hinterlegen. Dadurch kann die Performance von Animationen wesentlich gesteigert werden, insbesondere, wenn viel Text gezeichnet wird (z.B. Achsenbeschriftungen).
Achtung: Wenn sich die Grösse des Canvas ändert (Resize des Fensters), werden alle Snapshots gelöscht, weil deren Grafik sowieso neu berechnet und gezeichnet werden muss.
function Draw( g ) {
// canvas hier nicht löschen:
g.Reset( false );
g.SetWindowWH( x, y, w, h );
:
if (!g.DrawSnapshot(id)) {
g.Clear();
// statische Grafik zeichnen
g.MakeSnapshot(id);
}
// Assert: DrawSnapshot() oder Clear() haben hier den Canvas gelöscht
// dynamische Grafik zeichnen
}
JsGraph.DrawSnapshot( id, clear )
Zeichnet den Snapshot mit der id am selben Platz auf dem Canvas, wie er mit MakeSnapshot() erzeugt worden ist. Wenn der Snapshot nicht existiert oder durch einen Resize gelöscht worden ist, macht die Funktion nichts und gibt false zurück.
Die Funktion DrawSnapshot kann anstelle von Reset() oder Clear() verwendet werden, um auf dem Canvas eine statische Grafik zu zeichnen, welche vorher mit MakeSnapshot() gespeichert worden ist. Wenn vor dem Zeichnen des Snapshots der Canvas bereits mit Clear() oder Reset() gelöscht worden ist, kann clear = false gesetzt werden um das erneute Löschen des Snapshot-Bereiches einzusparen.
Achtung: Wenn clear = false gesetzt wird, wird der Snapshot mit bereits bestehender Grafik kombiniert (globalCompositeOperation = 'source-over', nicht 'copy')!
Anwendung: siehe MakeSnapshot()
JsGraph.SetDrawFunc( DrawFunc, DrawNow )
Installiert eine Draw-Funktion im JsGraph Objekt. Diese Funktion wird gerufen, wenn der Canvas neu gezeichnet werden muss, z.B. nach dem ersten Seitenaufbau oder nach einem Resize des Canvas.
Die Draw-Funktion kann auch beim JsGraph Konstruktor als Argument übergeben werden.
JsGraph.SetDeferedDrawFunc( DeferedDrawFunc )
Installiert eine DeferedDraw-Funktion im JsGraph Objekt. Die DeferedDraw-Funktion kann auch beim JsGraph Konstruktor als Argument übergeben werden.
Die DeferedDrawFunc wird frühestens nach der Zeit DeferedDrawTime (Default = 50 ms) aufgerufen, nachdem die DrawFunc beendet ist. Wiederholtes Aufrufen von Redraw() in kürzeren Zeitabständen bewirkt, dass die DeferedDrawFunc erst nach einer entsprechenden Pause nur einmal aufgerufen wird. Aufwändige Beschriftungen der Grafik werden also am besten in eine solche Defered-Funktion gepackt.
Anwendung: Eine animierte Grafik wird in zwei Draw-Funktionen aufgeteilt. Die DrawFunc wird über Redraw() bei jedem Animations-Frame gerufen. Darin sollten alle Zeichenfunktionen ausgeführt werden, welche innerhalb eines Frames erledigt werden können. Aufwändigere Zeichenfunktionen wie Beschriftungen mit Text sollten in die DeferedDrawFunc ausgelagert werden, welche erst aufgerufen wird, wenn die Animation stopt.
JsGraph.SetBeforeResetFunc( BeforeResetFunc )
Installiert eine BeforeReset Funktion im JsGraph Objekt. Diese Funktion wird gerufen, wenn der Canvas neu gezeichnet werden muss, z.B. nach dem ersten Seitenaufbau oder nach einem Resize des Canvas. Die Funktion BeforeResetFunc wird unmittelbar vor dem Löschen des Canvas mit Reset() gerufen. Nach dem Löschen des Canvas wird eine allenfalls installierte DrawFunc gerufen.
Die BeforeReset-Funktion kann auch beim JsGraph Konstruktor als Argument übergeben werden.
JsGraph.BeginDrawing( )
JsGraph.EndDrawing( EndAll )
Damit während dem Zeichnen nicht erneut ein Draw ausgelöst wird und damit die Grafik korrupt wird, müssen alle Zeichen-Funktionen zwischen die beiden Funktionen BeginDrawing und EndDrawing gesetzt werden, es sei denn, die Zeichenfunktion wird als Callback-Funktion installiert. Im letzteren Fall werden diese beiden Funktionen intern automatisch gerufen.
Diese beiden Funktionen können auch verschachtelt aufgerufen werden. Nach einem BeginDrawing liefert die Funktion IsDrawing() true bis entsprechend oft EndDrawing aufgerufen wird oder EndAll = true bei EndDrawing angegeben wird.
Da ein Canvas mit fixer Grösse keine Draw's auslöst, sind in diesem Fall diese beiden Funktionen optional. Es schadet jedoch nichts, diese trotzdem zu verwenden. Vor allem wenn mehrere Canvas auf einer Seite verwendet werden und einer davon eine dynamische Grösse hat, müssen diese Funktionen verwendet werden, sofern die entsprechende Zeichenfunktion nicht als Callback installiert ist!
JsGraph.IsDrawing( )
Gibt true zurück, wenn aktuell mehr BeginDrawing() Aufrufe für das JsGraph Objekt aufgerufen wurden als entsprechende EndDrawing() Aufrufe.
JsGraph.IsInvalidDrawing( )
Diese Funktion gibt true zurück, wenn die aktuelle Zeichen-Funktion abgebrochen werden kann, weil der Canvas durch einen während dem Zeichnen aufgetretenen Resize-Event erneut gezeichnet werden muss.
Diese Funktion gibt nur true zurück, wenn eine Draw Callback-Funktion im JsGraph Objekt installiert ist.
Hinweis: Intern werden alle Zeichenfunktionen ignoriert, solange IsInvalidDrawing true zurück gibt. Dadurch wird Rechenzeit eingespart, damit das System schneller für den nächsten Draw parat ist.
JsGraph.IsDrawPending( )
Gibt true zurück, wenn nach dem ersten Seitenaufbau oder nach einem Resize des Canvas ein Draw hängig ist. Beim ersten Aufruf von BeginDrawing() wird dieses Flag auf false zurückgesetzt.
Durch den Aufruf von CancelPendingDraws() kann dieses Flag zurückgesetzt werden. Dadurch werden alle hängigen Draw-Aufrufe gecancelt.
JsGraph.CancelPendingDraws( )
Löscht alle hängigen Draw-Aufrufe, falls IsDrawPending() = true ist.