gtk4

README

gtk4

Drive GTK4 from pure Go with CGO_ENABLED=0 — windows, the common controls, GObject signals and the GLib main loop — over ebitengine/purego.

It is the Linux sibling of go-macos/objc: the shared native-toolkit bridge a go-widgets host backend embeds real controls through, so a pixel-drawn app can inlay a real GtkEntry, GtkButton or secure field over its own rendering.

ok, err := gtk4.Init()
// win := gtk4.WindowNew(); win.SetTitle("…"); win.SetDefaultSize(360, 200)
// fixed := gtk4.FixedNew()          // the overlay container
// e := gtk4.EntryNew(); e.SetVisibility(false) // a password field
// b := gtk4.ButtonNewWithLabel("OK")
// b.Connect("clicked", func() { … }) // a GObject signal, as a Go closure
// fixed.Put(e, 10, 10); fixed.Put(b, 10, 44); win.SetChild(fixed); win.Present()

No cgo

libgtk-4, libgobject-2.0 and libglib-2.0 are dlopen'd by soname and every entry point is resolved with purego.RegisterLibFunc. A GObject signal reaches Go through a purego.NewCallback, retained for the process life (GTK holds the C pointer). The package links with no cgo and cross-compiles like any other Go code.

What it binds

Init · WindowNew (+ SetTitle/SetDefaultSize/SetChild/Present) · FixedNew (+ Put/Move — absolute overlay positioning) · ButtonNewWithLabel (+ SetLabel) · EntryNew (+ SetVisibility for a secure field) · CheckButtonNewWithLabel (+ Active/SetActive; grouped check buttons are GTK radios) · LabelNew · Text/SetText (GtkEditable) · SetSizeRequest · SetVisible · Unparent · Connect (signals) · MainLoop (Run/Quit) · IdleAdd (marshal onto the GTK thread).

Platform

Linux only — this is the GTK path; a go-widgets host uses AppKit/Win32 on macOS/Windows. Off Linux the package still compiles (a consumer cross-compiles without a build tag) and every constructor's Init returns ErrUnsupported, so nothing is a build-time surprise. It needs only the runtime libgtk-4 (libgtk-4-1 on Debian/Ubuntu) — no -dev package.

Testing

CI builds it on every platform and runs a live test against real GTK4 under a headless X server (Xvfb) — creating a window, entry, secure field, button and check button, round-tripping their values, and proving a changed signal reaches Go through the main loop.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package gtk4 binds the parts of GTK4 a windowing toolkit needs — windows, the common controls, GObject signals and the GLib main loop — from pure Go with CGO_ENABLED=0, over github.com/ebitengine/purego. It is the Linux sibling of github.com/go-macos/objc: the shared native-toolkit bridge a go-widgets host backend embeds real controls through.

It links no cgo: libgtk-4, libgobject-2.0 and libglib-2.0 are dlopen'd by soname and every entry point is resolved with purego.RegisterLibFunc, exactly as the feasibility spike proved on a stock Linux GTK4. A GObject signal reaches Go through a purego.NewCallback, so a control's clicks and edits are ordinary Go closures.

Index

• Constants
• Variables
• func IdleAdd(fn func())
• func Init() (ok bool, err error)
• func KeyvalToUnicode(keyval uint) rune
• func TextureFromRGBA(data []byte, width, height int) uintptr
• type MainLoop
  • func MainLoopNew() MainLoop
  • func (l MainLoop) Quit()
  • func (l MainLoop) Run()
• type Picture
  • func PictureNew() Picture
  • func (p Picture) SetRGBA(data []byte, width, height int)
  • func (p Picture) Widget() Widget
• type Widget
  • func BoxNew(horizontal bool) Widget
  • func ButtonNewWithLabel(label string) Widget
  • func CheckButtonNewWithLabel(label string) Widget
  • func ColorNew() Widget
  • func ComboNew(items []string) Widget
  • func DateNew() Widget
  • func DrawingAreaNew() Widget
  • func EntryNew() Widget
  • func FixedNew() Widget
  • func LabelNew(text string) Widget
  • func LinkNew(label string) Widget
  • func ListBoxNew() Widget
  • func PopUpNew(items []string) Widget
  • func ProgressNew() Widget
  • func SearchNew() Widget
  • func SliderNew(min, max, step float64) Widget
  • func SpinnerNew() Widget
  • func StepperNew(min, max, step float64) Widget
  • func TextViewNew() Widget
  • func ToggleButtonNewWithLabel(label string) Widget
  • func WindowNew() Widget
  • func (w Widget) Active() bool
  • func (w Widget) AddTickCallback(fn func() bool) uint64
  • func (w Widget) Append(child Widget)
  • func (w Widget) Buffer() Widget
  • func (w Widget) ColorHex() string
  • func (w Widget) ComboText() string
  • func (w Widget) Connect(signal string, fn func()) uint64
  • func (w Widget) ConnectBufferChanged(fn func()) uint64
  • func (w Widget) DateISO() string
  • func (w Widget) ListBoxAppendText(text string)
  • func (f Widget) Move(child Widget, x, y float64)
  • func (w Widget) OnActivateLink(fn func()) uint64
  • func (w Widget) OnKey(fn func(keyval, keycode, state uint, press bool))
  • func (w Widget) OnMotion(fn func(state uint, x, y float64))
  • func (w Widget) OnMouseDown(fn func(button int, state uint, x, y float64))
  • func (w Widget) OnMouseUp(fn func(button int, state uint, x, y float64))
  • func (w Widget) OnScroll(fn func(dx, dy float64, state uint))
  • func (w Widget) Present()
  • func (f Widget) Put(child Widget, x, y float64)
  • func (w Widget) QueueDraw()
  • func (w Widget) SelectRow(i int)
  • func (w Widget) Selected() int
  • func (w Widget) SelectedRow() int
  • func (w Widget) SetActive(on bool)
  • func (w Widget) SetChild(child Widget)
  • func (w Widget) SetColorHex(s string)
  • func (w Widget) SetComboText(s string)
  • func (w Widget) SetDateISO(s string)
  • func (w Widget) SetDefaultSize(width, height int)
  • func (w Widget) SetFraction(f float64)
  • func (w Widget) SetGroup(group Widget)
  • func (w Widget) SetLabel(label string)
  • func (w Widget) SetSelected(i int)
  • func (w Widget) SetSizeRequest(width, height int)
  • func (w Widget) SetSpinValue(v float64)
  • func (w Widget) SetText(s string)
  • func (w Widget) SetTextViewText(s string)
  • func (w Widget) SetTitle(title string)
  • func (w Widget) SetValue(v float64)
  • func (w Widget) SetVisibility(vis bool)
  • func (w Widget) SetVisible(vis bool)
  • func (w Widget) SpinValue() float64
  • func (w Widget) Start()
  • func (w Widget) Stop()
  • func (w Widget) Text() string
  • func (w Widget) TextViewText() string
  • func (w Widget) Unparent()
  • func (w Widget) Value() float64

Constants

const (
	ModShift   uint = 1 << 0  // GDK_SHIFT_MASK
	ModControl uint = 1 << 2  // GDK_CONTROL_MASK
	ModAlt     uint = 1 << 3  // GDK_ALT_MASK (Mod1)
	ModSuper   uint = 1 << 26 // GDK_SUPER_MASK
)

GDK modifier-state bits, as they arrive in a controller's current event state and in a key event's state argument. A host decodes the four the toolkit cares about; the lock and button-mask bits are left alone.

const MemoryR8G8B8A8 = 5

MemoryR8G8B8A8 is GdkMemoryFormat GDK_MEMORY_R8G8B8A8: four bytes per pixel in R, G, B, A order, not premultiplied — the layout a go-widgets pixel buffer uses, so a frame maps to a GdkTexture with no conversion.

Variables

var ErrUnsupported = errors.New("gtk4: only available on Linux")

ErrUnsupported is returned by Init on any platform without GTK4 (everything but Linux). It is defined on every platform so a portable consumer can test for it with errors.Is.

Functions

func IdleAdd

func IdleAdd(fn func())

IdleAdd schedules fn to run once on the main loop and be removed. A host uses it to marshal work onto the GTK thread. fn runs on the main loop thread.

func Init

func Init() (ok bool, err error)

Init loads GTK4 and initialises it, reporting whether a display could be opened. It is safe to call more than once. An error means the libraries could not be loaded at all (not merely that there is no display).

func KeyvalToUnicode

func KeyvalToUnicode(keyval uint) rune

KeyvalToUnicode returns the Unicode rune a GDK keyval produces, or 0 for a non-printable (named) key such as Return or an arrow. It is gdk_keyval_to_unicode, so a host maps named keys itself and takes the rune for the rest.

func TextureFromRGBA

func TextureFromRGBA(data []byte, width, height int) uintptr

TextureFromRGBA builds a GdkTexture from width*height*4 bytes of R8G8B8A8. The bytes are copied (g_bytes_new copies), so the caller may reuse its buffer at once. The returned handle is a GdkTexture with one reference the caller owns.

Types

type MainLoop

type MainLoop uintptr

A MainLoop is a GLib main loop.

func MainLoopNew

func MainLoopNew() MainLoop

MainLoopNew creates a GLib main loop.

func (MainLoop) Quit

func (l MainLoop) Quit()

func (MainLoop) Run

func (l MainLoop) Run()

type Picture

type Picture Widget

A Picture is a GtkPicture that shows an RGBA image a host refreshes each frame with Picture.SetRGBA — the widget the GTK4-hosted go-widgets backend puts the toolkit's pixel framebuffer into, with native controls overlaid above it.

func PictureNew

func PictureNew() Picture

PictureNew creates a picture widget. It returns the null Picture if the pixel entry points cannot be loaded.

func (Picture) SetRGBA

func (p Picture) SetRGBA(data []byte, width, height int)

SetRGBA shows width*height*4 bytes of R8G8B8A8 in the picture. It is safe to call every frame: a fresh texture is set and the previous one released (the picture took a reference, so unref-ing the caller's is correct).

func (Picture) Widget

func (p Picture) Widget() Widget

Widget is the picture as a plain widget, for putting into a container.

type Widget

type Widget uintptr

A Widget is a GTK widget — a GObject pointer. The zero value is the null widget. Methods on it are thin wrappers over the C API.

func BoxNew

func BoxNew(horizontal bool) Widget

BoxNew creates a GtkBox with zero spacing, horizontal (0) or vertical (1). It is the container a host composes a segmented control from, appending linked toggle buttons; visual linking (the .linked style class) is the host's job.

func ButtonNewWithLabel

func ButtonNewWithLabel(label string) Widget

ButtonNewWithLabel creates a push button.

func CheckButtonNewWithLabel

func CheckButtonNewWithLabel(label string) Widget

CheckButtonNewWithLabel creates a labelled check button. GTK check buttons that share a group act as radios; a host groups them for a NativeRadio.

func ColorNew

func ColorNew() Widget

ColorNew creates a GtkColorButton. Read and write the colour as "#RRGGBB" with ColorHex/SetColorHex; connect "color-set" for changes.

func ComboNew

func ComboNew(items []string) Widget

ComboNew creates an editable GtkComboBoxText prefilled with items (one append per string). Read and write the shown text with ComboText/SetComboText; connect "changed" for edits.

func DateNew

func DateNew() Widget

DateNew creates a GtkCalendar. Read and write the selected day as "YYYY-MM-DD" with DateISO/SetDateISO; connect "day-selected" for changes.

func DrawingAreaNew

func DrawingAreaNew() Widget

DrawingAreaNew creates a GtkDrawingArea. QueueDraw asks a widget to repaint.

func EntryNew

func EntryNew() Widget

EntryNew creates a single-line text entry. Call SetVisibility(false) for a secure (password) entry.

func FixedNew

func FixedNew() Widget

FixedNew creates a GtkFixed — the container a host overlays native controls in at absolute positions, over the pixel drawing area.

func LabelNew

func LabelNew(text string) Widget

LabelNew creates a static text label.

func LinkNew

func LinkNew(label string) Widget

LinkNew creates a GtkLinkButton showing label with an empty URI, so GTK opens nothing on its own. Wire OnActivateLink for a plain activation.

func ListBoxNew

func ListBoxNew() Widget

ListBoxNew creates a GtkListBox — a single-column selectable list. Append rows with ListBoxAppendText, read/write the selection with SelectedRow/SelectRow, and connect "row-selected" for changes.

func PopUpNew

func PopUpNew(items []string) Widget

PopUpNew creates a GtkDropDown listing items. The items are copied into a GtkStringList (one append per string, so no C string-array marshalling is needed). Read and write the selection index with Selected/SetSelected; connect "notify::selected" for changes.

func ProgressNew

func ProgressNew() Widget

ProgressNew creates a GtkProgressBar. It is read-only: set its position with SetFraction (0..1); there is no change signal (a host drives it).

func SearchNew

func SearchNew() Widget

SearchNew creates a GtkSearchEntry. It implements GtkEditable, so Text/SetText work on it directly; connect "search-changed" for edits.

func SliderNew

func SliderNew(min, max, step float64) Widget

SliderNew creates a horizontal GtkScale over [min,max] with the given step. Read and write its value with Value/SetValue; connect "value-changed" for edits.

func SpinnerNew

func SpinnerNew() Widget

SpinnerNew creates a GtkSpinner — an indeterminate activity indicator. Start and Stop animate it; it has no value.

func StepperNew

func StepperNew(min, max, step float64) Widget

StepperNew creates a GtkSpinButton over [min,max] with the given step. Read and write its value with SpinValue/SetSpinValue; connect "value-changed" for edits.

func TextViewNew

func TextViewNew() Widget

TextViewNew creates a multi-line GtkTextView. Read and write its whole contents with TextViewText/SetTextViewText. The change signal lives on the underlying GtkTextBuffer, not the view: connect it with ConnectBufferChanged, or reach the buffer with Buffer and connect "changed" yourself.

func ToggleButtonNewWithLabel

func ToggleButtonNewWithLabel(label string) Widget

ToggleButtonNewWithLabel creates a labelled GtkToggleButton. Group several with SetGroup for a mutually-exclusive (segmented) set; read and write pressed state with the shared Active/SetActive, and connect "toggled" for changes.

func WindowNew

func WindowNew() Widget

WindowNew creates a top-level window.

func (Widget) Active

func (w Widget) Active() bool

Active and SetActive read and write the pressed state of a check button OR a toggle button — GtkCheckButton and GtkToggleButton are distinct types in GTK4 with separate accessors, so the method dispatches on the widget's runtime type (GTK_IS_TOGGLE_BUTTON). This lets both the check/radio controls and the segmented toggles share one Active/SetActive pair.

func (Widget) AddTickCallback

func (w Widget) AddTickCallback(fn func() bool) uint64

AddTickCallback registers fn to run once per frame, driven by this widget's GdkFrameClock, for as long as fn returns true. It is the GTK-native animation tick: aligned to the display's refresh, and quiescent while the widget is unmapped (the frame clock does not run then), so an idle hidden window costs nothing. A host that renders its own pixels into a Picture uses it to present a fresh frame each vsync — unlike a one-shot IdleAdd, which the frame clock would fire before the window is even mapped. fn runs on the main-loop thread; returning false removes the callback. The callback is retained for the process life, like Widget.Connect's.

func (Widget) Append

func (w Widget) Append(child Widget)

Append adds child to the end of a GtkBox.

func (Widget) Buffer

func (w Widget) Buffer() Widget

Buffer returns the view's GtkTextBuffer (as a Widget handle — it is a GObject a host connects signals on, not a displayable widget).

func (Widget) ColorHex

func (w Widget) ColorHex() string

ColorHex returns the chosen colour as "#RRGGBB". GdkRGBA is four C floats (red,green,blue,alpha), 16 bytes; alpha is dropped.

func (Widget) ComboText

func (w Widget) ComboText() string

ComboText returns the combo's active text — for an editable combo, the text in its entry. gtk_combo_box_text_get_active_text returns a freshly g_malloc'd string that purego copies into Go; the C copy is not freed, a small acceptable per-call leak (no free plumbing, as agreed).

func (Widget) Connect

func (w Widget) Connect(signal string, fn func()) uint64

Connect wires a GObject signal (e.g. "clicked", "changed") to a Go func. The callback keeps the widget's value reachable through its own accessors, so the zero-argument closure is enough for the control signals a host cares about. The returned handler id is GObject's; a host rarely needs it.

The callback is retained for the process life (like the go-macos target classes): GTK holds a C pointer to it, and letting Go collect it would leave a dangling call.

func (Widget) ConnectBufferChanged

func (w Widget) ConnectBufferChanged(fn func()) uint64

ConnectBufferChanged connects fn to the view's buffer "changed" signal — fired on every edit. It resolves the buffer for the host.

func (Widget) DateISO

func (w Widget) DateISO() string

DateISO returns the selected day as "YYYY-MM-DD". gtk_calendar_get_date hands back a GDateTime we own and unref.

func (Widget) ListBoxAppendText

func (w Widget) ListBoxAppendText(text string)

ListBoxAppendText appends a row holding a left-aligned label with text.

func (Widget) Move

func (f Widget) Move(child Widget, x, y float64)

func (Widget) OnActivateLink

func (w Widget) OnActivateLink(fn func()) uint64

OnActivateLink connects fn to "activate-link", whose handler returns gboolean. The bound callback returns TRUE, which suppresses GTK's own URI-open so the link behaves as a plain clickable activation.

func (Widget) OnKey

func (w Widget) OnKey(fn func(keyval, keycode, state uint, press bool))

OnKey fires on a key press and release that reaches w — that is, one no focused child (a native entry) consumed first. It gives the GDK keyval and keycode, the modifier state, and whether this is a press. Use KeyvalToUnicode for the rune and a keyval table for named keys.

func (Widget) OnMotion

func (w Widget) OnMotion(fn func(state uint, x, y float64))

OnMotion fires when the pointer moves over w, with the modifier state (a button mask distinguishes a drag) and the widget-local point.

func (Widget) OnMouseDown

func (w Widget) OnMouseDown(fn func(button int, state uint, x, y float64))

OnMouseDown fires on a press of any mouse button over w, with the button (1 left, 2 middle, 3 right), the GDK modifier state, and the widget-local point.

func (Widget) OnMouseUp

func (w Widget) OnMouseUp(fn func(button int, state uint, x, y float64))

OnMouseUp fires on the matching release.

func (Widget) OnScroll

func (w Widget) OnScroll(fn func(dx, dy float64, state uint))

OnScroll fires on a wheel or trackpad scroll over w, with the delta in both axes (units are wheel notches / trackpad steps) and the modifier state.

func (Widget) Present

func (w Widget) Present()

func (Widget) Put

func (f Widget) Put(child Widget, x, y float64)

func (Widget) QueueDraw

func (w Widget) QueueDraw()

func (Widget) SelectRow

func (w Widget) SelectRow(i int)

SelectRow selects the row at index i (a no-op if i is out of range).

func (Widget) Selected

func (w Widget) Selected() int

Selected returns the selected index, or -1 when nothing is selected (GTK_INVALID_LIST_POSITION). SetSelected selects by index.

func (Widget) SelectedRow

func (w Widget) SelectedRow() int

SelectedRow returns the selected row's index, or -1 when nothing is selected.

func (Widget) SetActive

func (w Widget) SetActive(on bool)

func (Widget) SetChild

func (w Widget) SetChild(child Widget)

func (Widget) SetColorHex

func (w Widget) SetColorHex(s string)

SetColorHex sets the colour from an "#RRGGBB" string (alpha forced opaque). A malformed string is ignored.

func (Widget) SetComboText

func (w Widget) SetComboText(s string)

SetComboText sets the editable combo's text by writing into its child entry (gtk_combo_box_get_child → gtk_editable_set_text).

func (Widget) SetDateISO

func (w Widget) SetDateISO(s string)

SetDateISO selects the day named by an "YYYY-MM-DD" string. A malformed string or an impossible date is ignored.

func (Widget) SetDefaultSize

func (w Widget) SetDefaultSize(width, height int)

func (Widget) SetFraction

func (w Widget) SetFraction(f float64)

SetFraction sets a progress bar's fill, clamped by GTK to [0,1].

func (Widget) SetGroup

func (w Widget) SetGroup(group Widget)

SetGroup joins this toggle button to group's exclusive set. Pass the zero Widget to start a fresh group (become the group's first member).

func (Widget) SetLabel

func (w Widget) SetLabel(label string)

func (Widget) SetSelected

func (w Widget) SetSelected(i int)

func (Widget) SetSizeRequest

func (w Widget) SetSizeRequest(width, height int)

SetSizeRequest fixes a widget's size (a host sizes controls to the region it laid out).

func (Widget) SetSpinValue

func (w Widget) SetSpinValue(v float64)

func (Widget) SetText

func (w Widget) SetText(s string)

func (Widget) SetTextViewText

func (w Widget) SetTextViewText(s string)

SetTextViewText replaces the whole buffer contents.

func (Widget) SetTitle

func (w Widget) SetTitle(title string)

func (Widget) SetValue

func (w Widget) SetValue(v float64)

func (Widget) SetVisibility

func (w Widget) SetVisibility(vis bool)

func (Widget) SetVisible

func (w Widget) SetVisible(vis bool)

SetVisible shows or hides a widget in place.

func (Widget) SpinValue

func (w Widget) SpinValue() float64

func (Widget) Start

func (w Widget) Start()

func (Widget) Stop

func (w Widget) Stop()

func (Widget) Text

func (w Widget) Text() string

Text and SetText read and write an editable's text (entry, label via editable where applicable), through the GtkEditable interface.

func (Widget) TextViewText

func (w Widget) TextViewText() string

TextViewText returns the whole buffer contents. A GtkTextIter is an opaque fixed-size struct filled in place; a 128-byte buffer is comfortably larger than its ~80 bytes. gtk_text_buffer_get_text returns a freshly g_malloc'd string that purego copies into Go; the C copy is not freed, a small acceptable per-call leak.

func (Widget) Unparent

func (w Widget) Unparent()

Unparent removes a widget from its parent (a host reconciling controls away).

func (Widget) Value

func (w Widget) Value() float64

Value and SetValue read and write a slider's (GtkRange's) current value.