carousel — u_pbt_carousel #

← Référence des composants · Sommaire du guide

carousel fait défiler des éléments dont un seul est devant : le Cover Flow d'iTunes — l'élément courant de face, ses voisins inclinés en perspective qui se recouvrent, un reflet sous eux —, une bande plate où plusieurs éléments se voient entiers, une pile de cartes, ou un bandeau plein cadre qui montre un élément à la fois. Chaque élément est une image, un texte riche ou une carte (image, titre, sous-titre, corps écrit par un modèle, étiquettes, badge). L'utilisateur clique un voisin, balaie avec inertie, tourne la molette, tape les premières lettres d'un titre ou se sert du clavier ; ue_current_changed vous dit qui est devant. Le carrousel se remplit à la main ou depuis un DataStore, et peut avancer seul, avec un bouton PAUSE.

▶ Le voir en vrai — Application de démonstration, tuile Carousel : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// 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

Quatre dispositions, trois faces #

is_style choisit la disposition : STYLE_COVERFLOW (par défaut) met l'élément courant de face et incline ses voisins en perspective, qui se recouvrent, s'étalent sur la largeur disponible et s'assombrissent avec la distance (ii_angle, ii_spacing, ib_shade) ; STYLE_CAROUSEL aligne une bande plate où plusieurs éléments se voient entiers ; STYLE_STACK empile des cartes — le courant devant, les suivants derrière lui, les précédents partis sur le côté ; STYLE_HERO montre un seul élément sur toute la surface, le suivant glissant ou se fondant (is_transition) : le bandeau d'un tableau de bord. Une tuile garde une proportion (is_item_ratio ; vide : 1:1 pour des images, 3:4 pour des cartes, 16:9 pour des textes) et le contenu d'une carte ou d'un texte suit sa taille, entre un plancher lisible et un plafond. ib_reflection pose un reflet sous les éléments, ii_item_width et ii_item_height fixent la taille au pixel près.

Pourquoi des faces plutôt que des composants dans le carrousel ? Chaque composant de la bibliothèque est un contrôle à part entière, avec sa propre page web (un WebView2) : il ne peut pas se loger dans la page d'un autre. Le carrousel dessine donc lui-même ce que montreraient une image, un statictext ou une carte du kanban — ce sont les trois faces d'un même élément, et mille éléments ne coûtent qu'un seul contrôle. is_item_style choisit la face de tous les éléments, is_style d'un élément choisit la sienne (vide : il suit le carrousel). Avec ITEM_AUTO (par défaut), la face se déduit de ce que l'élément porte :

• un modèle de carte posé (is_card_template), ou des étiquettes, ou à la fois une image et un texte → une carte ;
• une image → une image, qui remplit la tuile (is_fit) ; son titre et son sous-titre deviennent la légende juste sous elle, son badge se pose sur son coin ;
• un texte seul → un texte : du balisage riche sur un panneau au thème, comme un statictext ; une zone [action=x] lève ue_action_clicked ;
• rien d'autre qu'un titre → une carte.

of_item(key).of_face() dit la face retenue. Une image est un fichier du poste, une ressource fichier.dll:nom, un glyphe mono: ou tint: dessiné au thème, ou une adresse https:// ; une adresse http:// est refusée et lève ue_image_failed avec REASON_INSECURE, un fichier absent avec 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

Une rangée alignée au début #

Sur une bande plate (STYLE_CAROUSEL), is_align = ALIGN_START donne la rangée d'un service vidéo : les éléments partent du bord de début (à droite en lecture de droite à gauche), tous entiers et à plat, et le dernier écran est plein — aucun vide après le dernier élément ; un élément coupé par un bord invite à défiler. L'élément courant n'est plus au milieu : c'est celui que l'utilisateur a choisi, toujours entier à l'écran. Les flèches et Page préc. / Page suiv. avancent d'un écran (les éléments qu'il montre entiers) et l'élément courant devient le premier que l'écran a amené ; les touches fléchées avancent d'un élément et ne font défiler que ce qu'il faut pour le garder entier ; la molette et le glisser défilent et se posent sur un élément entier, l'élément courant ne suivant que s'il allait sortir ; un clic sur un élément entier le rend courant et lève ue_item_clicked. Les flèches vivent dans les marges, ne se montrent que sous le pointeur ou au clavier, et disparaissent à un bout. Les points comptent les écrans (un point est un endroit où la bande peut se poser) ; le compteur compte toujours les éléments. La lecture automatique avance d'un écran et, au bout, le premier écran revient par le côté. Avec ib_loop, la rangée tourne quand elle est assez longue pour faire le tour de l'écran (environ trois éléments de plus qu'il n'en montre). ALIGN_START n'a aucun effet sur les autres dispositions.

// 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'élément devant #

L'élément courant est celui qui est devant ; of_current_key() lit sa clé en direct. Un clic sur un voisin l'amène devant ; un clic sur l'élément devant lève ue_item_clicked, un double-clic (ou Entrée) ue_item_opened. Un changement de l'utilisateur — clic, clavier, molette, balayage, point, flèche, lecture automatique — et un changement de votre code (of_select_item, of_next, of_previous) lèvent le même ue_current_changed, comme SelectItem lève l'événement du clic. Avec ib_veto_changes, ue_current_changing est posé avant, aux deux : renvoyer FALSE laisse l'élément devant, et of_select_item rend alors -4. ue_current_changed part aussi quand l'élément devant s'en va (masqué, retiré : le plus proche prend sa place) et quand le premier élément arrive dans un carrousel vide (as_from_key vide). Un ordre de votre code dans ue_current_changing (un autre élément sélectionné) l'emporte : la réponse qui suit ne change plus rien. of_select_row amène devant l'élément d'une ligne et of_current_row lit la ligne de l'élément devant ; avec ib_sync_row, le DataWindow donné à of_from_datastore suit l'élément devant — le maître-détail d'un DataWindow.

Un élément grisé (ib_enabled = false) reste à sa place, mais l'utilisateur ne peut ni l'amener devant ni le cliquer : le clavier, la molette, Page préc. / Page suiv., la barre de défilement et un lancer le sautent ; votre code le sélectionne quand même. Un élément masqué (ib_visible = false) sort du carrousel en gardant sa clé et sa place. Avec ib_loop (trois éléments au moins), le premier suit le dernier. Un double-clic sur un voisin l'amène devant et s'arrête là : ni ue_item_clicked ni ue_item_opened. il_autoplay_ms fait avancer le carrousel seul, tous les tant de millisecondes (500 au moins) : un bouton PAUSE / LECTURE se montre sous lui (ib_autoplay_button) et la pause de l'utilisateur tient jusqu'à LECTURE (of_pause, of_play, ue_autoplay_changed) ; la lecture s'interrompt aussi sous le pointeur, quand le clavier est dans le composant et quand le carrousel est caché. Au bout d'un carrousel qui ne boucle pas, le premier élément revient par le côté. Chaque pas passe par ue_current_changing comme un geste : un élément refusé est sauté, le suivant est demandé. Un lecteur d'écran n'est pas prévenu de chaque pas pendant la lecture.

Cartes et légende écrites par modèle #

Une carte montre son image en haut, son titre (is_title), son sous-titre (is_subtitle), son corps (is_text), ses étiquettes (is_tags, séparées par des virgules, colorées par is_tag_tones : New=success|Sale=danger) et un badge (is_badge). Le corps de toutes les cartes peut s'écrire par un modèle, is_card_template, et la légende sous le carrousel par is_caption_template : du balisage riche où {price} est un champ de l'élément — un des vôtres (of_set_field), une colonne du DataStore d'où il vient, ou un champ intégré (key, title, subtitle, text, image, badge, tags, position, count). {position} et {count} comptent les éléments dessinés, comme le compteur. {sold:dd/mm/yyyy hh:mm} écrit une date ou une date-heure, {price:#,##0.00} un nombre : les formats d'affichage d'une colonne de DataWindow (mm après une heure = les minutes, [shortdate], [longdate], [time], sections positif;négatif;zéro), dans la langue d'affichage — une valeur que le format ne sait pas écrire s'affiche telle quelle. {?x}…{/x} garde un morceau quand le champ dit quelque chose, {!x}…{/x} quand il ne dit rien, {{ }} sont des accolades. Une valeur est affichée telle quelle, jamais lue comme balisage ; {x:raw} la garde comme balisage — réservez-le à vos propres champs : sur une colonne de base de données, il lirait la donnée comme du balisage, zones d'action comprises. {title}, {subtitle}, {text} et {badge} écrits par votre code sont du balisage, comme dans la légende ; lus dans une colonne, du texte.

// 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]"

Depuis un DataStore #

of_from_datastore fait un élément de chaque ligne d'un DataStore, d'un DataWindow ou d'un DataWindowChild — l'appel est le même. Sa clé est le RowID de la ligne — il nomme sa ligne tant que le DataStore n'est ni vidé ni relu (Reset, Retrieve et ImportString redonnent les RowID 1, 2, 3), et of_item(key).of_row() la retrouve — ou la valeur de la colonne ROLE_KEY, la clé à donner dès que vous rafraîchissez. Une ligne dont la clé est vide, invalide, déjà vue ou tenue par un élément ajouté à la main n'est pas chargée : l'appel rend 0 et of_get_last_error la nomme — donnez à vos éléments à la main des clés qui ne sont pas des nombres. Une colonne joue un rôle quand elle en porte le nom (key, title, subtitle, text, image, badge, tags, color) ou quand of_map le dit ; la colonne ROLE_COLOR (un RGB() ou #rrggbb) peint la bande d'une carte. of_map et of_reload_row mettent les éléments à jour en place (drapeaux, champs, poignée et place restent). Un second chargement aussi, avec ROLE_KEY : un élément dont la clé revient garde ses drapeaux, ses champs et sa poignée. Sans ROLE_KEY, un second chargement est une nouvelle époque : un RowID qui revient peut nommer un autre enregistrement, chaque élément des lignes est refait (rien n'est hérité, les poignées des anciens sont libérées) et, si la clé devant revient, ue_current_changed le dit avec as_from_key = as_key. Dans tous les cas, les éléments prennent l'ordre des lignes (un of_move_item ne survit pas à un chargement), ceux des lignes parties s'en vont, ceux ajoutés à la main restent, après les lignes ; un élément de ligne retiré par of_remove_item revient avec sa ligne — masquez-le plutôt (ib_visible). Les dates sont lues dans l'ordre régional du poste, les nombres s'écrivent avec un point, les valeurs CHAR sans leur remplissage, au chargement comme après of_reload_row. Ce qu'une colonne donne est du texte, jamais du balisage — un [action=x] venu de la base n'est pas cliquable —, et une image d'une colonne ne va jamais chercher un chemin réseau (\\serveur\partage : ue_image_failed avec REASON_UNC). Quand la colonne ROLE_KEY d'une ligne relue change, l'élément prend la nouvelle clé : la poignée de l'ancienne est libérée. Toutes les colonnes sont des champs des modèles.

// 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)

Propriétés #

Propriétés d'un élément — n_pbt_carousel_item #

Sa poignée, par of_item(key). Une lecture demande au carrousel ce qu'il en est maintenant.

Trois lectures de la poignée, en lecture seule : of_position() rend la place de l'élément à partir de 1, of_row() le numéro de sa ligne dans le DataStore (0 pour un élément ajouté à la main), of_face() la face retenue. Un élément se déplace par of_move_item du carrousel.

Méthodes #

Événements #

Clavier et souris #

• Clic sur un voisin : il vient devant ; sur l'élément devant : ue_item_clicked ; double-clic : ue_item_opened (sur un voisin : il vient devant, rien d'autre) ; clic droit : ue_item_rclicked.
• Glisser ou balayer : la bande suit le pointeur ; au lâcher, sa vitesse l'emporte quelques éléments plus loin. Sans ib_loop, les bords sont élastiques. Lâché hors du carrousel, le glisser se termine quand même.
• Molette : elle suit sa vitesse — un cran, un élément ; un grand tour, plusieurs ; un pavé tactile cumule ses petits pas.
• Gauche / Droite : l'élément précédent, le suivant — inversées dans une application de droite à gauche ; Haut / Bas : de même ; Début / Fin : le premier, le dernier ; Page préc. / Page suiv. : d'autant d'éléments que la scène en montre. Les éléments grisés sont sautés, partout.
• Les premières lettres d'un titre l'amènent devant (casse et accents ignorés) ; la même lettre encore va au suivant qui commence par elle.
• Entrée : ue_item_opened ; Espace : ue_item_clicked ; touche Menu ou Maj + F10 : ue_item_rclicked sur l'élément devant.
• Les flèches des côtés (ib_arrows, dans leurs gouttières : elles ne couvrent aucune tuile), les points et la barre de défilement (is_indicator) se cliquent ; la barre se glisse aussi. Le bouton PAUSE / LECTURE (ib_autoplay_button) se clique ou se prend au clavier.
• Le carrousel est un arrêt de la touche Tab (deux avec le bouton PAUSE) ; un anneau de l'accent entoure l'élément devant tant que le clavier y est.

Exemples #

Une vitrine de produits #

// 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]"

Demander avant de changer d'élément #

// 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

Ouvrir un élément d'un DataStore dans votre fenêtre #

// 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)

Des nouvelles qui défilent seules #

// 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 grand catalogue #

// 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")

Bonnes pratiques #

• Des images de mêmes proportions : le Cover Flow se lit d'un coup d'œil quand les tuiles ont la même forme ; is_item_ratio la fixe, FIT_CONTAIN montre l'image entière.
• Peu de texte par face : une carte se lit en deux lignes, le détail va dans votre fenêtre (ue_item_opened).
• Une lecture automatique lente (quatre à six secondes), avec son bouton PAUSE : qui lit doit pouvoir arrêter ce qui bouge.
• Des clés qui ne sont pas des nombres pour vos éléments à la main, dans un carrousel alimenté par un DataStore : un élément de clé 12 empêche la ligne de RowID 12 d'être chargée (of_get_last_error le dit).
• ROLE_KEY dès que vous rafraîchissez un DataStore (Retrieve, Reset) : sans lui, un rechargement refait chaque élément, car un RowID qui revient peut nommer un autre enregistrement.
• Beaucoup d'éléments ne coûtent rien : seuls ceux à portée de l'élément devant sont dessinés, et une image ne se charge que lorsqu'elle approche — l'utilisateur atteint un titre en le tapant.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide