Toast Notifications (Board View)

Toast notifications are non-blocking, transient messages that appear at the top-center of the board view during gameplay. They replace modal doAlertDialog calls for feedback that doesn't require player input.

Quick Start

// From any class with access to ClientGUI
clientgui.addToast(ToastLevel.INFO, "ECM mode switched to Ghost Targets");
clientgui.addToast(ToastLevel.WARNING, "Can't perform charge: No target!", currentEntity());
clientgui.addToast(ToastLevel.ERROR, "Cannot land: insufficient runway", currentEntity());

API

ClientGUI.addToast() (Recommended)

The preferred way to show toasts. Null-safe -- silently does nothing if the board view hasn't been initialized yet (e.g., during the lobby phase).

// Text only
clientgui.addToast(ToastLevel level, String text)

// Text with entity sprite icon
clientgui.addToast(ToastLevel level, String text, @Nullable Entity entity)

BoardToastOverlay.show() (Advanced)

Direct access via clientgui.getToastOverlay(). Use this when you need explicit duration control.

// Default duration from ToastLevel
show(ToastLevel level, String text)
show(ToastLevel level, String text, @Nullable Entity entity)

// Custom duration (milliseconds)
show(ToastLevel level, String text, @Nullable Entity entity, int durationMs)

Toast Levels

Level	Color	Default Duration	Use For
INFO	Blue	3 seconds	Routine confirmations, mode changes, informational feedback
SUCCESS	Green	3 seconds	Positive outcomes (roll succeeded, action completed)
WARNING	Amber	4 seconds	Validation errors the player can recover from (invalid target, wrong phase)
ERROR	Red	5 seconds	Hard failures (can't deploy here, no valid positions, equipment destroyed)

Entity Icons

When you pass an Entity to the toast, its 56x48 sprite icon appears to the left of the message text. This helps players immediately identify which unit the message refers to.

• Pass the entity when the message is about a specific unit
• Pass null (or use the 2-parameter overload) for system-level messages

// With unit icon -- player sees the Atlas sprite next to the message
clientgui.addToast(ToastLevel.WARNING, "Can't perform DFA: No target!", currentEntity());

// No icon -- general feedback
clientgui.addToast(ToastLevel.ERROR, "No minefield in hex!");

Custom Duration

Most toasts should use the level's default duration. Override only when you have a specific reason:

// Brief "invalid click" feedback -- 1.5 seconds is enough
clientgui.getToastOverlay().show(ToastLevel.WARNING, "Outside deploy area", null, 1500);

// Detailed report the player needs time to read -- 10 seconds
clientgui.getToastOverlay().show(ToastLevel.INFO, longReportText, null, 10000);

Behavior

• Toasts appear at top-center of the board viewport
• Multiple toasts stack downward, each on its own timer
• Each toast fades in (300ms), holds (per-level duration), then fades out (1000ms)
• When a toast expires, remaining toasts slide up smoothly to close the gap
• Maximum 5 visible toasts at once -- excess toasts force the oldest to fade out early
• Toasts are screen-fixed (they don't scroll with the map)
• Thread-safe -- addToast() can be called from any thread

When to Use Toasts vs. Other Feedback

Feedback Type	Use When
Toast	Transient feedback: validation errors, action confirmations, mode changes, roll results
Status bar (setStatusBarText)	Persistent phase state: "It's your turn", "Waiting for movement phase"
Modal dialog (doAlertDialog)	Only when the player MUST acknowledge before continuing (almost never needed)
Confirm dialog (doYesNoDialog)	Player must make a YES/NO decision

Localization

Always use localized message strings:

// Good -- localized
clientgui.addToast(ToastLevel.ERROR,
      Messages.getString("MovementDisplay.NoPlaceToUnload.message"));

// Bad -- hardcoded English
clientgui.addToast(ToastLevel.ERROR, "No place to unload");

Key Files

File	Purpose
BoardToastOverlay.java	Overlay class -- rendering, animation, message queue
ToastLevel.java	Severity enum with colors and default durations
ClientGUI.java	addToast() convenience methods, overlay registration