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

// Un riquadro si aggiunge al suo INDIRIZZO : il gruppo, poi il proprio identificatore
uo_tuiles.of_add_group(/*key*/ "gestion", /*title*/ "Gestione")

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

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

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. Le aggiunte vivono sul componente: un handle porta soltanto proprietà.

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

Anche gli event portano l'indirizzo completo (as_keys, il gruppo poi la piastrella). 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_HORIZONTAL`	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_key)` → `n_pbt_tilesbox_group`	Restituisce l'handle di un gruppo (creato al primo accesso)
`of_add_group (string as_key, string as_title)` → `long`	Aggiunge un gruppo e restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato)
`of_add_tile (string as_keys, string as_text, string as_image, string as_size)` → `long`	Aggiunge un riquadro al suo indirizzo, `"gestion/clients"`: il gruppo in cui atterra, poi il proprio identificatore. Restituisce `0` (`-5` per un argomento non valido, `-2` se il componente non è creato) — `-5` se il padre non è un gruppo. Un overload omette l'icona e la dimensione
`of_tile (string as_keys)` → `n_pbt_tilesbox_tile`	Restituisce l'handle di un riquadro, tramite il suo indirizzo (creato al primo accesso)
`of_add_live_item (string as_keys, string as_text)` → `long`	Aggiunge una faccia alla banda animata di una piastrella, al suo indirizzo; da due facce in poi la piastrella le fa scorrere. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear_live_items (string as_keys)` → `long`	Svuota la banda animata di una piastrella: smette di scorrere e torna alla sua faccia semplice. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_group (string as_key)`	Elimina un gruppo e tutti i suoi riquadri. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_insert_tile (string as_keys, string as_text, integer ai_index)`	Inserisce un riquadro in una posizione precisa del suo gruppo (posizione contata a partire da 1). Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_insert_tile (string as_keys, 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. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_move_tile (string as_keys, integer ai_index)`	Sposta un riquadro esistente in un'altra posizione del suo gruppo, conservandone lo stato. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_tile (string as_keys)`	Elimina un solo riquadro, il resto del pannello viene preservato. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_clear ( )`	Svuota il pannello (gruppi e riquadri). Restituisce `0` una volta applicato, `-2` se il componente non è creato
`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`. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_reset ( )`	Svuota il contenuto e riporta le proprietà ai valori predefiniti. Restituisce `0` una volta applicato, `-2` se il componente non è creato

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

Su un riquadro — `n_pbt_tilesbox_tile` #

Membro	Tipo	Predefinito	Ruolo
`is_title`	string	`""`	Testo mostrato sulla casella. Posto da `of_add_tile`; scriverlo qui lo cambia, leggerlo dice cosa la casella mostra adesso
`is_image`	string	`""`	Icona della casella (percorso su disco o `resources.dll:nome`). Una stringa vuota toglie l'icona
`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

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_keys)`	Si fa clic su un riquadro
`ue_tile_moved (string as_keys, string as_to_keys, long al_index)`	Un riquadro è stato spostato: `as_keys` è l'indirizzo di partenza, `as_to_keys` il gruppo di destinazione, `al_index` la nuova posizione
`ue_group_toggled (string as_key, boolean ab_collapsed)`	Un gruppo viene compresso o espanso dalla sua intestazione
`ue_tile_context (string as_keys)`	Clic destro su un riquadro
`ue_tile_resized (string as_keys, 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 #


uo_tuiles.of_clear()
uo_tuiles.of_add_group(/*key*/ "accueil", /*title*/ "Home")

uo_tuiles.of_add_tile(/*keys*/ "accueil/tableau", /*label*/ "Cruscotto", /*icon_file*/ "mono:img\chart.svg",  /*size*/ "large")
uo_tuiles.of_add_tile(/*keys*/ "accueil/clients", /*label*/ "Clienti",         /*icon_file*/ "mono:img\users.svg",  /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "accueil/agenda",  /*label*/ "Agenda",          /*icon_file*/ "mono:img\cal.svg",    /*size*/ "wide")
uo_tuiles.of_add_tile(/*keys*/ "accueil/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 #


uo_tuiles.of_add_group(/*key*/ "admin", /*title*/ "Amministrazione")
uo_tuiles.of_add_tile(/*keys*/ "admin/users",  /*label*/ "Utenti", /*icon_file*/ "mono:img\users.svg", /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "admin/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_keys = "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(/*key*/ "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_keys = da dove viene, as_to_keys = dove va, al_index = posizione
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
if as_keys <> as_to_keys then
    of_tracer("Riquadro " + lnv_utils.of_leaf(as_keys) + " spostato da " + lnv_utils.of_parent(as_keys) + " a " + as_to_keys)
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 1)
uo_tuiles.of_move_tile(/*group*/ "accueil", /*key*/ "aide", /*index*/ 1)

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

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

Reagire al clic destro #

// event ue_tile_context di uo_tuiles: (as_keys)
// Memorizzare il riquadro interessato, poi aprire il proprio menu contestuale
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
// Un solo indirizzo : dividerlo se servono le due meta.
is_groupe_vise = lnv_utils.of_parent(as_keys)
is_tuile_visee = lnv_utils.of_leaf(as_keys)
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.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Membri	Ruolo	Descritto in
`of_count` · `of_keys_at` · `of_has`	Percorrere ciò che il componente contiene	3.2 Gli item
`of_reset`	Riportare il componente a zero	3.6 Riportare un componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Scorciatoie da tastiera del componente	3.5 Le scorciatoie da tastiera
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se è nato, se è pronto, cosa è fallito	3.7 Diagnostica
`of_save_as_png` · `of_save_as_jpg`	Esportare il rendering in immagine	3.8 Esportare il rendering come immagine
`of_set_redraw`	Raggruppare le modifiche in un solo ridisegno	3.10 Buone pratiche
`of_preload_icons`	Icone mostrate senza ritardo	Visualizzazione istantanea: `of_icon`
`of_set_translation`	Tradurre una dicitura del componente	5.2 Adattare un'etichetta: `of_set_translation`
`of_focus_webview`	Dare il focus al componente	6.4 Tastiera e focus
`of_print` · `of_print_to_pdf`	Stampare, o scrivere un PDF	6.9 Stampare
`of_set_property` · `of_get_property` · `of_component_name`	Pilotare una proprietà per nome	3.1 Il motore delle proprietà

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.