Documentation
¶
Overview ¶
Package titlebar provides a custom window title bar widget.
A TitleBar replaces the OS-native title bar with a GPU-rendered bar that integrates with the application's design system. It renders a horizontal bar with three zones: leading (left-aligned), center, and trailing (right-aligned window control buttons).
Construction uses functional options:
tb := titlebar.New(
titlebar.Title("My Application"),
titlebar.Leading(menuBtn, projectLabel),
titlebar.Center(searchWidget),
titlebar.Height(40),
titlebar.PainterOpt(painter),
)
Zones ¶
The title bar is divided into three horizontal zones:
- Leading: left-aligned widgets (menu button, project name, branch selector)
- Center: centered widgets (search bar, run configuration)
- Trailing: auto-generated window control buttons (minimize, maximize/restore, close)
Window Chrome Integration ¶
When a WindowChrome is provided via Chrome, the title bar registers a hit-test callback so that empty space acts as a drag region for moving the window, and the control buttons perform minimize/maximize/close operations. Without a WindowChrome, the title bar renders as a purely visual bar with no window management capabilities.
Visual Style ¶
The visual rendering is delegated to a Painter implementation. Each design system can supply its own painter. If no painter is set, DefaultPainter is used.
Accessibility ¶
The title bar has the a11y.RoleBanner role, following the WAI-ARIA banner landmark pattern for site/application-wide content.
Index ¶
- type BackgroundState
- type ControlState
- type ControlType
- type DefaultPainter
- type HitTestResult
- type Option
- type Painter
- type Widget
- func (w *Widget) AccessibilityActions() []a11y.Action
- func (w *Widget) AccessibilityHint() string
- func (w *Widget) AccessibilityLabel() string
- func (w *Widget) AccessibilityRole() a11y.Role
- func (w *Widget) AccessibilityState() a11y.State
- func (w *Widget) AccessibilityValue() string
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(ctx widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(ctx widget.Context, e event.Event) bool
- func (w *Widget) HasChrome() bool
- func (w *Widget) HitTest(x, y float64) HitTestResult
- func (w *Widget) IsFocusable() bool
- func (w *Widget) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) SetFocusedState(focused bool)
- func (w *Widget) SetTitle(title string)
- func (w *Widget) Title() string
- type WindowChrome
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BackgroundState ¶
type BackgroundState struct {
// Focused indicates whether the application window has input focus.
Focused bool
}
BackgroundState provides the current title bar background state to the painter.
type ControlState ¶
type ControlState struct {
// Hovered indicates the mouse cursor is over the control button.
Hovered bool
// Pressed indicates the mouse button is held down on the control button.
Pressed bool
}
ControlState provides the current window control button state to the painter.
type ControlType ¶
type ControlType uint8
ControlType identifies a window control button.
const ( // ControlMinimize is the minimize window button. ControlMinimize ControlType = iota // ControlMaximize is the maximize window button (when window is not maximized). ControlMaximize // ControlRestore is the restore window button (when window is maximized). ControlRestore // ControlClose is the close window button. ControlClose )
func (ControlType) String ¶
func (ct ControlType) String() string
String returns a human-readable name for the control type.
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws a simple dark bar with basic window controls.
func (DefaultPainter) DrawBackground ¶
func (p DefaultPainter) DrawBackground(canvas widget.Canvas, bounds geometry.Rect, _ BackgroundState)
DrawBackground renders a dark background bar.
func (DefaultPainter) DrawControlButton ¶
func (p DefaultPainter) DrawControlButton(canvas widget.Canvas, bounds geometry.Rect, control ControlType, state ControlState)
DrawControlButton renders a minimal window control button.
type HitTestResult ¶
type HitTestResult int
HitTestResult identifies what region of the title bar a point falls in. This is used by the window system to determine drag, resize, and control button behavior.
const ( // HitTestClient means the point is over a child widget (not draggable). HitTestClient HitTestResult = iota // HitTestCaption means the point is over empty title bar area (drag to move). HitTestCaption // HitTestClose means the point is over the close button. HitTestClose // HitTestMaximize means the point is over the maximize/restore button. HitTestMaximize // HitTestMinimize means the point is over the minimize button. HitTestMinimize )
type Option ¶
type Option func(*config)
Option configures a title bar during construction.
func Chrome ¶
func Chrome(wc WindowChrome) Option
Chrome sets the window chrome interface for window management operations. When provided, the title bar can minimize, maximize, and close the window, and empty space becomes a drag region for moving the window.
If not set, the title bar renders as a purely visual bar with no window management capabilities; control buttons are not displayed.
func Focused ¶
Focused sets the initial focused state of the title bar. This affects the visual appearance (e.g., dimmed controls when unfocused).
func PainterOpt ¶
PainterOpt sets the painter used to render the title bar. Each design system provides its own painter. If not set, DefaultPainter is used.
type Painter ¶
type Painter interface {
// DrawBackground draws the title bar background.
DrawBackground(canvas widget.Canvas, bounds geometry.Rect, state BackgroundState)
// DrawControlButton draws a window control button (minimize, maximize, close).
DrawControlButton(canvas widget.Canvas, bounds geometry.Rect, control ControlType, state ControlState)
}
Painter draws the visual representation of a title bar. Each design system (Material 3, Fluent, DevTools) provides its own Painter implementation to render the title bar in its visual style.
If no Painter is set, the title bar uses DefaultPainter.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a custom window title bar.
The title bar renders a horizontal bar with three zones: leading (left), center, and trailing (right). The trailing zone contains window control buttons (minimize, maximize/restore, close) when a WindowChrome is provided.
Empty space in the title bar acts as a drag region for window movement. Child widgets placed in the leading and center zones receive events normally.
A Widget is created with New using functional options:
tb := titlebar.New(
titlebar.Title("My App"),
titlebar.Leading(menuBtn),
titlebar.Chrome(windowChrome),
titlebar.PainterOpt(painter),
)
func New ¶
New creates a new title bar Widget with the given options.
The returned widget is visible and enabled by default. The default height is 40 logical pixels.
func (*Widget) AccessibilityActions ¶
AccessibilityActions returns nil.
func (*Widget) AccessibilityHint ¶
AccessibilityHint returns the window title as a hint.
func (*Widget) AccessibilityLabel ¶
AccessibilityLabel returns "Title Bar".
func (*Widget) AccessibilityRole ¶
AccessibilityRole returns a11y.RoleBanner.
func (*Widget) AccessibilityState ¶
AccessibilityState returns the accessibility state.
func (*Widget) AccessibilityValue ¶
AccessibilityValue returns an empty string.
func (*Widget) HitTest ¶
func (w *Widget) HitTest(x, y float64) HitTestResult
HitTest returns what region of the title bar a screen-space point falls in. This is intended to be called from a hit-test callback registered with the window system.
func (*Widget) IsFocusable ¶
IsFocusable reports whether the title bar can receive keyboard focus. Title bars are not typically focusable.
func (*Widget) Layout ¶
Layout calculates the title bar's preferred size within the given constraints.
func (*Widget) SetFocusedState ¶
SetFocusedState updates whether the window is focused, affecting visual appearance.
type WindowChrome ¶
type WindowChrome interface {
// Minimize minimizes the window.
Minimize()
// Maximize maximizes the window.
Maximize()
// IsMaximized reports whether the window is currently maximized.
IsMaximized() bool
// Close closes the window.
Close()
}
WindowChrome provides window management operations.
This interface is a subset of gpucontext.WindowChrome, defined locally to avoid a direct dependency on the gpucontext package. Callers should pass the gpucontext.WindowChrome value obtained from the window provider.
Source Files