Carousel — version history

u_pbt_carousel · Introduced in 5.0

Items leafed through like the Cover Flow of iTunes, a flat strip, a stack of cards or a full-surface banner, one of them in front. Introduced in 5.0.

5.0 #

New #

• Four layouts (is_style): the Cover Flow of iTunes (STYLE_COVERFLOW, the default) — the item in front face on, its neighbours turned in perspective and overlapping, spread over the width available and darker with their distance, with an optional reflection (ib_reflection; in a stack, only the card in front shows one, as on a real floor) —, a flat strip where several items show in full (STYLE_CAROUSEL), a stack of cards (STYLE_STACK) and a banner that shows one item on the whole surface (STYLE_HERO), the next one sliding or fading in (is_transition). The turn of the covers (ii_angle), their spacing (ii_spacing) and the shade of the neighbours (ib_shade) are yours to set.
• A tile keeps a proportion (is_item_ratio; by default 1:1 for pictures, 3:4 for cards, 16:9 for texts) whatever the size of the carousel, unless its size is given in pixels (ii_item_width, ii_item_height); the content of a card or a text follows the size of its tile, between a readable floor and a ceiling, and a long title is cut cleanly after two lines.
• Each item is drawn with one of three faces: a picture that fills its tile (is_fit) with its badge over its corner, a rich text on a themed panel with clickable [action=x] zones (ue_action_clicked), or a card with a picture, a title, a subtitle, a body, coloured tags (is_tags, tones given by is_tag_tones) and a badge. is_item_style chooses the face of every item and is_style of an item its own; ITEM_AUTO, the default, decides from what the item holds — a picture stays a picture with a subtitle and a badge —, and the read-only is_face of the item tells the face chosen.
• Items added at the end or at a place counted from 1 (of_add_item, of_insert_item), moved (of_move_item) and removed (of_remove_item, of_clear, of_reset), their handles freed; a key that is empty, holds a / or a |, starts with __ or is already taken is refused with -5. The handle of an item (of_item) writes and reads its title, subtitle, text, picture, badge, tags, face, visibility and greyed state, and reads its place (il_position) and the row number of its DataStore row (il_row), both read only; a tooltip and an accent colour per item.
• Pictures from a file of the workstation, a resource of a DLL, a glyph drawn in the theme or an https:// address, with a themed placeholder while they load and the next ones asked before they come in sight; an http:// address is refused and, like a missing file, reported once by ue_image_failed with its reason (REASON_INSECURE, REASON_NOT_FOUND).
• The item in front changes by a click on a neighbour, a drag or a swipe with inertia (the strip follows the pointer and its speed carries it a few items further, the ends elastic; released outside the carousel, the drag still ends), the wheel (which follows its speed: a notch moves one item, a big turn several), the arrow buttons on the sides (ib_arrows, in gutters that keep them off the tiles), the dots or the scrollbar under it (is_indicator: dots — up to 48 items, the scrollbar beyond —, a scrollbar, a counter 3 / 12, or nothing), the first letters of a title typed on the keyboard — or by the code (of_select_item, of_next, of_previous). Every one of them raises ue_current_changed; with ib_veto_changes, ue_current_changing is asked first and can refuse the change, gestures, autoplay and code alike (of_select_item then returns -4); an order of your code inside ue_current_changing wins over the answer that follows. The read-only is_current_key reads the item in front live. A greyed item is never brought in front by a gesture.
• ue_item_clicked for a click on the item in front (or Space), ue_item_opened for a double click (or Enter) — a double click on a neighbour only brings it in front —, ue_item_rclicked for a right click (or the context-menu key) with its screen position.
• A loop (ib_loop) and an autoplay (il_autoplay_ms) with a PAUSE / PLAY button and the time left to the next item (ib_autoplay_button, of_pause, of_play, the read-only ib_playing, ue_autoplay_changed); the autoplay also stops for a moment under the pointer, while the keyboard is in the carousel and while the carousel is hidden, skips an item ue_current_changing refuses, brings the first item back from the side at the end, and does not announce every step to a screen reader.
• The caption — the title and subtitle of the item in front, underlined with the accent (ib_show_caption) — stands right under the item or over its foot (is_caption_position; none under cards and texts, which already write their title). It and the body of the cards can be written by templates (is_caption_template, is_card_template): fields of your own (of_set_field, of_get_field), the columns of a DataStore, built-in fields such as the place and the count of the items drawn, dates, date-times and numbers written by the display formats of a DataWindow column ({sold:dd/mm/yyyy hh:mm}, {price:#,##0.00}, [shortdate]…) and pieces shown only when a field says something ({?x}…{/x}); a title your code wrote is markup there, as in the caption. The badges that are a number or a date follow a display format too (is_badge_format).
• The carousel is fed from a DataStore, a DataWindow or a DataWindowChild (of_from_datastore): one item per row, its key the RowID of the row or the value of a key column, a column playing a role when it is named like it or when of_map says so (title, subtitle, text, picture, badge, tags, colour), dates read in the regional order of the workstation, numbers written with a point, CHAR values without their padding; what a column holds is shown as text, never as markup, and a picture of a column never reaches a network path (REASON_UNC). A row whose key is empty, not valid, met twice or held by an item added by hand is not loaded, and is_last_error names it; a DataWindow that refuses to share its rows is refused with -5. of_map and of_reload_row update the items in place (flags, fields, handle and place stay), and so does a second load keyed by a column; a second load keyed by the RowID makes every item of the rows anew, since a RowID that comes back after a Reset or a Retrieve may name another record — nothing of the old item is inherited, and ue_current_changed says it when the key in front now names another record. The items take the order of the rows; a reloaded row whose key column changed gives its item the new key.
• Master-detail with a DataWindow: of_select_row brings in front the item of a row whatever its key, the read-only il_current_row reads the row of the item in front, and with ib_sync_row the DataWindow given to of_from_datastore scrolls to the row of the item in front at every change.
• Keyboard: Left and Right (inverted right to left), Up and Down, Home and End, Page Up and Page Down by what the stage shows, greyed items skipped, and the first letters of a title; the carousel is one stop of the Tab key (two with the PAUSE button) and a ring of the accent shows the item in front while the keyboard is in it.
• The row of a video service (is_align = ALIGN_START, on a flat strip): the items stand from the start edge, every one whole, the last screen full with no empty room after the last item, an item cut by an edge inviting to scroll. The arrows — shown only under the pointer or with the keyboard, gone at an end — and Page Up / Page Down move a whole screen and make current the first item it brought; the arrow keys move one item and scroll just enough to keep it whole; the wheel and a swipe rest on a whole item; a click on a whole item makes it current and raises ue_item_clicked; the dots count screens; the autoplay leafs a screen at a time.
• The items slide to their new places (ib_animated, ii_anim_duration, is_anim_easing with five curves); a workstation set to reduce motion jumps straight there.
• Thousands of items cost the same as twenty: only the items within reach of the one in front are drawn, and their pictures loaded.
• is_accessible_name and is_accessible_description: the name and the description a screen reader says for the whole component, like the AccessibleName and AccessibleDescription of a PowerBuilder control. Both read back, go through of_set_property, and of_reset empties them.
• Items added one by one in a loop are drawn once, when the loop is over, and an add no longer waits for the carousel to answer: 5,000 of_add_item take a fraction of a second instead of several seconds. In STYLE_STACK, the fading reflection costs less to draw while the covers glide.