carousel — u_pbt_carousel #

← Referencia de componentes · Índice de la guía

carousel hace desfilar elementos de los que solo uno está al frente: el Cover Flow de iTunes — el elemento actual de frente, sus vecinos inclinados en perspectiva y superpuestos, un reflejo debajo —, una franja plana donde se ven enteros varios elementos, una pila de tarjetas, o un banner a toda la superficie que muestra un elemento a la vez. Cada elemento es una imagen, un texto enriquecido o una tarjeta (imagen, título, subtítulo, cuerpo escrito por una plantilla, etiquetas, insignia). El usuario hace clic en un vecino, desliza con inercia, gira la rueda, teclea las primeras letras de un título o usa el teclado; ue_current_changed le dice qué elemento está al frente. El carrusel se llena a mano o desde un DataStore, y puede avanzar solo, con un botón PAUSA.

▶ Verlo en vivo — Aplicación de demostración, mosaico Carousel: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

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

Cuatro disposiciones, tres caras #

is_style elige la disposición: STYLE_COVERFLOW (por defecto) pone el elemento actual de frente e inclina sus vecinos en perspectiva, superpuestos, repartidos por el ancho disponible y más oscuros con la distancia (ii_angle, ii_spacing, ib_shade); STYLE_CAROUSEL alinea una franja plana donde se ven enteros varios elementos; STYLE_STACK apila tarjetas — la actual delante, las siguientes detrás, las anteriores apartadas a un lado; STYLE_HERO muestra un solo elemento en toda la superficie, el siguiente deslizándose o fundiéndose (is_transition): el banner de un cuadro de mando. Un mosaico conserva una proporción (is_item_ratio; vacío: 1:1 para imágenes, 3:4 para tarjetas, 16:9 para textos) y el contenido de una tarjeta o de un texto sigue su tamaño, entre un mínimo legible y un máximo. ib_reflection pone un reflejo bajo los elementos, ii_item_width e ii_item_height fijan el tamaño al píxel.

¿Por qué caras en lugar de componentes dentro del carrusel? Cada componente de la biblioteca es un control propio, con su propia página web (un WebView2): no puede alojarse en la página de otro. El carrusel dibuja pues por sí mismo lo que mostrarían una imagen, un statictext o una tarjeta del kanban — son las tres caras de un mismo elemento, y mil elementos cuestan un solo control. is_item_style elige la cara de todos los elementos, is_style de un elemento elige la suya (vacío: sigue al carrusel). Con ITEM_AUTO (por defecto), la cara se deduce de lo que el elemento lleva:

• una plantilla de tarjeta puesta (is_card_template), o etiquetas, o a la vez una imagen y un texto → una tarjeta;
• una imagen → una imagen, que llena el mosaico (is_fit); su título y su subtítulo se convierten en el pie justo debajo, su insignia se posa en su esquina;
• un texto solo → un texto: texto enriquecido con etiquetas sobre un panel con el tema, como un statictext; una zona [action=x] lanza ue_action_clicked;
• nada más que un título → una tarjeta.

of_item(key).of_face() dice la cara elegida. Una imagen es un archivo del equipo, un recurso archivo.dll:nombre, un glifo mono: o tint: dibujado con el tema, o una dirección https://; una dirección http:// se rechaza y lanza ue_image_failed con REASON_INSECURE, un archivo ausente 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 alineada al inicio #

En una franja plana (STYLE_CAROUSEL), is_align = ALIGN_START da la fila de un servicio de vídeo: los elementos parten del borde de inicio (el derecho en lectura de derecha a izquierda), todos enteros y planos, y la última pantalla está llena — ningún hueco tras el último elemento; un elemento cortado por un borde invita a desplazarse. El elemento actual ya no está en el centro: es el que el usuario eligió, siempre entero en pantalla. Las flechas y Re Pág / Av Pág avanzan una pantalla (los elementos que muestra enteros) y el elemento actual pasa a ser el primero que la pantalla trajo; las teclas de flecha avanzan un elemento y solo desplazan lo necesario para mantenerlo entero; la rueda y el arrastre desplazan y se posan en un elemento entero, el elemento actual solo sigue si iba a salir; un clic en un elemento entero lo hace actual y lanza ue_item_clicked. Las flechas viven en los márgenes, solo se muestran bajo el puntero o con el teclado, y desaparecen en un extremo. Los puntos cuentan pantallas (un punto es un lugar donde la franja puede posarse); el contador sigue contando elementos. La reproducción automática avanza una pantalla y, al final, la primera pantalla vuelve por el lado. Con ib_loop, la fila da la vuelta cuando es lo bastante larga para dar la vuelta a la pantalla (unos tres elementos más de los que muestra). ALIGN_START no tiene efecto en las demás disposiciones.

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

El elemento al frente #

El elemento actual es el que está al frente; of_current_key() lee su clave en directo. Un clic en un vecino lo trae al frente; un clic en el elemento al frente lanza ue_item_clicked, un doble clic (o Intro) ue_item_opened. Un cambio del usuario — clic, teclado, rueda, deslizamiento, punto, flecha, reproducción automática — y un cambio de su código (of_select_item, of_next, of_previous) lanzan el mismo ue_current_changed, como SelectItem lanza el evento del clic. Con ib_veto_changes, ue_current_changing se plantea antes, en ambos casos: devolver FALSE deja el elemento al frente, y of_select_item devuelve entonces -4. ue_current_changed se lanza también cuando el elemento al frente se va (oculto, quitado: el más cercano ocupa su lugar) y cuando el primer elemento llega a un carrusel vacío (as_from_key vacío). Una orden de su código dentro de ue_current_changing (otro elemento seleccionado) prevalece: la respuesta que sigue ya no cambia nada. of_select_row trae al frente el elemento de una fila y of_current_row lee la fila del elemento al frente; con ib_sync_row, el DataWindow dado a of_from_datastore sigue al elemento al frente — el maestro-detalle de un DataWindow.

Un elemento desactivado (ib_enabled = false) se queda en su lugar, pero el usuario no puede ni traerlo al frente ni hacer clic en él: el teclado, la rueda, Re Pág / Av Pág, la barra de desplazamiento y un lanzamiento lo saltan; su código lo selecciona de todos modos. Un elemento oculto (ib_visible = false) sale del carrusel conservando su clave y su lugar. Con ib_loop (tres elementos como mínimo), el primero sigue al último. Un doble clic en un vecino lo trae al frente y se detiene ahí: ni ue_item_clicked ni ue_item_opened. il_autoplay_ms hace avanzar el carrusel solo, cada tantos milisegundos (500 como mínimo): un botón PAUSA / REPRODUCIR aparece debajo (ib_autoplay_button) y la pausa del usuario se mantiene hasta REPRODUCIR (of_pause, of_play, ue_autoplay_changed); también se interrumpe bajo el puntero, mientras el teclado está en el componente y mientras el carrusel está oculto. Al final de un carrusel sin bucle, el primer elemento vuelve por un lado. Cada paso pasa por ue_current_changing como un gesto: un elemento rechazado se salta, se pregunta por el siguiente. A un lector de pantalla no se le avisa de cada paso durante la reproducción.

Tarjetas y pie escritos por plantilla #

Una tarjeta muestra su imagen arriba, su título (is_title), su subtítulo (is_subtitle), su cuerpo (is_text), sus etiquetas (is_tags, separadas por comas, coloreadas por is_tag_tones: New=success|Sale=danger) y una insignia (is_badge). El cuerpo de todas las tarjetas puede escribirse con una plantilla, is_card_template, y el pie bajo el carrusel con is_caption_template: texto enriquecido con etiquetas donde {price} es un campo del elemento — uno de los suyos (of_set_field), una columna del DataStore del que procede, o un campo integrado (key, title, subtitle, text, image, badge, tags, position, count). {position} y {count} cuentan los elementos dibujados, como el contador. {sold:dd/mm/yyyy hh:mm} escribe una fecha o una fecha-hora, {price:#,##0.00} un número: los formatos de visualización de una columna de DataWindow (mm tras una hora = los minutos, [shortdate], [longdate], [time], secciones positivo;negativo;cero), en el idioma de visualización — un valor que el formato no sabe escribir se muestra tal cual. {?x}…{/x} conserva un fragmento cuando el campo dice algo, {!x}…{/x} cuando no dice nada, {{ }} son llaves. Un valor se muestra tal cual, nunca se lee como etiquetas; {x:raw} lo conserva como etiquetas — resérvelo a sus propios campos: en una columna de base de datos leería el dato como etiquetas, zonas de acción incluidas. {title}, {subtitle}, {text} y {badge} escritos por su código son etiquetas, como en el pie; leídos de una columna, texto.

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

Desde un DataStore #

of_from_datastore hace un elemento de cada fila de un DataStore, de un DataWindow o de un DataWindowChild — la misma llamada. Su clave es el RowID de la fila — nombra su fila mientras el DataStore no se vacíe ni se vuelva a leer (Reset, Retrieve e ImportString vuelven a dar los RowID 1, 2, 3), y of_item(key).of_row() la encuentra — o el valor de la columna ROLE_KEY, la clave que hay que dar en cuanto se refresca. Una fila cuya clave está vacía, no es válida, ya se vio o está tomada por un elemento añadido a mano no se carga: la llamada devuelve 0 y of_get_last_error la nombra — dé a sus elementos a mano claves que no sean números. Una columna desempeña un rol cuando se llama como él (key, title, subtitle, text, image, badge, tags, color) o cuando of_map lo dice; la columna ROLE_COLOR (un RGB() o #rrggbb) pinta la franja de una tarjeta. of_map y of_reload_row actualizan los elementos en su sitio (indicadores, campos, handle y lugar se quedan). También una segunda carga, con ROLE_KEY: un elemento cuya clave vuelve conserva sus indicadores, sus campos y su handle. Sin ROLE_KEY, una segunda carga es una nueva época: un RowID que vuelve puede nombrar otro registro, cada elemento de las filas se rehace (nada se hereda, los handles de los antiguos se liberan) y, si la clave al frente vuelve, ue_current_changed lo dice con as_from_key = as_key. En todos los casos los elementos toman el orden de las filas (un of_move_item no sobrevive a una carga), los de las filas desaparecidas se van, los añadidos a mano se quedan, después de las filas; un elemento de fila quitado con of_remove_item vuelve con su fila — mejor ocúltelo (ib_visible). Las fechas se leen en el orden regional del puesto, los números se escriben con punto, los valores CHAR sin su relleno, en la carga como tras of_reload_row. Lo que da una columna es texto, nunca etiquetas — un [action=x] llegado de la base de datos no es clicable —, y una imagen de una columna nunca va a buscar una ruta de red (\\servidor\recurso: ue_image_failed con REASON_UNC). Cuando la columna ROLE_KEY de una fila releída cambia, el elemento toma la nueva clave: el handle de la antigua se libera. Todas las columnas son campos de las plantillas.

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

Propiedades #

Propiedades de un elemento — n_pbt_carousel_item #

Su handle, mediante of_item(key). Una lectura pregunta al carrusel cómo está ahora.

Tres lecturas del handle, solo lectura: of_position() devuelve el lugar del elemento desde 1, of_row() el número de su fila en el DataStore (0 para un elemento añadido a mano), of_face() la cara elegida. Un elemento se mueve con of_move_item del carrusel.

Métodos #

Eventos #

Teclado y ratón #

• Clic en un vecino: viene al frente; en el elemento al frente: ue_item_clicked; doble clic: ue_item_opened (en un vecino: viene al frente, nada más); clic derecho: ue_item_rclicked.
• Arrastrar o deslizar: la franja sigue al puntero; al soltar, su velocidad la lleva unos elementos más allá. Sin ib_loop, los bordes son elásticos. Soltado fuera del carrusel, el arrastre termina igualmente.
• Rueda: sigue su velocidad — una muesca, un elemento; un gran giro, varios; un panel táctil acumula sus pequeños pasos.
• Izquierda / Derecha: el elemento anterior, el siguiente — invertidas en una aplicación de derecha a izquierda; Arriba / Abajo: lo mismo; Inicio / Fin: el primero, el último; Re Pág / Av Pág: de tantos elementos como muestra la escena. Los elementos desactivados se saltan, en todas partes.
• Las primeras letras de un título lo traen al frente (mayúsculas y acentos ignorados); la misma letra otra vez va al siguiente que empieza por ella.
• Intro: ue_item_opened; Espacio: ue_item_clicked; tecla Menú o Mayús + F10: ue_item_rclicked sobre el elemento al frente.
• Las flechas laterales (ib_arrows, en sus canaletas: no cubren ningún mosaico), los puntos y la barra de desplazamiento (is_indicator) se pulsan; la barra también se arrastra. El botón PAUSA / REPRODUCIR (ib_autoplay_button) se pulsa o se alcanza con el teclado.
• El carrusel es una parada de la tecla Tab (dos con el botón PAUSA); un anillo del acento rodea el elemento al frente mientras el teclado está en él.

Ejemplos #

Un escaparate de productos #

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

Preguntar antes de cambiar de 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

Abrir un elemento de un DataStore en su ventana #

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

Noticias que avanzan solas #

// 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 gran catálogo #

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

Buenas prácticas #

• Imágenes de las mismas proporciones: el Cover Flow se lee de un vistazo cuando los mosaicos tienen la misma forma; is_item_ratio la fija, FIT_CONTAIN muestra la imagen entera.
• Poco texto por cara: una tarjeta se lee en dos líneas, el detalle va a su ventana (ue_item_opened).
• Una reproducción automática lenta (de cuatro a seis segundos), con su botón PAUSA: quien lee debe poder detener lo que se mueve.
• Claves que no sean números para sus elementos a mano, en un carrusel alimentado por un DataStore: un elemento de clave 12 impide cargar la fila de RowID 12 (of_get_last_error lo dice).
• ROLE_KEY en cuanto refresque un DataStore (Retrieve, Reset): sin ella, una recarga rehace cada elemento, porque un RowID que vuelve puede nombrar otro registro.
• Muchos elementos no cuestan nada: solo se dibujan los que están al alcance del elemento al frente, y una imagen solo se carga cuando se acerca — el usuario alcanza un título tecleándolo.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía