• Name
• Übersicht
• Beschreibung
  • Die Verwendung von Chart
  • Ein Objekt erzeugen
  • Optionen einstellen
  • API im GIFgraph.pm-Stil
  • API im Graph.pm-Stil
• To do
• Bugs
• Version
• Autor
• Copyright
• Übersetzer

Name

Übersicht

use Chart::type;

$obj = Chart::type->new;
$obj = Chart::type->new ( $gif_width, $gif_height );
   
$obj->set ( $key_1, $val_1, ... ,$key_n, $val_n );
$obj->set ( $key_1 => $val_1,
            ...
            $key_n => $val_n );
$obj->set ( %hash );

# API im GIFgraph.pm-Stil
@data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
$obj->gif ( "filename", \@data );
$obj->gif ( $filehandle, \@data );
$obj->gif ( FILEHANDLE, \@data );
$obj->cgi_gif ( \@data );

# API im Graph.pm-Stil
$obj->add_pt ($label, $val_1, ... , $val_n);
$obj->add_dataset ($val_1, ... , $val_n);
$obj->gif ( "filename" );
$obj->gif ( $filehandle );
$obj->gif ( FILEHANDLE );
$obj->cgi_gif ();

# Imagemap-Informationen einholen
$obj->set ( 'imagemap' => 'true' );
$imagemap_ref = $obj->imagemap_dump ();

Beschreibung

Die Verwendung von Chart

use Chart::Lines;

das lines-Modul aufrufen.

Ein Objekt erzeugen

$obj = Chart::Bars (600,400);

ein Chart::Bars-Objekt zurück, das ein Image von 600 x 400 Pixeln enthält. New initialisiert auch die meisten der Standardvariablen, die dann über die set-Methode verändert werden können.

Optionen einstellen

%hash = ('title' => 'Foo Bar');
$obj->set (%hash);

oder Sie können den Hash innerhalb des set-Aufrufs aufbauen:

$obj->set ('title' => 'Foo Bar');

Nachfolgend alle momentan unterstützten Optionen:

'transparent'

Macht den Hintergrund des Images transparent, wenn sie auf 'true' (wahr) gesetzt wird. Nützlich zur Generierung von Images für Web-Seiten. Voreingestellt ist 'false' (falsch).

'gif_border'

Legt die Anzahl von Pixeln fest, die zwischen dem Diagramm und den Kanten des Gifs frei bleiben. Voreingestellt ist 10.

'graph_border'

Legt die Anzahl der Pixel fest, die zwischen Titel/Labeln und dem eigentlichen Diagramm innerhalb des Gifs frei bleiben. Voreingestellt ist 10.

'text_space'

Legt den Raum fest, der an den Seiten von Text frei bleibt, um ihn lesbarer zu machen. Voreingestellt ist 2.

'title'

Teilt GD graph mit, wie der Titel des Diagramms lautet. Ist 'title' leer, wird kein Titel gezeichnet. Erkennt \n als Newline-Zeichen und verhält sich entsprechend. Standardmäßig leer.

'sub_title'

Veraltet. Nur wegen Rückwärtskompatibilität verblieben. Diese Option wird wahrscheinlich ab der nächsten Version weggelassen.

'x_label'

Teilt Chart mit, welches Label für die X-Achse zu verwenden ist. Ist diese Option leer, wird kein Label gezeichnet. Standardmäßig leer.

'y_label'

Teilt Chart mit, welches Label für die Y-Achse zu verwenden ist. Ist diese Option leer, wird kein Label gezeichnet. Per Voreinstellung leer.

'legend'

Zeichnet eine Legende in der oberen rechten Ecke des Gifs, wenn diese Option auf 'true' (wahr) gesetzt wird. Voreingestellt auf 'true'.

'legend_labels'

Legt die Werte der Label der verschiedenen Datensätze fest. Es muß eine Referenz auf ein Array von Labels übergeben werden. Beispiel: @labels = ('foo', 'bar'); $obj->set ('legend_labels' => \@labels);

Standardmäßig leer, wobei in diesem Fall 'Dataset 1', 'Dataset 2' etc. als Label verwendet werden.

Bei einem Pareto-Diagramm muß der erste Wert den Namen des Satzes enthalten, und der zweite muß der Name der laufenden Summe der Werte sein.

Bei einem Kuchendiagramm wird diese Option ignoriert, da die Werte für die Legende aus dem Array der Datenpunkt-Label entnommen werden.

'tick_len'

Legt die Länge der X- und Y-Ticks in Pixeln fest. Voreingestellt ist 4.

'grid_lines'

Fügt ein hellgraues Raster in den Hintergrund des Diagramms ein, wenn diese Option auf 'true' gesetzt wird. Voreingestellt ist undef.

'stagger_x_labels'

Ordnet die X-Tick-Label vertikal an, um sie lesbar zu machen, wenn diese Option auf 'true' gesetzt wird. Voreingestellt ist 'true'.

'y_ticks'

Legt die Anzahl der zu zeichnenden Y-Ticks fest. Voreingestellt ist 5.

'max_val'

Legt den maximalen Y-Wert des Diagramms fest und hebt so das Autoscaling auf. Voreingestellt ist undef.

'pt_size'

Legt die Größe der Punkte für Points-, Linespoints- und Pareto-Diagramme fest. Punkte werden als Quadrate mit der Seitenlänge 'pt_size' dargestellt. Voreingestellt ist 4.

'dashed_lines'

Verwendet im Diagramm gestrichelte Linien anstelle durchgehender Linien, wenn diese Option auf einen Wert ungleich " oder undef gesetzt wird. (Ich verwende diese Option, wenn das Diagramm mit einem S/W-Drucker ausgedruckt werden soll. Unglücklicherweise wird es nach 4 Datensätzen schwierig, die Linien zu unterscheiden. Es gab einfach nicht ausreichend verschiedene Möglichkeiten, gestrichelte Linien zu zeichnen.) Voreingestellt ist undef.

'skip_x_ticks'

Legt die Zahl der zu überspringenden X- und Y-Tick-Label fest. (D.h., wenn 'skip_x_ticks' auf 4 gesetzt wird, zeichnet Chart jeden vierten X-Tick und jedes vierte X-Tick-Label.) Voreingestellt ist undef.

'custom_x_ticks'

Wird bei den Diagrammarten Point, Line, Linespoints und Bar verwendet. Mit dieser Option können Sie exakt festlegen, welche X-Ticks und X-Tick-Label gezeichnet werden sollen. Sie müssen eine Referenz auf ein Array mit den gewünschten Ticks übergeben. Denken Sie nur daran, daß ich das Zählen mit dem nullten Element des Arrays beginne (d.h., wird 'custom_x_ticks' [0,3,4] zugewiesen, werden die nullten, dritten und vierten X-Ticks ausgegeben).

'colors'

Mit dieser Option können Sie die Farben der verschiedenen Datensätze festlegen. Als Parameter müssen Sie eine Referenz auf ein Array von Arrayreferenzen übergeben. Steht ein Eintrag auf undef, wählt Chart eine Farbe für Sie. Bei

$obj->set ('colors' => [undef, [0,0,0], [255,0,0]]);

wählt Chart die Farbe des ersten Datensatzes, setzt den zweiten auf schwarz und den dritten auf rot. Voreingestellt ist undef.

'sort'

Weist Chart an, die Daten vor dem Plot zu sortieren. Eine Sortierreihenfolge ('asc' oder 'desc' für auf- bzw. absteigend) kann angegeben werden. In diesem Fall wird dann numerisch sortiert. Alternativ kann eine Arrayreferenz übergeben werden. Diese Arrayreferenz muß drei Elemente enthalten: die Suchreihenfolge (wie oben), die zu verwendenden Datensätze (denken Sie daran, daß 0 die X-Tick-Label enthält) und die Art der Sortierung ('alpha' oder 'num' für alphabetische bzw. numerische Sortierung). So sortiert beispielsweise

$obj->set ('sort' => ['asc', 2, 'num']);

die Daten anhand des dritten Datensatzes (des zweiten, wenn Sie die X-Tick-Label nicht mitrechnen). Beachten Sie, daß

$obj->set ('sort' => ['asc', 0, 'alpha']);

die Daten anhand der X-Tick-Label in aufsteigender Reihenfolge alphabetisch sortiert. Voreingestellt mit undef bzw. 'desc' für Pareto.

'nosort'

Deaktiviert die Standardsortierung für Pareto-Diagramme. Voreingestellt ist undef.

'cutoff'

Wird nur für Pareto-Diagramme verwendet. Diese Option bestimmt, an welchem Punkt (Cutoff-Punkt) abgeschnitten wird. Alles, was hinter dem höchsten Cutoff-Punkt liegt, wird in den 'Andere'-Eintrag des Diagramms übernommen. Voreingestellt ist 5.

'nocutoff'

Deaktiviert das standardmäßig aktive 'Cutoff'-Feature für Pareto-Diagramme. Voreingestellt ist undef.

API im GIFgraph.pm-Stil

Das Image in einer Datei ablegen

Der Aufruf der gif-Methode sorgt dafür, daß das Diagramm erstellt und in einer Datei abgelegt wird. Als Argumente werden der Name der Ausgabedatei und eine Referenz auf die Daten erwartet. So würde

$obj->gif ("foo.gif", \@data);

die Daten in @data aufbereiten und das erzeugte Image in foo.gif ablegen. Das führt natürlich zu der Frage, wie @data auszusehen hat. Nun, genau wie bei GIFgraph muß @data Referenzen auf Arrays von Daten enthalten, wobei die erste Arrayreferenz auf ein Array mit X-Tick-Labeln verweist. Zum Beispiel würde

@data = ( [ 'foo', 'bar', 'junk' ],
          [ 30.2,  23.5,  92.1   ] );

ein Diagramm mit einem Datensatz und drei Datenpunkten innerhalb dieses Satzes einrichten. Generell muß das Array @data wie folgt aussehen:

@data = ( \@x_tick_labels, \@datasatz1, ... , \@datasatz_n );

Und keine Sorge, ich erzeuge eine interne Kopie der Daten, so daß Sie mit Ihren Daten nicht durcheinanderkommen.

CGI und Chart

OK, werden Sie denken, muß man denn diese Images immer auf der Platte ablegen? Was tun, wenn Chart eingesetzt werden soll, um dynamische Images für eine Website zu erzeugen? Nun, die Antwort lautet:

$obj->cgi_gif ( \@data );

Die Methode cgi_gif gibt das Diagramm zusammen mit dem entsprechenden HTTP-Header über Stdout aus. Das erlaubt Ihnen den direkten Aufruf diagrammgenerierender Skripten aus Ihren HTML-Seiten heraus (d.h. mit einem <img src=image.pl> HTML-Tag). Das @data-Array sieht dabei genauso aus wie bei der normalen gif-Methode.

API im Graph.pm-Stil

$obj->add_pt ('foo', 30, 25);
$obj->add_pt ('bar', 16, 32);

Oder, wenn Sie gesamte Datensätze hinzufügen möchten, verwenden Sie einfach die Methode add_dataset:

$obj->add_dataset ('foo', 'bar');
$obj->add_dataset (30, 16);
$obj->add_dataset (25, 32);

Diese Methoden stellen sicher, daß die von Ihnen hinzugefügten Punkte und Datensätze die gleiche Größe besitzen wie die bereits vorhandenen. Wenn Sie also bereits zwei Datensätze abgelegt haben und versuchen, einen Datenpunkt mit drei anderen Werten hinzuzufügen, wird eine Fehlermeldung erzeugt (über Carp.pm). Ebenso ergeht es Ihnen, wenn Sie einen Datensatz mit vier Datenpunkten einfügen möchten, während alle anderen Datensätze nur drei Datenpunkte besitzen.

Vergessen Sie bei der Nutzung dieses APIs nicht, daß ich den ersten Datensatz als Serie von X-Tick-Labeln betrachte. In den obigen Beispielen besäße das Diagramm also zwei X-Ticks namens 'foo' und 'bar', jedes mit jeweils zwei Datenpunkten.

Löschen der Daten

Ein einfacher Aufruf der clear_data-Methode entfernt alle möglicherweise eingegebenen Werte.

$obj->clear_data ();

Eine Kopie der Daten erzeugen

Wenn Sie eine Kopie der bislang eingegebenen Daten benötigen, rufen Sie die get_data-Methode einfach wie folgt auf:

$dataref = $obj->get_data;

Die Methode gibt (Sie ahnen es!) eine Referenz auf ein Array von Referenzen auf Datensätze zurück. Die X-Tick-Labels könnten also wie folgt gespeichert werden:

@x_labels = @{$dataref->[0]};

Ein Image in einer Datei ablegen

Der Aufruf der gif-Methode erzeugt das Diagramm und speichert es in einer Datei. Es verlangt den Namen der Ausgabedatei als Argument. Beispielsweise würde

$obj->gif ("foo.gif");

die Daten aufbereiten und das erzeugte Image in der Datei foo.gif ablegen.

CGI und Chart

OK, werden Sie (erneut) denken, muß man diese Images immer auf der Platte ablegen? Was tun, wenn man mit Chart dynamische Images für Websites erzeugen möchte? Nun, hier ist die Antwort:

$obj->cgi_gif ();

Die Methode cgi_gif gibt das Diagramm zusammen mit dem entsprechenden HTTP-Header über Stdout aus. Das erlaubt Ihnen den direkten Aufruf diagrammgenerierender Skripten aus Ihren HTML-Seiten heraus (d.h. mit einem <img src=image.pl> HTML-Tag).

Version

Autor

Copyright

Übersetzer