Alert Popup

What it is for

The alert is a borderless, top-most window with a shaped skin, in the manner of the Outlook and MSN Messenger desktop alerts. It is shown without activation, so typing carries on in the application while it is up. It carries a title, a line of body text, a title icon, an exit button and, optionally, a menu.

How to use it

Create one AlertPopup, keep it for the life of the form, and call one of the Show() overloads each time there is something to say. Showing it again while it is up starts it afresh with the new text. Show it on the UI thread; Hide may be called from any thread.

Each showing has three phases, each with its own duration: it grows out of the corner, stays for the visible time, and then goes away in the ControlDisappearingStyle. While the pointer is over it it stays (AlertPopupIsShownWhenMouseIsOver), and KeepShowingUntilHiddenDeterministically keeps it up until Hide is called.

Where it appears

In a corner of the primary screen's working area, clear of the taskbar – the bottom right unless PopupScreenCorner says otherwise – or at AlertPopupCustomLocation. The user can drag it by the strip along its top (AllowUserToDragDropPopupWindow).

Responding to the user

Clicks are reported, not acted on: PopupMessageTextClicked, PopupTitleTextClicked, PopupExitButtonClicked, PopupCustomImageClicked and ContextMenuShown. AboutToPopup, AboutToPlaySound, PopupExitButtonClicked and ContextMenuShown can each be cancelled.

Appearance

• AlertPopupStyle and PopupAlertThemeColor choose the built-in skin; DrawUsingCustomColors fills it with colours of your own.
• CustomAlertPopupWindowImage replaces the skin with a picture of your own, whose shape the window takes.
• EnableCustomUserPaint hands the whole surface to your Control.Paint handler and child controls.

The built-in skins and their layout are in logical pixels and are scaled for the display.

An alert for incoming orders on a dispatch screen: clicking the text opens the order, and the exit button only hides the alert once it has been logged.

using System;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.NotificationControls;

public partial class DispatchForm : Form
{
    private readonly AlertPopup orderAlert = new AlertPopup
    {
        AlertPopupStyle = AlertPopupStyle.Outlook,
        PopupAlertThemeColor = AlertPopupThemeColor.Silver,
        PopupScreenCorner = AlertPopupScreenCorner.BottomRight,
        ControlDisappearingStyle = DisappearingStyle.VanishOutWhileSlidingDown,
        CanClickTitle = true
    };

    private string latestOrderNumber;

    public DispatchForm()
    {
        InitializeComponent();

        orderAlert.PopupMessageTextClicked += (sender, e) => OpenOrder(latestOrderNumber);
        orderAlert.PopupTitleTextClicked += (sender, e) => OpenOrder(latestOrderNumber);
        orderAlert.PopupExitButtonClicked += (object sender, ref bool cancelNow) =>
            Console.WriteLine("Alert dismissed for " + latestOrderNumber);

        FormClosed += (sender, e) => orderAlert.Dispose();
    }

    private void OnOrderReceived(string orderNumber, string customer, decimal total)
    {
        latestOrderNumber = orderNumber;

        // Grow for 400 ms, stay for 6 seconds, go away over 600 ms.
        orderAlert.Show("New order " + orderNumber,
                        customer + " - " + total.ToString("C"),
                        400, 6000, 600);
    }

    private void OpenOrder(string orderNumber)
    {
        // Show the order in the application.
    }
}