02 — Catalogue de widgets

Tous les constructeurs statiques Element.<Nom>(...), regroupés par catégorie.

Convention : chaque constructeur retourne un Element, ce qui permet de composer des chaînes fluentes — .AddChild(...), .Attr(...), .Style(...), .On<Event>(...) fonctionnent sur tous les widgets.

Texte et titres

Element.Stack()
    .AddChild(Element.Heading("Hello"))
    .AddChild(Element.Label("Welcome to the demo."))
    .AddChild(Element.Pre("(submit to see the payload)").Id("out"))

LinkLabel

Element.Link(text, url) émet un <a href> dont l'attribut onclick route via le navigateur de l'OS (xdg-open / open / ShellExecute). L'utilisateur n'atterrit jamais dans la webview.

Pour naviguer dans la même fenêtre, créez un new Element("a") et attachez votre propre .OnClick(h).

Boutons

Element.Button("Save")
    .OnClick((req: string) => req)        // echo the form
    .OnResult("out")                       // dump into #out

Enabled(false) produit un bouton désactivé grisé. Tooltip(t) ajoute une infobulle native de l'OS via l'attribut HTML title.

Saisies sur une ligne

Chaque name est collecté automatiquement par le pont d'état du formulaire — les handlers reçoivent un objet JSON dont les clés sont ces noms. Voir 03-events-and-state.md.

Element.Row()
    .AddChild(Element.Label("Quantity:").Size(120, 0))
    .AddChild(Element.Number("qty", 1, 100, 1))

Les valeurs min/max de Number sont 0 par défaut — passez (name, 0, 0, 0) pour laisser les trois attributs non définis.

Depuis la v0.0.5, Number est un composant composite (le <input type=number> plus une colonne de boutons verticaux ▲ / ▼). WebKitGTK ne dessine pas le ::-webkit-inner-spin-button natif, donc les boutons sont toujours visibles et se comportent de manière identique sur les trois moteurs OS.

Texte multi-lignes

Element.Textarea("message")
    .Attr("placeholder", "Type a message…")
    .Size(0, 80)        // height in px; 0 = auto width

Element.RichTextBox("notes")
    .Attr("placeholder-text", "Write notes here…")
    .Style("min-height:120px")

textarea n'est intentionnellement pas redimensionnable par défaut — la poignée de glissement déstabilise les mises en page déclaratives. Réactivez via .Style("resize:vertical") si nécessaire.

RichTextBox (v0.0.9) accepte le formatage en ligne via les raccourcis clavier intégrés du navigateur (Ctrl-B / Ctrl-I / Ctrl-U) et le contenu riche collé. Le payload du formulaire rapporte le contenu enrichi sous forme de HTML interne sous la clé name du widget.

Widgets booléens / de choix

Utilisez la variante *Label lorsque vous souhaitez que la légende soit cliquable — correspond à la propriété Text de WinForms et aux attentes des utilisateurs.

Element.Stack()
    .AddChild(Element.CheckBoxLabel("agree", "I agree to the terms"))
    .AddChild(Element.Row()
        .AddChild(Element.Label("Priority:").Size(120, 0))
        .AddChild(Element.RadioLabel("priority", "low",    "Low"))
        .AddChild(Element.RadioLabel("priority", "normal", "Normal")
            .Attr("checked", "checked"))
        .AddChild(Element.RadioLabel("priority", "high",   "High")))

Les boutons radio d'un même groupe name sont mutuellement exclusifs.

Listes

let cols: List<string> = ["Name", "Size", "Modified"]
let r1:  List<string> = ["readme.md", "2 KB", "today"]

Element.ListView(cols, "files-body")
    .AddChild(Element.ListViewRow(r1))

Le paramètre bodyId est l'id du <tbody> — passez-le lorsque vous utiliserez Page.AppendInner(win, bodyId, …) pour faire grandir le tableau au moment de l'exécution (voir 03-events-and-state.md). Passez "" pour omettre l'id.

Arborescence (v0.0.7)

Element.TreeView()
    .AddChild(Element.TreeNode("src")
        .AddChild(Element.TreeNode("parser")
            .AddChild(Element.TreeLeaf("ast.am"))
            .AddChild(Element.TreeLeaf("parser.am")))
        .AddChild(Element.TreeLeaf("main.am")))
    .AddChild(Element.TreeLeaf("README.md"))

Construit sur <details> / <summary>, donc le développement/réduction et la navigation clavier fonctionnent sans aucun JS. Passez .Attr("open", "open") sur un TreeNode pour le rendre développé par défaut. Le thème de base gère le caret ▶ rotatif, le fond au survol et l'indentation de 18 px via les variables --amc-*.

Widgets d'affichage

Element.Row()
    .AddChild(Element.Label("Loading:").Size(80, 0))
    .AddChild(Element.ProgressBar(42, 100))

Element.MonthCalendar("birthday", 2026, 5)

MonthCalendar (v0.0.9) affiche une grille mensuelle intégrée. L'en-tête (v0.0.10) porte ◀ / menu déroulant mois / menu déroulant année / ▶ pour permettre à l'utilisateur de naviguer directement vers n'importe quel mois ou année. Cliquer sur un jour le met en surbrillance et transmet la sélection sous forme de chaîne ISO YYYY-MM-DD sous la clé name du widget dans le payload du formulaire (la clé est absente si aucun jour n'est sélectionné).

Menus (v0.0.8)

La MenuBar rendue en HTML, compatible tous OS — même forme que le MenuStrip de WinForms, thématisée avec --amc-*. Une variante native OS (Win32 HMENU / NSMenu / GtkMenuBar) est prévue en opt-in via data-mode="native" en v0.1.0 ; l'API est d'ores et déjà compatible vers l'avant.

Element.MenuBar()
    .AddChild(Element.MenuItem("File")
        .AddChild(Element.MenuOption("New",   "amc_new"))
        .AddChild(Element.MenuOption("Open…", "amc_open"))
        .AddChild(Element.MenuSeparator())
        .AddChild(Element.MenuOption("Quit",  "amc_quit")))
    .AddChild(Element.MenuItem("Edit")
        .AddChild(Element.MenuOption("Undo",  "amc_undo")))

Liez chaque nom d'action via win.Bind("amc_new", handler). Un écouteur click global ferme tout menu ouvert lorsque l'utilisateur clique en dehors ; Escape ferme à la fois les menus déroulants de la barre de menus et le menu contextuel.

ContextMenu se rattache à l'élément hôte dont vous passez l'id et écoute l'événement DOM contextmenu :

let cm = Element.ContextMenu("workspace")
    .AddChild(Element.MenuOption("Cut",   "amc_cut"))
    .AddChild(Element.MenuOption("Copy",  "amc_copy"))
    .AddChild(Element.MenuSeparator())
    .AddChild(Element.MenuOption("Paste", "amc_paste"))

Element.Div().Id("workspace").Class("amc-ctx-target")
    .AddChild(cm)
    .AddChild( … your actual content … )

Conteneurs et mise en page

Ces éléments ne portent pas de données, ils organisent les enfants. Référence complète dans 04-layout-and-theme.md.

Element.GroupBox("Personal info")
    .AddChild(Element.Input("name").Attr("placeholder", "Name"))
    .AddChild(Element.Input("email").Attr("placeholder", "Email"))

SplitContainer (v0.0.8) prend une orientation ("row" → gauche/droite avec un séparateur vertical, "column" → haut/bas) et un ratio initial en pourcentage de 5 à 95 (par ex. 30 pour un découpage 30/70). Le séparateur est déplaçable à la souris, au stylet ou au toucher :

Element.SplitContainer("row", 30)
    .AddChild(Element.Stack().AddChild( … left pane … ))
    .AddChild(Element.Stack().AddChild( … right pane … ))

Boîtes de dialogue (v0.0.6 → v0.0.8)

Boîtes de message modales et sélecteurs de fichiers. Tous les points d'entrée sont des méthodes statiques sur Dialog, pas des constructeurs Element — ils ne s'insèrent pas dans l'arbre de la page ; ils s'affichent à la demande.

Boîtes de message (v0.0.6)

Le handler reçoit l'id du bouton cliqué dans req — "ok" / "cancel" / "yes" / "no" — ou "cancel" si l'utilisateur ferme avec Echap ou un clic sur l'arrière-plan.

Dialog.Confirm(win, "Quit?", "Discard unsaved changes?",
    (req: string) => {
        if (req == "ok") { win.Terminate() }
        return ""
    })

L'implémentation utilise l'élément HTML <dialog> — le piège de focus, la fermeture par Echap et le voile d'arrière-plan sont fournis gratuitement par le navigateur. L'en-tête porte un accent coloré (bleu / orange / rouge) selon le type.

Sélecteurs de fichiers (v0.0.7 + v0.0.8)

Dialog.OpenFileContent(win, ".txt,.json", false,
    (payload: string) => {
        // payload = ""  on cancel
        // payload = {"name":"notes.txt","content":"Hello, file…"} on success
        return ""
    })

Sorties de secours

Lorsqu'aucun constructeur ne convient :

// 1. Use a raw HTML tag — same fluent API as the builders.
new Element("aside")
    .Class("my-side-panel")
    .AddChild(Element.Label("Custom widget"))

// 2. Inject raw HTML inside an element.
Element.Div().Id("plot").Raw("<svg width=200 height=200>...</svg>")

Les deux formes produisent du HTML ordinaire ; le pont de collecte automatique fonctionne toujours pour tout [name] input à l'intérieur.

Pour des sorties de secours plus avancées — bibliothèques JS, primitives C personnalisées, surcharges CSS thématisées — voir 05-extending.md.

Accesseurs de propriétés (sur tout Element)

Miroir du panneau Propriétés du concepteur WinForms. Chacun retourne this pour permettre l'enchaînement.

Pour les événements (.OnClick, .OnChange, .OnFocus, …) voir 03-events-and-state.md.