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	`ib_reorderable`: spostare e ridimensionare i riquadri con il mouse

Avvio rapido #

// event open della finestra

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

// Poi i suoi riquadri, ognuno con la sua dimensioneuo_tiles.of_add_tile(/*keys*/ "office/clients",   /*label*/ "Clienti",   /*icon_file*/ "mono:img\clients.svg",   /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "office/invoices",  /*text*/ "Fatture",  /*image*/ "mono:img\factures.svg",  /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "office/stock",     /*text*/ "Magazzino",     /*image*/ "mono:img\stock.svg",     /*size*/ "small")

// event ue_tile_clicked di uo_tiles: (string as_keys)
choose case as_keys
    case "office/clients"  ; open(w_clients)
    case "office/invoices" ; open(w_invoices)
    case "office/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_tiles.of_tile(/*keys*/ "office/invoices").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 riorganizzare i riquadri: con il mouse, o dalla tastiera con Ctrl+Sinistra/Destra (una posizione nel gruppo, nel senso di lettura) e Ctrl+Su/Giù (verso il gruppo precedente o successivo); il clic destro ridimensiona. Mouse e tastiera attivano lo stesso `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	`""`	Stile visivo del componente (costanti `THEME_STYLE_*`); vuoto = quello dell'applicazione, seguito a ogni cambio
`is_theme_mode`	string	`""`	Variante chiara o scura (costanti `THEME_MODE_*`); vuoto = quella dell'applicazione, seguita a ogni cambio
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento dell'applicazione, o quello 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). Su un gruppo che non esiste non scrive nulla — non crea mai il gruppo, lo fa `of_add_group`; una chiave che non può nominare un gruppo (vuota, con `/` o `	`) dà un handle inerte che si rilegge vuoto
`of_add_group (string as_key, string as_title)` → `long`	Aggiunge un gruppo. Restituisce `0` una volta applicato, `-5` se la chiave è vuota, contiene un `/` o un `	`, o è già presa,` -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, `"office/clients"`: il gruppo in cui finisce, poi il suo identificativo. Restituisce `0` una volta applicato, `-5` se l'indirizzo non è `gruppo/riquadro`, se il gruppo non è stato aggiunto con `of_add_group`, se la chiave è già presa in quel gruppo (o vuota, o contiene un `	`),` -2` se il componente non è creato. 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). Un indirizzo che non è `gruppo/riquadro` dà un handle inerte: non scrive nulla e si legge vuoto
`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. La prima faccia cancella `is_live_text`; `of_tile(indirizzo).of_count()` legge il numero di facce. Restituisce `0` una volta applicato, `-5` su un testo vuoto o se nessun riquadro vive a quell'indirizzo, `-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` se nessun riquadro vive a quell'indirizzo, `-2` se il componente non è creato
`of_remove_group (string as_key)`	Rimuove un gruppo e tutti i suoi riquadri. Restituisce `0` una volta applicato, `-5` se tale gruppo non esiste, `-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 gli stessi rifiuti di `of_add_tile`, `-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 gli stessi rifiuti di `of_add_tile`, `-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` se nessun riquadro vive a quell'indirizzo, `-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` se nessun riquadro vive a quell'indirizzo, `-2` se il componente non è creato
`of_clear ( )`	Svuota il pannello (gruppi e riquadri); gli handle forniti per essi vengono liberati. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_get_layout ( )`	Rilegge la disposizione corrente in JSON: i gruppi nel loro ordine, compressi o no, visibili o no, e i loro riquadri in ordine con dimensione e visibilità. Un testo opaco: da conservare così com'è, poi da restituire a `of_set_layout`
`of_set_layout (string as_state_json)`	Ripristina una disposizione letta con `of_get_layout` o ricevuta con `ue_layout_changed`: ordine, gruppi compressi, dimensioni e visibilità. Un riquadro si ritrova tramite il suo gruppo e la sua chiave; ciò che la disposizione non nomina mantiene il suo posto. Non solleva alcun evento. Restituisce `0` una volta applicato, `-5` su un testo vuoto o che non è JSON, `-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	la chiave	Titolo mostrato nell'intestazione, testo formattato con tag accettato
`ib_collapsed`	boolean	`false`	Gruppo compresso: i suoi riquadri sono nascosti sotto l'intestazione. Impostarlo solleva `ue_group_toggled` quando lo stato cambia, come un clic sull'intestazione
`ib_enabled`	boolean	`true`	Intero gruppo disattivato e inerte: la sua intestazione non lo comprime più, i suoi riquadri non rispondono più, nessun riquadro vi può essere rilasciato
`ib_visible`	boolean	`true`	Gruppo nascosto, senza essere eliminato dal modello
`il_back_color` · `il_text_color` · `il_back_color_hover` · `il_text_color_hover` · `il_accent`	long	`-1`	Colori dell'intestazione del gruppo — sfondo, titolo, entrambi sotto il puntatore, e una linea d'accento sotto l'intestazione. Non scendono sui riquadri, che mantengono i propri

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	`-1`	Sfondo del badge, in RGB PowerBuilder (`-1` = il colore che proviene dal tema; `0` è il nero)
`is_live_text`	string	`""`	Testo fisso sovrapposto al riquadro; la prima faccia di `of_add_live_item` lo cancella (si rilegge allora vuoto), 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_key, long al_index)`	L'utente ha spostato un riquadro, con il mouse o con Ctrl+frecce (`of_move_tile` non attiva nulla): `as_keys` è l'indirizzo di partenza, `as_to_key` 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, o dal suo `ib_collapsed` impostato dal suo codice (nulla quando è già in quello stato)
`ue_tile_context (string as_keys)`	Clic destro su un riquadro
`ue_tile_resized (string as_keys, string as_size)`	L'utente ha dato un'altra dimensione a un riquadro dal suo menu del clic destro (mostrato solo quando `ib_reorderable` vale `true`); `as_size` porta la nuova dimensione
`ue_layout_changed (string as_layout_json)`	L'utente ha cambiato la disposizione: un riquadro spostato, un riquadro ridimensionato dal suo menu, un gruppo compresso o espanso dalla sua intestazione. Porta la disposizione intera, lo stesso testo di `of_get_layout`. Ciò che l'applicazione cambia via codice non lo solleva (l'`ib_collapsed` di un gruppo solleva solo `ue_group_toggled`)
`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 #

// Ripartire da un contenitore vuoto, con un gruppo
uo_tiles.of_clear()
uo_tiles.of_add_group(/*key*/ "home", /*title*/ "Home")

// Quattro riquadri, di quattro dimensioni
uo_tiles.of_add_tile(/*keys*/ "home/dashboard", /*text*/ "Cruscotto", /*image*/ "mono:img\chart.svg",  /*size*/ "large")
uo_tiles.of_add_tile(/*keys*/ "home/clients", /*text*/ "Clienti",         /*image*/ "mono:img\users.svg",  /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "home/agenda",  /*text*/ "Agenda",          /*image*/ "mono:img\cal.svg",    /*size*/ "wide")
uo_tiles.of_add_tile(/*keys*/ "home/help",    /*text*/ "Guida",            /*image*/ "mono:img\help.svg",   /*size*/ "small")

Badge, colore e riquadro animato #

// Local variables
n_pbt_tilesbox_tile lnv_tile

// Un badge segnala un numero di elementi in attesa
uo_tiles.of_tile(/*keys*/ "home/clients").is_badge = String(ll_new_count)

// Rosso quando il ritardo diventa critico, colore del tema altrimenti (-1)
if ll_new_count > 50 then
    uo_tiles.of_tile(/*keys*/ "home/clients").il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)
else
    uo_tiles.of_tile(/*keys*/ "home/clients").il_badge_color = -1
end if

// Un colore proprio mette in evidenza un riquadro : sfondo, testo e cio che
// ciascuno diventa sotto il puntatore
lnv_tile = uo_tiles.of_tile(/*keys*/ "home/dashboard")
lnv_tile.il_back_color = RGB(/*red*/ 0, /*green*/ 103, /*blue*/ 192)
lnv_tile.il_back_color_hover = RGB(/*red*/ 0, /*green*/ 80, /*blue*/ 150)
lnv_tile.il_text_color = RGB(/*red*/ 255, /*green*/ 255, /*blue*/ 255)

// Riquadro ANIMATO: ogni facciata aggiunta scorre a turno sul riquadro. Una
// facciata si aggiunge dal COMPONENTE, all indirizzo del riquadro
uo_tiles.of_clear_live_items(/*keys*/ "home/agenda")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*text*/ "3 appuntamenti oggi")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*text*/ "Riunione di squadra alle 14:00")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*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_tiles.of_tile(/*keys*/ "home/dashboard").is_live_text = "[b]48[/b] ordini di oggi"

Gruppi comprimibili #

// Local variables
n_pbt_tilesbox_group lnv_admin

// Un gruppo e i suoi due riquadri, poi un handle sul gruppo
uo_tiles.of_add_group(/*key*/ "admin", /*title*/ "Amministrazione")
uo_tiles.of_add_tile(/*keys*/ "admin/users",  /*text*/ "Utenti", /*image*/ "mono:img\users.svg", /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "admin/params", /*text*/ "Impostazioni", /*image*/ "mono:img\gear.svg",  /*size*/ "medium")
lnv_admin = uo_tiles.of_group(/*key*/ "admin")

// 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_profile = "ADMIN")

// event ue_group_toggled di uo_tiles
if as_key = "admin" and not ab_collapsed then of_trace("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_tiles.ib_show_group_headers = false
uo_tiles.of_add_group(/*key*/ "all", /*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. Dalla tastiera, il riquadro con il focus avanza o arretra di una posizione con Ctrl+Sinistra/Destra (nel senso di lettura: invertito da destra a sinistra) e passa al gruppo precedente o successivo con Ctrl+Su/Giù — stesso ue_tile_moved, stessi rifiuti (chiave già presa, gruppo disattivato o compresso). Il tasto Tab si ferma una sola volta per gruppo: le frecce percorrono i riquadri.

// Lasciare all'utente riordinare i riquadri : false per impostazione predefinita
uo_tiles.ib_reorderable = true

// event ue_tile_moved di uo_tiles
// as_keys = da dove viene, as_to_key = dove va, al_index = posizione
n_pbt_utils lnv_utils   // autoinstantiate : niente da creare, niente da distruggere
if lnv_utils.of_parent(/*keys*/ as_keys) <> as_to_key then
    of_trace("Riquadro " + lnv_utils.of_leaf(/*keys*/ as_keys) + " spostato da " + lnv_utils.of_parent(/*keys*/ as_keys) + " a " + as_to_key)
end if

// event ue_layout_changed di uo_tiles: conservare la disposizione scelta
is_layout_json = as_layout_json

// All'apertura successiva: ripristinare la schermata come l'utente l'aveva sistemata
if is_layout_json <> "" then uo_tiles.of_set_layout(/*state_json*/ is_layout_json)

Per bloccare la schermata, basta disattivare la riorganizzazione:

// Freeze the screen : the tiles stay where they are
uo_tiles.ib_reorderable = false

Riorganizzare dal codice #

// Mettere il riquadro "help" in testa al suo gruppo (posizioni contate a partire da 1)
uo_tiles.of_move_tile(/*keys*/ "home/help", /*index*/ 1)

// Inserire un nuovo riquadro in seconda posizione
uo_tiles.of_insert_tile(/*keys*/ "home/quotes", /*text*/ "Preventivi", /*index*/ 2)

// Rimuovere un riquadro senza toccare il resto
uo_tiles.of_remove_tile(/*keys*/ "home/help")

// Ogni chiamata restituisce -5 se l indirizzo non nomina nulla (o, all inserimento, una chiave gia presa)

Reagire al clic destro #

// event ue_tile_context di uo_tiles: (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_target_group = lnv_utils.of_parent(/*keys*/ as_keys)
is_target_tile = lnv_utils.of_leaf(/*keys*/ as_keys)
of_open_tile_menu(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.