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 TextureFromRGBA(data []byte, width, height int) uintptr
- type MainLoop
- type Picture
- type 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) Present()
- func (f Widget) Put(child Widget, x, y float64)
- func (w Widget) QueueDraw()
- 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) SetSizeRequest(width, height int)
- func (w Widget) SetText(s string)
- func (w Widget) SetTitle(title string)
- func (w Widget) SetVisibility(vis bool)
- func (w Widget) SetVisible(vis bool)
- func (w Widget) Text() string
- func (w Widget) Unparent()
Constants ¶
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 ¶
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 TextureFromRGBA ¶ added in v0.2.0
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 Picture ¶ added in v0.2.0
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 ¶ added in v0.2.0
func PictureNew() Picture
PictureNew creates a picture widget. It returns the null Picture if the pixel entry points cannot be loaded.
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 ¶
ButtonNewWithLabel creates a push button.
func CheckButtonNewWithLabel ¶
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 ¶ added in v0.2.0
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 (Widget) AddTickCallback ¶ added in v0.2.4
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 ¶
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) SetDefaultSize ¶
func (Widget) SetSizeRequest ¶
SetSizeRequest fixes a widget's size (a host sizes controls to the region it laid out).
func (Widget) SetVisibility ¶
func (Widget) SetVisible ¶
SetVisible shows or hides a widget in place.
Source Files