carousel — u_pbt_carousel #

← Riferimento dei componenti · Sommario della guida

carousel fa scorrere degli elementi di cui uno solo è davanti: il Cover Flow di iTunes — l'elemento corrente di fronte, i suoi vicini inclinati in prospettiva che si sovrappongono, un riflesso sotto di essi —, una striscia piatta dove più elementi si vedono interi, una pila di schede, o un banner a tutta superficie che mostra un elemento alla volta. Ogni elemento è un'immagine, un testo formattato o una scheda (immagine, titolo, sottotitolo, corpo scritto da un modello, etichette, badge). L'utente clicca un vicino, scorre con inerzia, gira la rotellina, digita le prime lettere di un titolo o usa la tastiera; ue_current_changed vi dice quale elemento è davanti. Il carosello si riempie a mano o da un DataStore, e può avanzare da solo, con un pulsante PAUSA.

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

In breve #

Avvio rapido #

// Three album covers : a key, a title, a picture
uo_covers.of_add_item(/*key*/ "c1", /*title*/ "Northern Lights", /*image*/ "img\packimages.dll:SVG/COVERS/COVER-01")
uo_covers.of_add_item(/*key*/ "c2", /*title*/ "Blue Hour", /*image*/ "img\packimages.dll:SVG/COVERS/COVER-02")
uo_covers.of_add_item(/*key*/ "c3", /*title*/ "Evergreen", /*image*/ "img\packimages.dll:SVG/COVERS/COVER-03")

// A reflection under the covers, as on a glossy floor
uo_covers.ib_reflection = true

// event ue_current_changed of uo_covers : (string as_from_key, string as_key)
// The album now in front, in the title of the window ("" : the carousel is empty)
if as_key <> "" then Parent.Title = this.of_item(/*key*/ as_key).is_title

Quattro disposizioni, tre facce #

is_style sceglie la disposizione: STYLE_COVERFLOW (predefinito) mette l'elemento corrente di fronte e inclina i suoi vicini in prospettiva, sovrapposti, distribuiti sulla larghezza disponibile e più scuri con la distanza (ii_angle, ii_spacing, ib_shade); STYLE_CAROUSEL allinea una striscia piatta dove più elementi si vedono interi; STYLE_STACK impila delle schede — la corrente davanti, le successive dietro di essa, le precedenti spostate di lato; STYLE_HERO mostra un solo elemento su tutta la superficie, il successivo che scivola o appare in dissolvenza (is_transition): il banner di un cruscotto. Un riquadro mantiene una proporzione (is_item_ratio; vuoto: 1:1 per immagini, 3:4 per schede, 16:9 per testi) e il contenuto di una scheda o di un testo segue la sua dimensione, tra un minimo leggibile e un massimo. ib_reflection mette un riflesso sotto gli elementi, ii_item_width e ii_item_height fissano la dimensione al pixel.

Perché delle facce piuttosto che dei componenti nel carosello? Ogni componente della libreria è un controllo a sé stante, con la propria pagina web (un WebView2): non può stare nella pagina di un altro. Il carosello disegna quindi da sé ciò che mostrerebbero un'immagine, uno statictext o una scheda del kanban — sono le tre facce di uno stesso elemento, e mille elementi costano un solo controllo. is_item_style sceglie la faccia di tutti gli elementi, is_style di un elemento sceglie la sua (vuoto: segue il carosello). Con ITEM_AUTO (predefinito), la faccia si deduce da ciò che l'elemento porta:

• un modello di scheda impostato (is_card_template), o delle etichette, o insieme un'immagine e un testo → una scheda;
• un'immagine → un'immagine, che riempie il riquadro (is_fit); il suo titolo e il suo sottotitolo diventano la didascalia subito sotto, il suo badge si posa sul suo angolo;
• un testo solo → un testo: testo formattato con tag su un pannello a tema, come uno statictext; una zona [action=x] solleva ue_action_clicked;
• nient'altro che un titolo → una scheda.

of_item(key).of_face() dice la faccia scelta. Un'immagine è un file della postazione, una risorsa file.dll:nome, un glifo mono: o tint: disegnato nel tema, o un indirizzo https://; un indirizzo http:// è rifiutato e solleva ue_image_failed con REASON_INSECURE, un file mancante con REASON_NOT_FOUND.

// The covers as a pile of cards, the whole picture in each tile
uo_covers.is_style = u_pbt_carousel.STYLE_STACK
uo_covers.is_fit = u_pbt_carousel.FIT_CONTAIN

// This item is a card, whatever it holds
uo_covers.of_item(/*key*/ "c2").is_style = u_pbt_carousel.ITEM_CARD

Una fila allineata all'inizio #

Su una striscia piatta (STYLE_CAROUSEL), is_align = ALIGN_START dà la fila di un servizio video: gli elementi partono dal bordo d'inizio (a destra nella lettura da destra a sinistra), tutti interi e piatti, e l'ultima schermata è piena — nessun vuoto dopo l'ultimo elemento; un elemento tagliato da un bordo invita a scorrere. L'elemento corrente non è più al centro: è quello che l'utente ha scelto, sempre intero sullo schermo. Le frecce e Pag su / Pag giù avanzano di una schermata (gli elementi che mostra interi) e l'elemento corrente diventa il primo che la schermata ha portato; i tasti freccia avanzano di un elemento e fanno scorrere solo quanto serve per tenerlo intero; la rotellina e il trascinamento scorrono e si posano su un elemento intero, l'elemento corrente segue solo se stava per uscire; un clic su un elemento intero lo rende corrente e solleva ue_item_clicked. Le frecce stanno nei margini, si mostrano solo sotto il puntatore o con la tastiera, e spariscono a un'estremità. I punti contano le schermate (un punto è un posto dove la striscia può posarsi); il contatore conta sempre gli elementi. La riproduzione automatica avanza di una schermata e, alla fine, la prima schermata torna dal lato. Con ib_loop, la fila gira quando è abbastanza lunga da fare il giro dello schermo (circa tre elementi in più di quelli che mostra). ALIGN_START non ha effetto sulle altre disposizioni.

// The row of a video service : the covers from the start edge, a screen at a time
uo_covers.is_style = u_pbt_carousel.STYLE_CAROUSEL
uo_covers.is_align = u_pbt_carousel.ALIGN_START

// Small covers : the row holds several screens
uo_covers.ii_item_height = 150

L'elemento davanti #

L'elemento corrente è quello davanti; of_current_key() ne legge la chiave in diretta. Un clic su un vicino lo porta davanti; un clic sull'elemento davanti solleva ue_item_clicked, un doppio clic (o Invio) ue_item_opened. Un cambiamento dell'utente — clic, tastiera, rotellina, scorrimento, punto, freccia, riproduzione automatica — e un cambiamento del vostro codice (of_select_item, of_next, of_previous) sollevano lo stesso ue_current_changed, come SelectItem solleva l'evento del clic. Con ib_veto_changes, ue_current_changing è posto prima, nei due casi: restituire FALSE lascia l'elemento davanti, e of_select_item restituisce allora -4. ue_current_changed parte anche quando l'elemento davanti se ne va (nascosto, rimosso: il più vicino prende il suo posto) e quando il primo elemento arriva in un carosello vuoto (as_from_key vuoto). Un ordine del vostro codice dentro ue_current_changing (un altro elemento selezionato) prevale: la risposta che segue non cambia più nulla. of_select_row porta davanti l'elemento di una riga e of_current_row legge la riga dell'elemento davanti; con ib_sync_row, il DataWindow dato a of_from_datastore segue l'elemento davanti — il master-detail di un DataWindow.

Un elemento disattivato (ib_enabled = false) resta al suo posto, ma l'utente non può né portarlo davanti né cliccarlo: la tastiera, la rotellina, Pag su / Pag giù, la barra di scorrimento e un lancio lo saltano; il vostro codice lo seleziona comunque. Un elemento nascosto (ib_visible = false) esce dal carosello mantenendo la sua chiave e il suo posto. Con ib_loop (almeno tre elementi), il primo segue l'ultimo. Un doppio clic su un vicino lo porta davanti e si ferma lì: né ue_item_clicked né ue_item_opened. il_autoplay_ms fa avanzare il carosello da solo, ogni tot millisecondi (almeno 500): un pulsante PAUSA / RIPRODUZIONE compare sotto di esso (ib_autoplay_button) e la pausa dell'utente tiene fino a RIPRODUZIONE (of_pause, of_play, ue_autoplay_changed); si interrompe anche sotto il puntatore, quando la tastiera è nel componente e quando il carosello è nascosto. Alla fine di un carosello che non gira in tondo, il primo elemento ritorna dal lato. Ogni passo passa da ue_current_changing come un gesto: un elemento rifiutato viene saltato, si chiede il successivo. Un lettore di schermo non viene avvisato di ogni passo durante la riproduzione.

Schede e didascalia scritte da un modello #

Una scheda mostra la sua immagine in alto, il suo titolo (is_title), il suo sottotitolo (is_subtitle), il suo corpo (is_text), le sue etichette (is_tags, separate da virgole, colorate da is_tag_tones: New=success|Sale=danger) e un badge (is_badge). Il corpo di tutte le schede può essere scritto da un modello, is_card_template, e la didascalia sotto il carosello da is_caption_template: testo formattato con tag dove {price} è un campo dell'elemento — uno dei vostri (of_set_field), una colonna del DataStore da cui proviene, o un campo predefinito (key, title, subtitle, text, image, badge, tags, position, count). {position} e {count} contano gli elementi disegnati, come il contatore. {sold:dd/mm/yyyy hh:mm} scrive una data o una data-ora, {price:#,##0.00} un numero: i formati di visualizzazione di una colonna di DataWindow (mm dopo un'ora = i minuti, [shortdate], [longdate], [time], sezioni positivo;negativo;zero), nella lingua di visualizzazione — un valore che il formato non sa scrivere è mostrato così com'è. {?x}…{/x} mantiene un pezzo quando il campo dice qualcosa, {!x}…{/x} quando non dice nulla, {{ }} sono parentesi graffe. Un valore è mostrato così com'è, mai letto come tag; {x:raw} lo mantiene come tag — riservatelo ai vostri campi: su una colonna di database leggerebbe il dato come tag, zone d'azione comprese. {title}, {subtitle}, {text} e {badge} scritti dal vostro codice sono tag, come nella didascalia; letti da una colonna, testo.

// A price, a field of our own, then the body of every card
uo_shop.of_set_field(/*key*/ "p1", /*field*/ "price", /*value*/ "$12.90")
uo_shop.is_card_template = "{?price}From [b]{price}[/b]{/price}{!price}Price on request{/price}"

// Under the carousel : the place of the item in front, then its title
uo_shop.is_caption_template = "{position} / {count} - [b]{title}[/b]"

Da un DataStore #

of_from_datastore fa un elemento di ogni riga di un DataStore, di un DataWindow o di un DataWindowChild — la stessa chiamata. La sua chiave è il RowID della riga — nomina la sua riga finché il DataStore non viene né svuotato né riletto (Reset, Retrieve e ImportString ridanno i RowID 1, 2, 3), e of_item(key).of_row() la ritrova — o il valore della colonna ROLE_KEY, la chiave da dare non appena aggiornate. Una riga la cui chiave è vuota, non valida, già vista o tenuta da un elemento aggiunto a mano non viene caricata: la chiamata restituisce 0 e of_get_last_error la nomina — date ai vostri elementi a mano chiavi che non siano numeri. Una colonna svolge un ruolo quando ne porta il nome (key, title, subtitle, text, image, badge, tags, color) o quando of_map lo dice; la colonna ROLE_COLOR (un RGB() o #rrggbb) colora la banda di una scheda. of_map e of_reload_row aggiornano gli elementi sul posto (indicatori, campi, handle e posto restano). Anche un secondo caricamento, con ROLE_KEY: un elemento la cui chiave torna mantiene i suoi indicatori, i suoi campi e il suo handle. Senza ROLE_KEY, un secondo caricamento è una nuova epoca: un RowID che torna può nominare un altro record, ogni elemento delle righe viene rifatto (nulla è ereditato, gli handle dei vecchi sono liberati) e, se la chiave davanti torna, ue_current_changed lo dice con as_from_key = as_key. In ogni caso gli elementi prendono l'ordine delle righe (un of_move_item non sopravvive a un caricamento), quelli delle righe sparite se ne vanno, quelli aggiunti a mano restano, dopo le righe; un elemento di riga rimosso con of_remove_item torna con la sua riga — nascondetelo piuttosto (ib_visible). Le date sono lette nell'ordine regionale della postazione, i numeri si scrivono con il punto, i valori CHAR senza il loro riempimento, al caricamento come dopo of_reload_row. Ciò che una colonna dà è testo, mai tag — un [action=x] venuto dal database non è cliccabile —, e un'immagine di una colonna non va mai a cercare un percorso di rete (\\server\condivisione: ue_image_failed con REASON_UNC). Quando la colonna ROLE_KEY di una riga riletta cambia, l'elemento prende la nuova chiave: l'handle della vecchia viene liberato. Tutte le colonne sono campi dei modelli.

// The rows of the albums : columns named title and subtitle play their role
ids_albums.Retrieve()

// The picture is in a column with another name
uo_covers.of_map(/*role*/ u_pbt_carousel.ROLE_IMAGE, /*column*/ "cover_file")

// One item per row, its key the RowID of the row
uo_covers.of_from_datastore(/*ads*/ ids_albums)

// Master-detail : the DataWindow follows the item in front, and the carousel reads its rows
uo_covers.ib_sync_row = true
uo_covers.of_from_datastore(/*adw*/ dw_albums)

// event rowfocuschanged of dw_albums : the item of the row comes in front
uo_covers.of_select_row(/*row*/ currentrow)

Proprietà #

Proprietà di un elemento — n_pbt_carousel_item #

Il suo handle, tramite of_item(key). Una lettura chiede al carosello com'è ora.

Tre letture dell'handle, in sola lettura: of_position() restituisce la posizione dell'elemento a partire da 1, of_row() il numero della sua riga nel DataStore (0 per un elemento aggiunto a mano), of_face() la faccia scelta. Un elemento si sposta con of_move_item del carosello.

Metodi #

Eventi #

Tastiera e mouse #

• Clic su un vicino: viene davanti; sull'elemento davanti: ue_item_clicked; doppio clic: ue_item_opened (su un vicino: viene davanti, nient'altro); clic destro: ue_item_rclicked.
• Trascinare o scorrere: la striscia segue il puntatore; al rilascio, la sua velocità la porta qualche elemento più in là. Senza ib_loop, i bordi sono elastici. Rilasciato fuori dal carosello, il trascinamento termina comunque.
• Rotellina: segue la sua velocità — uno scatto, un elemento; un grande giro, diversi; un touchpad somma i suoi piccoli passi.
• Sinistra / Destra: l'elemento precedente, il successivo — invertite in un'applicazione da destra a sinistra; Su / Giù: lo stesso; Inizio / Fine: il primo, l'ultimo; Pag su / Pag giù: di tanti elementi quanti la scena ne mostra. Gli elementi disattivati sono saltati, ovunque.
• Le prime lettere di un titolo lo portano davanti (maiuscole e accenti ignorati); la stessa lettera di nuovo va al successivo che inizia con essa.
• Invio: ue_item_opened; Spazio: ue_item_clicked; tasto Menu o Maiusc + F10: ue_item_rclicked sull'elemento davanti.
• Le frecce laterali (ib_arrows, nelle loro scanalature: non coprono nessun riquadro), i punti e la barra di scorrimento (is_indicator) si cliccano; la barra si trascina anche. Il pulsante PAUSA / RIPRODUZIONE (ib_autoplay_button) si clicca o si raggiunge con la tastiera.
• Il carosello è una fermata del tasto Tab (due con il pulsante PAUSA); un anello dell'accento circonda l'elemento davanti finché la tastiera è lì.

Esempi #

Una vetrina di prodotti #

// A flat strip : several products in full, a counter under it
uo_shop.is_style = u_pbt_carousel.STYLE_CAROUSEL
uo_shop.is_indicator = u_pbt_carousel.INDICATOR_COUNTER

// A product : a picture and a title, then a badge and tags (it becomes a card)
uo_shop.of_add_item(/*key*/ "p1", /*title*/ "Northern Lights", /*image*/ "img\packimages.dll:SVG/COVERS/COVER-01")
uo_shop.of_item(/*key*/ "p1").is_badge = "New"
uo_shop.of_item(/*key*/ "p1").is_tags = "Vinyl, Sale"

// The tone of each tag, and the price in the body of every card
uo_shop.is_tag_tones = "Vinyl=info|Sale=danger"
uo_shop.of_set_field(/*key*/ "p1", /*field*/ "price", /*value*/ "$12.90")
uo_shop.is_card_template = "From [b]{price}[/b]"

Chiedere prima di cambiare elemento #

// Once : ask before the item in front changes
uo_covers.ib_veto_changes = true

// event ue_current_changing of uo_covers : not while the form beside it is not saved
if ib_unsaved then return false
return true

Aprire un elemento di un DataStore nella vostra finestra #

// Local variables
long ll_row

// event ue_item_opened of uo_covers : the row of the item, edited in a RESPONSE window (the code waits for it)
ll_row = uo_covers.of_item(/*key*/ as_key).of_row()
OpenWithParm(w_album_edit, ll_row)

// The row may have changed : the item follows it
uo_covers.of_reload_row(/*row*/ ll_row)

Notizie che scorrono da sole #

// A banner : one item on the whole surface
uo_news.is_style = u_pbt_carousel.STYLE_HERO

// Text items : rich text on a themed panel, with an [action] zone
uo_news.of_add_item(/*key*/ "n1", /*title*/ "Release")
uo_news.of_item(/*key*/ "n1").is_text = "[b]Version 5.0[/b] is out. [action=notes]Read the notes[/action]"
uo_news.of_add_item(/*key*/ "n2", /*title*/ "Webinar")
uo_news.of_item(/*key*/ "n2").is_text = "[b]Webinar[/b] on Thursday at 10:00."
uo_news.of_add_item(/*key*/ "n3", /*title*/ "Support")
uo_news.of_item(/*key*/ "n3").is_text = "[b]Support[/b] answers within one day."

// A new one every 5 seconds, faded in, the first again after the last :
// a PAUSE button shows under the banner
uo_news.is_transition = u_pbt_carousel.TRANSITION_FADE
uo_news.il_autoplay_ms = 5000
uo_news.ib_loop = true

// event ue_action_clicked of uo_news : (string as_key, string as_action)
// The zone [action=notes] of the first item opens the release notes
if as_action = "notes" then Open(w_release_notes)

Un grande catalogo #

// The products : one row = one item, its key the product code
ids_products.Retrieve()
uo_shop.of_map(/*role*/ u_pbt_carousel.ROLE_KEY, /*column*/ "code")
uo_shop.of_from_datastore(/*ads*/ ids_products)

// Only the tiles near the one in front are drawn : thousands of rows cost nothing.
// Beyond 12 items a scrollbar replaces the dots ; the user types a name to reach it
uo_shop.of_select_item(/*key*/ "P250")

Buone pratiche #

• Immagini delle stesse proporzioni: il Cover Flow si legge con un colpo d'occhio quando i riquadri hanno la stessa forma; is_item_ratio la fissa, FIT_CONTAIN mostra l'immagine intera.
• Poco testo per faccia: una scheda si legge in due righe, il dettaglio va nella vostra finestra (ue_item_opened).
• Una riproduzione automatica lenta (da quattro a sei secondi), con il suo pulsante PAUSA: chi legge deve poter fermare ciò che si muove.
• Chiavi che non siano numeri per i vostri elementi a mano, in un carosello alimentato da un DataStore: un elemento di chiave 12 impedisce alla riga di RowID 12 di essere caricata (of_get_last_error lo dice).
• ROLE_KEY non appena aggiornate un DataStore (Retrieve, Reset): senza, un ricaricamento rifà ogni elemento, perché un RowID che torna può nominare un altro record.
• Molti elementi non costano nulla: solo quelli alla portata dell'elemento davanti sono disegnati, e un'immagine si carica solo quando si avvicina — l'utente raggiunge un titolo digitandolo.

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.

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.

← Riferimento dei componenti · Sommario della guida