Documentation
¶
Overview ¶
Package dialog provides a modal dialog widget for confirmations, alerts, and custom content.
Construction uses functional options for immutable configuration:
d := dialog.New(
dialog.Title("Confirm Delete"),
dialog.Actions(
dialog.Action{Label: "Cancel"},
dialog.Action{Label: "Delete", Variant: VariantFilled, Default: true},
),
)
Show/Close Lifecycle ¶
A dialog is created in a hidden state. Call Widget.Show to push it as a modal overlay, and Widget.Close to remove it:
d.Show(ctx) // pushes to overlay stack d.Close(ctx) // removes from overlay stack
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) supplies its own painter to render dialogs in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal dialog suitable for testing and prototyping.
Dismissal ¶
By default, dialogs are dismissible by clicking the backdrop and pressing the Escape key. This behavior can be configured:
d := dialog.New(
dialog.Title("Processing..."),
dialog.DismissibleOpt(false), // cannot click backdrop to close
dialog.EscapeToCloseOpt(false), // cannot press Escape to close
)
Convenience Constructors ¶
Alert creates a simple informational dialog with one button:
dialog.Alert("Error", "Something went wrong.", func() {})
Confirm creates a confirmation dialog with Cancel and OK buttons:
dialog.Confirm("Delete?", "This cannot be undone.", onCancel, onConfirm)
Signal Binding ¶
The dialog title can be bound to reactive signals from the state package:
title := state.NewSignal("Loading...")
d := dialog.New(dialog.TitleSignal(title))
Focus ¶
Dialogs implement focus trapping: Tab/Shift+Tab cycles between action buttons within the dialog, and focus does not escape to the background.
Index ¶
- Constants
- type Action
- type DefaultPainter
- type DialogColorScheme
- type Option
- func Actions(actions ...Action) Option
- func Content(w widget.Widget) Option
- func DismissibleOpt(v bool) Option
- func EscapeToCloseOpt(v bool) Option
- func MaxHeight(v float32) Option
- func MaxWidth(v float32) Option
- func OnClose(fn func()) Option
- func PainterOpt(p Painter) Option
- func Title(s string) Option
- func TitleFn(fn func() string) Option
- func TitleReadonlySignal(sig state.ReadonlySignal[string]) Option
- func TitleSignal(sig state.Signal[string]) Option
- type PaintState
- type Painter
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Close(ctx widget.Context)
- func (w *Widget) Draw(_ widget.Context, _ widget.Canvas)
- func (w *Widget) Event(_ widget.Context, _ event.Event) bool
- func (w *Widget) IsOpen() bool
- func (w *Widget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) Mount(ctx widget.Context)
- func (w *Widget) Show(ctx widget.Context)
- func (w *Widget) Unmount()
Constants ¶
const ( // VariantTextOnly renders an action as text-only (no background). VariantTextOnly uint8 = 2 // VariantFilled renders an action with a solid background. VariantFilled uint8 = 0 // VariantOutlined renders an action with a border. VariantOutlined uint8 = 1 // VariantTonal renders an action with a tinted background. VariantTonal uint8 = 3 )
Variant constants for action button styling. These are uint8 values that match button.Variant values but do not import the button package, avoiding tight coupling between core widgets.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// Label is the text displayed on the action button.
Label string
// OnClick is called when the action button is activated.
// After OnClick returns, the dialog is automatically closed.
OnClick func()
// Variant controls the visual style of the button.
// Use the Variant* constants in this package (e.g. VariantTextOnly).
// Zero value is VariantFilled.
Variant uint8
// Default indicates this action receives initial focus when the
// dialog is shown. If multiple actions have Default set, the last
// one wins.
Default bool
}
Action describes a button displayed in the dialog's action area.
Action is a value struct; it is passed by value and does not require pointer semantics. The Variant field uses uint8 constants defined in this package (e.g. VariantFilled) that correspond to button variant values without importing the button package.
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws a simple dialog -- useful for testing and as a base reference.
func (DefaultPainter) PaintDialog ¶
func (p DefaultPainter) PaintDialog(canvas widget.Canvas, ps PaintState)
PaintDialog renders a minimal dialog with white surface and gray border. If state.ColorScheme is non-zero, its colors are used instead of built-in defaults.
type DialogColorScheme ¶
type DialogColorScheme struct {
Backdrop widget.Color // backdrop color (semi-transparent)
Surface widget.Color // dialog background
Title widget.Color // title text color
Content widget.Color // content text color
Border widget.Color // dialog border (optional)
Shadow widget.Color // shadow color
ActionFg widget.Color // action button text color
ActionBg widget.Color // primary action button background
}
DialogColorScheme provides theme-derived colors for dialog painting. Zero value means the painter should use its built-in defaults.
type Option ¶
type Option func(*config)
Option configures a dialog during construction.
func Actions ¶
Actions sets the action buttons displayed at the bottom of the dialog. Actions are rendered right-aligned in the order provided.
func Content ¶
Content sets the widget displayed in the dialog's content area. The content widget is laid out between the title and action buttons.
func DismissibleOpt ¶
DismissibleOpt controls whether clicking the backdrop closes the dialog. Default is true.
func EscapeToCloseOpt ¶
EscapeToCloseOpt controls whether pressing Escape closes the dialog. Default is true.
func MaxHeight ¶
MaxHeight sets the maximum height of the dialog surface in logical pixels. Default is 0 (no limit; constrained to 90% of window height).
func MaxWidth ¶
MaxWidth sets the maximum width of the dialog surface in logical pixels. Default is 560.
func OnClose ¶
func OnClose(fn func()) Option
OnClose sets a callback invoked when the dialog is closed for any reason (action click, backdrop click, Escape key).
func PainterOpt ¶
PainterOpt sets the painter used to render the dialog. Each design system provides its own painter. If not set, DefaultPainter is used.
func TitleFn ¶
TitleFn sets a dynamic title function evaluated on each draw. When set, this takes precedence over the static title but not over a signal set via TitleSignal.
func TitleReadonlySignal ¶
func TitleReadonlySignal(sig state.ReadonlySignal[string]) Option
TitleReadonlySignal binds the dialog's title to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other title sources.
func TitleSignal ¶
TitleSignal binds the dialog's title to a reactive signal. When set, the signal value takes precedence over both TitleFn and Title but not over TitleReadonlySignal.
type PaintState ¶
type PaintState struct {
Title string
HasContent bool
Actions []Action
Focused bool
Bounds geometry.Rect // dialog surface bounds (not backdrop)
ColorScheme DialogColorScheme
}
PaintState provides the current dialog state to the painter.
type Painter ¶
type Painter interface {
PaintDialog(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a dialog. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the dialog in its visual style.
If no Painter is set, the dialog uses DefaultPainter.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a modal dialog with title, content, and action buttons.
A dialog is created in a hidden state with New. Call Widget.Show to push it as a modal overlay, and Widget.Close to remove it.
The dialog renders a semi-transparent backdrop that blocks interaction with the background, and a centered surface containing the title, optional content widget, and action buttons.
func Alert ¶
Alert creates a simple informational dialog with a title, message, and a single OK button. The onOK callback is invoked when the OK button is clicked or when the dialog is dismissed.
The returned dialog must still be shown with Widget.Show.
Example:
d := dialog.Alert("Error", "File not found.", func() { log.Println("dismissed") })
d.Show(ctx)
func Confirm ¶
Confirm creates a confirmation dialog with Cancel and OK buttons. The onCancel callback is invoked when Cancel is clicked or the dialog is dismissed. The onConfirm callback is invoked when OK is clicked.
The returned dialog must still be shown with Widget.Show.
Example:
d := dialog.Confirm("Delete?", "This cannot be undone.",
func() { log.Println("canceled") },
func() { deleteItem() },
)
d.Show(ctx)
func New ¶
New creates a new dialog Widget with the given options.
The returned widget is NOT visible until Widget.Show is called. By default, the dialog is dismissible (backdrop click) and closes on Escape.
func (*Widget) Children ¶
Children returns nil because the dialog's content is rendered via the overlay surface, not as a direct child.
func (*Widget) Close ¶
Close removes the dialog from the overlay stack. If the dialog is not open, this is a no-op.
func (*Widget) Draw ¶
Draw renders the dialog. When shown as an overlay, drawing is handled by the surfaceWidget. This is a no-op when hidden.
func (*Widget) Event ¶
Event handles input events. When shown as an overlay, events are handled by the surfaceWidget. This returns false when hidden.
func (*Widget) Layout ¶
Layout calculates the dialog's preferred size. When shown as an overlay, layout is handled by the surfaceWidget. This returns zero size when hidden.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Show ¶
Show pushes the dialog as a modal overlay via the context's OverlayManager. If the dialog is already open, this is a no-op.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the dialog is removed from the widget tree. Implements widget.Lifecycle.
Source Files