carousel — u_pbt_carousel #

← Komponentenreferenz · Inhalt des Handbuchs

carousel blättert durch Elemente, von denen nur eines vorn steht: das Cover Flow von iTunes — das aktuelle Element von vorn, seine Nachbarn perspektivisch gedreht und einander überdeckend, eine Spiegelung darunter —, ein flacher Streifen, in dem mehrere Elemente ganz zu sehen sind, ein Kartenstapel oder ein flächenfüllendes Banner, das ein Element nach dem anderen zeigt. Jedes Element ist ein Bild, ein Rich Text oder eine Karte (Bild, Titel, Untertitel, über eine Vorlage geschriebener Inhalt, Tags, Badge). Der Benutzer klickt einen Nachbarn an, wischt mit Trägheit, dreht das Mausrad, tippt die ersten Buchstaben eines Titels oder nutzt die Tastatur; ue_current_changed sagt Ihnen, welches Element vorn steht. Das Karussell wird von Hand oder aus einem DataStore gefüllt und kann von selbst weiterlaufen, mit einer PAUSE-Schaltfläche.

▶ Live ansehen — Demoanwendung, Kachel Carousel: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

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

Vier Anordnungen, drei Ansichten #

is_style wählt die Anordnung: STYLE_COVERFLOW (Standard) zeigt das aktuelle Element von vorn und dreht seine Nachbarn perspektivisch, einander überdeckend, über die verfügbare Breite verteilt und mit der Entfernung dunkler (ii_angle, ii_spacing, ib_shade); STYLE_CAROUSEL reiht einen flachen Streifen auf, in dem mehrere Elemente ganz zu sehen sind; STYLE_STACK stapelt Karten — die aktuelle vorn, die folgenden dahinter, die vorigen zur Seite geschoben; STYLE_HERO zeigt ein einziges Element auf der ganzen Fläche, das nächste gleitet oder blendet ein (is_transition): das Banner eines Dashboards. Eine Kachel behält ein Seitenverhältnis (is_item_ratio; leer: 1:1 für Bilder, 3:4 für Karten, 16:9 für Texte), und der Inhalt einer Karte oder eines Textes folgt ihrer Größe, zwischen einer lesbaren Untergrenze und einer Obergrenze. ib_reflection legt eine Spiegelung unter die Elemente, ii_item_width und ii_item_height legen die Größe pixelgenau fest.

Warum Ansichten statt Komponenten im Karussell? Jede Komponente der Bibliothek ist ein eigenständiges Steuerelement mit eigener Webseite (einem WebView2): Sie kann nicht in der Seite einer anderen sitzen. Das Karussell zeichnet also selbst, was ein Bild, ein statictext oder eine Kanban-Karte zeigen würde — das sind die drei Ansichten eines Elements, und tausend Elemente kosten ein einziges Steuerelement. is_item_style wählt die Ansicht aller Elemente, is_style eines Elements wählt seine eigene (leer: es folgt dem Karussell). Mit ITEM_AUTO (Standard) ergibt sich die Ansicht aus dem, was das Element trägt:

• eine gesetzte Kartenvorlage (is_card_template), oder Tags, oder zugleich ein Bild und ein Text → eine Karte;
• ein Bild → ein Bild, das die Kachel füllt (is_fit); Titel und Untertitel werden zur Beschriftung direkt darunter, sein Badge sitzt auf seiner Ecke;
• ein Text allein → ein Text: Rich-Text-Auszeichnung auf einem Feld im Design, wie ein statictext; eine Zone [action=x] löst ue_action_clicked aus;
• nichts als ein Titel → eine Karte.

of_item(key).of_face() nennt die gewählte Ansicht. Ein Bild ist eine Datei des Arbeitsplatzes, eine Ressource datei.dll:name, ein im Design gezeichnetes Symbol mono: oder tint: oder eine https://-Adresse; eine http://-Adresse wird abgelehnt und löst ue_image_failed mit REASON_INSECURE aus, eine fehlende Datei mit 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

Eine am Anfang ausgerichtete Reihe #

Auf einem flachen Streifen (STYLE_CAROUSEL) ergibt is_align = ALIGN_START die Reihe eines Videodienstes: Die Elemente beginnen am Anfangsrand (rechts bei Leserichtung von rechts nach links), alle ganz und flach, und der letzte Bildschirm ist voll — kein leerer Platz nach dem letzten Element; ein von einem Rand angeschnittenes Element lädt zum Blättern ein. Das aktuelle Element steht nicht mehr in der Mitte: Es ist das vom Benutzer gewählte, immer ganz auf dem Bildschirm. Die Pfeile und Bild auf / Bild ab blättern um einen Bildschirm (die Elemente, die er ganz zeigt), und das aktuelle Element wird das erste, das der Bildschirm gebracht hat; die Pfeiltasten gehen um ein Element weiter und blättern nur so weit, dass es ganz bleibt; Mausrad und Wischen blättern und kommen auf einem ganzen Element zur Ruhe, das aktuelle Element folgt nur, wenn es hinausginge; ein Klick auf ein ganzes Element macht es zum aktuellen und löst ue_item_clicked aus. Die Pfeile liegen in den Rändern, erscheinen nur unter dem Zeiger oder mit der Tastatur und verschwinden an einem Ende. Die Punkte zählen Bildschirme (ein Punkt ist eine Stelle, an der der Streifen ruhen kann); der Zähler zählt weiterhin Elemente. Die automatische Wiedergabe blättert um einen Bildschirm, und am Ende kommt der erste Bildschirm von der Seite zurück. Mit ib_loop läuft die Reihe rund, wenn sie lang genug ist, um den Bildschirm zu umrunden (etwa drei Elemente mehr, als er zeigt). ALIGN_START wirkt auf die anderen Anordnungen nicht.

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

Das vordere Element #

Das aktuelle Element ist das vordere; of_current_key() liest seinen Schlüssel live. Ein Klick auf einen Nachbarn holt ihn nach vorn; ein Klick auf das vordere Element löst ue_item_clicked aus, ein Doppelklick (oder Eingabe) ue_item_opened. Ein Wechsel des Benutzers — Klick, Tastatur, Mausrad, Wischen, Punkt, Pfeil, automatische Wiedergabe — und ein Wechsel Ihres Codes (of_select_item, of_next, of_previous) lösen dasselbe ue_current_changed aus, so wie SelectItem das Ereignis des Klicks auslöst. Mit ib_veto_changes wird ue_current_changing in beiden Fällen vorher gestellt: FALSE zurückzugeben lässt das Element vorn, und of_select_item gibt dann -4 zurück. ue_current_changed wird auch ausgelöst, wenn das vordere Element geht (ausgeblendet, entfernt: das nächste nimmt seinen Platz ein) und wenn das erste Element in einem leeren Karussell ankommt (as_from_key leer). Ein Befehl Ihres Codes in ue_current_changing (ein anderes Element ausgewählt) hat Vorrang: Die folgende Antwort ändert nichts mehr. of_select_row holt das Element einer Zeile nach vorn, und of_current_row liest die Zeile des vorderen Elements; mit ib_sync_row folgt das an of_from_datastore übergebene DataWindow dem vorderen Element — das Master-Detail eines DataWindow.

Ein ausgegrautes Element (ib_enabled = false) bleibt an seinem Platz, aber der Benutzer kann es weder nach vorn holen noch anklicken: Tastatur, Mausrad, Bild auf / Bild ab, die Bildlaufleiste und ein Schwung überspringen es; Ihr Code wählt es trotzdem aus. Ein ausgeblendetes Element (ib_visible = false) verlässt das Karussell und behält Schlüssel und Platz. Mit ib_loop (mindestens drei Elemente) folgt das erste auf das letzte. Ein Doppelklick auf einen Nachbarn holt ihn nach vorn und hört dort auf: weder ue_item_clicked noch ue_item_opened. il_autoplay_ms lässt das Karussell von selbst weiterlaufen, alle so viele Millisekunden (mindestens 500): Eine Schaltfläche PAUSE / WIEDERGABE erscheint darunter (ib_autoplay_button), und die Pause des Benutzers hält bis WIEDERGABE (of_pause, of_play, ue_autoplay_changed); sie unterbricht auch unter dem Mauszeiger, solange die Tastatur in der Komponente ist und solange das Karussell verborgen ist. Am Ende eines Karussells ohne Schleife kommt das erste Element von der Seite zurück. Jeder Schritt geht wie eine Geste über ue_current_changing: Ein abgelehntes Element wird übersprungen, das nächste wird gefragt. Ein Bildschirmleser wird während der Wiedergabe nicht über jeden Schritt informiert.

Karten und Beschriftung per Vorlage #

Eine Karte zeigt oben ihr Bild, ihren Titel (is_title), ihren Untertitel (is_subtitle), ihren Inhalt (is_text), ihre Tags (is_tags, durch Kommas getrennt, gefärbt durch is_tag_tones: New=success|Sale=danger) und ein Badge (is_badge). Der Inhalt aller Karten kann über eine Vorlage geschrieben werden, is_card_template, und die Beschriftung unter dem Karussell über is_caption_template: Rich-Text-Auszeichnung, in der {price} ein Feld des Elements ist — eines Ihrer eigenen (of_set_field), eine Spalte des DataStores, aus dem es stammt, oder ein eingebautes Feld (key, title, subtitle, text, image, badge, tags, position, count). {position} und {count} zählen die gezeichneten Elemente, wie der Zähler. {sold:dd/mm/yyyy hh:mm} schreibt ein Datum oder einen Zeitpunkt, {price:#,##0.00} eine Zahl: die Anzeigeformate einer DataWindow-Spalte (mm nach einer Stunde = die Minuten, [shortdate], [longdate], [time], Abschnitte positiv;negativ;null), in der Anzeigesprache — ein Wert, den das Format nicht schreiben kann, wird so angezeigt, wie er ist. {?x}…{/x} behält ein Stück, wenn das Feld etwas enthält, {!x}…{/x}, wenn es nichts enthält, {{ }} sind geschweifte Klammern. Ein Wert wird so angezeigt, wie er ist, nie als Auszeichnung gelesen; {x:raw} behält ihn als Auszeichnung — nur für Ihre eigenen Felder: Auf einer Datenbankspalte würde es die Daten als Auszeichnung lesen, Aktionszonen inbegriffen. {title}, {subtitle}, {text} und {badge}, von Ihrem Code geschrieben, sind Auszeichnung, wie in der Beschriftung; aus einer Spalte gelesen, 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]"

Aus einem DataStore #

of_from_datastore macht aus jeder Zeile eines DataStores, eines DataWindow oder eines DataWindowChild ein Element — derselbe Aufruf. Sein Schlüssel ist die RowID der Zeile — sie benennt ihre Zeile, solange der DataStore weder geleert noch neu gelesen wird (Reset, Retrieve und ImportString vergeben die RowIDs 1, 2, 3 erneut), und of_item(key).of_row() findet sie — oder der Wert der Spalte ROLE_KEY, der Schlüssel, den Sie angeben, sobald Sie aktualisieren. Eine Zeile, deren Schlüssel leer, ungültig, schon gesehen oder von einem von Hand hinzugefügten Element belegt ist, wird nicht geladen: Der Aufruf gibt 0 zurück, und of_get_last_error nennt sie — geben Sie Ihren Elementen von Hand Schlüssel, die keine Zahlen sind. Eine Spalte spielt eine Rolle, wenn sie so heißt (key, title, subtitle, text, image, badge, tags, color) oder wenn of_map es sagt; die Spalte ROLE_COLOR (ein RGB() oder #rrggbb) färbt den Streifen einer Karte. of_map und of_reload_row aktualisieren die Elemente an Ort und Stelle (Kennzeichen, Felder, Handle und Platz bleiben). Ein zweites Laden ebenso, mit ROLE_KEY: Ein Element, dessen Schlüssel zurückkommt, behält seine Kennzeichen, seine Felder und seinen Handle. Ohne ROLE_KEY ist ein zweites Laden eine neue Epoche: Eine zurückkommende RowID kann einen anderen Datensatz benennen, jedes Element der Zeilen wird neu erstellt (nichts wird geerbt, die Handles der alten werden freigegeben), und kommt der vordere Schlüssel zurück, sagt es ue_current_changed mit as_from_key = as_key. In jedem Fall nehmen die Elemente die Reihenfolge der Zeilen an (ein of_move_item überlebt kein Laden), die Elemente verschwundener Zeilen gehen, die von Hand hinzugefügten bleiben, nach den Zeilen; ein mit of_remove_item entferntes Zeilenelement kommt mit seiner Zeile zurück — blenden Sie es lieber aus (ib_visible). Datumswerte werden in der regionalen Reihenfolge des Arbeitsplatzes gelesen, Zahlen werden mit Punkt geschrieben, CHAR-Werte ohne ihre Auffüllung, beim Laden wie nach of_reload_row. Was eine Spalte liefert, ist Text, nie Auszeichnung — ein [action=x] aus der Datenbank ist nicht anklickbar —, und ein Bild aus einer Spalte greift nie auf einen Netzwerkpfad zu (\\server\freigabe: ue_image_failed mit REASON_UNC). Ändert sich die Spalte ROLE_KEY einer neu gelesenen Zeile, nimmt das Element den neuen Schlüssel an: Der Handle des alten wird freigegeben. Jede Spalte ist ein Feld der Vorlagen.

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

Eigenschaften #

Eigenschaften eines Elements — n_pbt_carousel_item #

Sein Handle, über of_item(key). Ein Lesen fragt das Karussell, wie es jetzt ist.

Drei Lesefunktionen des Handles, nur lesend: of_position() liefert den Platz des Elements ab 1, of_row() die Nummer seiner Zeile im DataStore (0 für ein von Hand hinzugefügtes Element), of_face() die gewählte Ansicht. Ein Element wird über of_move_item des Karussells verschoben.

Methoden #

Ereignisse #

Tastatur und Maus #

• Klick auf einen Nachbarn: Er kommt nach vorn; auf das vordere Element: ue_item_clicked; Doppelklick: ue_item_opened (auf einen Nachbarn: Er kommt nach vorn, sonst nichts); Rechtsklick: ue_item_rclicked.
• Ziehen oder Wischen: Der Streifen folgt dem Zeiger; beim Loslassen trägt ihn sein Schwung einige Elemente weiter. Ohne ib_loop sind die Enden elastisch. Außerhalb des Karussells losgelassen, endet das Ziehen trotzdem.
• Mausrad: Es folgt seiner Geschwindigkeit — eine Raste, ein Element; eine große Drehung, mehrere; ein Touchpad summiert seine kleinen Schritte.
• Links / Rechts: das vorige Element, das nächste — in einer Rechts-nach-links-Anwendung vertauscht; Auf / Ab: ebenso; Pos1 / Ende: das erste, das letzte; Bild auf / Bild ab: um so viele Elemente, wie die Bühne zeigt. Ausgegraute Elemente werden überall übersprungen.
• Die ersten Buchstaben eines Titels holen ihn nach vorn (Groß-/Kleinschreibung und Akzente ignoriert); derselbe Buchstabe noch einmal geht zum nächsten, das damit beginnt.
• Eingabe: ue_item_opened; Leertaste: ue_item_clicked; Kontextmenütaste oder Umschalt + F10: ue_item_rclicked auf dem vorderen Element.
• Die seitlichen Pfeile (ib_arrows, in ihren Rinnen: Sie verdecken keine Kachel), die Punkte und die Bildlaufleiste (is_indicator) werden angeklickt; die Leiste lässt sich auch ziehen. Die Schaltfläche PAUSE / WIEDERGABE (ib_autoplay_button) wird angeklickt oder mit der Tastatur erreicht.
• Das Karussell ist ein Halt der Tabulatortaste (zwei mit der PAUSE-Schaltfläche); ein Ring im Akzent umgibt das vordere Element, solange die Tastatur darin ist.

Beispiele #

Ein Produktschaufenster #

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

Vor dem Wechsel des Elements fragen #

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

Ein Element eines DataStores in Ihrem Fenster öffnen #

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

Neuigkeiten, die von selbst weiterlaufen #

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

Ein großer Katalog #

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

Bewährte Praxis #

• Bilder mit gleichem Seitenverhältnis: Das Cover Flow ist auf einen Blick lesbar, wenn die Kacheln dieselbe Form haben; is_item_ratio legt sie fest, FIT_CONTAIN zeigt das ganze Bild.
• Wenig Text pro Ansicht: Eine Karte liest sich in zwei Zeilen, das Detail gehört in Ihr Fenster (ue_item_opened).
• Eine langsame automatische Wiedergabe (vier bis sechs Sekunden), mit ihrer PAUSE-Schaltfläche: Wer liest, muss anhalten können, was sich bewegt.
• Schlüssel, die keine Zahlen sind, für Ihre Elemente von Hand, in einem aus einem DataStore gespeisten Karussell: Ein Element mit dem Schlüssel 12 verhindert, dass die Zeile mit RowID 12 geladen wird (of_get_last_error sagt es).
• ROLE_KEY, sobald Sie einen DataStore aktualisieren (Retrieve, Reset): Ohne ihn erstellt ein erneutes Laden jedes Element neu, denn eine zurückkommende RowID kann einen anderen Datensatz benennen.
• Viele Elemente kosten nichts: Nur die in Reichweite des vorderen Elements werden gezeichnet, und ein Bild wird erst geladen, wenn es näher kommt — der Benutzer erreicht einen Titel, indem er ihn tippt.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs