ChartDataOpen

Die Anweisung öffnet ein neues ChartData-Objekt. In diesem Objekt werden Daten zur Anzeige in einem Chart-Objekt angegeben. Dabei können neben den darzustellenden Daten, Bezeichnungen und Farben angegeben werden.

Im Argument (obj) wird der Deskriptor des Chart-Objekts übergeben. Dieser wird von der Anweisung ``ChartOpen() zurück gegeben. In (int1) wird angegeben, wieviel Werte das Chart-Objekt maximal enthalten soll. Die später tatsächlich dargestellte Anzahl kann darunter liegen, darf diese Obergrenze jedoch nicht überschreiten.

Das Argument (int2) bestimmt die Art der Daten, die das ChartData-Objekt transportieren kann. Jedes Chart benötigt eine Datenmenge. Diese repräsentiert die darzustellenden Daten. Die Konstante hierfür lautet _ChartDataValue. Da die Datenmenge obligatorisch ist, muss sie nicht angegeben werden.

Neben der Datenmenge gibt es noch weitere Datentypen. Folgende Konstanten können als Datentypen angegeben werden:

• _ChartDataValue

  Mit dieser Konstante wird das Objekt zum Transport der Datenmenge vorbereitet. Da jedes Chart-Objekt einen Datenmenge zur Anzeige benötigt, muss diese Konstante beim Erzeugen des ChartData-Objekts nicht angegeben werden. Beim Hinzufügen von Daten ist das der Default-Wert.

• _ChartDataLabel

  Mit dieser Konstante wird das Objekt zum Transport von Beschriftungen für die einzelnen Daten vorbereitet. Diese Beschriftungen werden neben den Sektoren (Darstellung als Torten-Diagramm, _ChartPie) oder unter der X-Achse (Darstellung als Koordinaten-Diagramm, _ChartXY) angezeigt.

• _ChartDataColor

  Mit dieser Konstante wird das Objekt zum Transport von Farben für die einzelnen Daten vorbereitet. Die Sektoren (Darstellung als Torten-Diagramm, _ChartPie) bzw. die Balken (Darstellung als Koordinaten-Diagramm, _ChartXY) werden in diesen Farben gezeichnet.

• _ChartDataExtra

  Mit dieser Konstante können zusätzliche alphanumerische Daten angegeben werden. Beim Koordinaten-Diagramm (_ChartXY) dienen sie zur Anzeige einer Beschriftung zum entsprechenden Wert der Datenmenge.

Das Objekt wird mit der Anweisung ChartDataOpen() zur Aufnahme der entsprechenden Daten vorbereitet. Sollen in den späteren ChartDataAdd()-Anweisungen neben den Daten noch Bezeichner, Farben und/oder zusätzliche Werte übertragen werden, muss in der Anweisung eine entsprechende Kombination aus den Konstanten angegeben werden.

Chart-Objekte vom Typ _ChartXY können mehr als eine Datenmenge besitzen. Die zusätzlichen Datenmengen stellen dann weitere Reihen von Balken, Linien- oder Flächen dar. Als Bezeichner für die X-Achse wird der Inhalt der letzten Datenreihe verwendet. Damit die zusätzlichen Beschriftungen angezeigt werden, muss in der Eigenschaft ChartXYStyleLabel des Chart-Objektes die Konstante _ChartXYStyleLabelDataExtra gesetzt sein. Die Textfarbe lässt sich über ChartXYLabelColData beeinflussen. Die Textrotation geschieht über die Eigenschaft ChartXYLabelRotData.

ChartData-Objekte von den Typen _ChartXY und _ChartSurface können untergeordnete Datenmengen besitzen. Bei gestapelten (_ChartXYStyleDataStack) und prozentualen (_ChartXYStyleDataPercent) Koordinatendiagrammen ist jede untergeordnete Datenreihe eine Ebene in die Höhe. Die Farbe der Datenreihe wird von der ersten Farbe in der untergeordneten Datenreihe bestimmt. Bei Streudiagrammen (_ChartXYStyleDataScatter) müssen 2 bis 3 untergeordnete Datenreihen angegeben werden. Die erste gibt Koordinaten auf der x-Achse, die zweite auf der y-Achse an. Sind 3 untergeordnete Datenreihen vorhanden, bestimmt die dritte Datenreihe die Größe der Punkte in Pixeln. Ist diese nicht angegeben, werden alle Daten in der Größe der Eigenschaft ChartXYLineSymbolSize dargestellt.

Bei Oberflächen-Diagrammen (_ChartSurface) müssen 3 untergeordnete Datenmengen angegeben werden. Diese definieren die Daten der x-, y- und z-Achse. Auf der z-Achse sollten x * y Daten angegeben werden. Um die Farben der Oberfläche zu beeinflussen, müssen diese in der Hauptdatenmenge angegeben werden. Die Angabe von Beschriftungen (_ChartDataLabel) ist bei der ersten und zweiten untergeordneten Datenmenge möglich.

info

Untergeordnete Datenmengen können nicht mit ``ChartDataSort() sortiert oder mit ChartDataClose() geschlossen werden.

Die eigentlichen Daten, Bezeichner und Farben werden durch die Anweisung ``ChartDataAdd() eingefügt.

Beispiele:

Es werden nur Daten übermittelt:

tHdlChart # ChartOpen(_ChartPie, 400, 300);
tHdlChartData # tHdlChart->ChartDataOpen(20);
...

Es werden Daten, Bezeichner und Farben übermittelt:

tHdlChart # ChartOpen(_ChartPie, 400, 300);
tHdlChartData # tHdlChart->ChartDataOpen(20, _ChartDataLabel | _ChartDataColor);
...

Mehrere Datenreihen:

tHdlChart # ChartOpen(_ChartXY, 400, 300);
// first row
tHdlChartData # tHdlChart->ChartDataOpen(20, _ChartDataLabel | _ChartDataColor);
...
tHdlChartData->ChartDataClose();
// second row
tHdlChartData # tHdlChart->ChartDataOpen(20, _ChartDataLabel | _ChartDataColor);
...
tHdlChartData->ChartDataClose();

Datenreihen für Oberflächen-Diagramme:

tHdlChart # ChartOpen(_ChartSurface, 400, 300);
tHdlChartDataMain # tHdlChart->ChartDataOpen(10, _ChartDataColor);
...
// first sub data
tHdlChartDataSub # tHdlChartDataMain ->ChartDataOpen(20);
...
// second sub data
tHdlChartDataSub # tHdlChartDataMain ->ChartDataOpen(20);
...
// third sub data
tHdlChartDataSub # tHdlChartDataMain ->ChartDataOpen(400);
...
tHdlChartDataMain->ChartDataClose();

Die Funktion liefert bei erfolgreicher Durchführung einen Deskriptor auf ein ChartData-Objekt. Kann das Objekt wegen Speichermangel nicht angelegt werden, wird die Konstante _ErrOutOfMemory zurückgegeben.

Mögliche Laufzeitfehler:

• _ErrHdlInvalid: Bei dem übergebenen Deskriptor in (obj) handelt es sich nicht um einen gültigen Deskriptor eines Chart-Objekts.
• _ErrValueInvalid: Das Argument (int2) enthält einen ungültigen Wert oder das Argument (int1) ist negativ.