tilesbox — `u_pbt_tilesbox` #

← Komponentenreferenz · Inhalt des Handbuchs

Panel mit gruppierten Kacheln im Startbildschirm-Stil: vier Kachelgrößen, Farben, Plaketten, animierte Kacheln, einklappbare Gruppen und Umsortieren mit der Maus.

▶ Live ansehen — Demoanwendung, Kachel Tiles box: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Userobject	`u_pbt_tilesbox`
Item-Klassen	`n_pbt_tilesbox_group` (Gruppe) → `n_pbt_tilesbox_tile` (Kachel)
Wofür	Einen Startbildschirm oder einen Funktionsstarter anbieten: anklickbare, von Weitem lesbare Kacheln, nach Thema geordnet
Opt-in-Optionen	—

Schnellstart #

// open-Event des Fensters

// Eine Kachel wird an ihrer ADRESSE hinzugefuegt : die Gruppe, dann ihre eigene Id
uo_tuiles.of_add_group(/*key*/ "gestion", /*titel*/ "Verwaltung")

uo_tuiles.of_add_tile(/*keys*/ "gestion/clients",   /*label*/ "Kunden",   /*symbol_datei*/ "mono:img\clients.svg",   /*groesse*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/factures",  /*label*/ "Rechnungen",  /*symbol_datei*/ "mono:img\factures.svg",  /*groesse*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/stock",     /*label*/ "Bestand",     /*symbol_datei*/ "mono:img\stock.svg",     /*groesse*/ "small")

// Event ue_tile_clicked von uo_tuiles: (string as_keys)
choose case as_keys
    case "gestion/clients"  ; open(w_clients)
    case "gestion/factures" ; open(w_factures)
    case "gestion/stock"    ; open(w_stock)
end choose

Das Modell: Gruppen und Kacheln #

Das Panel enthält Gruppen, jede mit ihrem Titel und ihrer einklappbaren Kopfzeile. Die Kacheln gehören zu einer Gruppe: Ihr Bezeichner ist nur innerhalb dieser Gruppe eindeutig. Der Zugriff läuft daher immer über den vollständigen Pfad. Die Hinzufügungen leben auf der Komponente: ein Handle trägt nur Eigenschaften.

// Pflichtpfad: Gruppe, dann Kachel
uo_tuiles.of_tile("gestion/factures").is_badge = "12"

Auch die Events tragen die vollständige Adresse (as_keys, die Gruppe, dann die Kachel). Siehe Gemeinsame Basis · Die Items.

Eigenschaften #

Eigenschaft	Typ	Standard	Zweck
`ib_reorderable`	boolean	`false`	Erlaubt dem Benutzer, die Kacheln mit der Maus zu verschieben (löst `ue_tile_moved` aus)
`is_scroll`	string	`SCROLL_HORIZONTAL`	Bildlaufrichtung: `SCROLL_VERTICAL` (die Kacheln brechen um) oder `SCROLL_HORIZONTAL` (Spalten im Startbildschirm-Stil)
`ib_show_group_headers`	boolean	`true`	`false` blendet die Gruppenkopfzeilen aus. Nützlich, wenn der Bereich nur eine einzige Gruppe enthält: Es gibt nichts zu benennen und die Kopfzeile frisst nur Höhe. Ohne Kopfzeile gibt es auch kein Chevron mehr: Die Gruppen werden immer ausgeklappt angezeigt
`ii_anim_duration`	integer	`180`	Dauer der Ein-/Ausklappanimation einer Gruppe in Millisekunden; `0` = sofort
`ii_tile_unit`	integer	`0`	Grundgröße einer Kachel in Pixeln: jede Kachelgröße (klein, mittel, breit, groß) ist ein Vielfaches davon, sodass ein Wert das ganze Brett dichter oder luftiger macht. `0` gibt sie dem Thema zurück
`ii_badge_size`	integer	`0`	Höhe der Kachel-Plaketten in Pixeln, für die ganze Box (`0` = die Größe aus dem Design). Die Schriftgröße folgt von selbst. Die Farbe einer Plakette gehört zur Kachel, weil sie etwas bedeutet; ihre Größe nicht
`is_theme_style`	string	`fluent`	Visueller Stil der Komponente (Konstanten `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Helle oder dunkle Variante (Konstanten `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Akzentfarbe dieser Komponente (`-1` = Akzent des Designs)
`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 zulässig)
`is_super_tooltip_image`	string	`""`	Bild des erweiterten Tooltips

Methoden #

Methode	Zweck
`of_group (string as_key)` → `n_pbt_tilesbox_group`	Liefert das Handle einer Gruppe (wird beim ersten Zugriff erzeugt)
`of_add_group (string as_key, string as_title)` → `long`	Fügt eine Gruppe hinzu und liefert `0` (`-5` bei einem ungültigen Argument, `-2` wenn die Komponente nicht erzeugt ist)
`of_add_tile (string as_keys, string as_text, string as_image, string as_size)` → `long`	Fügt eine Kachel an ihrer Adresse hinzu, `"gestion/clients"`: die Gruppe, in der sie landet, dann ihre eigene Id. Liefert `0` (`-5` bei einem ungültigen Argument, `-2` wenn die Komponente nicht erzeugt ist) — `-5`, wenn das übergeordnete Element keine Gruppe ist. Eine Überladung lässt Symbol und Größe weg
`of_tile (string as_keys)` → `n_pbt_tilesbox_tile`	Gibt das Handle einer Kachel über ihre Adresse zurück (beim ersten Zugriff erzeugt)
`of_add_live_item (string as_keys, string as_text)` → `long`	Fügt dem Laufband einer Kachel eine Seite hinzu, an ihrer Adresse; ab zwei Seiten wechselt die Kachel zwischen ihnen. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_clear_live_items (string as_keys)` → `long`	Leert das Laufband einer Kachel: sie hört auf zu wechseln und zeigt wieder ihre einfache Seite. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_remove_group (string as_key)`	Entfernt eine Gruppe und alle ihre Kacheln. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_insert_tile (string as_keys, string as_text, integer ai_index)`	Fügt eine Kachel an einer bestimmten Position innerhalb ihrer Gruppe ein (Position ab 1 gezählt). Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_insert_tile (string as_keys, string as_text, string as_image, string as_size, integer ai_index)`	Ebenso, mit Symbol und Größe (`small` / `medium` / `wide` / `large`): eine Kachel ist ein Bild mit einer Beschriftung darunter, und ihre Größe ist im Raster sichtbar. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_move_tile (string as_keys, integer ai_index)`	Verschiebt eine vorhandene Kachel an eine andere Position ihrer Gruppe, unter Beibehaltung ihres Zustands. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_remove_tile (string as_keys)`	Entfernt eine einzelne Kachel, der Rest des Panels bleibt erhalten. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_clear ( )`	Leert das Panel (Gruppen und Kacheln). Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist
`of_get_layout ( )`	Liest die aktuelle Anordnung als JSON zurück: Gruppen, Kacheln, Reihenfolge und Größen. Speichern und mit `of_set_layout` zurückgeben
`of_set_layout (string as_state_json)`	Stellt eine mit `of_get_layout` gelesene oder über `ue_layout_changed` empfangene Anordnung wieder her. Liefert `0` nach der Anwendung, `-5` bei einem ungültigen Argument (leerer Schlüssel, falsche Adresse), `-2` wenn die Komponente nicht erzeugt ist
`of_reset ( )`	Leert den Inhalt und setzt die Eigenschaften auf ihre Standardwerte zurück. Liefert `0` nach der Anwendung, `-2` wenn die Komponente nicht erzeugt ist

Auf einer Gruppe — `n_pbt_tilesbox_group` #

Mitglied	Typ	Standard	Zweck
`is_title`	string	`""`	In der Kopfzeile angezeigter Titel, Rich-Text-Auszeichnung zulässig
`ib_collapsed`	boolean	`false`	Eingeklappte Gruppe: Ihre Kacheln sind unter der Kopfzeile verborgen
`ib_enabled`	boolean	`true`	Gesamte Gruppe ausgegraut und inaktiv
`ib_visible`	boolean	`true`	Gruppe ausgeblendet, ohne aus dem Modell entfernt zu werden

Auf einer Kachel — `n_pbt_tilesbox_tile` #

Mitglied	Typ	Standard	Zweck
`is_title`	string	`""`	Text auf der Kachel. Von `of_add_tile` gesetzt; hier geschrieben ändert er sich, gelesen sagt er, was die Kachel gerade zeigt
`is_image`	string	`""`	Symbol der Kachel (Dateipfad oder `resources.dll:Name`). Eine leere Zeichenkette entfernt das Symbol
`is_size`	string	`SIZE_MEDIUM`	Größe: `SIZE_SMALL`, `SIZE_MEDIUM`, `SIZE_WIDE`, `SIZE_LARGE`
`il_back_color` · `il_text_color`	long	`-1`	Hintergrund und Text dieser Kachel, als `RGB(r,g,b)` (`-1` = was das Design vorgibt)
`il_back_color_hover` · `il_text_color_hover`	long	`-1`	Dieselben zwei, aber unter dem Mauszeiger
`is_badge`	string	`""`	In der Ecke der Kachel angezeigte Plakette (ein Zähler, ein kurzer Status)
`il_badge_color`	long	`0`	Hintergrund der Plakette, als PowerBuilder-RGB (`0` = die Farbe aus dem Design)
`is_live_text`	string	`""`	Über die Kachel gelegter Text, Rich-Text-Auszeichnung zulässig
`ib_enabled`	boolean	`true`	Kachel ausgegraut und nicht anklickbar
`ib_visible`	boolean	`true`	Kachel ausgeblendet, ohne aus ihrer Gruppe entfernt zu werden

Die Symbole akzeptieren alle von der Bibliothek erkannten Formen: Pfad, mono:, tint:, DLL-Ressource. Ziehen Sie auf einer großen Kachel ein scharfes, hochauflösendes Bild oder ein SVG vor.

Die vier Größen #

Größe	Platzbedarf	Typische Verwendung
`small`	1 Feld	Nachrangige Verknüpfung; die Beschriftung wird nicht angezeigt, der Tooltip übernimmt
`medium`	2 × 2 Felder	Referenzgröße: Symbol und Beschriftung
`wide`	4 × 2 Felder	Längliche Kachel, ideal für einen animierten Text
`large`	4 × 4 Felder	Hauptkachel des Bildschirms

Events #

Event	Ausgelöst wenn
`ue_tile_clicked (string as_keys)`	Auf eine Kachel wird geklickt
`ue_tile_moved (string as_keys, string as_to_keys, long al_index)`	Eine Kachel wurde verschoben: `as_keys` ist die Adresse, von der sie kommt, `as_to_keys` die Zielgruppe, `al_index` die neue Position
`ue_group_toggled (string as_key, boolean ab_collapsed)`	Eine Gruppe wird über ihre Kopfzeile ein- oder ausgeklappt
`ue_tile_context (string as_keys)`	Rechtsklick auf eine Kachel
`ue_tile_resized (string as_keys, string as_size)`	Die Größe einer Kachel hat sich geändert; `as_size` trägt die neue Größe
`ue_layout_changed (string as_layout_json)`	Die Anordnung hat sich geändert — der Benutzer hat eine Kachel verschoben oder ihre Größe geändert. Trägt die gesamte Anordnung, nicht nur das Verschobene
`ue_ready ( )`	Die Komponente ist fertig geladen; alles zuvor Gesendete wurde nachgespielt
`ue_runtime_missing ( )`	Die WebView2-Runtime fehlt: die Komponente bleibt leer
`ue_bg_color (long al_color)`	Die Komponente hat ihre Design-Hintergrundfarbe berechnet; das Userobject hat sie bereits übernommen (`backcolor`)

Beispiele #

Gemischte Größen innerhalb einer Gruppe #


uo_tuiles.of_clear()
uo_tuiles.of_add_group(/*key*/ "accueil", /*titel*/ "Startseite")

uo_tuiles.of_add_tile(/*keys*/ "accueil/tableau", /*label*/ "Dashboard", /*symbol_datei*/ "mono:img\chart.svg",  /*groesse*/ "large")
uo_tuiles.of_add_tile(/*keys*/ "accueil/clients", /*label*/ "Kunden",         /*symbol_datei*/ "mono:img\users.svg",  /*groesse*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "accueil/agenda",  /*label*/ "Kalender",          /*symbol_datei*/ "mono:img\cal.svg",    /*groesse*/ "wide")
uo_tuiles.of_add_tile(/*keys*/ "accueil/aide",    /*label*/ "Hilfe",            /*symbol_datei*/ "mono:img\help.svg",   /*groesse*/ "small")

Plakette, Farbe und animierte Kachel #

n_pbt_tilesbox_tile lnv_tuile

// Eine Plakette meldet eine Anzahl wartender Elemente
uo_tuiles.of_group("accueil").of_tile("clients").is_badge = String(ll_nouveaux)

// Rot, wenn der Rueckstand kritisch wird, sonst die Farbe des Designs (0)
if ll_nouveaux > 50 then
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = RGB(200, 30, 30)
else
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = 0
end if

// Eine eigene Farbe hebt eine Kachel hervor : Hintergrund, Text und das,
// was aus beiden unter dem Mauszeiger wird
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("tableau")
lnv_tuile.il_back_color = RGB(0, 103, 192)
lnv_tuile.il_back_color_hover = RGB(0, 80, 150)
lnv_tuile.il_text_color = RGB(255, 255, 255)

// ANIMIERTE Kachel: jede hinzugefuegte Seite laeuft der Reihe nach ueber die Kachel
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("agenda")
lnv_tuile.of_clear_live_items()
lnv_tuile.of_add_live_item(/*text*/ "3 Termine heute")
lnv_tuile.of_add_live_item(/*text*/ "Teambesprechung um 14:00 Uhr")
lnv_tuile.of_add_live_item(/*text*/ "2 überfällige Nachfassaktionen")

Ein fester Text statt eines Durchlaufs #

// is_live_text legt EINEN dauerhaften Text auf die Kachel (Rich-Text-Auszeichnung zulaessig)
uo_tuiles.of_group("accueil").of_tile("tableau").is_live_text = "[b]48[/b] Bestellungen heute"

Einklappbare Gruppen #


uo_tuiles.of_add_group(/*key*/ "admin", /*titel*/ "Administration")
uo_tuiles.of_add_tile(/*keys*/ "admin/users",  /*label*/ "Benutzer", /*symbol_datei*/ "mono:img\users.svg", /*groesse*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "admin/params", /*label*/ "Einstellungen",   /*symbol_datei*/ "mono:img\gear.svg",  /*groesse*/ "medium")

// Diese Gruppe startet eingeklappt: der Benutzer oeffnet sie, wenn er sie braucht
lnv_admin.ib_collapsed = true

// Eine ganze Gruppe kann je nach Rechten auch ausgegraut werden
lnv_admin.ib_enabled = (is_profil = "ADMIN")

// Event ue_group_toggled von uo_tuiles
if as_keys = "admin" and not ab_collapsed then of_tracer("Verwaltungsbereich geoeffnet")

Ein Bereich mit einer einzigen Gruppe, ohne Kopfzeile #

// Eine einzige Gruppe hat nichts zu benennen : ihre Kopfzeile frisst nur Hoehe.
// Ohne Kopfzeile auch kein Chevron mehr : die Kacheln bleiben immer sichtbar.
uo_tuiles.ib_show_group_headers = false
uo_tuiles.of_add_group(/*key*/ "tout", /*titel*/ "")

Eine Kachel zwischen zwei Gruppen verschieben #

Mit ib_reorderable = true zieht der Benutzer eine Kachel dorthin, wohin er will, auch von einer Gruppe in eine andere. Das Event ue_tile_moved liefert beide Gruppen und die neue Position.

uo_tuiles.ib_reorderable = true    // standardmaessig false : anfordern

// Event ue_tile_moved von uo_tuiles
// as_keys = woher sie kommt, as_to_keys = wohin sie geht, al_index = Position
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
if as_keys <> as_to_keys then
    of_tracer("Kachel " + lnv_utils.of_leaf(as_keys) + " verschoben von " + lnv_utils.of_parent(as_keys) + " nach " + as_to_keys)
end if
uo_tuiles.of_get_layout()    // die Anordnung anfordern, um sie aufzubewahren

// Event ue_layout_changed von uo_tuiles: die gewaehlte Anordnung aufbewahren
is_disposition = as_layout_json

// Beim naechsten Oeffnen: den Bildschirm so wiederherstellen, wie der Benutzer ihn eingerichtet hatte
if is_disposition <> "" then uo_tuiles.of_set_layout(is_disposition)

Um den Bildschirm festzusetzen, genügt es, das Umsortieren abzuschalten:

uo_tuiles.ib_reorderable = false

Aus dem Code heraus umsortieren #

// Die Kachel "aide" an den Anfang ihrer Gruppe setzen (Positionen ab 1 gezaehlt)
uo_tuiles.of_move_tile(/*gruppe*/ "accueil", /*key*/ "aide", /*index*/ 1)

// Eine neue Kachel an zweiter Position einfuegen
uo_tuiles.of_insert_tile(/*gruppe*/ "accueil", /*key*/ "devis", /*text*/ "Angebote", /*index*/ 2)

// Eine Kachel entfernen, ohne den Rest anzuruehren
uo_tuiles.of_remove_tile(/*gruppe*/ "accueil", /*key*/ "aide")

Auf den Rechtsklick reagieren #

// Event ue_tile_context von uo_tuiles: (as_keys)
// Die anvisierte Kachel merken, dann Ihr eigenes Kontextmenue oeffnen
n_pbt_utils lnv_utils   // autoinstantiate : nichts zu erzeugen, nichts zu zerstoeren
// Eine einzige Adresse : aufteilen, wenn beide Haelften gebraucht werden.
is_groupe_vise = lnv_utils.of_parent(as_keys)
is_tuile_visee = lnv_utils.of_leaf(as_keys)
of_ouvrir_menu_tuile(PointerX(), PointerY())

Best Practices #

Eine large-Kachel pro Bildschirm genügt: Sie ist der Haupteinstiegspunkt, der Rest muss lesbar bleiben.
small-Kacheln zeigen ihre Beschriftung nicht an — füllen Sie stets den Tooltip des Items aus.
Behalten Sie il_back_color den Kacheln vor, die sich abheben sollen: Über zwei oder drei Farben hinaus verliert der Bildschirm seine Hierarchie. Und wenn Sie einen hellen Hintergrund setzen, setzen Sie il_text_color gleich mit — der Text des Designs ist darauf nicht garantiert lesbar.
Ziehen Sie of_add_live_item (Durchlauf) dem is_live_text (fester Text) vor, wenn Sie mehrere Informationen auf derselben Kachel unterbringen wollen.
Wenn Sie das Umsortieren aktiv lassen, bewahren Sie die Anordnung über of_get_layout / ue_layout_changed auf und spielen Sie of_set_layout beim Öffnen wieder ein.
Verwenden Sie ib_visible und ib_enabled (Gruppe oder Kachel), um das Panel an die Rechte des Benutzers anzupassen, statt es neu aufzubauen.
Wenn der Platz für Kacheln nicht ausreicht, ziehen Sie die kompakte seitliche Navigation der listbar vor; für häufige Aktionen die toolbar.

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

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.