Window management API

An App manages one main window and zero or more independent top-level child windows. Components remain in the root package; Window is a lifecycle handle, not a View, and should not be constructed as a zero value. Start with multiple windows; exact signatures are in runtime references.

Creation and scheduling

API	Parameters and results	Scope, constraints, and errors
App.CreateWindow(options WindowOptions, root func() View) (*Window, error)	Configuration and non-nil root builder; returns a child handle on success.	Call in a UI callback or App.Update. Shows after preparing the first frame; failures clean up partial resources without changing existing windows.
App.Update(update func()) error	Queues non-nil state changes in FIFO order.	Main window only; safe across goroutines. Returns ErrAppNotRunning/ErrAppClosed outside its lifecycle.
App.Invalidate() error	Requests a main-window rebuild without changing state.	Concurrent-safe; lifecycle errors match App.Update. Does not synchronize background state writes.
Window.Update(update func()) error	Queues non-nil state changes in FIFO order.	Target child only; concurrent-safe. Closed/nil handles return ErrWindowClosed; shutdown may return ErrAppClosed.
Window.Invalidate() error	Requests a target child rebuild.	Equivalent to an empty update; lifecycle errors match Window.Update.
Window.Close()	Requests child shutdown; no result.	Idempotent and concurrent-safe. Leaves other windows open and bypasses OnCloseRequest. Nil is a no-op.
Window.Closed() bool	Reports requested or completed closure.	Concurrent-safe; nil returns true. Does not guarantee a subsequent operation succeeds.
Window.Diagnostics() RuntimeDiagnostics	Returns this window's metrics snapshot.	Concurrent-safe; nil returns a zero snapshot. Fields.

App.Close closes every window and ends the shared event loop. App.Diagnostics still describes the main window rather than an aggregate. Do not submit work requiring a window after it closes.

All WindowOptions fields

Field	Type	Default and behavior
Title	string	Empty defaults to dxui.
Width / Height	float32	Defaults to 640 / 480 logical units, unlike the main window's 800 / 600. Finite, nonnegative, at most MaxInt32; explicit positive values must round to at least 1.
MinWidth / MinHeight	float32	0 leaves minima unspecified; finite, nonnegative, at most MaxInt32.
Background	RGBAColor	All-zero uses the App background, then RGBA(28,30,36,255) if still zero.
Shortcuts	[]Shortcut	Independent copied shortcuts; empty by default, with no automatic inheritance from AppOptions.Shortcuts.
OnCloseRequest	func(*Window)	Nil accepts system close requests. A callback must call Window.Close to accept; otherwise it rejects.
OnShown	func(*Window)	Called once after the complete first frame is presented and shown, before CreateWindow returns. Use its handle argument.

Theme, Fonts, DefaultFont, DisableSystemFontFallback, Renderer, Caches, and Diagnostics use App configuration. Windows have no individual SetTheme; App.SetTheme updates all live windows. Budgets apply per window, so total resource capacity grows with more windows.

The baseline WindowOptions source comment broadly claims shortcut inheritance, but creation explicitly replaces them with options.Shortcuts. This page and the displayed reference follow the implementation; the raw maintenance snapshot retains the original comment.

Operations shared by main and child windows

Each method below exists on *App (main window) and *Window (target child). Native SetTitle, SetSize, Maximize, Unmaximize, Minimize, and Unminimize operations require a UI callback or Update closure. Title, Size, IsMaximized, and IsMinimized are concurrent-safe snapshots.

Method	Result	Purpose and constraints
Title()	string	Last successfully configured title; before Run, App returns the original option. Nil Window returns an empty string.
SetTitle(title string)	error	Updates the title snapshot on success without rebuilding the root. Empty strings are used literally, not replaced by the creation default.
Size()	Size	Logical client size, updated by successful SetSize and later resize/scale events. Before Run, App returns configured dimensions; nil Window returns zero Size.
SetSize(width, height float32)	error	Both dimensions must be finite, positive, round to at least 1, and not exceed MaxInt32. Success updates the snapshot; layout follows viewport events, and the platform may adjust the final size.
Maximize()	error	Requests maximization; nil does not mean a state event has confirmed it.
Unmaximize()	error	Requests restoration to normal state.
Minimize()	error	Requests minimization; nil does not mean a state event has confirmed it.
Unminimize()	error	Requests normal state; shares the platform restore operation with Unmaximize.
IsMaximized()	bool	State confirmed by the latest window event, not optimistically set by requests. False for an uncreated main window or nil Window.
IsMinimized()	bool	Minimized state confirmed by the latest window event. False for an uncreated main window or nil Window.

Main-window commands return ErrWindowNotRunning before Run and ErrAppClosed after closure. Closed-child commands return ErrWindowClosed. Title/size/state getters remain snapshots; do not use them as liveness checks.

WindowOptions has no state-event callback. If displaying IsMaximized/IsMinimized, do not assume a request immediately changes them. The Read confirmed state button below reads confirmed state when clicked.

Complete window controls example

This example provides the same title, size, maximize, and minimize buttons for main and child windows. The child first builds before CreateWindow returns, so it retrieves the handle through a function only during later button events.

package main

import (
	"fmt"
	"log"

	"github.com/dxui-org/dxui"
)

// App and Window share these window-level operations.
type windowControl interface {
	Title() string
	SetTitle(string) error
	Size() dxui.Size
	SetSize(float32, float32) error
	Maximize() error
	Unmaximize() error
	Minimize() error
	Unminimize() error
	IsMaximized() bool
	IsMinimized() bool
	Invalidate() error
	Diagnostics() dxui.RuntimeDiagnostics
}

func controls(target func() windowControl, message *string) dxui.View {
	action := func(label string, run func() error) dxui.View {
		return dxui.TextButton(
			dxui.ButtonProps{
				OnPress: func() {
					if err := run(); err != nil {
						*message = err.Error()
						return
					}
					*message = "Requested: " + label
				},
			},
			label,
		)
	}
	row := func(children ...dxui.View) dxui.View {
		return dxui.Box(dxui.BoxProps{
			Direction: dxui.Horizontal,
			Gap:       8,
		}, children...)
	}
	return dxui.Box(
		dxui.BoxProps{
			Gap: 12,
		},
		row(
			action("Set title", func() error {
				return target().SetTitle("Updated title")
			}),
			action("Set size", func() error {
				return target().SetSize(720, 600)
			}),
		),
		row(
			action("Maximize", func() error {
				return target().Maximize()
			}),
			action("Unmaximize", func() error {
				return target().Unmaximize()
			}),
		),
		row(
			action("Minimize", func() error {
				return target().Minimize()
			}),
			action("Unminimize", func() error {
				return target().Unminimize()
			}),
		),
		row(
			action("Refresh root", func() error {
				return target().Invalidate()
			}),
			dxui.TextButton(
				dxui.ButtonProps{
					OnPress: func() {
						w := target()
						*message = fmt.Sprintf(
							"%s | size=%v | maximized=%t | minimized=%t",
							w.Title(),
							w.Size(),
							w.IsMaximized(),
							w.IsMinimized(),
						)
					},
				},
				"Read confirmed state",
			),
		),
		dxui.TextButton(
			dxui.ButtonProps{
				OnPress: func() {
					d := target().Diagnostics()
					*message = fmt.Sprintf("Builds: %d, paints: %d", d.BuildCount, d.PaintCount)
				},
			},
			"Snapshot",
		),
		dxui.Text(dxui.TextProps{
			Value: *message,
			Wrap:  dxui.TextWrapWords,
		}),
	)
}

func main() {
	mainMessage, childMessage := "Ready", "Ready"
	var child *dxui.Window
	app := dxui.NewApp(dxui.AppOptions{
		Title:       "Window controls",
		Width:       720,
		Height:      600,
		Diagnostics: true,
		Background:  dxui.RGBA(248, 250, 252, 255),
	})
	open := func() {
		if child != nil && !child.Closed() {
			mainMessage = "Child is already open"
			return
		}
		childMessage = "Ready"
		window, err := app.CreateWindow(
			dxui.WindowOptions{
				Title:  "Child controls",
				Width:  720,
				Height: 600,
			},
			func() dxui.View {
				return dxui.Box(
					dxui.BoxProps{
						Style: dxui.Style{
							Padding: dxui.Padding(24),
						},
					},
					controls(func() windowControl {
						return child
					}, &childMessage),
				)
			},
		)
		if err != nil {
			mainMessage = err.Error()
			return
		}
		child = window
		mainMessage = "Child opened"
	}
	if err := app.Run(func() dxui.View {
		return dxui.Box(
			dxui.BoxProps{
				Gap: 16,
				Style: dxui.Style{
					Padding: dxui.Padding(24),
				},
			},
			dxui.TextButton(dxui.ButtonProps{
				OnPress: open,
			}, "Open child"),
			dxui.TextButton(
				dxui.ButtonProps{
					OnPress: func() {
						if child == nil || child.Closed() {
							mainMessage = "Open a child first"
							return
						}
						if err := child.Unminimize(); err != nil {
							mainMessage = err.Error()
						}
					},
				},
				"Restore child",
			),
			controls(func() windowControl {
				return app
			}, &mainMessage),
		)
	}); err != nil {
		log.Fatal(err)
	}
}

After minimizing, restore through the taskbar/window manager or the main window's Restore child button. Refresh root demonstrates targeted Invalidate; Snapshot demonstrates Diagnostics. These APIs do not create polling loops.

Lifecycle errors

Error	Scenario
ErrWindowNotRunning	CreateWindow outside App.Run, or main-window commands before Run.
ErrWindowClosed	Update, Invalidate, or commands on nil/closed children.
ErrAppClosed	Submitting work or executing main-window commands during shutdown.
Other errors	Nil builders/closures, invalid dimensions, shortcut validation, first-frame build failures, or platform failures.

Use errors.Is for lifecycle errors and handle return values instead of matching text. Checks have an order: CreateWindow may return ErrWindowNotRunning first after runtime destruction. Not every shutdown-stage failure has the same error.