# GTKX Widget Reference ## Common Props (All Widgets) | Prop | Type | Description | |------|------|-------------| | `hexpand` / `vexpand` | boolean | Expand to fill available space | | `halign` / `valign` | `Gtk.Align.START \| CENTER \| END \| FILL` | Alignment | | `marginStart/End/Top/Bottom` | number | Margins in pixels | | `sensitive` | boolean | Enabled/disabled state | | `visible` | boolean | Visibility | | `cssClasses` | string[] | CSS classes for styling | | `widthRequest` / `heightRequest` | number | Minimum size | --- ## Containers ### GtkBox Linear layout (horizontal or vertical). ```tsx {children} ``` ### GtkGrid 2D grid with explicit positioning using `GridChild`. ```tsx ``` **GridChild props:** `column`, `row`, `columnSpan`, `rowSpan` ### GtkStack Page container, shows one child at a time. ```tsx ``` **StackPage props:** `id` (optional), `title`, `iconName`, `needsAttention`, `badgeNumber` (AdwViewStack only) ### GtkNotebook Tabbed container with visible tabs. ```tsx ``` Custom tab widget: ```tsx ``` **NotebookPage props:** `label`, `tabExpand`, `tabFill` ### GtkPaned Resizable split with draggable divider. **Requires Slot components.** ```tsx ``` ### GtkOverlay Stack widgets on top of each other. First child is base layer, additional children need `OverlayChild` wrapper. Multiple children supported per overlay. ```tsx ``` ### GtkFixed Absolute positioning with optional 3D transforms. Use `x.FixedChild` wrapper for children. ```tsx ``` **FixedChild props:** `x`, `y` (pixel coordinates), `transform` (optional `Gsk.Transform`) ### GtkScrolledWindow Scrollable container. ```tsx ``` --- ## Virtual Lists All virtual list widgets use an `items` data prop and a `renderItem` function. Items are `{ id: string, value: T }` objects. ### GtkListView High-performance scrollable list with selection. ```tsx setSelectedId(ids[0])} items={items.map(item => ({ id: item.id, value: item }))} renderItem={(item: Item) => } /> ``` ### GtkGridView Grid-based virtual scrolling. ```tsx ({ id: item.id, value: item }))} renderItem={(item: Item) => ( )} /> ``` ### GtkColumnView Table with sortable columns. ```tsx ({ id: item.id, value: item }))} > } /> } /> ``` ### GtkDropDown Selection dropdown. ```tsx ({ id: opt.id, value: opt.label }))} /> ``` ### GtkListView (tree mode) Hierarchical tree with expand/collapse. Items with nested `children` arrays trigger tree behavior. ```tsx setSelectedId(ids[0])} items={files.map(file => ({ id: file.id, value: file, children: file.children?.map(child => ({ id: child.id, value: child })), }))} renderItem={(item: FileNode, row) => ( )} /> ``` **ListItem data props:** `id`, `value`, `children` (nested items for tree mode), `hideExpander`, `indentForDepth`, `indentForIcon`, `section` (for sectioned lists) --- ## Inputs ### GtkEntry Single-line text input. **Requires two-way binding.** ```tsx const [text, setText] = useState(""); setText(e.getText())} placeholderText="Enter text..." /> ``` ### GtkToggleButton Toggle button. Auto-prevents signal feedback loops. ```tsx setIsActive(!isActive)} label="Toggle" /> ``` ### GtkCheckButton Checkbox. ```tsx setChecked(!checked)} label="Option" /> ``` ### GtkSwitch On/off switch. ```tsx { setEnabled(!enabled); return true; }} /> ``` ### GtkSpinButton Numeric input with increment/decrement. Adjustment props are set directly. ```tsx ``` ### GtkScale Slider with adjustment props and optional marks. ```tsx ``` **Adjustment props:** `value`, `lower`, `upper`, `stepIncrement`, `pageIncrement`, `pageSize`, `onValueChanged` **ScaleMark type:** `{ value: number, position?: Gtk.PositionType, label?: string }` ### GtkCalendar Date picker with markable days. ```tsx setDate(cal.getDate())} markedDays={[15, 20, 25]} /> ``` ### GtkLevelBar Progress/level indicator with customizable thresholds. ```tsx ``` **LevelBarOffset type:** `{ id: string, value: number }` --- ## Display ### GtkLabel ```tsx ``` ### GtkButton ```tsx ``` ### GtkImage ```tsx ``` --- ## Header & Action Bars ### GtkHeaderBar Title bar with packed widgets. Use `x.ContainerSlot` for packing and `x.Slot` for titleWidget. ```tsx ``` ### GtkActionBar Bottom action bar. ```tsx ``` --- ## Menus ### GtkPopoverMenu with GtkMenuButton ```tsx ``` **Menu.Item props:** `id` (required), `label`, `onActivate`, `accels` (e.g., `"n"`) --- ## Windows ### GtkApplicationWindow ```tsx ``` Custom titlebar: ```tsx ``` --- ## Adwaita (Libadwaita) Import: `import * as Adw from "@gtkx/ffi/adw";` ### AdwApplicationWindow + AdwToolbarView Modern app structure. ```tsx ``` ### AdwStatusPage Welcome, error, or empty state. ```tsx ``` ### AdwBanner Dismissable notification. ```tsx setShow(false)} /> ``` ### AdwPreferencesPage / AdwPreferencesGroup Settings UI. ```tsx setDark(!dark)} /> ``` **ActionRow children:** Use `x.ContainerSlot for={AdwActionRow} id="addPrefix"` for left widgets, `x.ContainerSlot for={AdwActionRow} id="addSuffix"` for right widgets, or `x.Slot for={AdwActionRow} id="activatableWidget"` for clickable suffix. ### AdwExpanderRow Expandable settings row with optional action widget. ```tsx ``` **ExpanderRow slots:** `x.ContainerSlot for={AdwExpanderRow} id="addRow"` for nested rows, `x.ContainerSlot for={AdwExpanderRow} id="addAction"` for header action widget. Direct children also work for simple cases. ### AdwEntryRow / AdwPasswordEntryRow Input in list row. ```tsx setUsername(e.getText())} /> ``` ### AdwToggleGroup Segmented button group for mutually exclusive options. ```tsx const [mode, setMode] = useState("list"); setMode(name ?? "list")}> ``` **ToggleGroup props:** `activeName`, `active` (index), `onActiveChanged` (callback with index and name) **Toggle props:** `id` (optional), `label`, `iconName`, `tooltip`, `enabled` ### AdwNavigationView Stack-based navigation with history. ```tsx const [history, setHistory] = useState(["home"]); setHistory([...history, "details"])} /> ``` **NavigationPage props:** `for` (required, parent widget type), `id` (required), `title`, `canPop`. Control navigation via `history` array. ### AdwNavigationSplitView Sidebar/content split layout for master-detail interfaces. ```tsx const [selected, setSelected] = useState(items[0]); { if (!row) return; const item = items[row.getIndex()]; if (item) setSelected(item); }}> {items.map((item) => )} ``` **Props:** `sidebarWidthFraction`, `minSidebarWidth`, `maxSidebarWidth`, `collapsed`, `showContent`. **NavigationPage:** Use `for={AdwNavigationSplitView}` with `id="sidebar"` for left pane, `id="content"` for right pane. **Selection:** Use `GtkListBox` with `onRowSelected` (single click) not `onRowActivated` (double click). ### AdwAlertDialog Modern modal alert dialogs with response buttons. ```tsx const [showDialog, setShowDialog] = useState(false); {showDialog && ( { if (id === "delete") handleDelete(); setShowDialog(false); }} > )} ``` **AlertDialogResponse props:** `id`, `label`, `appearance` (SUGGESTED, DESTRUCTIVE), `enabled` ### GtkColorDialogButton / GtkFontDialogButton Color and font picker dialogs. ```tsx ``` ### Other Adwaita Widgets | Widget | Description | |--------|-------------| | `AdwClamp` | Limits content width (`maximumSize={600}`) | | `AdwAvatar` | User avatar (`size={48} text="Name" showInitials`) | | `AdwSpinner` | Loading indicator | | `AdwWindowTitle` | Title + subtitle for header bars | | `AdwButtonRow` | Button styled as list row | --- ## Animations Wrap widgets in `x.Animation` for declarative animations with spring or timed transitions: ```tsx console.log("done")} > ... ``` **Props:** `initial`, `animate`, `exit`, `transition` (`AnimationTransition` discriminated union), `animateOnMount`, `onAnimationStart`, `onAnimationComplete` **Spring transition:** `{ mode: "spring", damping, stiffness, mass, initialVelocity, clamp, delay }` **Timed transition:** `{ mode: "timed", duration, easing (from Adw.Easing), delay, repeat, reverse, alternate }` --- ## Drag and Drop All widgets support drag-and-drop through props. Use `onDragPrepare`, `onDragBegin`, and `onDragEnd` to make a widget draggable, and `dropTypes`, `onDrop`, `onDropEnter`, and `onDropLeave` to accept drops. ```tsx import * as Gdk from "@gtkx/ffi/gdk"; import { Type, Value } from "@gtkx/ffi/gobject"; const DraggableButton = ({ label }: { label: string }) => ( Gdk.ContentProvider.newForValue(Value.newFromString(label))} dragIcon={someTexture} dragIconHotX={16} dragIconHotY={16} /> ); const DropZone = () => { const [dropped, setDropped] = useState(null); return ( { setDropped(value.getString()); return true; }} > ); }; ``` **Drag source props:** `dragIcon`, `dragIconHotX`, `dragIconHotY` ## GValue Factories Create typed values for drag-and-drop and signal emission: | Factory | Description | | ------------------------------ | ----------------------------- | | `Value.newFromString(str)` | String values | | `Value.newFromDouble(num)` | 64-bit floating point | | `Value.newFromInt(num)` | 32-bit signed integer | | `Value.newFromBoolean(bool)` | Boolean values | | `Value.newFromObject(obj)` | GObject instances | | `Value.newFromBoxed(boxed)` | Boxed types (Gdk.RGBA, etc.) | | `Value.newFromEnum(gtype, n)` | Enum values (requires GType) | | `Value.newFromFlags(gtype, n)` | Flags values (requires GType) | Type constants for `dropTypes`: `Type.STRING`, `Type.INT`, `Type.DOUBLE`, `Type.BOOLEAN`, `Type.OBJECT`. ## Custom Drawing Render custom graphics with `GtkDrawingArea` using the `render` callback: ```tsx import type { Context } from "@gtkx/ffi/cairo"; const Canvas = () => { const handleDraw = (cr: Context, width: number, height: number) => { cr.setSourceRgb(0.2, 0.4, 0.8); cr.rectangle(10, 10, width - 20, height - 20); cr.fill(); }; return ; }; ``` Changing the `render` callback reference automatically queues a redraw. Add a `GtkGestureDrag` child for interactive drawing. ## Event Controllers Event controllers are added as children to any widget. They are auto-generated from GTK's introspection data. ```tsx console.log("Entered at", x, y)} onMotion={(x, y) => setPosition({ x, y })} onLeave={() => console.log("Left")} /> { console.log("Key pressed:", keyval); return false; }} /> console.log("Clicked")} /> ``` **Input controllers:** `GtkEventControllerMotion`, `GtkEventControllerKey`, `GtkEventControllerScroll`, `GtkEventControllerFocus` **Gesture controllers:** `GtkGestureClick`, `GtkGestureDrag`, `GtkGestureLongPress`, `GtkGestureZoom`, `GtkGestureRotate`, `GtkGestureSwipe`, `GtkGestureStylus`, `GtkGesturePan` **Drag-and-drop:** `GtkDragSource`, `GtkDropTarget`, `GtkDropControllerMotion` ## SearchBar ```tsx const [searchActive, setSearchActive] = useState(false); setQuery(entry.getText())} /> ``` The `onSearchModeChanged` callback fires when search mode changes (e.g., user presses Escape). ## TextView / SourceView Text content is provided as direct children. Use `x.TextTag` for formatting and `x.TextAnchor` for embedded widgets. ```tsx console.log(text)}> Normal text, bold, and inline. ``` **TextView props:** `enableUndo`, `onBufferChanged`, `onTextInserted`, `onTextDeleted`, `onCanUndoChanged`, `onCanRedoChanged` **TextTag props:** `id` (required), `priority`, `foreground`, `background`, `weight`, `style`, `underline`, `strikethrough`, `family`, `size`, `sizePoints`, `scale`, `justification`, `leftMargin`, `rightMargin`, `indent`, `editable`, `invisible` **TextAnchor:** Embeds widgets inline with `children` **TextPaintable:** Embeds images inline with `paintable` prop ```tsx {code} ``` **SourceView additional props:** `language`, `styleScheme`, `highlightSyntax`, `highlightMatchingBrackets`, `implicitTrailingNewline`, `onCursorMoved`, `onHighlightUpdated` ## Keyboard Shortcuts Attach shortcuts with `` and `x.Shortcut`: ```tsx setCount((c) => c + 1)} /> setCount((c) => c - 1)} /> ``` **Scopes:** `LOCAL` (widget focus), `MANAGED` (parent managed), `GLOBAL` (window-wide) **Trigger syntax:** `s`, `s`, `F4`, `q`, `F5` **Multiple triggers:** `trigger={["F5", "r"]}`