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 ButtonNewWithLabel(label string) Widget
  • func CheckButtonNewWithLabel(label string) Widget
  • func DrawingAreaNew() Widget
  • func EntryNew() Widget
  • func FixedNew() Widget
  • func LabelNew(text string) Widget
  • func PopUpNew(items []string) Widget
  • func SliderNew(min, max, step float64) Widget
  • func WindowNew() Widget
  • func (w Widget) Active() bool
  • func (w Widget) AddTickCallback(fn func() bool) uint64
  • func (w Widget) Connect(signal string, fn func()) uint64
  • func (f Widget) Move(child Widget, x, y float64)
  • 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) Selected() int
  • func (w Widget) SetActive(on bool)
  • func (w Widget) SetChild(child Widget)
  • func (w Widget) SetDefaultSize(width, height int)
  • func (w Widget) SetLabel(label string)
  • func (w Widget) SetSelected(i int)
  • func (w Widget) SetSizeRequest(width, height int)
  • func (w Widget) SetText(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) Text() 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 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 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 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 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 WindowNew

func WindowNew() Widget

WindowNew creates a top-level window.

func (Widget) Active

func (w Widget) Active() bool

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

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

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

func (w Widget) SetActive(on bool)

func (Widget) SetChild

func (w Widget) SetChild(child Widget)

func (Widget) SetDefaultSize

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

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

func (w Widget) SetText(s string)

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