# tilesbox — `u_pbt_tilesbox` #

← Riferimento dei componenti · Sommario della guida

> Pannello di riquadri raggruppati in stile schermata iniziale: quattro dimensioni di riquadro, colori, badge, riquadri animati, gruppi comprimibili e riorganizzazione con il mouse.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Tiles box: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_tilesbox`
Classi degli item | `n_pbt_tilesbox_group` (gruppo) → `n_pbt_tilesbox_tile` (riquadro)
Serve per | Offrire una schermata iniziale o un avviatore di funzioni: riquadri cliccabili, leggibili da lontano, ordinati per tema
Opzioni opt-in | —

## Avvio rapido #

    // event open della finestra
    n_pbt_tilesbox_group lnv_grp

    // of_add_group restituisce l'handle del gruppo: vi si agganciano i suoi riquadri
    lnv_grp = uo_tuiles.of_add_group(/*group_id*/ "gestion", /*title*/ "Gestione")

    lnv_grp.of_add_tile(/*id*/ "clients",   /*label*/ "Clienti",   /*icon_file*/ "mono:img\clients.svg",   /*size*/ "medium")
    lnv_grp.of_add_tile(/*id*/ "factures",  /*label*/ "Fatture",  /*icon_file*/ "mono:img\factures.svg",  /*size*/ "medium")
    lnv_grp.of_add_tile(/*id*/ "stock",     /*label*/ "Magazzino",     /*icon_file*/ "mono:img\stock.svg",     /*size*/ "small")

    // event ue_tile_clicked di 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

## Il modello: gruppi e riquadri #

Il pannello contiene dei gruppi, ciascuno con il proprio titolo e la propria intestazione comprimibile. I riquadri appartengono a un gruppo: il loro identificatore è univoco solo all'interno di quel gruppo. L'accesso passa quindi sempre dal percorso completo, e le aggiunte vivono sull'handle del gruppo.

    // Percorso obbligatorio: gruppo poi riquadro
    uo_tuiles.of_group("gestion").of_tile("factures").is_badge = "12"

Anche gli event portano il percorso completo (`as_group` poi `as_id`). Vedere Base comune · Gli item.

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`ib_reorderable` | boolean | `false` | Consente all'utente di spostare i riquadri con il mouse (attiva `ue_tile_moved`)
`is_scroll` | string | `SCROLL_VERTICAL` | Senso di scorrimento: `SCROLL_VERTICAL` (i riquadri vanno a capo) o `SCROLL_HORIZONTAL` (colonne in stile schermata iniziale)
`ib_show_group_headers` | boolean | `true` | `false` nasconde le intestazioni di gruppo. Utile quando il pannello contiene un solo gruppo: non c'è nulla da nominare e l'intestazione non fa che consumare altezza. Senza intestazione non c'è più il chevron: i gruppi si mostrano sempre espansi
`ii_anim_duration` | integer | `180` | Durata in millisecondi dell'animazione di compressione / espansione di un gruppo; `0` = istantanea
`ii_tile_unit` | integer | `0` | Dimensione di base di una piastrella, in pixel: ogni formato (piccola, media, larga, grande) ne è un multiplo, quindi un valore rende tutta la lavagna più densa o più ariosa. `0` la restituisce al tema
`ii_badge_size` | integer | `0` | Altezza dei badge delle piastrelle in pixel, per tutto il riquadro (`0` = la dimensione che proviene dal tema). La dimensione del carattere segue da sola. Il colore di un badge appartiene alla piastrella perché significa qualcosa; la sua dimensione no
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)
`is_tooltip` | string | `""` | Tooltip semplice mostrato al passaggio del mouse sul componente
`is_super_tooltip_title` | string | `""` | Titolo del tooltip avanzato (prevale su `is_tooltip`)
`is_super_tooltip_text` | string | `""` | Testo del tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image` | string | `""` | Immagine del tooltip avanzato

## Metodi #

Metodo | Ruolo
--- | ---
`of_group (string as_id)` → `n_pbt_tilesbox_group` | Restituisce l'handle di un gruppo (creato al primo accesso)
`of_add_group (string as_group_id, string as_title)` → `n_pbt_tilesbox_group` | Aggiunge un gruppo e ne restituisce l'handle
`of_remove_group (string as_id)` | Elimina un gruppo e tutti i suoi riquadri
`of_insert_tile (string as_group, string as_id, string as_text, integer ai_index)` | Inserisce un riquadro in una posizione precisa del suo gruppo (posizione contata a partire da 0)
`of_insert_tile (string as_group, string as_id, string as_text, string as_image, string as_size, integer ai_index)` | Idem, con l’icona e la dimensione (`small` / `medium` / `wide` / `large`): un riquadro è un’immagine con un’etichetta sotto, e la sua dimensione si vede nella griglia
`of_move_tile (string as_group, string as_id, integer ai_index)` | Sposta un riquadro esistente in un'altra posizione del suo gruppo, conservandone lo stato
`of_remove_tile (string as_group, string as_id)` | Elimina un solo riquadro, il resto del pannello viene preservato
`of_clear ( )` | Svuota il pannello (gruppi e riquadri)
`of_get_layout ( )` | Rilegge la disposizione corrente in JSON: gruppi, riquadri, ordine e dimensioni. Da memorizzare, poi da restituire con `of_set_layout`
`of_set_layout (string as_state_json)` | Ripristina una disposizione letta con `of_get_layout` o ricevuta con `ue_layout_changed`
`of_reset ( )` | Svuota il contenuto e riporta le proprietà ai valori predefiniti

### Su un gruppo — `n_pbt_tilesbox_group` #

Membro | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_title` | string | `""` | Titolo mostrato nell'intestazione, testo formattato con tag accettato
`ib_collapsed` | boolean | `false` | Gruppo compresso: i suoi riquadri sono nascosti sotto l'intestazione
`ib_enabled` | boolean | `true` | Intero gruppo disattivato e inerte
`ib_visible` | boolean | `true` | Gruppo nascosto, senza essere eliminato dal modello
`of_tile (string as_id)` → `n_pbt_tilesbox_tile` |  |  | Restituisce l'handle di un riquadro di questo gruppo
`of_add_tile (as_id, as_label, as_icon_file, as_size)` → `n_pbt_tilesbox_tile` |  |  | Aggiunge un riquadro a questo gruppo e ne restituisce l'handle

### Su un riquadro — `n_pbt_tilesbox_tile` #

Membro | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_size` | string | `SIZE_MEDIUM` | Dimensione: `SIZE_SMALL`, `SIZE_MEDIUM`, `SIZE_WIDE`, `SIZE_LARGE`
`il_back_color` · `il_text_color` | long | `-1` | Sfondo e testo di questo riquadro, come `RGB(r,g,b)` (`-1` = quello che dà il tema)
`il_back_color_hover` · `il_text_color_hover` | long | `-1` | Gli stessi due, ma sotto il puntatore
`is_badge` | string | `""` | Badge mostrato nell'angolo del riquadro (un contatore, uno stato breve)
`il_badge_color` | long | `0` | Sfondo del badge, in RGB PowerBuilder (`0` = il colore che proviene dal tema)
`is_live_text` | string | `""` | Testo sovrapposto al riquadro, testo formattato con tag accettato
`ib_enabled` | boolean | `true` | Riquadro disattivato e non cliccabile
`ib_visible` | boolean | `true` | Riquadro nascosto, senza essere rimosso dal suo gruppo
`of_add_live_item (string as_text)` |  |  | Aggiunge una facciata alla banda animata; a partire da due facciate, il riquadro le fa scorrere
`of_clear_live_items ( )` |  |  | Svuota la banda animata: il riquadro smette di scorrere

Le icone accettano tutte le forme riconosciute dalla libreria: percorso, `mono:`, `tint:`, risorsa di DLL. Su un riquadro grande, preferisca un'immagine nitida ad alta definizione o un SVG.

## Le quattro dimensioni #

Dimensione | Ingombro | Uso tipico
--- | --- | ---
`small` | 1 casella | Collegamento secondario; l'etichetta non viene mostrata, subentra il tooltip
`medium` | 2 × 2 caselle | Dimensione di riferimento: icona ed etichetta
`wide` | 4 × 2 caselle | Riquadro allungato, ideale per un testo animato
`large` | 4 × 4 caselle | Riquadro di punta della schermata

## Event #

Event | Attivato quando
--- | ---
`ue_tile_clicked (string as_group, string as_id)` | Si fa clic su un riquadro
`ue_tile_moved (string as_group, string as_id, string as_to_group, long al_index)` | Un riquadro è stato spostato: `as_group` è il gruppo di origine, `as_to_group` il gruppo di destinazione, `al_index` la nuova posizione
`ue_group_toggled (string as_group, boolean ab_collapsed)` | Un gruppo viene compresso o espanso dalla sua intestazione
`ue_tile_context (string as_group, string as_id)` | Clic destro su un riquadro
`ue_tile_resized (string as_group, string as_id, string as_size)` | La dimensione di un riquadro è cambiata; `as_size` porta la nuova dimensione
`ue_layout_changed (string as_layout_json)` | La disposizione è cambiata — l'utente ha spostato o ridimensionato un riquadro. Porta la disposizione intera, non solo ciò che si è mosso
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Esempi #

### Dimensioni miste in uno stesso gruppo #

    n_pbt_tilesbox_group lnv_grp

    uo_tuiles.of_clear()
    lnv_grp = uo_tuiles.of_add_group(/*group_id*/ "accueil", /*title*/ "Home")

    lnv_grp.of_add_tile(/*id*/ "tableau", /*label*/ "Cruscotto", /*icon_file*/ "mono:img\chart.svg",  /*size*/ "large")
    lnv_grp.of_add_tile(/*id*/ "clients", /*label*/ "Clienti",         /*icon_file*/ "mono:img\users.svg",  /*size*/ "medium")
    lnv_grp.of_add_tile(/*id*/ "agenda",  /*label*/ "Agenda",          /*icon_file*/ "mono:img\cal.svg",    /*size*/ "wide")
    lnv_grp.of_add_tile(/*id*/ "aide",    /*label*/ "Guida",            /*icon_file*/ "mono:img\help.svg",   /*size*/ "small")

### Badge, colore e riquadro animato #

    n_pbt_tilesbox_tile lnv_tuile

    // Un badge segnala un numero di elementi in attesa
    uo_tuiles.of_group("accueil").of_tile("clients").is_badge = String(ll_nouveaux)

    // Rosso quando il ritardo diventa critico, colore del tema altrimenti (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

    // Un colore proprio mette in evidenza un riquadro : sfondo, testo e cio che
    // ciascuno diventa sotto il puntatore
    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)

    // Riquadro ANIMATO: ogni facciata aggiunta scorre a turno sul riquadro
    lnv_tuile = uo_tuiles.of_group("accueil").of_tile("agenda")
    lnv_tuile.of_clear_live_items()
    lnv_tuile.of_add_live_item(/*text*/ "3 appuntamenti oggi")
    lnv_tuile.of_add_live_item(/*text*/ "Riunione di squadra alle 14:00")
    lnv_tuile.of_add_live_item(/*text*/ "2 solleciti in ritardo")

### Un testo fisso anziché uno scorrimento #

    // is_live_text mette UN testo permanente sul riquadro (testo formattato con tag accettato)
    uo_tuiles.of_group("accueil").of_tile("tableau").is_live_text = "[b]48[/b] ordini di oggi"

### Gruppi comprimibili #

    n_pbt_tilesbox_group lnv_admin

    lnv_admin = uo_tuiles.of_add_group(/*group_id*/ "admin", /*title*/ "Amministrazione")
    lnv_admin.of_add_tile(/*id*/ "users",  /*label*/ "Utenti", /*icon_file*/ "mono:img\users.svg", /*size*/ "medium")
    lnv_admin.of_add_tile(/*id*/ "params", /*label*/ "Impostazioni",   /*icon_file*/ "mono:img\gear.svg",  /*size*/ "medium")

    // Questo gruppo parte compresso: l'utente lo apre se ne ha bisogno
    lnv_admin.ib_collapsed = true

    // Un intero gruppo puo anche essere disattivato in base ai diritti
    lnv_admin.ib_enabled = (is_profil = "ADMIN")

    // event ue_group_toggled di uo_tuiles
    if as_group = "admin" and not ab_collapsed then of_tracer("Apertura del riquadro amministrazione")

### Un pannello a gruppo unico, senza intestazione #

    // Un solo gruppo non ha nulla da nominare : la sua intestazione consuma solo altezza.
    // Senza intestazione, niente piu chevron : i riquadri restano sempre visibili.
    uo_tuiles.ib_show_group_headers = false
    uo_tuiles.of_add_group(/*group_id*/ "tout", /*title*/ "")

### Spostare un riquadro tra due gruppi #

Con `ib_reorderable = true`, l'utente trascina un riquadro dove vuole, anche da un gruppo a un altro. L'event `ue_tile_moved` fornisce i due gruppi e la nuova posizione.

    uo_tuiles.ib_reorderable = true    // false per impostazione predefinita

    // event ue_tile_moved di uo_tuiles
    // as_group = gruppo di origine, as_to_group = gruppo di destinazione, al_index = posizione
    if as_group <> as_to_group then
        of_tracer("Riquadro " + as_id + " spostato da " + as_group + " a " + as_to_group)
    end if
    uo_tuiles.of_get_layout()    // richiedere la disposizione per conservarla

    // event ue_layout_changed di uo_tuiles: conservare la disposizione scelta
    is_disposition = as_layout_json

    // All'apertura successiva: ripristinare la schermata come l'utente l'aveva sistemata
    if is_disposition <> "" then uo_tuiles.of_set_layout(is_disposition)

Per bloccare la schermata, basta disattivare la riorganizzazione:

    uo_tuiles.ib_reorderable = false

### Riorganizzare dal codice #

    // Mettere il riquadro "aide" in testa al suo gruppo (posizioni contate a partire da 0)
    uo_tuiles.of_move_tile(/*group*/ "accueil", /*id*/ "aide", /*index*/ 0)

    // Inserire un nuovo riquadro in seconda posizione
    uo_tuiles.of_insert_tile(/*group*/ "accueil", /*id*/ "devis", /*text*/ "Preventivi", /*index*/ 1)

    // Rimuovere un riquadro senza toccare il resto
    uo_tuiles.of_remove_tile(/*group*/ "accueil", /*id*/ "aide")

### Reagire al clic destro #

    // event ue_tile_context di uo_tuiles: (as_group, as_id)
    // Memorizzare il riquadro interessato, poi aprire il proprio menu contestuale
    is_groupe_vise = as_group
    is_tuile_visee = as_id
    of_ouvrir_menu_tuile(PointerX(), PointerY())

## Buone pratiche #

- Un solo riquadro `large` per schermata è sufficiente: è il punto di ingresso principale, il resto deve restare leggibile.
- I riquadri `small` non mostrano la propria etichetta — compili sistematicamente il tooltip dell'item.
- Riservi `il_back_color` ai riquadri che devono spiccare: oltre due o tre colori, la schermata perde la sua gerarchia. E se mette uno sfondo chiaro, metta anche `il_text_color` — il testo del tema non è garantito leggibile sopra.
- Preferisca `of_add_live_item` (scorrimento) a `is_live_text` (testo fisso) quando ha più informazioni da far passare sullo stesso riquadro.
- Se lascia attiva la riorganizzazione, conservi la disposizione tramite `of_get_layout` / `ue_layout_changed` e riapplichi `of_set_layout` all'apertura.
- Utilizzi `ib_visible` e `ib_enabled` (gruppo o riquadro) per adattare il pannello ai diritti dell'utente, anziché ricostruirlo.
- Quando lo spazio non basta per i riquadri, preferisca la navigazione laterale compatta della listbar; per le azioni frequenti, la toolbar.

← Riferimento dei componenti · Sommario della guida