WaBis

walter.bislins.ch

JSG: Verwaltungs-Funktionen

Die Verwaltungsfunktionen des JSG-Moduls ermöglichen den automatischen Redraw eines Canvas nach einem Resize des Browser-Fensters und dienen der Synchronisation und Verwaltung des Redraw.
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()

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()

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()

JsGraph.Reset( clear )

clear: Boolean; Optional; Default = true
Wenn true, wird die Funktion Clear() intern gerufen

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.

Beispiel einer Animation

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()

JsGraph.AddEventHandler( EventType, EventHandler, Capture )

EventType: String
siehe JavaScript funktion addEventListener, z.B. 'click'
EventHandler: function(xEvent,JsGraph)
Capture: Boolean; Optional; Default = false
siehe JavaScript funktion addEventListener

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()

JsGraph.MakeSnapshot( id, x, y, w, h )
JsGraph.MakeSnapshot( id )
JsGraph.MakeSnapshot( id, 'viewport' )

id: Number or String
Eindeutige ID unter welcher der Snapshot referenziert werden kann.
x,y,w,h: Position und Grösse des Snapshots in Canvas-Koordinaten

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.

Anwendung

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()

JsGraph.DrawSnapshot( id, clear )

id: Number or String
Eindeutige ID unter welcher der Snapshot referenziert werden kann.
clear: Boolean; Optional; Default = true
true → löscht den Snapshot-Bereich vor dem Zeichnen.
Return: Boolean
Gibt true zurück, wenn der Snapshot gezeichnet werden konnte.

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()

JsGraph.SetDrawFunc( DrawFunc, DrawNow )

DrawFunc: Function( JsGraph ) or null
Installiert eine Draw-Funktion oder deinstalliert eine installierte Funktion, wenn null angegeben wird. Der Funktion wird beim Aufruf als Argument das JsGraph Objekt übergeben.
DrawNow: Boolean; Optional; Default = false
Bewirkt, dass die Draw-Funktion nach der Installation ausgeführt wird, selbst wenn der Canvas nicht ungültig geworden ist. Sinnvoll, wenn eine andere Draw-Funktion installiert wird.

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()

JsGraph.SetDeferedDrawFunc( DeferedDrawFunc )

DeferedDrawFunc: Function( JsGraph ) or null
Installiert eine DeferedDraw-Funktion oder deinstalliert eine installierte Funktion, wenn null angegeben wird. Der Funktion wird beim Aufruf als Argument das JsGraph Objekt übergeben.

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()

JsGraph.SetBeforeResetFunc( BeforeResetFunc )

BeforeResetFunc: Function( JsGraph ) or null
Installiert eine Funktion oder deinstalliert eine installierte Funktion, wenn null angegeben wird. Der Funktion wird beim Aufruf als Argument das JsGraph Objekt übergeben. Die Funktion wird gerufen bevor die Grafik mir Reset() gelöscht wird und bevor eine installierte DrawFunc gerufen wird (siehe SetDrawFunc()). In dieser Funktion kann typischerweise eine asynchrone Zeichen-Loop abgebrochen werden, weil danach sowieso ein Draw angestossen wird.

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(), EndDrawing()

JsGraph.BeginDrawing( )
JsGraph.EndDrawing( EndAll )

EndAll: Boolean; Optional; Default = false
true → Schliesst alle noch offenen BeginDrawings ab.

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()

JsGraph.IsDrawing( )

Return: Boolean

Gibt true zurück, wenn aktuell mehr BeginDrawing() Aufrufe für das JsGraph Objekt aufgerufen wurden als entsprechende EndDrawing() Aufrufe.

JsGraph.IsInvalidDrawing()

JsGraph.IsInvalidDrawing( )

Return: Boolean
true → Canvas-Grösse wurde zwischenzeitlich geändert und muss neu gezeichnet werden. Alle folgenden Zeichenfunktionen werden ignoriert.

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()

JsGraph.IsDrawPending( )

Return: Boolean

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()

JsGraph.CancelPendingDraws( )

Löscht alle hängigen Draw-Aufrufe, falls IsDrawPending() = true ist.

Weitere Infos zur Seite
Erzeugt Dienstag, 2. Februar 2016
von wabis
Zum Seitenanfang
Geändert Montag, 10. Dezember 2018
von wabis