API Reference

Complete API documentation for cToast class.

Table of Contents

• Enumerations
• Chain Call Methods
• Management Methods
• Properties
• Events
• Method Call Order
• Error Handling

Enumerations

EnumPos - Display Positions

Public Enum EnumPos
    LeftTop = 0      ' Top-left (stacking)
    LeftCenter = 1   ' Left-center (overlay)
    LeftBottom = 2   ' Bottom-left (stacking)
    CenterTop = 3    ' Top-center (sequential stacking)
    Center = 4       ' Center (overlay)
    CenterBottom = 5 ' Bottom-center (reverse stacking)
    RightTop = 6     ' Top-right (stacking)
    RightCenter = 7  ' Right-center (overlay)
    RightBottom = 8  ' Bottom-right (stacking)
End Enum

Description: Defines 9 display positions for the popup.

Stacking Behavior:

• Center positions (Center, LeftCenter, RightCenter): Only one popup can exist, new ones overlay old ones
• Top positions (CenterTop, LeftTop, RightTop): Sequential stacking, newest at the bottom
• Bottom positions (CenterBottom, LeftBottom, RightBottom): Reverse stacking, newest at the top

EnumTheme - Color Themes

Public Enum EnumTheme
    Light = 0  ' Light theme (default)
    Dark = 1   ' Dark theme
End Enum

Description: Defines color themes for the popup.

Features:

• Light theme: White background, suitable for light interface
• Dark theme: Dark background, suitable for dark interface

EnumState - State Themes

Public Enum EnumState
    Info = 0     ' Information (blue)
    Success = 1  ' Success (green)
    Warning = 2  ' Warning (yellow)
    Danger = 3   ' Danger (red)
End Enum

Description: Defines state themes that control color and icon.

State Colors:

• Info: Blue (#007BFF), information prompts
• Success: Green (#28A745), success messages
• Warning: Yellow (#FFC107), warning messages
• Danger: Red (#DC3545), error messages

Chain Call Methods

All chain call methods return Me to support chained calling.

Pos

Public Function Pos(ByVal ePos As EnumPos) As cToast

Parameters:

• ePos: Display position enumeration value

Return Value: Returns Me to support chained calling

Description: Sets the display position of the popup. Must be called before Show.

Example:

With New cToast
    .Pos(RightTop).Show "Message", 2000, "Title"
End With

State

Public Function State(ByVal eState As EnumState) As cToast

Parameters:

• eState: State enumeration value

Return Value: Returns Me to support chained calling

Description: Sets the state theme of the popup, controlling color and icon.

Example:

With New cToast
    .State(Success).Show "Success", 2000
End With

Theme

Public Function Theme(ByVal eTheme As EnumTheme) As cToast

Parameters:

• eTheme: Theme enumeration value

Return Value: Returns Me to support chained calling

Description: Sets the color theme of the popup.

Example:

With New cToast
    .Theme(Dark).Show "Dark theme message", 2000
End With

InstIndex

Public Function InstIndex(ByVal Index As Long) As cToast

Parameters:

• Index: Stack index, starting from 0

Return Value: Returns Me to support chained calling

Description: Manually sets the stacking index of the popup.

Note:

• Center positions (Center, LeftCenter, RightCenter) do not support stacking, calling this method has no effect
• If not called, the system will automatically calculate and assign an index

Example:

With New cToast
    .Pos(RightTop).InstIndex(0).Show "First message", 0
End With

Tag

Public Function Tag(ByVal TagName As String) As cToast

Parameters:

• TagName: Unique identifier string

Return Value: Returns Me to support chained calling

Description: Sets a unique identifier for the popup, used for management and closing.

Note:

• Popups with the same TagName will not be created repeatedly
• Used in conjunction with CloseMe to close specific popups

Example:

With New cToast
    .Tag("msg1").Show "Message 1", 0
End With

' Close by name
Toast.CloseMe "msg1"

Show

Public Sub Show(Optional ByVal Content As String = "", _
                Optional ByVal DelayMs As Long = 3000, _
                Optional ByVal Title As String = "")

Parameters:

• Content: Popup content text
• DelayMs: Display duration in milliseconds, 0 means no auto-close
• Title: Popup title text

Description: Displays the popup.

Example:

With New cToast
    .Pos(RightTop).State(Success).Show "Operation successful", 2000, "Notification"
End With

Management Methods

CloseMe

Public Function CloseMe(ByVal TagName As String) As Boolean

Parameters:

• TagName: The unique identifier of the popup to close

Return Value:

• True: Successfully closed
• False: Popup does not exist or failed to close

Description: Closes the popup with the specified TagName.

Example:

Dim Toast As New cToast
Toast.Tag("warning1").Show "Warning", 0

' Later close
Toast.CloseMe "warning1"

CloseAll

Public Sub CloseAll()

Description: Closes all currently displayed popups.

Example:

Dim Toast As New cToast

' Display multiple popups
Toast.State(Info).Show "Message 1", 0
Toast.State(Warning).Show "Message 2", 0

' Close all at once
Toast.CloseAll

Exists

Public Function Exists(ByVal TagName As String) As Boolean

Parameters:

• TagName: Unique identifier string

Return Value:

• True: Popup exists
• False: Popup does not exist

Description: Checks if a popup with the specified TagName exists.

Example:

If Toast.Exists("warning1") Then
    Toast.CloseMe "warning1"
End If

Properties

Count

Public Property Get Count() As Long

Return Value: Current number of active popups

Description: Gets the total number of currently displayed popups.

Example:

Debug.Print "Current popups: " & Toast.Count

ActiveKeys

Public Property Get ActiveKeys() As Collection

Return Value: Collection containing all active popup TagNames

Description: Gets a collection of all currently active popup TagNames.

Example:

Dim Keys As Collection
Dim Key As Variant

Set Keys = Toast.ActiveKeys

For Each Key In Keys
    Debug.Print "Active popup: " & CStr(Key)
Next Key

Events

OnToastCountChange

Public Event OnToastCountChange(ByVal TagName As String, _
                                 ByVal IsDelete As Boolean, _
                                 ByVal CurrentCount As Long)

Parameters:

• TagName: The TagName of the popup that changed
• IsDelete: Whether it was a delete operation (True=deleted, False=added)
• CurrentCount: Current total number of popups

Description: Triggered when the number of popups changes (add or delete).

Usage Scenario:

• Update UI list
• Display current count statistics
• Trigger other business logic

Example:

Private WithEvents Toast As cToast

Private Sub Toast_OnToastCountChange(ByVal TagName As String, _
                                     ByVal IsDelete As Boolean, _
                                     ByVal CurrentCount As Long)
    If IsDelete Then
        Debug.Print "Popup " & TagName & " was closed"
    Else
        Debug.Print "Popup " & TagName & " was created, total: " & CurrentCount
    End If
End Sub

OnCloseAll

Public Event OnCloseAll(ByVal ClosedCount As Long)

Parameters:

• ClosedCount: Number of popups closed

Description: Triggered when CloseAll is called to batch close popups.

Usage Scenario:

• Perform batch cleanup operations
• Update UI after all popups close
• Trigger logging or statistics

Example:

Private WithEvents Toast As cToast

Private Sub Toast_OnCloseAll(ByVal ClosedCount As Long)
    Debug.Print "Batch closed " & ClosedCount & " popups"
    RefreshUI
End Sub

Method Call Order

Recommended Call Sequence

With New cToast
    ' 1. Set position (recommended to set first)
    .Pos(RightTop)
    
    ' 2. Set state
    .State(Success)
    
    ' 3. Set theme (optional, defaults to Light)
    .Theme(Dark)
    
    ' 4. Set Tag (optional, for management)
    .Tag("msg1")
    
    ' 5. Set stack index (optional, auto-calculated if not set)
    .InstIndex(0)
    
    ' 6. Display (must be last)
    .Show "Content", 2000, "Title"
End With

Chain Call Version

With New cToast
    .Pos(RightTop).State(Success).Theme(Dark).Tag("msg1").Show "Content", 2000, "Title"
End With

Minimal Call

With New cToast
    .Show "Simple message"
End With

Error Handling

Common Error Scenarios

1. TagName Not Unique

   • Issue: Popups with the same TagName will not be created
   • Solution: Ensure TagName uniqueness or use auto-generated Tags

2. Center Position Stacking Invalid

   • Issue: InstIndex called on Center, LeftCenter, RightCenter has no effect
   • Solution: Avoid calling InstIndex on these positions

3. Show Not Called

   • Issue: Popup won't display without calling Show
   • Solution: Ensure Show method is called as the last step

4. Object Not Released

   • Issue: Not releasing object reference may cause memory issues
   • Solution: Use Set Toast = Nothing when done

Error Handling Example

Private Sub ShowToastSafely()
    On Error GoTo ErrorHandler
    
    Dim Toast As New cToast
    
    ' Try to display
    Toast.Pos(RightTop).State(Success).Show "Operation successful", 2000, "Notification"
    
    Exit Sub
    
ErrorHandler:
    Debug.Print "Error displaying popup: " & Err.Description
    ' Perform cleanup
    Set Toast = Nothing
End Sub

Best Practices

1. Always check TagName uniqueness
2. Use appropriate positions for different scenarios
3. Set reasonable display duration
4. Use persistent display for important messages (DelayMs=0)
5. Release object references promptly
6. Handle events appropriately in multi-popup scenarios