# 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
    n_pbt_tilesbox_group lnv_grp

    // of_add_group liefert das Handle der Gruppe: daran haengt man ihre Kacheln
    lnv_grp = uo_tuiles.of_add_group(/*gruppe_id*/ "gestion", /*titel*/ "Verwaltung")

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

    // Event ue_tile_clicked von uo_tuiles: (string as_group, string as_id)
    choose case as_group + "/" + as_id
        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, und die Hinzufügungen leben auf dem Handle der Gruppe.

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

Auch die Events tragen den vollständigen Pfad (`as_group`, dann `as_id`). 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_VERTICAL` | 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_id)` → `n_pbt_tilesbox_group` | Liefert das Handle einer Gruppe (wird beim ersten Zugriff erzeugt)
`of_add_group (string as_group_id, string as_title)` → `n_pbt_tilesbox_group` | Fügt eine Gruppe hinzu und liefert ihr Handle
`of_remove_group (string as_id)` | Entfernt eine Gruppe und alle ihre Kacheln
`of_insert_tile (string as_group, string as_id, string as_text, integer ai_index)` | Fügt eine Kachel an einer bestimmten Position innerhalb ihrer Gruppe ein (Position ab 0 gezählt)
`of_insert_tile (string as_group, string as_id, 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
`of_move_tile (string as_group, string as_id, integer ai_index)` | Verschiebt eine vorhandene Kachel an eine andere Position ihrer Gruppe, unter Beibehaltung ihres Zustands
`of_remove_tile (string as_group, string as_id)` | Entfernt eine einzelne Kachel, der Rest des Panels bleibt erhalten
`of_clear ( )` | Leert das Panel (Gruppen und Kacheln)
`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
`of_reset ( )` | Leert den Inhalt und setzt die Eigenschaften auf ihre Standardwerte zurück

### 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
`of_tile (string as_id)` → `n_pbt_tilesbox_tile` |  |  | Liefert das Handle einer Kachel dieser Gruppe
`of_add_tile (as_id, as_label, as_icon_file, as_size)` → `n_pbt_tilesbox_tile` |  |  | Fügt dieser Gruppe eine Kachel hinzu und liefert ihr Handle

### Auf einer Kachel — `n_pbt_tilesbox_tile` #

Mitglied | Typ | Standard | Zweck
--- | --- | --- | ---
`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
`of_add_live_item (string as_text)` |  |  | Fügt dem animierten Band eine Seite hinzu; ab zwei Seiten lässt die Kachel sie durchlaufen
`of_clear_live_items ( )` |  |  | Leert das animierte Band: Die Kachel hört auf zu wechseln

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_group, string as_id)` | Auf eine Kachel wird geklickt
`ue_tile_moved (string as_group, string as_id, string as_to_group, long al_index)` | Eine Kachel wurde verschoben: `as_group` ist die Ausgangsgruppe, `as_to_group` die Zielgruppe, `al_index` die neue Position
`ue_group_toggled (string as_group, boolean ab_collapsed)` | Eine Gruppe wird über ihre Kopfzeile ein- oder ausgeklappt
`ue_tile_context (string as_group, string as_id)` | Rechtsklick auf eine Kachel
`ue_tile_resized (string as_group, string as_id, 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 #

    n_pbt_tilesbox_group lnv_grp

    uo_tuiles.of_clear()
    lnv_grp = uo_tuiles.of_add_group(/*gruppe_id*/ "accueil", /*titel*/ "Startseite")

    lnv_grp.of_add_tile(/*id*/ "tableau", /*label*/ "Dashboard", /*symbol_datei*/ "mono:img\chart.svg",  /*groesse*/ "large")
    lnv_grp.of_add_tile(/*id*/ "clients", /*label*/ "Kunden",         /*symbol_datei*/ "mono:img\users.svg",  /*groesse*/ "medium")
    lnv_grp.of_add_tile(/*id*/ "agenda",  /*label*/ "Kalender",          /*symbol_datei*/ "mono:img\cal.svg",    /*groesse*/ "wide")
    lnv_grp.of_add_tile(/*id*/ "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 #

    n_pbt_tilesbox_group lnv_admin

    lnv_admin = uo_tuiles.of_add_group(/*gruppe_id*/ "admin", /*titel*/ "Administration")
    lnv_admin.of_add_tile(/*id*/ "users",  /*label*/ "Benutzer", /*symbol_datei*/ "mono:img\users.svg", /*groesse*/ "medium")
    lnv_admin.of_add_tile(/*id*/ "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_group = "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(/*gruppe_id*/ "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_group = Ausgangsgruppe, as_to_group = Zielgruppe, al_index = Position
    if as_group <> as_to_group then
        of_tracer("Kachel " + as_id + " verschoben von " + as_group + " nach " + as_to_group)
    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 0 gezaehlt)
    uo_tuiles.of_move_tile(/*gruppe*/ "accueil", /*id*/ "aide", /*index*/ 0)

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

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

### Auf den Rechtsklick reagieren #

    // Event ue_tile_context von uo_tuiles: (as_group, as_id)
    // Die anvisierte Kachel merken, dann Ihr eigenes Kontextmenue oeffnen
    is_groupe_vise = as_group
    is_tuile_visee = as_id
    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.

← Komponentenreferenz · Inhalt des Handbuchs