gtk

Kind	ffi-zig
Capabilities	ffi file
Categories	gui ffi
Keywords	gtk gtk4 gui linux zig-ffi

GTK 4 application and window foundation for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/simple/`	Current developer-facing simple demos
`examples/simple/hello-world.kit`	Minimal GTK window example
`examples/simple/counter.kit`	Simple stateful UI example
`examples/simple/file-open.kit`	File dialog example
`examples/simple/form.kit`	Form and input example
`examples/simple/grid.kit`	Grid layout example
`examples/simple/settings.kit`	Settings-backed UI example
`examples/simple/todo-list.kit`	List model and view example
`examples/simple/widgets.kit`	Interactive widget showcase covering the current public surface
`examples/canonical/`	Canonical GTK example ports
`examples/linux-packaging.md`	Linux packaging notes
`kit.toml`	Package manifest with metadata, dependencies, and native requirements
`src/gtk.kit`	Public Kit API for GTK bindings
`tests/lifecycle.test.kit`	Lifecycle tests
`tests/model-view.test.kit`	Model/view tests
`tests/widget-behavior.test.kit`	Widget behavior tests
`tests/widget-state.test.kit`	Widget state tests
`zig/gtk.zig`	Zig FFI implementation
`zig/kit_ffi.zig`	Shared Zig FFI helpers

Dependencies

Kit package dependencies:

kit-glib

System packages:

macOS: brew install gtk4 pkg-config
Ubuntu: apt install libgtk-4-dev pkg-config
Fedora: dnf install gtk4-devel pkgconf-pkg-config

Installation

kit add gitlab.com/kit-lang/packages/kit-gtk.git

Usage

import GLib
import GTK

build-ui = fn(app) =>
  window = GTK.Window.new app "Hello World" |> Result.unwrap
  box = GTK.Box.vertical 12 |> Result.unwrap
  label = GTK.Label.new "Hello from Kit" |> Result.unwrap
  button = GTK.Button.new "Dismiss" |> Result.unwrap

  GTK.Box.append box label |> Result.unwrap
  GTK.Box.append box button |> Result.unwrap
  GTK.Window.set-child window box |> Result.unwrap
  GTK.Button.on-click button (fn(_) =>
    GTK.Window.close window |> Result.unwrap
  ) |> Result.unwrap
  GTK.Window.present window |> Result.unwrap

main = fn =>
  app = GTK.Application.new "dev.kitlang.helloworld" |> Result.unwrap
  GTK.Application.on-activate app build-ui |> Result.unwrap
  GTK.Application.run app |> Result.unwrap

main

The current API surface includes:

application and window lifecycle
core widgets, layout containers, and styling hooks
dialogs, file selection, and assets
list, selection, filter, and sort model support
action, shortcut, and signal plumbing built on kit-glib

Development

Running Examples

Run a GTK example with the interpreter:

kit run examples/simple/widgets.kit --allow=ffi,file

Compile an example to a native binary:

kit build examples/simple/widgets.kit -o widgets --allow=ffi,file && ./widgets

For headless Linux CI or VM runs, use xvfb-run -a.

Running Tests

Run the package tests:

kit test tests/ --allow=ffi,file

Running kit dev

Run the standard development workflow:

kit dev --no-spinner

Linux Packaging

See examples/linux-packaging.md for notes on packaging compiled Kit GTK applications with assets, icons, and desktop entries.

Cleaning Build Artifacts

Remove generated files, caches, and native build outputs:

kit task clean

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/gtk/, making it available for import as GTK in other projects.

License

This package is released under the MIT License. See LICENSE for details.

Exported Functions & Types

`GTKError`

Narrow GTK error used by the first native wrapper slice.

Variants

GTKError {message}

`ApplicationRef`

Opaque reference to a native GtkApplication.

Variants

ApplicationRef {handle}

`WindowRef`

Opaque reference to a native GtkWindow.

Variants

WindowRef {handle}

`BuilderRef`

Opaque reference to a native GtkBuilder.

Variants

BuilderRef {handle}

`WidgetRef`

Opaque reference to a native GtkWidget.

Variants

WidgetRef {handle}

`BoxRef`

Opaque reference to a native GtkBox.

Variants

BoxRef {handle}

`ScrolledWindowRef`

Opaque reference to a native GtkScrolledWindow.

Variants

ScrolledWindowRef {handle}

`GridRef`

Opaque reference to a native GtkGrid.

Variants

GridRef {handle}

`CenterBoxRef`

Opaque reference to a native GtkCenterBox.

Variants

CenterBoxRef {handle}

`ListBoxRef`

Opaque reference to a native GtkListBox.

Variants

ListBoxRef {handle}

`ListBoxRowRef`

Opaque reference to a native GtkListBoxRow.

Variants

ListBoxRowRef {handle}

`FlowBoxRef`

Opaque reference to a native GtkFlowBox.

Variants

FlowBoxRef {handle}

`FlowBoxChildRef`

Opaque reference to a native GtkFlowBoxChild.

Variants

FlowBoxChildRef {handle}

`PanedRef`

Opaque reference to a native GtkPaned.

Variants

PanedRef {handle}

`StackRef`

Opaque reference to a native GtkStack.

Variants

StackRef {handle}

`StackSwitcherRef`

Opaque reference to a native GtkStackSwitcher.

Variants

StackSwitcherRef {handle}

`HeaderBarRef`

Opaque reference to a native GtkHeaderBar.

Variants

HeaderBarRef {handle}

`PopoverRef`

Opaque reference to a native GtkPopover.

Variants

PopoverRef {handle}

`OverlayRef`

Opaque reference to a native GtkOverlay.

Variants

OverlayRef {handle}

`RevealerRef`

Opaque reference to a native GtkRevealer.

Variants

RevealerRef {handle}

`ExpanderRef`

Opaque reference to a native GtkExpander.

Variants

ExpanderRef {handle}

`FrameRef`

Opaque reference to a native GtkFrame.

Variants

FrameRef {handle}

`ListStoreRef`

Opaque reference to a native GListStore containing GtkStringObject items.

Variants

ListStoreRef {handle}

`StringListRef`

Opaque reference to a native GtkStringList.

Variants

StringListRef {handle}

`StringObjectRef`

Opaque reference to a native GtkStringObject.

Variants

StringObjectRef {handle}

`CustomFilterRef`

Opaque reference to a native GtkCustomFilter.

Variants

CustomFilterRef {handle}

`FilterListModelRef`

Opaque reference to a native GtkFilterListModel.

Variants

FilterListModelRef {handle}

`CustomSorterRef`

Opaque reference to a native GtkCustomSorter.

Variants

CustomSorterRef {handle}

`SortListModelRef`

Opaque reference to a native GtkSortListModel.

Variants

SortListModelRef {handle}

`NoSelectionRef`

Opaque reference to a native GtkNoSelection.

Variants

NoSelectionRef {handle}

`MultiSelectionRef`

Opaque reference to a native GtkMultiSelection.

Variants

MultiSelectionRef {handle}

`SingleSelectionRef`

Opaque reference to a native GtkSingleSelection.

Variants

SingleSelectionRef {handle}

`FileChooserRef`

Opaque reference to a native GtkFileChooserNative.

Variants

FileChooserRef {handle}

`DropdownRef`

Opaque reference to a native GtkDropDown.

Variants

DropdownRef {handle}

`ListViewRef`

Opaque reference to a native GtkListView.

Variants

ListViewRef {handle}

`GridViewRef`

Opaque reference to a native GtkGridView.

Variants

GridViewRef {handle}

`ColumnViewRef`

Opaque reference to a native GtkColumnView.

Variants

ColumnViewRef {handle}

`ColumnViewColumnRef`

Opaque reference to a native GtkColumnViewColumn.

Variants

ColumnViewColumnRef {handle}

`SignalListItemFactoryRef`

Opaque reference to a native GtkSignalListItemFactory.

Variants

SignalListItemFactoryRef {handle}

`ListItemRef`

Opaque reference to a native GtkListItem.

Variants

ListItemRef {handle}

`LabelRef`

Opaque reference to a native GtkLabel.

Variants

LabelRef {handle}

`LevelBarRef`

Opaque reference to a native GtkLevelBar.

Variants

LevelBarRef {handle}

`ProgressBarRef`

Opaque reference to a native GtkProgressBar.

Variants

ProgressBarRef {handle}

`ButtonRef`

Opaque reference to a native GtkButton.

Variants

ButtonRef {handle}

`MenuButtonRef`

Opaque reference to a native GtkMenuButton.

Variants

MenuButtonRef {handle}

`LinkButtonRef`

Opaque reference to a native GtkLinkButton.

Variants

LinkButtonRef {handle}

`ShortcutLabelRef`

Opaque reference to a native GtkShortcutLabel.

Variants

ShortcutLabelRef {handle}

`SeparatorRef`

Opaque reference to a native GtkSeparator.

Variants

SeparatorRef {handle}

`CheckButtonRef`

Opaque reference to a native GtkCheckButton.

Variants

CheckButtonRef {handle}

`ToggleButtonRef`

Opaque reference to a native GtkToggleButton.

Variants

ToggleButtonRef {handle}

`SwitchRef`

Opaque reference to a native GtkSwitch.

Variants

SwitchRef {handle}

`SpinnerRef`

Opaque reference to a native GtkSpinner.

Variants

SpinnerRef {handle}

`ScaleRef`

Opaque reference to a native GtkScale.

Variants

ScaleRef {handle}

`ScaleButtonRef`

Opaque reference to a native GtkScaleButton.

Variants

ScaleButtonRef {handle}

`SpinButtonRef`

Opaque reference to a native GtkSpinButton.

Variants

SpinButtonRef {handle}

`TextViewRef`

Opaque reference to a native GtkTextView.

Variants

TextViewRef {handle}

`TextBufferRef`

Opaque reference to a native GtkTextBuffer.

Variants

TextBufferRef {handle}

`TextTagRef`

Opaque reference to a native GtkTextTag.

Variants

TextTagRef {handle}

`EntryRef`

Opaque reference to a native GtkEntry.

Variants

EntryRef {handle}

`SearchEntryRef`

Opaque reference to a native GtkSearchEntry.

Variants

SearchEntryRef {handle}

`SearchBarRef`

Opaque reference to a native GtkSearchBar.

Variants

SearchBarRef {handle}

`PasswordEntryRef`

Opaque reference to a native GtkPasswordEntry.

Variants

PasswordEntryRef {handle}

`AspectFrameRef`

Opaque reference to a native GtkAspectFrame.

Variants

AspectFrameRef {handle}

`FixedRef`

Opaque reference to a native GtkFixed.

Variants

FixedRef {handle}

`ViewportRef`

Opaque reference to a native GtkViewport.

Variants

ViewportRef {handle}

`WindowHandleRef`

Opaque reference to a native GtkWindowHandle.

Variants

WindowHandleRef {handle}

`WindowControlsRef`

Opaque reference to a native GtkWindowControls.

Variants

WindowControlsRef {handle}

`ActionBarRef`

Opaque reference to a native GtkActionBar.

Variants

ActionBarRef {handle}

`AssistantRef`

Opaque reference to a native GtkAssistant.

Variants

AssistantRef {handle}

`InfoBarRef`

Opaque reference to a native GtkInfoBar.

Variants

InfoBarRef {handle}

`StatusbarRef`

Opaque reference to a native GtkStatusbar.

Variants

StatusbarRef {handle}

`EmojiChooserRef`

Opaque reference to a native GtkEmojiChooser.

Variants

EmojiChooserRef {handle}

`FontButtonRef`

Opaque reference to a native GtkFontButton.

Variants

FontButtonRef {handle}

`ColorButtonRef`

Opaque reference to a native GtkColorButton.

Variants

ColorButtonRef {handle}

`AboutDialogRef`

Opaque reference to a native GtkAboutDialog.

Variants

AboutDialogRef {handle}

`VideoRef`

Opaque reference to a native GtkVideo.

Variants

VideoRef {handle}

`DrawingAreaRef`

Opaque reference to a native GtkDrawingArea.

Variants

DrawingAreaRef {handle}

`DrawContextRef`

Opaque reference to a native Cairo drawing context.

Variants

DrawContextRef {handle}

`ImageSurfaceRef`

Opaque reference to a native Cairo image surface.

Variants

ImageSurfaceRef {handle}

`GestureDragRef`

Opaque reference to a native GtkGestureDrag.

Variants

GestureDragRef {handle}

`GestureClickRef`

Opaque reference to a native GtkGestureClick.

Variants

GestureClickRef {handle}

`CalendarRef`

Opaque reference to a native GtkCalendar.

Variants

CalendarRef {handle}

`GLAreaRef`

Opaque reference to a native GtkGLArea.

Variants

GLAreaRef {handle}

`MediaFileRef`

Opaque reference to a native GtkMediaFile.

Variants

MediaFileRef {handle}

`MediaControlsRef`

Opaque reference to a native GtkMediaControls.

Variants

MediaControlsRef {handle}

`ImageRef`

Opaque reference to a native image widget.

Variants

ImageRef {handle}

`Application`

Minimal application API for the first vertical GTK slice.

`Window`

Minimal top-level window API for the first vertical GTK slice.

`Builder`

Minimal builder helpers for loading UI descriptions and fetching named objects.

`Widget`

Generic widget helpers for the current GTK MVP slice.

`Box`

Basic box layout helpers returning opaque widget refs.

`ScrolledWindow`

Minimal scroll container helpers.

`Grid`

Minimal grid layout helpers.

`CenterBox`

Minimal center-box helpers for three-part header and footer composition.

`ListBox`

Minimal list container helpers.

`ListBoxRow`

Minimal list-box-row helpers for explicit row composition.

`FlowBox`

Minimal flow-box helpers for wrapping child layouts.

`FlowBoxChild`

Minimal flow-box-child helpers for explicit wrapped-item composition.

`Paned`

Minimal paned helpers for split-view layouts.

`Stack`

Minimal stack helpers for named page switching.

`StackSwitcher`

Minimal stack-switcher helpers for stack navigation controls.

`HeaderBar`

Minimal header-bar helpers for window chrome composition.

`Popover`

Minimal popover helpers for transient attached content.

`Overlay`

Minimal overlay helpers for stacked child composition.

`Revealer`

Minimal revealer helpers for animated show and hide composition.

`Expander`

Minimal expander helpers for collapsible content sections.

`Frame`

Minimal framed container helpers for grouped content.

`ListStore`

Mutable string-object-backed list store for general list-model workflows.

`StringList`

Simple string-list model helpers for dropdown-backed selection UIs.

`ListModel`

Generic list-model read helpers for StringList-backed models.

`StringObject`

String-object helpers exposed to model filter callbacks.

`CustomFilter`

Minimal custom-filter helpers for StringList-backed models.

`FilterListModel`

Minimal filtered-list-model helpers for derived StringList views.

`CustomSorter`

Minimal custom-sorter helpers for StringList-backed models.

`SortListModel`

Minimal sorted-list-model helpers for derived StringList views.

`NoSelection`

Minimal selection-model helpers for list-backed model/view widgets.

`MultiSelection`

Minimal multi-selection helpers for list-backed model/view widgets.

`SingleSelection`

Minimal single-selection helpers for model/view widgets.

`Dropdown`

Minimal dropdown helpers using the generic widget ref.

`ListView`

Minimal list-view helpers backed by a selection model.

`GridView`

Minimal grid-view helpers backed by a selection model.

`ColumnView`

Minimal column-view helpers backed by a selection model.

`ColumnViewColumn`

Minimal column-view-column helpers for StringList-backed columns.

`SignalListItemFactory`

Minimal signal-list-item-factory helpers for StringList-backed views.

`ListItem`

Minimal list-item helpers exposed to signal-list-item-factory callbacks.

`Label`

Minimal label widget helpers.

`LevelBar`

Minimal level-bar helpers for bounded progress/level feedback.

`ProgressBar`

Minimal progress-bar helpers for determinate and pulsing progress UI.

`Button`

Minimal button widget helpers.

`MenuButton`

Minimal menu-button helpers for popover-backed menus.

`LinkButton`

Minimal link-button helpers for URI-backed actions.

`ShortcutLabel`

Minimal shortcut-label helpers for accelerator display.

`Separator`

Minimal separator helpers for simple visual grouping.

`CheckButton`

Minimal check-button helpers using the generic widget ref.

`ToggleButton`

Minimal toggle-button helpers for latched button state.

`Switch`

Minimal switch helpers using the generic widget ref.

`Spinner`

Minimal spinner helpers for loading/status feedback.

`Scale`

Minimal slider helpers for bounded numeric input.

`ScaleButton`

Minimal scale-button helpers for compact numeric adjustment UI.

`SpinButton`

Minimal spin-button helpers for numeric entry with step controls.

`TextView`

Minimal text-view helpers using the generic widget ref.

`TextBuffer`

Narrow text-buffer helpers for styled content loaded into text views.

`Entry`

Minimal entry widget helpers.

`SearchEntry`

Minimal search-entry helpers for search-specific text input.

`SearchBar`

Minimal search-bar helpers for search entry composition and mode state.

`PasswordEntry`

Minimal password-entry helpers for secret text input.

`AspectFrame`

Minimal aspect-frame helpers for ratio-constrained layout.

`Fixed`

Minimal fixed-layout helpers for absolute positioning.

`Viewport`

Minimal viewport helpers for wrapping a single child in a scrollable viewport.

`WindowHandle`

Minimal window-handle helpers for draggable titlebar content.

`WindowControls`

Minimal window-controls helpers for titlebar button groups.

`ActionBar`

Minimal action-bar helpers for bottom command rows.

`Video`

Minimal video helpers for autoplay and loop state.

`DrawingArea`

Minimal drawing-area helpers for content size state.

`DrawContext`

Minimal Cairo helpers for drawing-area callbacks and offscreen image surfaces.

`ImageSurface`

Minimal Cairo image-surface helpers for interactive drawing examples.

`Gesture`

Shared mouse button constants for gesture controllers.

`GestureDrag`

Minimal drag-gesture helpers for drawing interactions.

`GestureClick`

Minimal click-gesture helpers for discrete press interactions.

`Calendar`

Minimal calendar helpers for day marks and heading visibility.

`GLArea`

Minimal GL-area helpers for render-state configuration.

`MediaFile`

Minimal media-file helpers for GTK media streams backed by files.

`MediaControls`

Minimal media-controls helpers for binding a media stream to playback controls.

`FontButton`

Minimal font-button helpers for font dialog state.

`Assistant`

Minimal assistant helpers for multi-page wizard state.

`InfoBar`

Minimal info-bar helpers for inline message UI.

`Statusbar`

Minimal statusbar helpers for contextual status messages.

`EmojiChooser`

Minimal emoji-chooser helper.

`ColorButton`

Minimal color-button helpers for dialog title and modal state.

`AboutDialog`

Minimal about-dialog helpers for program metadata.

`Image`

Minimal image helper backed by GTK picture widgets.

`FileChooser`

Minimal native file chooser helpers for open-file flows.

`Style`

Global styling helper for loading CSS files into the default display.

`Dialog`

Minimal message dialog helper built from current window/widget primitives.