carousel — u_pbt_carousel #

← Component reference · Guide contents

carousel leafs through items, only one of which is in front: the Cover Flow of iTunes — the current item face on, its neighbours turned in perspective and overlapping, a reflection under them —, a flat strip where several items show in full, a stack of cards, or a full-surface banner that shows one item at a time. Each item is a picture, a rich text or a card (picture, title, subtitle, body written by a template, tags, badge). The user clicks a neighbour, swipes with inertia, turns the wheel, types the first letters of a title or uses the keyboard; ue_current_changed tells you which item is in front. The carousel is filled by hand or from a DataStore, and can move on by itself, with a PAUSE button.

▶ See it live — Demo application, Carousel tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

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

Four layouts, three faces #

is_style chooses the layout: STYLE_COVERFLOW (the default) puts the current item face on and turns its neighbours in perspective, overlapping, spread over the width available and darker with the distance (ii_angle, ii_spacing, ib_shade); STYLE_CAROUSEL lines up a flat strip where several items show in full; STYLE_STACK piles up cards — the current one in front, the next ones behind it, the previous ones gone to the side; STYLE_HERO shows one item on the whole surface, the next one sliding or fading in (is_transition): the banner of a dashboard. A tile keeps a proportion (is_item_ratio; empty: 1:1 for pictures, 3:4 for cards, 16:9 for texts) and the content of a card or a text follows its size, between a readable floor and a ceiling. ib_reflection puts a reflection under the items, ii_item_width and ii_item_height set the size to the pixel.

Why faces rather than components inside the carousel? Every component of the library is a control of its own, with its own web page (a WebView2): it cannot sit inside the page of another one. So the carousel draws by itself what a picture, a statictext or a kanban card would show — these are the three faces of one item, and a thousand items cost one single control. is_item_style chooses the face of every item, is_style of an item chooses its own (empty: it follows the carousel). With ITEM_AUTO (the default), the face follows from what the item holds:

• a card template set (is_card_template), or tags, or both a picture and a text → a card;
• a picture → an image, which fills the tile (is_fit); its title and its subtitle become the caption right under it, its badge stands over its corner;
• a text alone → a text: rich text markup on a themed panel, like a statictext; an [action=x] zone raises ue_action_clicked;
• nothing but a title → a card.

of_item(key).of_face() tells the face chosen. A picture is a file of the workstation, a resource file.dll:name, a mono: or tint: glyph drawn in the theme, or an https:// address; an http:// address is refused and raises ue_image_failed with REASON_INSECURE, a missing file with 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

A row aligned at its start #

On a flat strip (STYLE_CAROUSEL), is_align = ALIGN_START gives the row of a video service: the items stand from the start edge (the right one, right to left), every one whole and level, and the last screen is full — no empty room after the last item; an item cut by an edge invites to scroll. The current item is no longer in the middle: it is the one the user chose, always whole on the screen. The arrows and Page Up / Page Down move a screen (the items it shows whole) and the current item becomes the first one the screen brought; the arrow keys move one item and scroll just enough to keep it whole; the wheel and a swipe scroll and rest on a whole item, the current item following only when it would leave; a click on a whole item makes it current and raises ue_item_clicked. The arrows live in the margins, show only under the pointer or with the keyboard, and are gone at an end. The dots count screens (a dot is a place the strip can rest on); the counter still counts items. The autoplay moves a screen and, at the end, the first screen comes back from the side. With ib_loop, the row goes round when it is long enough to go round the screen (about three items more than it shows). ALIGN_START has no effect on the other layouts.

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

The item in front #

The current item is the one in front; of_current_key() reads its key live. A click on a neighbour brings it in front; a click on the item in front raises ue_item_clicked, a double click (or Enter) ue_item_opened. A change of the user — click, keyboard, wheel, swipe, dot, arrow, autoplay — and a change of your code (of_select_item, of_next, of_previous) raise the same ue_current_changed, as SelectItem raises the event of the click. With ib_veto_changes, ue_current_changing is asked first, in both cases: returning FALSE leaves the item in front, and of_select_item then returns -4. ue_current_changed is raised too when the item in front leaves (hidden, removed: the nearest takes its place) and when the first item arrives in an empty carousel (as_from_key empty). An order of your code inside ue_current_changing (another item selected) wins: the answer that follows changes nothing any more. of_select_row brings the item of a row in front and of_current_row reads the row of the item in front; with ib_sync_row, the DataWindow given to of_from_datastore follows the item in front — the master-detail of a DataWindow.

A greyed item (ib_enabled = false) stays in its place, but the user can neither bring it in front nor click it: the keyboard, the wheel, Page Up / Page Down, the scrollbar and a throw jump over it; your code still selects it. A hidden item (ib_visible = false) leaves the carousel and keeps its key and its place. With ib_loop (three items at least), the first comes after the last. A double click on a neighbour brings it in front and stops there: neither ue_item_clicked nor ue_item_opened. il_autoplay_ms makes the carousel move on by itself, every so many milliseconds (500 at least): a PAUSE / PLAY button shows under it (ib_autoplay_button) and the user's pause holds until PLAY (of_pause, of_play, ue_autoplay_changed); it also stops for a moment under the pointer, while the keyboard is in the component and while the carousel is hidden. At the end of a carousel that does not loop, the first item comes back from the side. Every step goes through ue_current_changing like a gesture: a refused item is skipped, the next one is asked. A screen reader is not told every step while it plays.

Cards and caption written by template #

A card shows its picture on top, its title (is_title), its subtitle (is_subtitle), its body (is_text), its tags (is_tags, separated by commas, coloured by is_tag_tones: New=success|Sale=danger) and a badge (is_badge). The body of every card can be written by a template, is_card_template, and the caption under the carousel by is_caption_template: rich text markup where {price} is a field of the item — one of yours (of_set_field), a column of the DataStore it came from, or a built-in field (key, title, subtitle, text, image, badge, tags, position, count). {position} and {count} count the items drawn, as the counter does. {sold:dd/mm/yyyy hh:mm} writes a date or a date-time, {price:#,##0.00} a number: the display formats of a DataWindow column (mm after an hour = the minutes, [shortdate], [longdate], [time], sections positive;negative;zero), in the display language — a value the format cannot write is shown as it is. {?x}…{/x} keeps a piece when the field says something, {!x}…{/x} when it says nothing, {{ }} are braces. A value is shown as it is, never read as markup; {x:raw} keeps it as markup — keep it for your own fields: on a database column it would read the data as markup, action zones included. {title}, {subtitle}, {text} and {badge} written by your code are markup, as in the caption; read from a column, text.

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

From a DataStore #

of_from_datastore makes one item of each row of a DataStore, a DataWindow or a DataWindowChild — the same call. Its key is the RowID of the row — it names its row as long as the DataStore is neither emptied nor read again (Reset, Retrieve and ImportString give the RowIDs 1, 2, 3 again), and of_item(key).of_row() finds it — or the value of the ROLE_KEY column, the key to give as soon as you refresh. A row whose key is empty, not valid, already met or held by an item added by hand is not loaded: the call returns 0 and of_get_last_error names it — give your hand items keys that are not numbers. A column plays a role when it is named like it (key, title, subtitle, text, image, badge, tags, color) or when of_map says so; the ROLE_COLOR column (an RGB() or #rrggbb) paints the stripe of a card. of_map and of_reload_row update the items in place (flags, fields, handle and place stay). A second load too, with ROLE_KEY: an item whose key comes back keeps its flags, its fields and its handle. Without ROLE_KEY, a second load is a new epoch: a RowID that comes back may name another record, every item of the rows is made anew (nothing is inherited, the handles of the old ones are freed) and, if the key in front comes back, ue_current_changed says it with as_from_key = as_key. Either way, the items take the order of the rows (an of_move_item does not survive a load), the items of the rows gone leave, those added by hand stay, after the rows; an item of a row removed by of_remove_item comes back with its row — hide it instead (ib_visible). Dates are read in the regional order of the workstation, numbers are written with a point, CHAR values without their padding, at a load as after of_reload_row. What a column gives is text, never markup — an [action=x] coming from the database is not clickable —, and a picture of a column never reaches a network path (\\server\share: ue_image_failed with REASON_UNC). When the ROLE_KEY column of a reloaded row changed, the item takes the new key: the handle of the old one is freed. Every column is a field of the templates.

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

Properties #

Properties of an item — n_pbt_carousel_item #

Its handle, through of_item(key). A read asks the carousel what it is now.

Three reads of the handle, read only: of_position() returns the place of the item counted from 1, of_row() the number of its row in the DataStore (0 for an item added by hand), of_face() the face chosen. An item moves through of_move_item of the carousel.

Methods #

Events #

Keyboard and mouse #

• Click on a neighbour: it comes in front; on the item in front: ue_item_clicked; double click: ue_item_opened (on a neighbour: it comes in front, nothing else); right click: ue_item_rclicked.
• Drag or swipe: the strip follows the pointer; when let go, its speed carries it a few items further. Without ib_loop, the ends are elastic. Let go outside the carousel, the drag still ends.
• Wheel: it follows its speed — a notch, one item; a big turn, several; a touchpad adds its small steps up.
• Left / Right: the previous item, the next one — inverted in a right-to-left application; Up / Down: the same; Home / End: the first, the last; Page Up / Page Down: by as many items as the stage shows. Greyed items are skipped, everywhere.
• The first letters of a title bring it in front (case and accents ignored); the same letter again goes to the next one that starts with it.
• Enter: ue_item_opened; Space: ue_item_clicked; context-menu key or Shift + F10: ue_item_rclicked on the item in front.
• The side arrows (ib_arrows, in their gutters: they cover no tile), the dots and the scrollbar (is_indicator) are clicked; the scrollbar is dragged too. The PAUSE / PLAY button (ib_autoplay_button) is clicked or reached with the keyboard.
• The carousel is one stop of the Tab key (two with the PAUSE button); a ring of the accent surrounds the item in front while the keyboard is in it.

Examples #

A product showcase #

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

Asking before the item changes #

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

Opening an item of a DataStore in your window #

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

News that move on by themselves #

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

A large 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")

Good practice #

• Pictures of the same proportions: the Cover Flow reads at a glance when the tiles have the same shape; is_item_ratio sets it, FIT_CONTAIN shows the whole picture.
• Little text per face: a card reads in two lines, the detail goes into your window (ue_item_opened).
• A slow autoplay (four to six seconds), with its PAUSE button: whoever reads must be able to stop what moves.
• Keys that are not numbers for your hand items, in a carousel fed by a DataStore: an item keyed 12 keeps the row of RowID 12 from being loaded (of_get_last_error says it).
• ROLE_KEY as soon as you refresh a DataStore (Retrieve, Reset): without it, a reload makes every item anew, since a RowID that comes back may name another record.
• Many items cost nothing: only those within reach of the item in front are drawn, and a picture is loaded only when it comes near — the user reaches a title by typing it.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents