carousel — u_pbt_carousel #

← Referência dos componentes · Índice do guia

carousel faz desfilar elementos dos quais só um está à frente: o Cover Flow do iTunes — o elemento atual de frente, os seus vizinhos inclinados em perspetiva e sobrepostos, um reflexo por baixo —, uma faixa plana onde vários elementos se veem inteiros, uma pilha de cartões, ou um banner em toda a superfície que mostra um elemento de cada vez. Cada elemento é uma imagem, um texto formatado ou um cartão (imagem, título, subtítulo, corpo escrito por um modelo, etiquetas, emblema). O utilizador clica num vizinho, desliza com inércia, roda a roda do rato, escreve as primeiras letras de um título ou usa o teclado; ue_current_changed diz-lhe que elemento está à frente. O carrossel preenche-se à mão ou a partir de um DataStore, e pode avançar sozinho, com um botão PAUSA.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Carousel: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início 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

Quatro disposições, três faces #

is_style escolhe a disposição: STYLE_COVERFLOW (por omissão) põe o elemento atual de frente e inclina os seus vizinhos em perspetiva, sobrepostos, espalhados pela largura disponível e mais escuros com a distância (ii_angle, ii_spacing, ib_shade); STYLE_CAROUSEL alinha uma faixa plana onde vários elementos se veem inteiros; STYLE_STACK empilha cartões — o atual à frente, os seguintes atrás dele, os anteriores afastados para o lado; STYLE_HERO mostra um único elemento em toda a superfície, o seguinte a deslizar ou a aparecer em transparência (is_transition): o banner de um painel de controlo. Um mosaico mantém uma proporção (is_item_ratio; vazio: 1:1 para imagens, 3:4 para cartões, 16:9 para textos) e o conteúdo de um cartão ou de um texto segue o seu tamanho, entre um mínimo legível e um máximo. ib_reflection põe um reflexo sob os elementos, ii_item_width e ii_item_height fixam o tamanho ao píxel.

Porquê faces em vez de componentes dentro do carrossel? Cada componente da biblioteca é um controlo próprio, com a sua própria página web (um WebView2): não pode alojar-se na página de outro. O carrossel desenha portanto ele próprio o que mostrariam uma imagem, um statictext ou um cartão do kanban — são as três faces de um mesmo elemento, e mil elementos custam um único controlo. is_item_style escolhe a face de todos os elementos, is_style de um elemento escolhe a sua (vazio: segue o carrossel). Com ITEM_AUTO (por omissão), a face deduz-se do que o elemento tem:

• um modelo de cartão definido (is_card_template), ou etiquetas, ou ao mesmo tempo uma imagem e um texto → um cartão;
• uma imagem → uma imagem, que preenche o mosaico (is_fit); o seu título e o seu subtítulo tornam-se a legenda logo por baixo, o seu emblema pousa no seu canto;
• um texto sozinho → um texto: texto formatado com etiquetas num painel com o tema, como um statictext; uma zona [action=x] levanta ue_action_clicked;
• nada além de um título → um cartão.

of_item(key).of_face() diz a face escolhida. Uma imagem é um ficheiro do posto, um recurso ficheiro.dll:nome, um glifo mono: ou tint: desenhado com o tema, ou um endereço https://; um endereço http:// é recusado e levanta ue_image_failed com REASON_INSECURE, um ficheiro ausente com 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

Uma fila alinhada no início #

Numa faixa plana (STYLE_CAROUSEL), is_align = ALIGN_START dá a fila de um serviço de vídeo: os elementos partem da borda de início (a direita na leitura da direita para a esquerda), todos inteiros e planos, e o último ecrã está cheio — nenhum vazio após o último elemento; um elemento cortado por uma borda convida a deslocar. O elemento atual já não está ao meio: é o que o utilizador escolheu, sempre inteiro no ecrã. As setas e Page Up / Page Down avançam um ecrã (os elementos que mostra inteiros) e o elemento atual passa a ser o primeiro que o ecrã trouxe; as teclas de seta avançam um elemento e só deslocam o necessário para o manter inteiro; a roda e o arrastar deslocam e pousam num elemento inteiro, o elemento atual só segue se ia sair; um clique num elemento inteiro torna-o atual e levanta ue_item_clicked. As setas vivem nas margens, só aparecem sob o ponteiro ou com o teclado, e desaparecem numa ponta. Os pontos contam ecrãs (um ponto é um lugar onde a faixa pode pousar); o contador continua a contar elementos. A reprodução automática avança um ecrã e, no fim, o primeiro ecrã volta pelo lado. Com ib_loop, a fila dá a volta quando é suficientemente longa para dar a volta ao ecrã (cerca de três elementos a mais do que mostra). ALIGN_START não tem efeito nas outras disposições.

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

O elemento à frente #

O elemento atual é o que está à frente; of_current_key() lê a sua chave em direto. Um clique num vizinho trá-lo para a frente; um clique no elemento à frente levanta ue_item_clicked, um duplo clique (ou Enter) ue_item_opened. Uma mudança do utilizador — clique, teclado, roda, deslizar, ponto, seta, reprodução automática — e uma mudança do seu código (of_select_item, of_next, of_previous) levantam o mesmo ue_current_changed, como SelectItem levanta o evento do clique. Com ib_veto_changes, ue_current_changing é colocado antes, nos dois casos: devolver FALSE deixa o elemento à frente, e of_select_item devolve então -4. ue_current_changed é levantado também quando o elemento à frente sai (escondido, retirado: o mais próximo toma o seu lugar) e quando o primeiro elemento chega a um carrossel vazio (as_from_key vazio). Uma ordem do seu código dentro de ue_current_changing (outro elemento selecionado) prevalece: a resposta que se segue já não muda nada. of_select_row traz para a frente o elemento de uma linha e of_current_row lê a linha do elemento à frente; com ib_sync_row, o DataWindow dado a of_from_datastore segue o elemento à frente — o mestre-detalhe de um DataWindow.

Um elemento desativado (ib_enabled = false) fica no seu lugar, mas o utilizador não pode nem trazê-lo para a frente nem clicar nele: o teclado, a roda, Page Up / Page Down, a barra de deslocamento e um lançamento saltam-no; o seu código seleciona-o na mesma. Um elemento escondido (ib_visible = false) sai do carrossel mantendo a sua chave e o seu lugar. Com ib_loop (três elementos no mínimo), o primeiro segue o último. Um duplo clique num vizinho trá-lo para a frente e fica por aí: nem ue_item_clicked nem ue_item_opened. il_autoplay_ms faz avançar o carrossel sozinho, a cada tantos milissegundos (500 no mínimo): um botão PAUSA / REPRODUZIR aparece por baixo (ib_autoplay_button) e a pausa do utilizador mantém-se até REPRODUZIR (of_pause, of_play, ue_autoplay_changed); também se interrompe sob o ponteiro, enquanto o teclado está no componente e enquanto o carrossel está escondido. No fim de um carrossel sem ciclo, o primeiro elemento volta pelo lado. Cada passo passa por ue_current_changing como um gesto: um elemento recusado é saltado, pede-se o seguinte. Um leitor de ecrã não é avisado de cada passo durante a reprodução.

Cartões e legenda escritos por modelo #

Um cartão mostra a sua imagem em cima, o seu título (is_title), o seu subtítulo (is_subtitle), o seu corpo (is_text), as suas etiquetas (is_tags, separadas por vírgulas, coloridas por is_tag_tones: New=success|Sale=danger) e um emblema (is_badge). O corpo de todos os cartões pode ser escrito por um modelo, is_card_template, e a legenda sob o carrossel por is_caption_template: texto formatado com etiquetas onde {price} é um campo do elemento — um dos seus (of_set_field), uma coluna do DataStore de onde vem, ou um campo integrado (key, title, subtitle, text, image, badge, tags, position, count). {position} e {count} contam os elementos desenhados, como o contador. {sold:dd/mm/yyyy hh:mm} escreve uma data ou uma data-hora, {price:#,##0.00} um número: os formatos de apresentação de uma coluna de DataWindow (mm depois de uma hora = os minutos, [shortdate], [longdate], [time], secções positivo;negativo;zero), na língua de apresentação — um valor que o formato não sabe escrever é mostrado tal como é. {?x}…{/x} mantém um pedaço quando o campo diz alguma coisa, {!x}…{/x} quando não diz nada, {{ }} são chavetas. Um valor é mostrado tal como é, nunca lido como etiquetas; {x:raw} mantém-no como etiquetas — reserve-o aos seus próprios campos: numa coluna de base de dados leria o dado como etiquetas, zonas de ação incluídas. {title}, {subtitle}, {text} e {badge} escritos pelo seu código são etiquetas, como na legenda; lidos de uma coluna, 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]"

A partir de um DataStore #

of_from_datastore faz um elemento de cada linha de um DataStore, de um DataWindow ou de um DataWindowChild — a mesma chamada. A sua chave é o RowID da linha — nomeia a sua linha enquanto o DataStore não for esvaziado nem relido (Reset, Retrieve e ImportString voltam a dar os RowID 1, 2, 3), e of_item(key).of_row() encontra-a — ou o valor da coluna ROLE_KEY, a chave a dar assim que atualiza. Uma linha cuja chave está vazia, é inválida, já foi vista ou está ocupada por um elemento acrescentado à mão não é carregada: a chamada devolve 0 e of_get_last_error nomeia-a — dê aos seus elementos à mão chaves que não sejam números. Uma coluna desempenha um papel quando tem o seu nome (key, title, subtitle, text, image, badge, tags, color) ou quando of_map o diz; a coluna ROLE_COLOR (um RGB() ou #rrggbb) pinta a faixa de um cartão. of_map e of_reload_row atualizam os elementos no lugar (indicadores, campos, handle e lugar ficam). Também um segundo carregamento, com ROLE_KEY: um elemento cuja chave volta mantém os seus indicadores, os seus campos e o seu handle. Sem ROLE_KEY, um segundo carregamento é uma nova época: um RowID que volta pode nomear outro registo, cada elemento das linhas é refeito (nada é herdado, os handles dos antigos são libertados) e, se a chave à frente voltar, ue_current_changed di-lo com as_from_key = as_key. Em todos os casos os elementos tomam a ordem das linhas (um of_move_item não sobrevive a um carregamento), os das linhas desaparecidas saem, os acrescentados à mão ficam, depois das linhas; um elemento de linha retirado com of_remove_item volta com a sua linha — esconda-o antes (ib_visible). As datas são lidas na ordem regional do posto, os números escrevem-se com ponto, os valores CHAR sem o seu preenchimento, no carregamento como depois de of_reload_row. O que uma coluna dá é texto, nunca etiquetas — um [action=x] vindo da base de dados não é clicável —, e uma imagem de uma coluna nunca vai buscar um caminho de rede (\\servidor\partilha: ue_image_failed com REASON_UNC). Quando a coluna ROLE_KEY de uma linha relida muda, o elemento toma a nova chave: o handle da antiga é libertado. Todas as colunas são campos dos modelos.

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

Propriedades #

Propriedades de um elemento — n_pbt_carousel_item #

O seu handle, através de of_item(key). Uma leitura pergunta ao carrossel como está agora.

Três leituras do handle, só de leitura: of_position() devolve o lugar do elemento a partir de 1, of_row() o número da sua linha no DataStore (0 para um elemento acrescentado à mão), of_face() a face escolhida. Um elemento desloca-se com of_move_item do carrossel.

Métodos #

Eventos #

Teclado e rato #

• Clique num vizinho: vem para a frente; no elemento à frente: ue_item_clicked; duplo clique: ue_item_opened (num vizinho: vem para a frente, nada mais); clique direito: ue_item_rclicked.
• Arrastar ou deslizar: a faixa segue o ponteiro; ao largar, a sua velocidade leva-a alguns elementos mais longe. Sem ib_loop, as pontas são elásticas. Largado fora do carrossel, o arrastar termina na mesma.
• Roda: segue a sua velocidade — um entalhe, um elemento; uma grande volta, vários; um touchpad soma os seus pequenos passos.
• Esquerda / Direita: o elemento anterior, o seguinte — invertidas numa aplicação da direita para a esquerda; Cima / Baixo: o mesmo; Home / End: o primeiro, o último; Page Up / Page Down: de tantos elementos quantos a cena mostra. Os elementos desativados são saltados, em todo o lado.
• As primeiras letras de um título trazem-no para a frente (maiúsculas e acentos ignorados); a mesma letra outra vez vai para o seguinte que começa por ela.
• Enter: ue_item_opened; Espaço: ue_item_clicked; tecla Menu ou Shift + F10: ue_item_rclicked sobre o elemento à frente.
• As setas laterais (ib_arrows, nas suas calhas: não cobrem nenhum mosaico), os pontos e a barra de deslocamento (is_indicator) clicam-se; a barra também se arrasta. O botão PAUSA / REPRODUZIR (ib_autoplay_button) clica-se ou alcança-se com o teclado.
• O carrossel é uma paragem da tecla Tab (duas com o botão PAUSA); um anel do destaque rodeia o elemento à frente enquanto o teclado lá está.

Exemplos #

Uma montra de produtos #

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

Perguntar antes de mudar 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 um elemento de um DataStore na sua janela #

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

Notícias que avançam sozinhas #

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

Um grande 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")

Boas práticas #

• Imagens das mesmas proporções: o Cover Flow lê-se num relance quando os mosaicos têm a mesma forma; is_item_ratio fixa-a, FIT_CONTAIN mostra a imagem inteira.
• Pouco texto por face: um cartão lê-se em duas linhas, o detalhe vai para a sua janela (ue_item_opened).
• Uma reprodução automática lenta (quatro a seis segundos), com o seu botão PAUSA: quem lê tem de poder parar o que se mexe.
• Chaves que não sejam números para os seus elementos à mão, num carrossel alimentado por um DataStore: um elemento de chave 12 impede que a linha de RowID 12 seja carregada (of_get_last_error di-lo).
• ROLE_KEY assim que atualizar um DataStore (Retrieve, Reset): sem ela, um recarregamento refaz cada elemento, porque um RowID que volta pode nomear outro registo.
• Muitos elementos não custam nada: só são desenhados os que estão ao alcance do elemento à frente, e uma imagem só é carregada quando se aproxima — o utilizador chega a um título escrevendo-o.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia