AlertPopup

Initialises an alert in the AlertPopupStyle.Outlook style and the AlertPopupThemeColor.Blue theme, for the bottom right-hand corner of the screen, with an exit button, a clickable body text and no sound.

The window is created here but stays hidden until a Show method is called.

Gets or sets the message drawn in the body of the alert.

The message is centred and is not word-wrapped; one too long for the body ends in an ellipsis.

Every Show method sets it. Setting it while the alert is on screen redraws the alert – to count down a reconnection, say – but the area that responds to the pointer stays measured for the message it was shown with.

Gets or sets the colour of the body text.

Gets or sets the font of the body text.

Gets or sets the colour of the title.

Gets or sets the font of the title.

Gets or sets the colour of the body text while the pointer is over it, marking it as a link.

Used only while CanClickAlertText is set.

Gets or sets the font of the body text while the pointer is over it.

The text's clickable area is measured in this font.

Gets or sets the colour of the title while the pointer is over it.

Used only while CanClickTitle is set.

Gets or sets the font of the title while the pointer is over it.

The title's clickable area is measured in this font, so it covers the title in either font.

Gets or sets where the alert appears when it is shown by an overload that takes no location.

With a bottom corner set in PopupScreenCorner the alert grows upwards from this point, so it is where the alert's lower-left corner comes to rest; with a top corner it is the upper-left corner.

Gets or sets whether an alert that is going away comes back when the pointer moves onto it.

An alert closed with its exit button does not come back.

Gets or sets whether the alert stays on screen past its visible time while the pointer is over it.

The alert starts to go away once the pointer leaves. That gives the user time to read and click.

Gets or sets which built-in skin the alert wears: Outlook's or MSN Messenger's.

The style sets the alert's size and shape, and where the title, text, icon and exit button go. PopupAlertThemeColor picks the colours of either skin. Only the Outlook style has a menu button.

Gets or sets the colour of the dotted rectangle drawn round the body text while the pointer is over it.

Drawn only while ShowTextAreaRectangle and CanClickAlertText are set.

Gets or sets the title drawn at the top of the alert.

Every Show method sets it. Setting it while the alert is on screen redraws the alert, but the area that responds to the pointer stays measured for the title it was shown with.

Gets or sets whether the user can move the alert by dragging the strip along its top edge.

The strip is the top 8 logical pixels of the alert; the pointer shows the move cursor over it. A moved alert goes away from where it was left.

Gets or sets whether the body text reacts to the pointer and raises PopupMessageTextClicked when clicked.

Under the pointer the text is drawn in AlertOnHoverBodyTextColor and AlertOnHoverBodyTextFont, inside a dotted rectangle while ShowTextAreaRectangle is set.

Gets or sets whether the exit button responds to the pointer and to clicks.

Set it to false to leave the button on show but inert. To remove it, set DisplayExitButton to false.

Gets or sets whether the title reacts to the pointer and raises PopupTitleTextClicked when clicked.

While it is clickable the title is drawn in AlertOnHoverTitleColor and AlertOnHoverTitleFont under the pointer, which shows a hand.

Gets or sets the colour of the menu button's highlight when it is a single colour.

Gets or sets the colour of the chevron drawn on the menu button.

The menu button is drawn only while Control.ContextMenu is set, in the AlertPopupStyle.Outlook style, without a CustomAlertPopupWindowImage.

Gets or sets the colour of the outline round the menu button while it is under the pointer or its menu is open.

Gets or sets how the alert goes away: fading out, sliding back into its edge of the screen, or both.

The styles that fade out also fade the alert in as it appears; DisappearingStyle.SlideDown shows it solid from the start.

Setting the property also sets the window's Opacity (to 1 when the previous style was DisappearingStyle.SlideDown, otherwise to 0), so set it while the alert is not on screen.

Gets or sets a picture to show as the whole alert, in place of the built-in skin – a branded banner, a reminder card.

The alert takes the picture's size, scaled for the display, and its shape: pixels of pure magenta (red 255, green 0, blue 255) are cut out of the window, so a picture with rounded corners painted on magenta gives a round-cornered alert.

While a picture is shown the alert draws no title, text, icon or menu button over it – put the message in the picture – but it does draw the exit button in the top right-hand corner. Clicks on the picture raise PopupCustomImageClicked. The image remains yours: the alert does not dispose it.

alert.CustomAlertPopupWindowImage = new Bitmap(@"C:\ProgramData\Contoso\renewal-banner.png");
alert.UseCustomAlertPopupWindowImage = true;
alert.PopupCustomImageClicked += (sender, e) => OpenRenewalPage();
alert.Show();

Gets or sets whether clicking an alert that shows CustomAlertPopupWindowImage raises PopupCustomImageClicked.

The pointer shows a hand over such an alert either way.

Gets or sets where the body text is drawn on the alert, in place of the style's own place for it.

The text is centred in the area and is not word-wrapped; text too long for it ends in an ellipsis. The clickable area is worked out when the alert is shown, so set this before calling a Show method.

The rectangle is used as it is, in device pixels, without scaling for the display – unlike the built-in areas, which are scaled.

Gets or sets an icon to draw as the exit button in place of the built-in one.

The icon is drawn 16 logical pixels square, whatever its own size, and does not change under the pointer.

Gets or sets the picture drawn as the alert's title icon, in place of the style's built-in one.

The icon is drawn at its own size up to 32 by 32 logical pixels; a larger picture is drawn at 32 by 32. It is placed by CustomTitleIconAlignment or CustomTitleIconLocation, or stretched over the alert by StretchTitleIconToCoverTheEntireControlArea.

It is not drawn while a CustomAlertPopupWindowImage is shown. The image remains yours: the alert does not dispose it.

Gets or sets where on the alert the title icon is placed: one of nine positions.

The icon is kept 8 logical pixels in from the edges; at ContentAlignment.TopRight it moves left of the exit button. Setting the alignment replaces any CustomTitleIconLocation.

Gets or sets exactly where the title icon's top-left corner is placed on the alert.

A location set here wins over the alignment until CustomTitleIconAlignment is set again or this is set back to Point.Empty.

Gets or sets where the title is drawn on the alert, in place of the style's own place for it.

The title is drawn on one line, left-aligned and centred vertically, and is cut short with an ellipsis if it does not fit. The clickable area is worked out when the alert is shown, so set this before calling a Show method.

The rectangle is used as it is, in device pixels, without scaling for the display – unlike the built-in areas, which are scaled.

Gets or sets the size of the surface you draw on when EnableCustomUserPaint is set – the size the alert window takes.

Setting it replaces CustomAlertPopupWindowImage with a blank bitmap of this size, whether or not custom painting is on, so set it before any image of your own. Set it before EnableCustomUserPaint, or set EnableCustomUserPaint again afterwards.

On a display scaled above 100% the window comes out larger than this size times the scale: the blank surface is made at the display's scale and is then scaled again as the window's skin.

alert.CustomUserWindowPaintSize = new Size(320, 140);
alert.EnableCustomUserPaint = true;
alert.Paint += (sender, e) =>
{
    e.Graphics.Clear(Color.White);
    TextRenderer.DrawText(e.Graphics, "Backup finished: 1,284 files", alert.Font,
                          new Point(12, 40), Color.DarkGreen);
};
alert.Controls.Add(new Button { Text = "View log", Location = new Point(12, 90), Width = 100 });

Gets or sets whether the alert has an exit button in its top right-hand corner.

Without it the alert goes away only by itself or by Hide.

Gets or sets whether custom colours fill the alert's body with one colour or a gradient.

Used while DrawUsingCustomColors is set.

Gets or sets whether the body of the skin is filled with colours of your own instead of the theme's.

The skin keeps its outline and shape; inside it the alert is filled with SpecificColor or with a gradient from StartColor to EndColor, as DrawUsingColorType says.

alert.DrawUsingCustomColors = true;
alert.DrawUsingColorType = CustomColorType.GradientColors;
alert.StartColor = Color.FromArgb(255, 243, 205);   // amber, for a warning
alert.EndColor = Color.White;
alert.GradientOrientationAngle = 90f;

Gets or sets whether you draw the alert yourself, in a Control.Paint handler, instead of the built-in skin.

Setting it to true gives the alert a blank, rectangular surface of CustomUserWindowPaintSize and sets UseCustomAlertPopupWindowImage. From then on the alert draws nothing of its own – no skin, text, icon or buttons – and raises Control.Paint, Control.MouseDown, Control.MouseMove, Control.MouseEnter and Control.MouseLeave instead of its click events. It still animates, and can still be dragged by its top strip. You can add child controls to it like any form.

Setting it back to false does not clear UseCustomAlertPopupWindowImage.

Gets or sets the colour the custom gradient in the alert's body ends in.

Gets or sets the colour the menu button's highlight gradient ends in.

Gets or sets whether the menu button's highlight is a gradient rather than a single colour.

The highlight is drawn while the button is under the pointer or its menu is open. The menu button is drawn only while Control.ContextMenu is set, in the AlertPopupStyle.Outlook style, without a CustomAlertPopupWindowImage.

Gets or sets the direction of the gradient in the alert's body when it is drawn in custom colours.

Gets or sets the direction of the colour gradient behind the menu button while it is under the pointer or its menu is open.

Used while FillContextMenuDropDownChevronRectangleWithGradientColors is set. The menu button is drawn only while Control.ContextMenu is set, in the AlertPopupStyle.Outlook style, without a CustomAlertPopupWindowImage.

Gets whether a mouse button is held down on the alert.

Gets or sets how opaque the alert window is, from 0 (invisible) to 1 (solid).

This property hides Opacity so that it can be set from any thread – off the UI thread the change is passed to the UI thread. Setting it yourself is overridden by the next step of the animation.

Gets or sets whether a sound is played each time the alert is shown.

The sound plays in the background as the alert starts to appear. Handle AboutToPlaySound to silence a particular showing.

Gets or sets the colour scheme of the built-in skin: blue, olive green or silver.

Applies to both AlertPopupStyle skins. Not used while DrawUsingCustomColors fills the skin, or a CustomAlertPopupWindowImage replaces it.

Gets or sets the corner of the screen's working area the alert appears in.

The screen is the one the application's active window is on, or the one under the pointer when none of its windows is active.

The corner also sets which way the alert travels: from a bottom corner it grows upwards and slides back down; from a top corner it grows downwards and draws back up. It sits a scroll bar's width in from the side of the working area, so it clears the taskbar.

The corner is not used when a location is given to the Show call or set in AlertPopupCustomLocation; it still sets the direction of travel.

Gets or sets whether the alert releases its animation timer each time it is hidden, rather than keeping it for the next showing.

The next Show creates a new timer, so the alert can go on being used. Worth setting for an alert that is shown rarely in a long-running application.

Gets or sets whether a dotted rectangle is drawn round the body text while the pointer is over it.

It marks the text as a link. Drawn in AlertTextSelectionRectangleColor, and only while CanClickAlertText is set.

Gets or sets the full path of the sound file played when the alert is shown.

Played only while PlaySoundWhenPopupIsDisplayed is set. Only wave files are supported.

alert.SoundPlayBackFile = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.Windows),
                                       @"Media\Windows Notify Messaging.wav");
alert.PlaySoundWhenPopupIsDisplayed = true;

Gets or sets the single colour the alert's body is filled with when it is drawn in custom colours.

Used while DrawUsingCustomColors is set and DrawUsingColorType is CustomColorType.SpecificColor. Takes effect the next time the alert is drawn.

Gets or sets the colour the custom gradient in the alert's body starts from.

Used while DrawUsingCustomColors is set and DrawUsingColorType is CustomColorType.GradientColors. Takes effect the next time the alert is drawn.

Gets or sets the colour the menu button's highlight gradient starts from.

Gets or sets whether the title icon is stretched over the whole alert, as a background picture under the text.

While it is set, CustomTitleIconAlignment and CustomTitleIconLocation are not used. The icon is CustomTitleIcon, or the built-in one when that is not set.

Gets or sets whether the alert shows CustomAlertPopupWindowImage instead of its built-in skin.

Tells the alert that its menu has closed, and starts it going away.

While its menu is open the alert stays on screen. Call this as the last line of each menu item's MenuItem.Click handler, so the alert goes away in its ControlDisappearingStyle once the user has made a choice.

var snooze = new MenuItem("Remind me in 10 minutes");
snooze.Click += (sender, e) =>
{
    reminders.Snooze(currentReminder, TimeSpan.FromMinutes(10));
    alert.CleanUpUponContextMenuItemClicked();
};

alert.ContextMenu = new ContextMenu();
alert.ContextMenu.MenuItems.Add(snooze);

Releases the timer that drives the animation and the skin bitmaps the alert made for itself.

Images you supplied – CustomAlertPopupWindowImage, CustomTitleIcon, CustomExitIcon – are not disposed; they remain yours.

Takes the alert off the screen at once, without its going-away animation.

Safe to call from any thread: off the UI thread the call is passed to the UI thread and returns before the alert has gone. It ends KeepShowingUntilHiddenDeterministically, and does nothing when the alert is not showing.

To let the alert go away in its ControlDisappearingStyle instead, leave it to its timer.

Keeps the alert on screen until Hide is called, instead of letting it go away after its visible time.

Call it after the Show method, because every Show starts with the alert's own timing again. Called while the alert is going away, it brings it back. Use it for news the user must acknowledge – a failed payment run, a lost connection.

alert.Show("Connection lost", "Trying to reconnect to the order server...");
alert.KeepShowingUntilHiddenDeterministically();

// Later, once the connection is back:
alert.Hide();

Raises Control.Click and clears the alert's open-menu state.

Control.Click is raised for a click anywhere on the alert. To act on a click on one part, handle PopupMessageTextClicked, PopupTitleTextClicked or PopupCustomImageClicked.

Shows the exit button pressed, and starts a drag when the press is on the strip along the top.

The Control.MouseDown event is raised only while EnableCustomUserPaint is set.

Notes that the pointer is over the alert, which keeps it on screen while AlertPopupIsShownWhenMouseIsOver is set.

The Control.MouseEnter event is raised only while EnableCustomUserPaint is set.

Notes that the pointer has left the alert, returning the title, text and buttons to their resting look.

The Control.MouseLeave event is raised only while EnableCustomUserPaint is set.

Lights up the part of the alert under the pointer – exit button, menu button, title or text – and moves the alert while it is being dragged.

The Control.MouseMove event is raised only while EnableCustomUserPaint is set.

Completes a click on the part of the alert under the pointer, raising the event for that part.

Raises ContextMenuShown and opens the menu, PopupExitButtonClicked and starts the alert going away, PopupTitleTextClicked, PopupMessageTextClicked or PopupCustomImageClicked.

While EnableCustomUserPaint is set none of these is raised. The Control.MouseUp event is raised in both modes, before the click is handled.

Raises the Control.Paint event while EnableCustomUserPaint is set, and does nothing otherwise.

The built-in drawing is done in OnPaintBackground.

Draws the whole alert: skin, exit and menu buttons, title icon, title and body text.

The alert is drawn off screen and copied in one step, so it does not flicker. While EnableCustomUserPaint is set nothing is drawn here, and the surface is yours.

Shows the alert with no title and no body text, with the standard timings.

The alert grows into place over half a second, stays for three seconds and goes away over half a second, in a corner of the screen (PopupScreenCorner) or at AlertPopupCustomLocation when that is set.

It clears AlertTitleText and AlertBodyText, so it suits an alert that carries its message in a picture (CustomAlertPopupWindowImage) or is drawn by you (EnableCustomUserPaint). This overload hides Show(): the alert is never activated and never takes the focus.

Shows the alert with this title and body text, with the standard timings.

The alert grows into place over half a second, stays for three seconds and goes away over half a second, in a corner of the screen (PopupScreenCorner) or at AlertPopupCustomLocation when that is set.

alert.Show("Export finished", "Orders-October.xlsx was saved to Documents");

Shows the alert with this title and body text, taking the times you give for each phase.

The alert appears in a corner of the screen (PopupScreenCorner) or at AlertPopupCustomLocation when that is set.

Shows the alert with this title and body text, for the times you give, at a place of your choosing.

Every other overload comes here. In order, it takes down an alert already on screen, raises AboutToPopup (and stops if that is cancelled), raises AboutToPlaySound and plays SoundPlayBackFile if PlaySoundWhenPopupIsDisplayed is set, measures the text, and starts the alert growing – fading in as well unless ControlDisappearingStyle is DisappearingStyle.SlideDown.

The animations move in small steps on a timer, so their durations are approximate. Call this method on the UI thread.

// Over the status bar of the main window rather than in a corner of the screen.
Point anchor = PointToScreen(new Point(ClientSize.Width - 340, statusStrip.Top));
alert.Show("Sync complete", "214 contacts updated", 300, 5000, 800, anchor);

Occurs each time the alert is shown, after AboutToPopup, before its sound would play.

Raised whether or not PlaySoundWhenPopupIsDisplayed is set. Set the handler's cancelNow argument to true to show the alert silently this time.

Occurs each time a Show method is called, before the alert appears.

Set the handler's cancelNow argument to true to stop it appearing – while the user is presenting, say. An alert that was already on screen has been taken down by then.

alert.AboutToPopup += (object sender, ref bool cancelNow) =>
{
    cancelNow = doNotDisturbCheckBox.Checked;
};

Occurs when the user clicks the menu button, before the menu opens.

The menu button – a small chevron beside the exit button – is drawn when the alert's Control.ContextMenu is set, in the AlertPopupStyle.Outlook style and without a CustomAlertPopupWindowImage. The menu opens below the button if it has any items.

Set the handler's cancelContextMenuDisplayNow argument to true to keep the menu closed, or to fill it with items for the current alert first.

Occurs when the user clicks an alert that is showing CustomAlertPopupWindowImage, anywhere but on the exit button and the drag strip along the top.

Raised only while UseCustomAlertPopupWindowImage and CustomAlertPopupWindowImageCanBeClicked are both set. The event data carries the mouse position, so a picture with several areas on it can tell which was clicked.

alert.PopupCustomImageClicked += (sender, e) =>
{
    // The left half of the banner opens the invoice, the right half snoozes the reminder.
    if (e.MouseEventArgs.X < alert.Width / 2) OpenInvoice(); else Snooze();
};

Occurs when the user clicks the exit button, before the alert starts to go away.

Set the handler's cancelNow argument to true to keep the alert on screen. Otherwise it goes away in its ControlDisappearingStyle, and does not come back under the pointer.

Occurs when the user clicks the body text, while CanClickAlertText is set.

Only the text itself is clickable, not the empty space round it. The alert stays on screen; call Hide from the handler to close it at once.

alert.PopupMessageTextClicked += (sender, e) =>
{
    alert.Hide();
    ordersGrid.Focus();
};

Occurs when the user clicks the title, while CanClickTitle is set.

The alert stays on screen; call Hide from the handler to close it at once.