CMFCDesktopAlertWnd Class

The CMFCDesktopAlertWnd class implements the functionality of a modeless dialog box which appears on the screen to inform the user about an event.

For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

Syntax

class CMFCDesktopAlertWnd : public CWnd

Members

Public Methods

Name	Description
CMFCDesktopAlertWnd::Create	Creates and initializes the desktop alert window.
CMFCDesktopAlertWnd::GetAnimationSpeed	Returns the animation speed.
CMFCDesktopAlertWnd::GetAnimationType	Returns the animation type.
CMFCDesktopAlertWnd::GetAutoCloseTime	Returns the auto-close time out.
CMFCDesktopAlertWnd::GetCaptionHeight	Returns the height of the caption.
CMFCDesktopAlertWnd::GetDialogSize
CMFCDesktopAlertWnd::GetLastPos	Returns the last valid position of the desktop alert window on the screen.
CMFCDesktopAlertWnd::GetTransparency	Returns the transparency level.
CMFCDesktopAlertWnd::HasSmallCaption	Determines whether the desktop alert window is displayed with the small caption.
CMFCDesktopAlertWnd::OnBeforeShow
CMFCDesktopAlertWnd::OnClickLinkButton	Called by the framework when the user clicks a link button located on the desktop alert menu.
CMFCDesktopAlertWnd::OnCommand	The framework calls this member function when the user selects an item from a menu, when a child control sends a notification message, or when an accelerator keystroke is translated. (Overrides CWnd::OnCommand.)
CMFCDesktopAlertWnd::OnDraw
CMFCDesktopAlertWnd::ProcessCommand
CMFCDesktopAlertWnd::SetAnimationSpeed	Sets the new animation speed.
CMFCDesktopAlertWnd::SetAnimationType	Sets the animation type.
CMFCDesktopAlertWnd::SetAutoCloseTime	Sets the auto-close time out.
CMFCDesktopAlertWnd::SetSmallCaption	Switches between small and normal captions.
CMFCDesktopAlertWnd::SetTransparency	Sets the transparency level.

Remarks

A desktop alert window can be transparent, it can appear with animation effects, and it can disappear (after a specified delay or when the user dismisses it by clicking the close button).

A desktop alert window can also contain a default dialog that in turn contains an icon, message text (a label), and a link. Alternatively, a desktop alert window can contain a custom dialog from the application's resources.

You create a desktop alert window in two steps. First, call the constructor to construct the CMFCDesktopAlertWnd object. Second, call the CMFCDesktopAlertWnd::Create member function to create the window and attach it to the CMFCDesktopAlertWnd object.

The CMFCDesktopAlertWnd object creates a special child dialog box that fills the client area of the desktop alert window. The dialog owns all the controls that are positioned on it.

To display a custom dialog box on the popup window, follow these steps:

1. Derive a class from CMFCDesktopAlertDialog.

2. Create a child dialog box template in the resources.

3. Call CMFCDesktopAlertWnd::Create using the resource ID of the dialog box template and a pointer to the runtime class information of the derived class.

4. Program the custom dialog box to handle all notifications coming from the hosted controls, or program the hosted controls to handle these notifications directly.

Use the following functions to control the behavior of the desktop alert window:

• Set the animation type by calling CMFCDesktopAlertWnd::SetAnimationType. Valid options include unfold, slide, and fade.

• Set the animation frame speed by calling CMFCDesktopAlertWnd::SetAnimationSpeed.

• Set the transparency level by calling CMFCDesktopAlertWnd::SetTransparency.

• Change the size of the caption to small by calling CMFCDesktopAlertWnd::SetSmallCaption. The small caption is 7 pixels high.

Example

The following example illustrates how to use various methods in the CMFCDesktopAlertWnd class to configure a CMFCDesktopAlertWnd object. The example shows how to set an animation type, set the transparency of the pop-up window, specify that the alert window displays a small caption, and set the time that elapses before the alert window automatically closes. The example also demonstrates how to create and initialize the desktop alert window. This code snippet is part of the Desktop Alert Demo sample.

CMFCDesktopAlertWnd *pPopup = new CMFCDesktopAlertWnd;

// int m_nAnimation
pPopup->SetAnimationType((CMFCPopupMenu::ANIMATION_TYPE)m_nAnimation);

// int m_nAnimationSpeed
pPopup->SetAnimationSpeed(m_nAnimationSpeed);

// int m_nTransparency
pPopup->SetTransparency((BYTE)m_nTransparency);

// BOOL m_bSmallCaption
pPopup->SetSmallCaption(m_bSmallCaption);

// BOOL m_bAutoClose, int m_nAutoCloseTime
pPopup->SetAutoCloseTime(m_bAutoClose ? m_nAutoCloseTime * 1000 : 0);

// int m_nPopupSource
if (m_nPopupSource == 0)
{
   // int m_nVisualMngr
   // CPoint m_ptPopup
   // The this pointer points to a CDesktopAlertDemoDlg class which extends the CDialogEx class.
   if (m_nVisualMngr == 5) // MSN-style
   {
      pPopup->Create(this, IDD_DIALOG2, NULL,
                     m_ptPopup, RUNTIME_CLASS(CMSNDlg));
   }
   else
   {
      pPopup->Create(this, IDD_DIALOG1,
                     m_menuPopup.GetSubMenu(0)->GetSafeHmenu(),
                     m_ptPopup, RUNTIME_CLASS(CMyPopupDlg));
   }
}

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CMFCDesktopAlertWnd

Requirements

Header: afxDesktopAlertWnd.h

CMFCDesktopAlertWnd::Create

Creates and initializes the desktop alert window.

virtual BOOL Create(
    CWnd* pWndOwner,
    UINT uiDlgResID,
    HMENU hMenu = NULL,
    CPoint ptPos = CPoint(-1,-1),
    CRuntimeClass* pRTIDlgBar = RUNTIME_CLASS(CMFCDesktopAlertDialog));

virtual BOOL Create(
    CWnd* pWndOwner,
    CMFCDesktopAlertWndInfo& params,
    HMENU hMenu = NULL,
    CPoint ptPos = CPoint(-1,-1));

Parameters

pWndOwner
[in, out] Specifies the owner of the alert window. That owner will then receive all notifications for the desktop alert window. This value cannot be NULL.

uiDlgResID
[in] Specifies the resource ID of the alert window.

hMenu
[in] Specifies the menu that displays when the user clicks the menu button. If NULL, the menu button is not displayed.

ptPos
[in] Specifies the initial position where the alert window is displayed, using screen coordinates. If this parameter is (-1, -1), the alert window is displayed in the lower-right corner of the screen.

pRTIDlgBar
[in] Runtime class information for a custom dialog box class that covers the alert window's client area.

params
[in] Specifies parameters that are used to create an alert window.

Return Value

TRUE if the alert window was created successfully; otherwise, FALSE.

Remarks

Call this method to create an alert window. The client area of the alert window contains a child dialog box that hosts all controls that are displayed to the user.

The first method overload creates an alert window that contains a child dialog box that is loaded from the application's resources. The first method overload can also specify runtime class information for a custom dialog box class.

The second method overload creates an alert window that contains default controls. You can specify which controls to display by modifying the CMFCDesktopAlertWndInfo Class.

CMFCDesktopAlertWnd::GetAnimationSpeed

Returns the animation speed.

UINT GetAnimationSpeed() const;

Return Value

The animation speed of the alert window, in milliseconds.

Remarks

The animation speed describes how fast the alert window opens and closes.

CMFCDesktopAlertWnd::GetAnimationType

Returns the animation type.

CMFCPopupMenu::ANIMATION_TYPE GetAnimationType();

Return Value

One of the following animation types:

• NO_ANIMATION

• UNFOLD

• SLIDE

• FADE

• SYSTEM_DEFAULT_ANIMATION

CMFCDesktopAlertWnd::GetAutoCloseTime

Returns the auto-close time out.

int GetAutoCloseTime() const;

Return Value

The time, in milliseconds, after which the alert window will automatically close.

Remarks

Use this method to determine how much time should elapse before the alert window will automatically close.

CMFCDesktopAlertWnd::GetCaptionHeight

Returns the height of the caption.

virtual int GetCaptionHeight();

Return Value

The height, in pixels, of the caption.

Remarks

This method can be overridden in a derived class. The default implementation either: returns the small caption height value (7 pixels) if the popup window should display the small caption, or the value obtained from the Windows API function GetSystemMetrics(SM_CYSMCAPTION).

CMFCDesktopAlertWnd::GetLastPos

Returns the last position of the desktop alert window on the screen.

CPoint GetLastPos() const;

Return Value

A point, in screen coordinates.

Remarks

This method returns the last valid position of the alert window on the screen.

CMFCDesktopAlertWnd::GetTransparency

Returns the transparency level.

BYTE GetTransparency() const;

Return Value

A transparency level between 0 and 255, inclusive. The greater the value, the more opaque the window.

Remarks

Use this method to retrieve the current transparency level of the alert window.

CMFCDesktopAlertWnd::HasSmallCaption

Determines whether the desktop alert window has a small caption or a regular-size caption.

BOOL HasSmallCaption() const;

Return Value

TRUE if the popup window is displayed with a small caption; FALSE if the popup window is displayed with a regular-sized caption.

Remarks

Use this method to determine whether the popup window has a small caption or a regular-size caption. By default, the small caption is 7 pixels high. You can obtain the height of the regular-size caption by calling the Windows API function GetSystemMetrics(SM_CYCAPTION).

CMFCDesktopAlertWnd::OnBeforeShow

virtual BOOL OnBeforeShow(CPoint&);

Parameters

[in] CPoint&

Return Value

Remarks

CMFCDesktopAlertWnd::OnClickLinkButton

Called by the framework when the user clicks a link button located on the desktop alert menu.

virtual BOOL OnClickLinkButton(UINT uiCmdID);

Parameters

uiCmdID
[in] This parameter is not used.

Return Value

Always FALSE.

Remarks

Override this method in a derived class if you want to be notified when a user clicks the link on the alert window.

CMFCDesktopAlertWnd::OnCommand

virtual BOOL OnCommand(
    WPARAM wParam,
    LPARAM lParam);

Parameters

[in] wParam

[in] lParam

Return Value

Remarks

CMFCDesktopAlertWnd::OnDraw

virtual void OnDraw(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCDesktopAlertWnd::ProcessCommand

BOOL ProcessCommand(HWND hwnd);

Parameters

[in] hwnd

Return Value

Remarks

CMFCDesktopAlertWnd::SetAnimationSpeed

Sets the new animation speed.

void SetAnimationSpeed(UINT nSpeed);

Parameters

nSpeed
[in] Specifies the new animation speed, in milliseconds.

Remarks

Call this method to set the animation speed for the alert window. The default animation speed is 30 milliseconds.

CMFCDesktopAlertWnd::SetAnimationType

Sets the animation type.

void SetAnimationType(CMFCPopupMenu::ANIMATION_TYPE type);

Parameters

type
[in] Specifies the animation type.

Remarks

Call this method to set animation type. You can specify one of the following values:

• NO_ANIMATION

• UNFOLD

• SLIDE

• FADE

• SYSTEM_DEFAULT_ANIMATION

CMFCDesktopAlertWnd::SetAutoCloseTime

Sets the auto-close time out.

void SetAutoCloseTime(int nTime);

Parameters

nTime
[in] The time, in milliseconds, that elapses before the alert window automatically closes.

Remarks

The alert window is automatically closed after the specified time if the user does not interact with the window.

CMFCDesktopAlertWnd::SetSmallCaption

Switches between small and regular-size captions.

void SetSmallCaption(BOOL bSmallCaption = TRUE);

Parameters

bSmallCaption
[in] TRUE to specify that the alert window displays a small caption; otherwise, FALSE to specify that the alert window displays a regular-size caption.

Remarks

Call this method to display the small or regular-size caption. By default, the small caption is 7 pixels high. You can obtain the size of the regular caption by calling the Windows API function GetSystemMetrics(SM_CYCAPTION).

CMFCDesktopAlertWnd::SetTransparency

Sets the transparency level of the popup window.

void SetTransparency(BYTE nTransparency);

Parameters

nTransparency
[in] Specifies the transparency level. This value must be between 0 and 255, inclusive. The greater the value, the more opaque the window.

Remarks

Call this function to set the transparency level of the popup window.

CMFCDesktopAlertWnd::GetDialogSize

virtual CSize GetDialogSize();

Return Value

Remarks

See also

Hierarchy Chart
Classes
CMFCDesktopAlertWndInfo Class
CMFCDesktopAlertDialog Class
CWnd Class