Documentation
¶
Overview ¶
Package toast provides animated notification stacks.
A Manager is a normal termdash widget, so it can be placed in a regular container, embedded in a modal window, wrapped with widgets/fx effects, or hosted by a container whose border is animated by widgets/borderfx.
Index ¶
- type Action
- type Animation
- type Direction
- type Manager
- func (m *Manager) Clear()
- func (m *Manager) Count() int
- func (m *Manager) Dismiss(id string) bool
- func (m *Manager) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error
- func (m *Manager) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error
- func (m *Manager) Mouse(event *terminalapi.Mouse, meta *widgetapi.EventMeta) error
- func (m *Manager) Notify(title, message string, opts ...NotificationOption) string
- func (m *Manager) Options() widgetapi.Options
- func (m *Manager) Push(n Notification) string
- type Notification
- type NotificationOption
- func Sticky() NotificationOption
- func WithAction(label string, callback func() error) NotificationOption
- func WithActionValues(actions ...Action) NotificationOption
- func WithActions(actions ...string) NotificationOption
- func WithCreated(created time.Time) NotificationOption
- func WithID(id string) NotificationOption
- func WithIcon(icon rune) NotificationOption
- func WithProgress(progress float64) NotificationOption
- func WithSeverity(sev Severity) NotificationOption
- func WithTTL(ttl time.Duration) NotificationOption
- type Option
- func ActionCellOpts(opts ...cell.Option) Option
- func Anchor(p Placement) Option
- func AnimationDuration(d time.Duration) Option
- func AnimationMode(a Animation) Option
- func Border(ls linestyle.LineStyle, opts ...cell.Option) Option
- func Borderless() Option
- func Clock(clock func() time.Time) Option
- func CustomPosition(fn PositionFunc) Option
- func DefaultTTL(ttl time.Duration) Option
- func DismissOnClick(enabled bool) Option
- func FillCellOpts(opts ...cell.Option) Option
- func Gap(gap int) Option
- func Margin(x, y int) Option
- func MaxMessageLines(count int) Option
- func MaxVisible(count int) Option
- func MaxWidth(width int) Option
- func MessageCellOpts(opts ...cell.Option) Option
- func MinWidth(width int) Option
- func MinimumSize(size image.Point) Option
- func NewestFirst(enabled bool) Option
- func SeverityStyle(sev Severity, style Style) Option
- func Shadow(enabled bool, opts ...cell.Option) Option
- func SlideDirection(d Direction) Option
- func Stack(direction StackDirection) Option
- func TitleCellOpts(opts ...cell.Option) Option
- func Width(width int) Option
- type Placement
- type PositionFunc
- type Severity
- type StackDirection
- type Style
- type Surface
- func (s *Surface) Clear()
- func (s *Surface) ClearAt(p Placement)
- func (s *Surface) Count() int
- func (s *Surface) Draw(cvs *canvas.Canvas, meta *widgetapi.Meta) error
- func (s *Surface) Keyboard(k *terminalapi.Keyboard, meta *widgetapi.EventMeta) error
- func (s *Surface) Manager(p Placement) (*Manager, bool)
- func (s *Surface) Mouse(event *terminalapi.Mouse, meta *widgetapi.EventMeta) error
- func (s *Surface) Notify(title, message string, opts ...NotificationOption) string
- func (s *Surface) NotifyAt(p Placement, title, message string, opts ...NotificationOption) string
- func (s *Surface) Options() widgetapi.Options
- func (s *Surface) Register(p Placement, opts ...Option) error
- type SurfaceOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// Label is drawn between square brackets.
Label string
// Callback runs when the label is clicked. A nil callback renders as a
// visual-only action.
Callback func() error
// Dismiss removes the notification after a successful click.
Dismiss bool
}
Action is a clickable label shown in a notification footer.
type Animation ¶
type Animation int
Animation identifies the motion used when a toast appears.
const ( // AnimationNone renders notifications at their final position immediately. AnimationNone Animation = iota // AnimationSlide slides notifications in from the configured direction. AnimationSlide // AnimationFade renders notifications with dimmed cells until settled. AnimationFade // AnimationPop grows notifications from a compact centered rectangle. AnimationPop )
Animation values supported by Manager.
type Direction ¶
type Direction int
Direction identifies the edge used by slide animations.
const ( // DirectionRight slides notifications in from the right edge. DirectionRight Direction = iota // DirectionLeft slides notifications in from the left edge. DirectionLeft // DirectionTop slides notifications in from the top edge. DirectionTop // DirectionBottom slides notifications in from the bottom edge. DirectionBottom )
Direction values supported by slide animations.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager renders and manages a stack of toast notifications.
Implements widgetapi.Widget. This object is thread-safe.
func (*Manager) Notify ¶
func (m *Manager) Notify(title, message string, opts ...NotificationOption) string
Notify creates a notification from the provided title and message.
func (*Manager) Push ¶
func (m *Manager) Push(n Notification) string
Push adds a prepared notification and returns its ID.
type Notification ¶
type Notification struct {
// ID uniquely identifies the notification. A stable ID is generated when
// empty.
ID string
// Title is the first, emphasized line.
Title string
// Message is wrapped underneath the title.
Message string
// Severity selects the visual style.
Severity Severity
// TTL controls how long the notification remains visible. Zero uses the
// manager default; negative values make the notification sticky.
TTL time.Duration
// Created is the timestamp used for TTL and entrance animation. The current
// manager clock is used when Created is zero.
Created time.Time
// Icon overrides the severity icon when non-zero.
Icon rune
// Progress is the optional progress value in the range [0, 1].
Progress float64
// ShowProgress controls whether Progress is drawn.
ShowProgress bool
// Actions are compact labels drawn at the bottom of the toast.
Actions []Action
}
Notification is a single toast entry.
type NotificationOption ¶
type NotificationOption interface {
// contains filtered or unexported methods
}
NotificationOption configures a notification passed to Notify.
func Sticky ¶
func Sticky() NotificationOption
Sticky makes the notification stay visible until dismissed.
func WithAction ¶
func WithAction(label string, callback func() error) NotificationOption
WithAction appends a clickable action label to the notification footer.
func WithActionValues ¶
func WithActionValues(actions ...Action) NotificationOption
WithActionValues replaces the notification footer with prepared actions.
func WithActions ¶
func WithActions(actions ...string) NotificationOption
WithActions sets compact action labels for the notification footer.
func WithCreated ¶
func WithCreated(created time.Time) NotificationOption
WithCreated sets the notification creation time.
func WithIcon ¶
func WithIcon(icon rune) NotificationOption
WithIcon sets a notification-specific icon.
func WithProgress ¶
func WithProgress(progress float64) NotificationOption
WithProgress shows a progress bar clamped to the range [0, 1].
func WithSeverity ¶
func WithSeverity(sev Severity) NotificationOption
WithSeverity sets the notification severity.
func WithTTL ¶
func WithTTL(ttl time.Duration) NotificationOption
WithTTL sets the notification lifetime.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures a Manager.
func ActionCellOpts ¶
ActionCellOpts sets the base styling for action labels.
func AnimationDuration ¶
AnimationDuration sets how long entrance animations run.
func AnimationMode ¶
AnimationMode sets the notification entrance animation.
func CustomPosition ¶
func CustomPosition(fn PositionFunc) Option
CustomPosition sets a custom placement function and selects PlacementCustom.
func DefaultTTL ¶
DefaultTTL sets the lifetime used by notifications that do not set a TTL.
func DismissOnClick ¶
DismissOnClick controls whether clicking a visible toast removes it.
func FillCellOpts ¶
FillCellOpts sets the base styling for toast interior cells.
func MaxMessageLines ¶
MaxMessageLines sets the maximum message lines shown in each toast.
func MaxVisible ¶
MaxVisible sets the maximum number of notifications drawn at once.
func MessageCellOpts ¶
MessageCellOpts sets the base styling for toast message text.
func MinimumSize ¶
MinimumSize sets the smallest canvas requested by the widget.
func NewestFirst ¶
NewestFirst controls whether the newest notifications are closest to the configured anchor.
func SeverityStyle ¶
SeverityStyle replaces the visual style for a severity.
func SlideDirection ¶
SlideDirection sets the edge used by AnimationSlide.
func Stack ¶
func Stack(direction StackDirection) Option
Stack sets how multiple visible notifications are stacked.
func TitleCellOpts ¶
TitleCellOpts sets the base styling for toast titles.
type Placement ¶
type Placement int
Placement identifies the anchor point used for toast stacks.
const ( // PlacementTopRight anchors notifications to the upper-right corner. PlacementTopRight Placement = iota // PlacementTopLeft anchors notifications to the upper-left corner. PlacementTopLeft // PlacementBottomRight anchors notifications to the lower-right corner. PlacementBottomRight // PlacementBottomLeft anchors notifications to the lower-left corner. PlacementBottomLeft // PlacementCenter anchors notifications near the center of the canvas. PlacementCenter // PlacementCustom delegates placement to a caller-provided PositionFunc. PlacementCustom )
Placement values supported by Manager.
type PositionFunc ¶
PositionFunc returns the top-left corner for a toast.
The canvas rectangle is the full drawing area, size is the toast's requested size, and index is the toast's index in the visible stack.
type Severity ¶
type Severity int
Severity identifies the semantic style of a notification.
const ( // SeverityInfo is the default informational notification style. SeverityInfo Severity = iota // SeveritySuccess is used for successful operations. SeveritySuccess // SeverityWarning is used for warnings and recoverable problems. SeverityWarning // SeverityError is used for failures and destructive outcomes. SeverityError // SeverityNeutral is used for low-emphasis notifications. SeverityNeutral )
Severity values supported by Manager.
type StackDirection ¶
type StackDirection int
StackDirection identifies how multiple notifications are stacked.
const ( // StackAuto chooses a natural stack direction for the configured Placement. StackAuto StackDirection = iota // StackDown stacks later notifications downward from the anchor. StackDown // StackUp stacks later notifications upward from the anchor. StackUp )
StackDirection values supported by Manager.
type Style ¶
type Style struct {
// Icon is drawn before the notification title when non-zero.
Icon rune
// Accent is the default accent color used when a more specific cell option
// is not supplied.
Accent cell.Color
// BorderCellOpts styles the toast border.
BorderCellOpts []cell.Option
// FillCellOpts styles the toast interior fill cells.
FillCellOpts []cell.Option
// TitleCellOpts styles the notification title.
TitleCellOpts []cell.Option
// MessageCellOpts styles the notification message.
MessageCellOpts []cell.Option
// IconCellOpts styles the severity icon.
IconCellOpts []cell.Option
// ProgressCellOpts styles the optional progress bar.
ProgressCellOpts []cell.Option
}
Style defines visual details for one notification severity.
type Surface ¶
type Surface struct {
// contains filtered or unexported fields
}
Surface is a reusable overlay widget that hosts toast managers at multiple placements.
Use Manager directly when an application needs one stack. Use Surface when a single widget should support multiple corners or a custom overlay point.
Implements widgetapi.Widget. This object is thread-safe.
func NewSurface ¶
func NewSurface(opts ...SurfaceOption) (*Surface, error)
NewSurface returns a toast surface with one default placement registered.
func (*Surface) Clear ¶
func (s *Surface) Clear()
Clear removes all notifications from every registered placement.
func (*Surface) Notify ¶
func (s *Surface) Notify(title, message string, opts ...NotificationOption) string
Notify adds a notification to the surface's default placement.
func (*Surface) NotifyAt ¶
func (s *Surface) NotifyAt(p Placement, title, message string, opts ...NotificationOption) string
NotifyAt adds a notification to the requested placement.
Built-in placements are created lazily. PlacementCustom must be registered first with Surface.Register or SurfacePlacement so it can provide a CustomPosition option.
type SurfaceOption ¶
type SurfaceOption interface {
// contains filtered or unexported methods
}
SurfaceOption configures a Surface.
func DefaultPlacement ¶
func DefaultPlacement(p Placement) SurfaceOption
DefaultPlacement sets the placement used by Surface.Notify.
func DefaultToastOptions ¶
func DefaultToastOptions(opts ...Option) SurfaceOption
DefaultToastOptions sets options inherited by managers created by a Surface.
func SurfaceMinimumSize ¶
func SurfaceMinimumSize(size image.Point) SurfaceOption
SurfaceMinimumSize sets the smallest canvas requested by a Surface.
func SurfacePlacement ¶
func SurfacePlacement(p Placement, opts ...Option) SurfaceOption
SurfacePlacement pre-registers a placement on a Surface.