chartpie — `u_pbt_chartpie` #

← Komponentenreferenz · Inhalt des Handbuchs

Kreisdiagramm: Torte, Ring oder Halbkreis. Jeder Winkel ist ein Anteil am Ganzen — die Legende blendet ein Segment aus, die anderen nehmen seinen Platz ein.

▶ Live ansehen — Demoanwendung, Kachel Pie chart : die Vorschau, der erzeugende Code und diese Seite nebeneinander.

Kurz gefasst #

Userobject	`u_pbt_chartpie`
Elementklasse	`n_pbt_chartpie_slice (of_item(key))`
Dient zu	Zeigen, wie sich ein Ganzes aufteilt — Umsatz nach Region, Tickets nach Status, verbrauchtes Budget
Prinzip	Sie fügen Segmente hinzu (Schlüssel, Name, Wert); Winkel, Prozente, Legende und Animation sind unsere Sache

Schnellstart #

// One slice per region : a key, a label and a value
uo_pie.of_add_slice(/*key*/ "north", /*label*/ "North", /*value*/ 420)
uo_pie.of_add_slice(/*key*/ "south", /*label*/ "South", /*value*/ 310)
uo_pie.of_add_slice(/*key*/ "east", /*label*/ "East", /*value*/ 260)

// The share of each region, written on its slice
uo_pie.ib_data_labels = true
uo_pie.is_label_format = "#percent#"

Ein Segment ist ein ANTEIL am Ganzen #

Sie geben Werte an, nie Winkel: Die Komponente summiert die angezeigten Segmente und gibt jedem den Winkel seines Anteils an dieser Summe. Ein Segment auszublenden — per Klick in der Legende oder über ib_visible — schließt es an Ort und Stelle: Die anderen teilen sich den Kreis neu, und #percent#, id_percent und of_total() folgen. Ein negativer Wert hat keinen Winkel: Er wird als null gezeichnet und so zurückgelesen, wie Sie ihn angegeben haben.

Winkel werden in Grad gezählt, 0 oben, in Zeichenrichtung: ii_start_angle = -90 und ii_sweep_angle = 180 ergeben die obere Hälfte eines Kreises — eine Anzeige. Der Kreis wird in den Platz eingepasst, den dieser Winkel braucht: Ein Halbkreis wird doppelt so groß gezeichnet.

Eigenschaften #

Eigenschaft	Typ	Standard	Rolle
`is_title`	string	`""`	Diagrammtitel, über dem Kreis. Auszeichnung erlaubt
`ib_show_legend`	boolean	`true`	Zeigt die Legende. Ein Klick auf einen Eintrag blendet sein Segment aus und löst `ue_slice_toggled` aus
`is_legend_location`	string	`end`	Wohin die Legende gehört (Konstanten `LEGEND_*`): neben den Kreis (`END`, `START`, als Spalte) oder darüber und darunter (`TOP`, `BOTTOM`, nebeneinander). `START`/`END` sind logisch: Sie folgen der Leserichtung. Eine unbekannte Position ist `end` und wird so zurückgelesen
`ib_legend_values`	boolean	`false`	Schreibt Wert und Anteil jedes Segments in die Legende, nach seinem Namen
`ib_value_tooltip`	boolean	`true`	Das Panel, das das Segment unter dem Zeiger — oder das der Tastatur — mit Wert und Anteil nennt. Es ist nicht `is_tooltip`, der Tooltip der ganzen Komponente. Der Tooltip eines Segments (sein `is_tooltip`) wird in dieses Panel geschrieben, auch bei `false`
`ib_data_labels`	boolean	`false`	Eine Beschriftung je Segment, die sagt, was `is_label_format` sagt, dort, wo `is_label_position` sie hinsetzt. In einem zu schmalen Segment wird sie weggelassen, statt über die Nachbarn geschrieben zu werden
`is_label_format`	string	`""`	Was eine Beschriftung sagt: `#value#` der Wert, `#percent#` sein Anteil am Ganzen, `#label#` sein Name (ohne Auszeichnung), `#key#` sein Schlüssel, `#total#` die Summe; `#participation#` sagt dasselbe wie `#percent#`. Der Rest wird unverändert geschrieben. Leer = nur der Wert
`is_label_position`	string	`inside`	Wohin die Beschriftungen gehören (Konstanten `LABEL_*`): `INSIDE`, auf dem Segment, schwarz oder weiß, je nachdem, was darauf lesbar ist; `OUTSIDE`, neben dem Kreis, mit einer Linie mit ihrem Segment verbunden und so verteilt, dass keine auf einer anderen liegt
`id_inner_radius`	double	`0`	Das Loch, als Bruchteil des Radius: `0` eine Torte, `0.6` ein Ring (begrenzt auf 0..0,9). Der Kreis gleitet vom einen zum anderen
`is_center_text`	string	`""`	Text im Loch eines Rings, Auszeichnung erlaubt. Platzhalter: `#total#` die Summe der angezeigten Segmente (im Zahlenformat), `#count#` ihre Anzahl; `#hover_label#`, `#hover_value#`, `#hover_percent#` das Segment unter dem Zeiger oder das der Tastatur — in Ruhe das Ganze: Gesamt, die Summe, 100 %; `#percent:key#` und `#value:key#` Anteil und Wert eines Segments, aktuell gehalten, was die Werte auch tun (eine Anzeige schreibt ihre „72 %“ selbst). Ein unbekannter Schlüssel schreibt nichts. In einer Torte wird nichts geschrieben
`ii_start_angle`	integer	`0`	Wo das erste Segment beginnt, in Grad: `0` oben, `90` rechts, `-90` links (450 wird als 90 zurückgelesen)
`ii_sweep_angle`	integer	`360`	Wie viel des Kreises sich die Segmente teilen, in Grad (begrenzt auf 10..360). Mit `ii_start_angle = -90` zeichnet `180` die obere Hälfte — eine Anzeige
`ib_clockwise`	boolean	`true`	Die Segmente folgen im Uhrzeigersinn aufeinander oder andersherum. Die Pfeiltasten folgen der Zeichenreihenfolge
`is_sort`	string	`"none"`	Die Zeichenreihenfolge (Konstanten `SORT_*`): `NONE` die Reihenfolge, in der die Segmente gegeben wurden, `DESC` das größte zuerst, `ASC` das kleinste zuerst. Kreis, Legende und Tastatur folgen ihr; das Modell behält seine Reihenfolge — `of_get_values`, `of_count` und die Palettenfarben bewegen sich nicht. Ein unbekannter Wert ist `none`
`id_hover_push_out`	double	`0.08`	Wie weit das Segment unter dem Zeiger — oder das der Tastatur — herausrückt, als Bruchteil des Radius (begrenzt auf 0..0,4). Addiert sich zum `id_push_out` des Segments. `0` = nichts bewegt sich
`ib_track_hover`	boolean	`false`	Abonnement für `ue_slice_hovered`: Ein Ereignis, das bei jeder Zeigerbewegung ausgelöst wird, geht nur an eine Anwendung, die es verlangt hat
`is_format`	string	`""`	Das Format aller Zahlen, die das Diagramm schreibt — Beschriftungen, Legende, Wertepanel, Mitteltext — in der Syntax eines DataWindow-Formats: `#,##0.00`, `$#,##0`, `#,##0 "Stück"`, Abschnitte positiv;negativ;null. Die Trennzeichen sind die der Anzeigesprache. Leer (oder ein nicht numerisches Format) = die Zahl, wie sie ist, auf das Tausendstel. Die Anteile (`#percent#`) werden immer auf das Zehntel geschrieben
`id_others_threshold`	double	`0`	Fasst die kleinen Segmente zusammen: Jedes Segment, dessen Anteil am Ganzen unter diesem Prozentsatz liegt, geht in ein Segment „Sonstige“ ein, zuletzt in neutralem Grau gezeichnet — die Legende zeigt es an ihrer Stelle. Die Mitglieder werden über alle Segmente beurteilt, angezeigte wie ausgeblendete: Ein großes Segment auszublenden holt die kleinen nie heraus, und das größte Segment geht nie hinein. Sein Schlüssel ist `OTHERS_KEY` (`"__others"`) in allen Ereignissen, sein Wert die Summe seiner angezeigten Mitglieder, `of_others_keys` nennt sie, `of_item(OTHERS_KEY)` liest Wert und Anteil oder blendet es aus. Ein einzelnes kleines Segment behält seinen Sektor. `0` = nie
`ii_others_top`	integer	`0`	Fasst nach Anzahl zusammen: Die N größten Segmente behalten ihren Sektor, alle anderen gehen in „Sonstige“ ein (mindestens zwei, wie beim Schwellwert). Wirkt mit `id_others_threshold` zusammen: Ein Segment geht hinein, sobald eine der beiden Regeln es sagt. `0` = keine solche Regel
`is_others_label`	string	`""`	Der Name des Segments „Sonstige“. Auszeichnung in Legende und Wertepanel erlaubt; die Beschriftungen und die Zusammenfassung für Bildschirmleser schreiben den reinen Text. Leer = das Wort der Anzeigesprache (Others, Sonstige…)
`ib_auto_height`	boolean	`false`	Die Komponente meldet ihre ideale Höhe, und das Userobject passt sich an (`ue_auto_height`). Die Breite bestimmt sie: Ein Halbkreis ist halb so hoch
`ib_enabled`	boolean	`true`	Ausgegraut zeigt das Diagramm weiter, was es zeigt, reagiert aber nicht mehr: kein Klick, kein Doppelklick, keine Taste, keine Legende, und es verlässt die Tab-Reihenfolge
`ib_animated`	boolean	`true`	Der Kreis kommt animiert an — er öffnet sich von seinem Anfang aus, Segment für Segment — und neue Werte gleiten: Die Kanten zwischen den Segmenten bewegen sich gemeinsam, der Kreis zeigt nie eine Lücke noch ein Segment über seinem Nachbarn; ein entferntes Segment schließt sich an seinem Platz. Ein Rechner mit reduzierter Bewegung animiert nie, und der Kreis landet an derselben Stelle
`ii_anim_duration`	integer	`450`	Dauer der Ankunft und jeder Bewegung, in Millisekunden (begrenzt auf 0..5000)
`is_anim_easing`	string	`ease-out`	Die Kurve der Bewegung (Konstanten `EASING_*`, die Namen von LiveCharts2): `back-out` schießt über und kommt zurück, `bounce-out` springt, `elastic-out` schnellt
`ii_anim_delay`	integer	`40`	Nur bei der Ankunft (ein Kreis, der nichts auf dem Bildschirm hatte) der Versatz zwischen zwei Segmenten, in Millisekunden (0 bis 1000): Der Kreis öffnet sich Segment für Segment, insgesamt nie mehr als 600 ms später, wie viele Segmente er auch hat. `0` = alle zusammen. Eine Wertänderung lässt immer alle Segmente zusammen gleiten
`is_theme_style`	string	`""`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`); leer = der der Anwendung, bei jeder Änderung übernommen
`is_theme_mode`	string	`""`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`); leer = die der Anwendung, bei jeder Änderung übernommen
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent des Themas)
`is_tooltip`	string	`""`	Einfacher Tooltip beim Überfahren der Komponente
`is_super_tooltip_title`	string	`""`	Titel des erweiterten Tooltips (hat Vorrang vor `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Text des erweiterten Tooltips (Rich-Markup erlaubt)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Methoden #

Methode	Rolle
`of_add_slice ( string as_key, string as_label, double ad_value { , long al_color } )`	Fügt ein Segment hinzu: Schlüssel, Name (Auszeichnung erlaubt) und Wert; die Überladung mit einer Farbe setzt sie, ohne sie wählt die Palette (ein Satz für ein helles, einer für ein dunkles Thema). Liefert `0` nach dem Hinzufügen, `-5`, wenn der Schlüssel leer ist, `/` oder `	`enthält mit` __ `beginnt (die Schlüssel des Diagramms selbst, etwa` OTHERS_KEY`) oder schon vergeben ist (ein Hinzufügen ersetzt nie ein Segment),` -2`, wenn die Komponente nicht erstellt ist
`of_clear ( )`	Entfernt alle Segmente — ihre Griffe gehen mit — und vergisst die Zeilen von `of_from_datastore`: Ein späteres `of_map` oder `of_reload` bringt sie nicht zurück. Die Einstellungen bleiben, die Rollen von `of_map` auch; an ihrer Stelle wird ein leerer Kreis gezeichnet. Liefert `0` nach dem Leeren, `-2`, wenn die Komponente nicht erstellt ist
`of_from_datastore (datastore ads)`	Speist das Diagramm aus einem DataStore: eine Zeile = ein Segment. Eine Spalte spielt eine Rolle, wenn sie so heißt (`key`, `label`, `value`, `color`) oder wenn `of_map` es sagt; eine Spalte `ROLE_VALUE` ist nötig. Ohne Spalte `ROLE_KEY` ist der Schlüssel eines Segments seine Zeilennummer; mit ihr werden Zeilen mit demselben Schlüssel zu einem Segment summiert (Name und Farbe der ersten) — ein Verkaufsjahr wird ohne Schleife zu einem Segment je Kategorie. Zahlen und Datumswerte werden gelesen, wie das DataWindow sie auf dem Arbeitsplatz schreibt (Dezimalkomma, regionale Datumsangaben: ein Datum wird zu `yyyy-mm-dd`). Ein zweites Laden aktualisiert die Segmente an Ort und Stelle: Ein wiederkehrender Schlüssel behält, was Benutzer und Code ihm gegeben haben (in der Legende ausgeblendet, herausgerückt, eine Farbe des Codes, sein Tooltip), und seinen Griff; die Segmente verschwundener Schlüssel gehen; die von Hand hinzugefügten Segmente bleiben, nach denen der Zeilen. Liefert `0` nach dem Laden — eine Zeile, deren Schlüssel leer ist, `/` oder `	`enthält, mit` __ `beginnt oder von einem von Hand hinzugefügten Segment gehalten wird, wird übersprungen, und` of_get_last_error `sagt, wie viele —,` -5`, wenn der DataStore ungültig ist, keine Spalte` ROLE_VALUE `spielt oder eine von` of_map `genannte Spalte fehlt (`of_get_last_error `nennt sie),` -2`, wenn die Komponente nicht erstellt ist
`of_from_datastore (datawindow adw)`	Dasselbe aus den Zeilen eines DataWindow — des einen, das der Benutzer neben dem Diagramm sieht. Seine Daten werden mit einem Hilfs-DataStore geteilt: Ein DataWindow, das sie nicht teilen kann, wird abgelehnt (`-5`, mit dem Grund). Liefert `0` nach dem Laden, `-5` wie oben, `-2`, wenn die Komponente nicht erstellt ist
`of_from_datastore (datawindowchild adwc)`	Dasselbe aus den Zeilen eines DataWindowChild (ein Dropdown-DataWindow, ein verschachtelter Bericht). Liefert `0` nach dem Laden, `-5` wie oben, `-2`, wenn die Komponente nicht erstellt ist
`of_get_last_error ( )`	Warum der letzte Aufruf abgelehnt wurde (eine Rolle von `of_map`, die die Zeilen nicht haben…), oder wie viele Zeilen das letzte `of_from_datastore` übersprungen hat und warum; sonst der letzte Fehler der DLL, wie bei jeder Komponente
`of_get_values ( ref string as_keys[], ref double ad_values[] )`	Füllt beide Felder mit den Segmenten, die das Diagramm jetzt hat, in der Reihenfolge, in der sie gegeben wurden (`is_sort` ändert nur die Zeichnung), und liefert ihre Anzahl — was das Diagramm liest, nicht was gesendet wurde
`of_item ( string as_key )`	Der Griff `n_pbt_chartpie_slice` eines Segments, um Name, Wert, Farbe, Versatz oder Sichtbarkeit zu lesen oder zu ändern. `of_item(OTHERS_KEY)` ist immer gültig: das Segment „Sonstige“, sein Wert, sein Anteil, seine Sichtbarkeit (`of_has` nennt es nicht: Es gehört dem Diagramm, nicht Ihnen). Ein Schlüssel, den das Diagramm nicht hat, liefert einen Griff, der nichts ändert und leere Werte liest — eine Eigenschaft kann nicht -5 antworten: Prüfen Sie einen Schlüssel von außen zuerst mit `of_has`
`of_map ( string as_role, string as_column )`	Gibt einer Spalte eine Rolle, wenn ihr Name sie nicht nennt: `of_map(ROLE_VALUE, "amount")`. Rollen: `ROLE_KEY` (die Zeilen eines Schlüssels werden summiert), `ROLE_LABEL`, `ROLE_VALUE`, `ROLE_COLOR` (ein `RGB()`-long oder `#rrggbb`). Vor `of_from_datastore` oder danach: Die Zeilen werden dann an Ort und Stelle neu gelesen. Die Spalte wird vom nächsten `of_from_datastore` beurteilt (dort `-5`, wenn sie fehlt); haben die bereits gegebenen Zeilen sie nicht, werden sie nicht neu gelesen — die Rolle wartet auf die Zeilen, die Sie gleich geben, und `of_get_last_error` sagt es. Eine leere Spalte gibt die Rolle an die gleichnamige Spalte zurück. Liefert `0` nach dem Setzen, `-5`, wenn die Rolle keine `ROLE_`-Konstante ist, `-2`, wenn die Komponente nicht erstellt ist
`of_others_keys ( ref string as_keys[] )`	Füllt das Feld mit den Schlüsseln der jetzt in „Sonstige“ zusammengefassten Segmente (siehe `id_others_threshold` und `ii_others_top`), in der Reihenfolge, in der sie gegeben wurden, und liefert ihre Anzahl — `0`, wenn keines zusammengefasst ist. Worum es bei einem Klick auf `OTHERS_KEY` geht
`of_reload ( )`	Liest die Zeilen des letzten `of_from_datastore` erneut — nach einem `Retrieve`, nach einer Eingabe — und aktualisiert die Segmente an Ort und Stelle, wie ein zweites `of_from_datastore`. Liefert `0` nach dem Lesen, `-5`, wenn keine Zeilen gegeben wurden (oder `of_clear` sie vergessen hat, oder der DataStore zerstört wurde), `-2`, wenn die Komponente nicht erstellt ist
`of_remove_slice ( string as_key )`	Entfernt ein Segment; die anderen nehmen seinen Platz ein, sein Griff wird zerstört. Liefert `0` nach dem Entfernen, `-5`, wenn kein Segment diesen Schlüssel hat, `-2`, wenn die Komponente nicht erstellt ist
`of_set_values ( string as_keys[], double ad_values[] )`	Neue Werte für mehrere Segmente in einem Aufruf — was ein Dashboard bei jeder Aktualisierung aufruft: Die Kanten zwischen den Segmenten gleiten gemeinsam zu ihren neuen Winkeln, der Kreis öffnet nie eine Lücke. Liefert `0` nach dem Anwenden, `-5`, wenn die beiden Felder unterschiedlich lang sind oder ein Schlüssel nicht vorhanden ist (dann wird nichts angewendet), `-2`, wenn die Komponente nicht erstellt ist
`of_total ( )`	Die Summe der angezeigten Segmente — was jetzt 100 % bedeutet: Ein in der Legende ausgeblendetes Segment zählt nicht, ebenso wenig ein negativer Wert
`of_reset ( )`	Leert das Diagramm — Segmentgriffe inbegriffen — und setzt alle Eigenschaften auf ihren Ausgangswert zurück. Liefert `0` danach, `-2`, wenn die Komponente nicht erstellt ist

Ereignisse #

Ereignis	Ausgelöst wenn
`ue_slice_clicked (string as_key, double ad_value)`	Ein Segment wurde angeklickt — oder mit Eingabe oder Leertaste auf dem Segment der Tastatur bestätigt (Tab bis zum Diagramm, dann die Pfeile): sein Schlüssel und sein Wert — `OTHERS_KEY` und die Summe seiner Segmente für das Segment „Sonstige“. Der Klick wird dort beurteilt, wo das Segment ruht: Nahe der Mitte gehört die Lücke, die ein angezeigtes Segment beim Herausrücken lässt, noch ihm. Ein ausgeblendetes Segment hat nichts anzuklicken
`ue_slice_dblclicked (string as_key, double ad_value)`	Doppelklick auf ein Segment: sein Schlüssel und sein Wert — der Ort, um die Zeilen dahinter zu öffnen (ein Drill-down: ein zweites `of_from_datastore` mit den Zeilen dieses Segments). Die beiden Klicks davor haben `ue_slice_clicked` ausgelöst, wie in einem DataWindow; Eingabe bleibt ein Klick
`ue_slice_rclicked (string as_key, long al_x, long al_y)`	Rechtsklick auf ein Segment oder Menütaste (Umschalt+F10) auf dem Segment der Tastatur. `al_x`, `al_y`: wo, in Bildschirmpixeln — der Zeiger, oder die Mitte des Segments bei der Menütaste, nie dort, wo die Maus gerade liegt. Eine Komponente `contextmenu` öffnet sich dort: `uo_menu.of_show(al_x, al_y)`
`ue_slice_toggled (string as_key, boolean ab_visible)`	Der Benutzer hat ein Segment per Klick in der Legende aus- oder wieder eingeblendet (oder mit Eingabe / Leertaste auf seinem Eintrag: Die Legende ist ein Tab-Stopp, die Pfeile durchlaufen sie). Auch das letzte Segment lässt sich ausblenden: Der Kreis sagt dann Alle Segmente sind ausgeblendet. Was das Diagramm zeigt, ist dann nicht mehr, was die Anwendung gesendet hat. `ib_visible` zu setzen ist ein Wert, wie ein Häkchen: Dieses Ereignis meldet die Geste des Benutzers
`ue_slice_hovered (string as_key)`	Nur mit `ib_track_hover`: Zeiger oder Tastatur erreichen ein anderes Segment — sein Schlüssel; ein leerer Schlüssel, wenn alle verlassen werden: der Zeiger außerhalb des Kreises, Esc, der Fokus, der das Diagramm verlässt
`ue_auto_height (long al_height)`	Mit `ib_auto_height`: Das Userobject wurde gerade auf seine ideale Höhe gebracht

Elementeigenschaften #

Am Griff eines Segments gelesen und geschrieben: uo_pie.of_item(/*key*/ "north").id_value = 450. Jedes Lesen fragt das Diagramm.

Eigenschaft	Typ	Standard	Rolle
`is_label`	string	`""`	Der Name des Segments, wie Legende und Panel ihn zeigen; leer = sein Schlüssel
`id_value`	double	`0`	Sein Wert; sein Winkel ist sein Anteil an der Summe, und es gleitet dorthin
`il_color`	long	`-1`	Seine Farbe; `-1` = die Palettenfarbe. Die geerbten Elementfarben (`il_accent`, `il_back_color`, `il_text_color` und ihre Hover-Varianten) haben keine Wirkung auf ein Segment: `il_color` entscheidet
`id_push_out`	double	`0`	Rückt es aus dem Kreis heraus, um es hervorzuheben, als Bruchteil des Radius (begrenzt auf 0..0,4)
`ib_visible`	boolean	`true`	Blendet das Segment aus, ohne es zu entfernen: Die anderen teilen sich den Kreis neu, die Legende behält einen Rückweg
`id_percent`	double	`0`	Sein Anteil an dem, was der Kreis zeigt, von 0 bis 100; 0, wenn es ausgeblendet ist (nur lesen). Jeder Anteil wird auf das Zehntel geschrieben: Drei gleiche Segmente lesen je 33,3 %, zusammen 99,9 % — die Anteile werden nie auf 100 gezwungen
`is_tooltip`	string	`""`	Sein Tooltip, in das Panel geschrieben, das das Segment unter dem Zeiger (oder das der Tastatur) nennt — nie eine zweite Blase. Mit `ib_value_tooltip` auf `false` öffnet sich das Panel trotzdem dafür, ohne die Zahlen. Markup erlaubt
`is_super_tooltip_title`	string	`""`	Der fette Titel seines Tooltips, im Panel unter seinem Namen geschrieben
`is_super_tooltip_text`	string	`""`	Der Text seines Tooltips, im Panel. Markup erlaubt
`is_super_tooltip_image`	string	`""`	Ein Bild oben in seinem Tooltip, im Panel (Bundle-Pfad, absoluter Pfad oder `resources.dll:name`)

Beispiele #

Ein Ring und seine Summe #

// A hole of 60 % of the radius : a doughnut
uo_pie.id_inner_radius = 0.6

// In the hole : the slice under the pointer, in bold above its name ;
// at rest, the total of the slices shown above the word Total
uo_pie.is_center_text = "[b]#hover_value#[/b][br]#hover_label#"

// Whole numbers with a thousands separator : a display format, as in a DataWindow
uo_pie.is_format = "#,##0"

Ein Halbkreis als Anzeige #

// From the left, over half a circle : the upper half
uo_pie.ii_start_angle = -90
uo_pie.ii_sweep_angle = 180
uo_pie.id_inner_radius = 0.62

// What is spent and what is left, in the colour they mean
uo_pie.of_add_slice(/*key*/ "spent", /*label*/ "Spent", /*value*/ 72, /*color*/ RGB(/*red*/ 15, /*green*/ 108, /*blue*/ 189))
uo_pie.of_add_slice(/*key*/ "left", /*label*/ "Remaining", /*value*/ 28, /*color*/ RGB(/*red*/ 150, /*green*/ 150, /*blue*/ 150))

// The share spent, in the hole : worked out by the chart, it follows every new value
uo_pie.is_center_text = "[b]#percent:spent#[/b][br]spent"

Ein lebendiges Dashboard #

// Timer event of the window : new values for the same slices
// Local variables
string ls_keys[] = {"s1", "s2", "s3"}
double ld_load[]

// Read the figures, then hand them to the slices already on the chart : they
// SLIDE to their new angles instead of replaying their arrival
ld_load = wf_read_load()
uo_pie.of_set_values(/*keys*/ ls_keys, /*values*/ ld_load)

Die Zeilen hinter einem Segment öffnen #

// Event ue_slice_dblclicked of uo_pie : the key of the slice is the region
wf_open_orders(/*region*/ as_key, /*amount*/ ad_value)

Ein Menü auf einem Segment #

// Event ue_slice_rclicked of uo_pie : (string as_key, long al_x, long al_y)
// Remember the slice, then open the contextmenu of the window where the gesture
// was made : the pointer, or the middle of the slice for the Menu key
is_menu_slice = as_key
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

Aus einem DataStore #

// Local variables
long ll_rc

// One slice per category : the rows of a category are SUMMED into its slice
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_KEY, /*column*/ "category")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_LABEL, /*column*/ "category")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_VALUE, /*column*/ "amount")

// ONE call reads every row of the DataStore retrieved when the window opened
// (an instance variable), no loop
ll_rc = uo_pie.of_from_datastore(/*ads*/ ids_sales)

// A row with no category is skipped : the chart says how many
if uo_pie.of_get_last_error() <> "" then wf_status(uo_pie.of_get_last_error())

Das DataWindow auf dem Bildschirm, an Ort und Stelle neu gelesen #

// Open event of the window : the chart reads the DataWindow the user sees
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_KEY, /*column*/ "region")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_VALUE, /*column*/ "amount")
uo_pie.of_from_datastore(/*adw*/ dw_sales)

// After a Retrieve : the slices follow IN PLACE - a region the user hid from
// the legend stays hidden, a new region gets its slice
dw_sales.Retrieve()
uo_pie.of_reload()

Die kleinen Segmente in „Sonstige“ #

// Every slice under 5 % of the total joins ONE slice, drawn last in grey,
// and only the six largest products keep a slice of their own
uo_pie.id_others_threshold = 5
uo_pie.ii_others_top = 6
uo_pie.is_others_label = "Other products"

// The largest first : the reader compares them from the top
uo_pie.is_sort = u_pbt_chartpie.SORT_DESC

// Event ue_slice_clicked of uo_pie : a click on Others opens the slices it holds
// Local variables
string ls_keys[]

// Others names the slices it gathered
if as_key = uo_pie.OTHERS_KEY then
	uo_pie.of_others_keys(/*keys*/ ls_keys)
	wf_open_products(/*keys*/ ls_keys)
end if

Bewährte Praxis #

Wenige Segmente. Ab sechs oder sieben vergleicht das Auge benachbarte Winkel nicht mehr: Fassen Sie die kleinen zu einem Segment „Sonstige“ zusammen (id_others_threshold) oder nehmen Sie das kartesische Diagramm.
Ordnen Sie die Segmente vom größten zum kleinsten (is_sort = SORT_DESC), oben beginnend: Das Lesen folgt der Zeichenrichtung.
Beschriftungen außen, wenn die Segmente schmal sind: Sie bleiben lesbar, mit ihrem Segment verbunden, statt weggelassen zu werden.
Schalten Sie die Animation auf einem sich auffrischenden Dashboard ab, oder behalten Sie sie und rufen Sie of_set_values auf: Die Segmente gleiten, statt ihre Ankunft neu zu beginnen.
Das Diagramm behält seine Zeichenrichtung in einer Rechts-nach-links-Anwendung — auch die Außenbeschriftungen werden von links nach rechts geschrieben, weg vom Kreis; nur die Legende START/END und ihre Pfeiltasten folgen der Leserichtung.
Ein Bild des Diagramms (of_save_as_png, Drucken) wird aufgenommen, sobald das Gleiten gelandet ist: Die Animation muss vorher nicht abgeschaltet werden.
Eine Farbe, die etwas bedeutet (verspätet, ausgegeben), wird über il_color gesetzt; überlassen Sie den Rest der Palette, sie wechselt mit hellem oder dunklem Thema.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Mitglieder	Rolle	Beschrieben in
`of_count` · `of_keys_at` · `of_has`	Durchlaufen, was die Komponente enthält	3.2 Die Items
`of_reset`	Die Komponente zurücksetzen	3.6 Eine Komponente zurücksetzen: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Tastenkürzel der Komponente	3.5 Tastenkombinationen
`of_is_created` · `of_is_ready` · `of_get_last_error`	Ob sie entstanden ist, ob sie bereit ist, was fehlschlug	3.7 Diagnose
`of_save_as_png` · `of_save_as_jpg`	Die Darstellung als Bild exportieren	3.8 Die Darstellung als Bild exportieren
`of_set_redraw`	Änderungen zu einem einzigen Neuzeichnen bündeln	3.10 Best Practices
`of_preload_icons`	Symbole ohne Verzögerung	Sofortige Anzeige: `of_icon`
`of_set_translation`	Eine Beschriftung der Komponente übersetzen	5.2 Eine Beschriftung anpassen: `of_set_translation`
`of_focus_webview`	Der Komponente den Fokus geben	6.4 Tastatur und Fokus
`of_print` · `of_print_to_pdf`	Drucken oder ein PDF schreiben	6.9 Drucken
`of_set_property` · `of_get_property` · `of_component_name`	Eine Eigenschaft über ihren Namen steuern	3.1 Die Eigenschaften-Engine
`is_accessible_name` · `is_accessible_description`	Name und Beschreibung, die ein Bildschirmleser sagt	3.4 Optionale Eigenschaften und Events

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.