Documentation
¶
Overview ¶
Package popover provides floating overlay widgets anchored to a trigger.
Two widget types are provided:
- Popover -- click-triggered, displays arbitrary widget content
- Tooltip -- hover-triggered, displays a text label
Both widgets position themselves relative to a trigger widget using one of 12 placement options (4 sides x 3 alignments). If the preferred placement would overflow the viewport, the widget automatically flips to the opposite side and clamps to the window bounds.
Popover ¶
A Popover opens on click and displays any widget.Widget as content. It uses the overlay stack for z-ordering and supports click-outside dismissal.
pop := popover.NewPopover(
popover.TriggerWidget(myButton),
popover.Content(menuPanel),
popover.PlacementOpt(popover.BottomStart),
popover.DismissOnClickOutside(true),
)
Tooltip ¶
A Tooltip opens after a configurable hover delay and displays a short text label. It closes when the mouse leaves the trigger.
tip := popover.NewTooltip(
popover.TriggerWidget(saveButton),
popover.TooltipText("Save document"),
popover.PlacementOpt(popover.Bottom),
popover.Delay(500 * time.Millisecond),
)
Visual Style ¶
Rendering is delegated to a Painter interface. If no painter is set, DefaultPainter is used, which draws a rounded rectangle with a shadow.
Overlay Integration ¶
Both widgets push themselves onto the window's overlay stack when shown and remove themselves when hidden. They integrate with widget.OverlayManager obtained from the widget.Context.
Signal Binding ¶
The visible state can be bound to a reactive signal:
visible := state.NewSignal(false)
pop := popover.NewPopover(
popover.TriggerWidget(btn),
popover.Content(panel),
popover.VisibleSignal(visible),
)
Index ¶
- func CalculatePosition(placement Placement, triggerBounds geometry.Rect, overlaySize geometry.Size, ...) geometry.Point
- type DefaultPainter
- type Option
- func Content(w widget.Widget) Option
- func ContentSize(width, height float32) Option
- func Delay(d time.Duration) Option
- func Disabled(d bool) Option
- func DisabledFn(fn func() bool) Option
- func DismissOnClickOutside(dismiss bool) Option
- func Gap(g float32) Option
- func MaxWidth(w float32) Option
- func OnHide(fn func()) Option
- func OnShow(fn func()) Option
- func PainterOpt(p Painter) Option
- func PlacementOpt(p Placement) Option
- func TooltipText(text string) Option
- func TriggerWidget(w widget.Widget) Option
- func VisibleSignal(sig state.Signal[bool]) Option
- type Painter
- type Placement
- type Popover
- func (p *Popover) Children() []widget.Widget
- func (p *Popover) Draw(ctx widget.Context, canvas widget.Canvas)
- func (p *Popover) Event(ctx widget.Context, e event.Event) bool
- func (p *Popover) Hide(ctx widget.Context)
- func (p *Popover) IsFocusable() bool
- func (p *Popover) IsOpen() bool
- func (p *Popover) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (p *Popover) Mount(ctx widget.Context)
- func (p *Popover) Show(ctx widget.Context)
- func (p *Popover) Toggle(ctx widget.Context)
- func (p *Popover) Unmount()
- type PopoverColorScheme
- type PopoverPaintState
- type Tooltip
- func (t *Tooltip) Children() []widget.Widget
- func (t *Tooltip) Draw(ctx widget.Context, canvas widget.Canvas)
- func (t *Tooltip) Event(ctx widget.Context, e event.Event) bool
- func (t *Tooltip) IsOpen() bool
- func (t *Tooltip) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size
- func (t *Tooltip) Mount(ctx widget.Context)
- func (t *Tooltip) Text() string
- func (t *Tooltip) Unmount()
- type TooltipColorScheme
- type TooltipPaintState
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CalculatePosition ¶
func CalculatePosition( placement Placement, triggerBounds geometry.Rect, overlaySize geometry.Size, windowSize geometry.Size, gap float32, ) geometry.Point
CalculatePosition computes the overlay position given the trigger bounds, overlay size, and window size. It applies auto-flip logic when the overlay would overflow the viewport, then clamps to the window bounds.
Types ¶
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter for popovers and tooltips. It draws rounded rectangles with a subtle shadow.
func (DefaultPainter) PaintPopover ¶
func (p DefaultPainter) PaintPopover(canvas widget.Canvas, st *PopoverPaintState)
PaintPopover renders a popover background with shadow.
func (DefaultPainter) PaintTooltip ¶
func (p DefaultPainter) PaintTooltip(canvas widget.Canvas, st *TooltipPaintState)
PaintTooltip renders a tooltip background and text.
type Option ¶
type Option func(*config)
Option configures a Popover or Tooltip during construction.
func ContentSize ¶
ContentSize sets a fixed size for the popover content area. If not set, the content widget's natural size is used.
func Delay ¶
Delay sets the hover delay before showing a tooltip. Defaults to 500ms. Only applies to Tooltip, not Popover.
func DisabledFn ¶
DisabledFn sets a dynamic function that determines whether the popover is disabled. When set, this takes precedence over the static value.
func DismissOnClickOutside ¶
DismissOnClickOutside controls whether clicking outside the popover content dismisses it. Defaults to true.
func Gap ¶
Gap sets the spacing between the trigger and the overlay in logical pixels. Defaults to 4.
func MaxWidth ¶
MaxWidth sets the maximum width for tooltip text wrapping. Defaults to 300 logical pixels.
func OnHide ¶
func OnHide(fn func()) Option
OnHide sets a callback invoked when the popover or tooltip is hidden.
func OnShow ¶
func OnShow(fn func()) Option
OnShow sets a callback invoked when the popover or tooltip becomes visible.
func PainterOpt ¶
PainterOpt sets the painter used to render the popover or tooltip.
func PlacementOpt ¶
PlacementOpt sets the preferred placement relative to the trigger.
func TooltipText ¶
TooltipText sets the text displayed in a tooltip.
func TriggerWidget ¶
TriggerWidget sets the widget that anchors the popover/tooltip.
type Painter ¶
type Painter interface {
// PaintPopover draws the popover background (rounded rect + shadow).
PaintPopover(canvas widget.Canvas, state *PopoverPaintState)
// PaintTooltip draws the tooltip background and text.
PaintTooltip(canvas widget.Canvas, state *TooltipPaintState)
}
Painter draws the visual representation of popovers and tooltips. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation. If no Painter is set, DefaultPainter is used.
type Placement ¶
type Placement uint8
Placement defines where the popover or tooltip appears relative to its trigger widget. There are 12 placements: 4 sides with 3 alignment variants each (start, center, end).
const ( // Bottom places the overlay below the trigger, centered horizontally. Bottom Placement = iota // BottomStart places the overlay below, aligned to the trigger's start edge. BottomStart // BottomEnd places the overlay below, aligned to the trigger's end edge. BottomEnd // Top places the overlay above the trigger, centered horizontally. Top // TopStart places the overlay above, aligned to the trigger's start edge. TopStart // TopEnd places the overlay above, aligned to the trigger's end edge. TopEnd // Left places the overlay to the left of the trigger, centered vertically. Left // LeftStart places the overlay to the left, aligned to the trigger's top edge. LeftStart // LeftEnd places the overlay to the left, aligned to the trigger's bottom edge. LeftEnd // Right places the overlay to the right of the trigger, centered vertically. Right // RightStart places the overlay to the right, aligned to the trigger's top edge. RightStart // RightEnd places the overlay to the right, aligned to the trigger's bottom edge. RightEnd )
Placement constants.
type Popover ¶
type Popover struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Popover is a click-triggered floating overlay that displays arbitrary widget content anchored to a trigger widget. It integrates with the overlay stack for z-ordering and supports click-outside dismissal.
Create with NewPopover using functional options.
func NewPopover ¶
NewPopover creates a new Popover with the given options.
The returned widget is visible and enabled by default, but the popover content is initially hidden until opened via click or Popover.Show.
func (*Popover) Children ¶
Children returns the trigger widget as the sole child. The popover content is rendered in the overlay, not as a child.
func (*Popover) Draw ¶
Draw renders the trigger widget. The popover content is drawn by the overlay stack, not as part of this widget's draw call.
func (*Popover) IsFocusable ¶
IsFocusable reports whether the popover trigger can receive focus.
func (*Popover) Layout ¶
Layout calculates the popover's size. The popover itself takes the size of its trigger widget.
type PopoverColorScheme ¶
type PopoverColorScheme struct {
Background widget.Color
Border widget.Color
Shadow widget.Color
ShadowBlur float32
}
PopoverColorScheme provides theme-derived colors for popover painting. Zero value means the painter should use its built-in defaults.
type PopoverPaintState ¶
type PopoverPaintState struct {
// Bounds is the popover content area bounds in window coordinates.
Bounds geometry.Rect
// Placement is the resolved placement direction.
Placement Placement
// ColorScheme provides theme-derived colors. Zero value means use defaults.
ColorScheme PopoverColorScheme
}
PopoverPaintState provides the current popover state to the painter.
type Tooltip ¶
type Tooltip struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Tooltip is a hover-triggered floating label anchored to a trigger widget. It appears after a configurable delay when the mouse enters the trigger, and disappears when the mouse leaves.
Create with NewTooltip using functional options.
func NewTooltip ¶
NewTooltip creates a new Tooltip with the given options.
The tooltip is initially hidden and appears on hover after the configured delay.
func (*Tooltip) Draw ¶
Draw renders the trigger widget. The tooltip content is drawn by the overlay stack.
func (*Tooltip) Layout ¶
Layout calculates the tooltip's size. The tooltip itself takes the size of its trigger widget.
type TooltipColorScheme ¶
type TooltipColorScheme struct {
Background widget.Color
TextColor widget.Color
Border widget.Color
}
TooltipColorScheme provides theme-derived colors for tooltip painting. Zero value means the painter should use its built-in defaults.
type TooltipPaintState ¶
type TooltipPaintState struct {
// Bounds is the tooltip's bounds in window coordinates.
Bounds geometry.Rect
// Text is the tooltip text to display.
Text string
// Placement is the resolved placement direction.
Placement Placement
// ColorScheme provides theme-derived colors. Zero value means use defaults.
ColorScheme TooltipColorScheme
}
TooltipPaintState provides the current tooltip state to the painter.
Source Files