/** * @file XTPTrayIcon.h * * @copyright * (c) 1998-2025 Codejock Software, All Rights Reserved. * * This source file is the property of Codejock Software and must not be * redistributed by any means without the explicit written permission of * Codejock Software. * * The use of this source code is governed by the terms and conditions specified * in the Toolkit Pro license agreement. Codejock Software grants you, as a * single software developer, the limited right to use this software on one * computer only. * * Contact Information: * support@codejock.com * http://www.codejock.com * */ /** @cond */ #if !defined(__XTPTRAYICON_H__) # define __XTPTRAYICON_H__ /** @endcond */ # if _MSC_VER > 1000 # pragma once # endif // _MSC_VER > 1000 # include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h" /** @cond */ # ifndef NIIF_NONE # define NIIF_NONE 0x00000000 # define NIIF_INFO 0x00000001 # define NIIF_WARNING 0x00000002 # define NIIF_ERROR 0x00000003 # define NIIF_ICON_MASK 0x0000000F # endif # ifndef NIS_HIDDEN # define NIS_HIDDEN 0x00000001 # endif # ifndef NIF_STATE # define NIF_STATE 0x00000008 # define NIF_INFO 0x00000010 # endif # ifndef NIN_BALLOONSHOW # define NIN_BALLOONSHOW (WM_USER + 2) # define NIN_BALLOONHIDE (WM_USER + 3) # define NIN_BALLOONTIMEOUT (WM_USER + 4) # define NIN_BALLOONUSERCLICK (WM_USER + 5) # endif # ifndef NIN_SELECT # define NIN_SELECT (WM_USER + 0) # define NINF_KEY 0x1 # define NIN_KEYSELECT (NIN_SELECT | NINF_KEY) # endif # ifndef NIM_SETFOCUS # define NIM_SETFOCUS 0x00000003 # endif /** @endcond */ /** * @brief * CXTPTrayIcon is a CWnd derived class of the NOTIFYICONDATA structure. * It is used to display a system tray icon with an animation. */ class _XTP_EXT_CLASS CXTPTrayIcon : public CWnd { private: /** * @brief * TRAYICONDATA is a standalone helper structure. It is used by CXTPTrayIcon * to maintain an animation icon list. */ struct TRAYICONDATA { HICON hIcon; /**< Handle to the icon displayed. */ CString strToolTip; /**< A NULL-terminated string that represents the tooltip displayed for the tray icon. */ }; /** * @brief * Helper structure for compatibility with older versions of * Visual C++. See NOTIFYICONDATA. */ struct NOTIFYICONDATAEX { DWORD cbSize; /**< Size of this structure, in bytes. */ HWND hWnd; /**< Handle to the window that will receive notification messages associated with an icon in the taskbar status area. The shell uses hWnd and uID to identify which icon is to be operated on when Shell_NotifyIcon is invoked. */ UINT uID; /**< Application-defined identifier of the taskbar icon. The shell uses hWnd and uID to identify which icon is to be operated on when Shell_NotifyIcon is invoked. You can have multiple icons associated with a single hWnd by assigning each a different uID. */ UINT uFlags; /**< Array of flags that indicate which of the other members contain valid data. */ UINT uCallbackMessage; /**< Application-defined message identifier. */ HICON hIcon; /**< Handle to the icon to be added, modified, or deleted. */ TCHAR szTip[128]; /**< Pointer to a NULL-terminated string with the text for a standard tooltip. */ DWORD dwState; /**< State of the icon. */ DWORD dwStateMask; /**< A value that specifies which bits of the state member will be retrieved or modified. */ TCHAR szInfo[256]; /**< Pointer to a NULL-terminated string with the text for a balloon-style tooltip. */ union { UINT uTimeout; /**< The timeout value, in milliseconds, for a balloon-style tooltip. */ UINT uVersion; /**< Used to specify whether the shell notify icon interface should use Windows 95 or Windows 2000 behavior. */ } DUMMYUNIONNAME; TCHAR szInfoTitle[64]; /**< Pointer to a NULL-terminated string containing a title for a balloon tooltip. */ DWORD dwInfoFlags; /**< Flags that can be set to add an icon to a balloon tooltip. */ GUID guidItem; /**< GUID identifier */ HICON hBalloonIcon; /**< Supported in Windows XP as well, but displayed as a small icon. Windows Vista and later display a bigger icon in a balloon. */ }; /** * @brief * Animated icon array. */ typedef CList CTrayIconList; public: /** * @brief * Constructs a CXTPTrayIcon object. */ CXTPTrayIcon(); /** * @brief * Destroys a CXTPTrayIcon object, handles cleanup and deallocation. */ virtual ~CXTPTrayIcon(); public: /** * @brief * Determines if shell32.dll has Major version 5 or above. * @details * shell32.dll Major version 5 and above provide extended functionality. * @return * TRUE if shell32.dll has Major version 5 or above. */ BOOL IsShellVersion5() const; public: /** * @brief * This member function will create the system tray icon. * @param lpszCaption A NULL-terminated string that contains the tooltip text * displayed when the cursor is over the tray icon. * @param pParentWnd Pointer to the window that will receive notification messages * associated with an icon in the taskbar status area. * @param nIconID Resource ID for the default tray icon. * @param uMenuID Pop-up menu resource identifier. * @param uDefMenuItemID Command ID that represents the default item for the menu. * @param bDefMenuItemByPos true if the default is defined by its position, * false if it is defined by its command ID. * @return * true if successful, otherwise false. */ virtual bool Create(LPCTSTR lpszCaption, CWnd* pParentWnd, UINT nIconID, UINT uMenuID = 0, UINT uDefMenuItemID = 0, bool bDefMenuItemByPos = false); /** @cond */ virtual bool Create(LPCTSTR lpszCaption, DWORD dwStyle, CWnd* pParentWnd, UINT nIconID); // DEPRECATED /** @endcond */ /** * @brief * Call this member function to display a balloon tooltip for the system * tray icon. Must have Windows 2000 or later. * @param lpszInfo Pointer to a NULL-terminated string with the text for a balloon * ToolTip. It can have a maximum of 255 characters. * @param lpszInfoTitle Pointer to a NULL-terminated string containing a title for a * balloon ToolTip. This title appears in boldface above the text. * It can have a maximum of 63 characters. * @param dwInfoFlags Flags that can be set to add an icon to a balloon ToolTip. * It is placed to the left of the title. If the 'lpszInfoTitle' * member is zero-length, then the icon is not shown and can * be any of the values listed in the Remarks section. * @param uTimeout The timeout value in seconds for a balloon ToolTip. The system * enforces minimum and maximum timeout values. 'uTimeout' values * that are too large default to the maximum value, and values that * are too small default to the minimum value. The system minimum * and maximum timeout values are currently set at 10 seconds and * 30 seconds, respectively. * @param hBaloonIcon Handle to the baloon icon to display. * @details * The icon shown can be any of the following values:

* * NIIF_ERROR: An error icon. * NIIF_INFO: An information icon. * NIIF_NONE: No icon. * NIIF_WARNING: A warning icon. * @return * true if successful, otherwise false. */ bool ShowBalloonTip(LPCTSTR lpszInfo = NULL, LPCTSTR lpszInfoTitle = NULL, DWORD dwInfoFlags = NIIF_NONE, UINT uTimeout = 10, HICON hBaloonIcon = NULL); /** * @brief * This member function will stop the tray icon animation timer. */ virtual void StopAnimation(); /** * @brief * This member function will start the tray icon animation timer. * @param uElapse Specifies the time-out value in milliseconds between frames. */ virtual void StartAnimation(UINT uElapse = 500); /** * @brief * This member function will set the icons used for animated system * tray icons. To use, call SetAnimationIcons and then SetTimer. * @param lpIDArray [in] An array of resource IDs that represent the icons to * display in the caption area. * @param nIDCount [in] Zero-based size of the array passed. lpIDArray * and lpStrTipArray must contain the same number of * items and must match value specified by nIDCount. * @param lpStrTipArray [in] An array of tooltips that match the icons passed in as * 'lpStrTipArray'. If NULL, the default tooltip will be used. */ virtual void SetAnimationIcons(const UINT* lpIDArray, const CString* lpStrTipArray, int nIDCount); /** * @brief * This member function will set the icons used for animated system * tray icons. To use, call SetAnimationIcons and then SetTimer. * @param lpIDArray [in] An array of resource IDs that represent the icons to * display in the caption area. * @param nIDCount [in] Zero-based size of the array passed. lpIDArray * and lpStrTipArray must contain the same number of * items and must match value specified by nIDCount. * @param lpStrTipArray [in] An array of tooltips that match the icons passed in as * 'lpStrTipArray'. If NULL, the default tooltip will be used. * @return * true if successful, otherwise false. */ virtual bool SetAnimationIcons(const UINT* lpIDArray, int nIDCount, const CString* lpStrTipArray = NULL); /** * @brief * Call this member function to set the tooltip text for the tray icon. * @param nTipText Windows string resource ID that represents the tooltip text * to display for the icon. * @return * true if successful, otherwise false. */ bool SetTooltipText(UINT nTipText); /** * @brief * Call this member function to set the tooltip text for the tray icon. * @param lpszTipText A NULL-terminated string that represents the tooltip * text to display for the icon. * @return * true if successful, otherwise false. */ bool SetTooltipText(LPCTSTR lpszTipText); /** * @brief * Call this member function to retrieve the tooltip text that is displayed * by the tray icon. * @return * A CString object that represents the tooltip text. */ CString GetTooltipText() const; /** * @brief * This member function is called to reset the tray icon control settings * to their default value. */ void SetDefaultValues(); /** * @brief * This member function will set the callback message to be used by the * tray icon. * @param uNewCallbackMessage Notification message ID. * @return * true if successful, otherwise false. */ bool SetCallbackMessage(UINT uNewCallbackMessage); /** * @brief * This member function will retrieve the notification message ID used * by the tray icon. * @return * An ID to a notification message. */ UINT GetCallbackMessage(); /** * @brief * This member function will set the default menu item for the tray icon's * pop-up menu if the tray icon handles notification messages. * @param uItem Command identifier or position of the default menu item. * @param bByPos true if 'uItem' is the menu item's index, * false if it is the menu item's command ID. * @return * true if successful, otherwise false. */ bool SetDefaultMenuItem(UINT uItem, bool bByPos); /** * @brief * Call this member function to retrieve the item ID and position flag * for the tray icon. * @param uItem Reference to a UINT that is to receive the default * menu item ID. * @param bByPos Reference to a bool that is to receive the default * menu item position flag. */ void GetDefaultMenuItem(UINT& uItem, bool& bByPos); /** * @brief * Call this member function to set the window that is to receive * notification messages from the tray icon. * @param pWndNotify Pointer to a valid CWnd object. * @return * true if successful, otherwise false. */ bool SetNotificationWnd(CWnd* pWndNotify); /** * @brief * Call this member function to retrieve a pointer to the window that * receives notification messages from the tray icon. * @return * A pointer to a valid CWnd object. */ CWnd* GetNotificationWnd(); /** * @brief * Call this member function to set the icon that is displayed in the * system tray. * @param hIcon Handle to the icon to display. * @return * true if the icon was set, otherwise false. */ bool SetIcon(HICON hIcon); /** * @brief * Call this member function to set the icon that is displayed in the * system tray. * @param lpszIconName Resource name of the icon to display. * @return * true if the icon was set, otherwise false. */ bool SetIcon(LPCTSTR lpszIconName); /** * @brief * Call this member function to set the icon that is displayed in the * system tray. * @param nIDResource Resource identifier of the icon to display. * @return * true if the icon was set, otherwise false. */ bool SetIcon(UINT nIDResource); /** * @brief * Call this member function to retrieve a handle to the icon displayed * in the system tray. * @return * A handle to the icon displayed in the system tray. */ HICON GetIcon() const; /** * @brief * Call this member function to add the icon to the system tray. * @return * true if successful, otherwise false. */ bool AddIcon(); /** * @brief * Call this member function to remove the icon from the system tray. * @return * true if successful, otherwise false. */ bool RemoveIcon(); /** * @brief * Call this member function to hide the system tray icon in Windows * 2000 or greater. * @return * true if successful, otherwise false. */ bool HideIcon(); /** * @brief * Call this member function to show the system tray icon in Windows * 2000 or greater. * @return * true if successful, otherwise false. */ bool ShowIcon(); /** * @brief * Call this member function to show the system tray icon in Windows * 2000 or greater. * @param bShow TRUE to show the tray icon, FALSE otherwise. * @return * TRUE if successful, otherwise FALSE. */ BOOL ShowIcon(BOOL bShow); /** * @brief * Call this member function to minimize the specified window to the * system tray. If window animation is supported, then the window * will glide down to the system tray. * @param pWnd Window to minimize. */ void MinimizeToTray(CWnd* pWnd); /** * @brief * Call this member function to maximize the specified window from the * system tray. If window animation is supported, then the window * will glide up from the system tray. * @param pWnd Window to maximize. */ void MaximizeFromTray(CWnd* pWnd); /** * @brief * Sends a message to the taskbar's status area. * @param dwMessage [in] Variable of type DWORD that specifies the action to * be taken. See remarks section for a list of values. * @details * dwMessage can have one of the following values:

* NIM_ADD: Adds an icon to the status area. The hWnd and * uID members of the NOTIFYICONDATA structure * pointed to by lpdata will be used to identify * the icon in later calls to Shell_NotifyIcon. * NIM_DELETE: Deletes an icon from the status area. Use the * hWnd and uID members of the NOTIFYICONDATA * structure pointed to by lpdata to identify * the icon to be deleted. * NIM_MODIFY: Modifies an icon in the status area. Use the * hWnd and uID members of the NOTIFYICONDATA * structure pointed to by lpdata to identify * the icon to be modified. * NIM_SETFOCUS: Version 5.0. Returns focus to the taskbar notification * area. Taskbar icons should use this message * when they have completed their user interface * operation. For example, if the taskbar icon * displays a shortcut menu, but the user presses * ESCAPE to cancel it, use NIM_SETFOCUS to return * focus to the taskbar notification area. * NIM_SETVERSION: Version 5.0. Instructs the taskbar to behave * according to the version number specified in * the uVersion member of the structure pointed * to by lpdata. This message allows you to specify * whether you want the version 5.0 behavior found * on Microsoft(r) Windows(r) 2000 systems, or that * found with earlier Shell versions. The default * value for uVersion is zero, indicating that * the original Windows 95 notify icon behavior * should be used. For details, see the Remarks * section. * The taskbar notification area is sometimes erroneously called the "tray." * * Version 5.0 of the Shell, found on Windows 2000, handles Shell_NotifyIcon * mouse and keyboard events differently than earlier Shell versions found * on Windows NT(r) 4.0, Windows 95, and Windows 98. The differences are: * * If a user selects a notify icon's shortcut menu with the keyboard, the * version 5.0 Shell sends the associated application a WM_CONTEXTMENU message. * Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.

* * If a user selects a notify icon with the keyboard and activates it with * the space bar or ENTER key, the version 5.0 Shell sends the associated * application an NIN_KEYSELECT notification. Earlier versions send WM_RBUTTONDOWN * and WM_RBUTTONUP messages.

* * If a user selects a notify icon with the mouse and activates it with * the ENTER key, the version 5.0 Shell sends the associated application * an NIN_SELECT notification. Earlier versions send WM_RBUTTONDOWN and * WM_RBUTTONUP messages.

* * If a user passes the mouse pointer over an icon with which a balloon * ToolTip is associated, the version 5.0 Shell sends the following messages:

* * NIN_BALLOONSHOW: Sent when the balloon is shown (balloons * are queued). * NIN_BALLOONHIDE: Sent when the balloon disappears when * the icon is deleted. For example, this * message is not sent if the balloon is * dismissed because of a timeout or mouse * click by the user. * NIN_BALLOONTIMEOUT: Sent when the balloon is dismissed because * of a timeout. * NIN_BALLOONUSERCLICK: Sent when the balloon is dismissed because * the user clicked the mouse. * * You can select which way the Shell should behave by calling Shell_NotifyIcon * with dwMessage set to NIM_SETVERSION. Set the uVersion member of the * NOTIFYICONDATA structure to indicate whether you want pre-version 5.0 * behavior or version 5.0 and later behavior. * @return * TRUE if successful, otherwise FALSE. If dwMessage is set to NIM_SETVERSION, * then this function returns TRUE if the version was successfully changed, * or FALSE if the requested version is not supported. */ BOOL ShellNotify(DWORD dwMessage); /** * @brief * Adds an icon to the system tray. * @details * This member is called by the CXTPTrayIcon object to initialize the * icon display in the system tray. It checks to see if there is a * pending request or if the icon is hidden first before attempting to * add the icon. You can override this member to provide additional * functionality. */ virtual void InstallIconPending(); /** * @brief * Creates the tray icon's min/max window. * @details * Called to create the minimize window used during minimize/maximize * operations. * @param pWndApp Pointer to the calling application's main window. * @return * true if the minimize window was successfully created, otherwise false. */ virtual bool CreateMinimizeWnd(CWnd* pWndApp); /** * @brief * Clears the animated icon array. * @details * Called to clear the animated icon array and free any associated * GDI resources. */ virtual void RemoveAnimationIcons(); /** * @brief * Sets the tooltip for the CXTPTrayIcon object. * @param strToolTip A NULL-terminated string that contains the tooltip text * displayed when the cursor is over the tray icon. * @details * This member function is called to set the tooltip text for the * icon that is displayed in the system tray. */ virtual void SetTooltip(LPCTSTR strToolTip); /** * @brief * Sets the icon for the CXTPTrayIcon object. * @param nIcon Resource ID of the new icon to set. * @param dwMessage Message to be sent. See ShellNotify for more details. * @details * This member function is called to set a new icon to be displayed * for the CXTPTrayIcon object. */ virtual void SetTrayIcon(UINT nIcon, DWORD dwMessage = NIM_ADD); /** * @brief * Stops the animation timer. * @details * Called by the CXTPTrayIcon object to stop the animation timer event * and sets the default icon and tooltip text. You can override this * member to provide additional functionality. */ virtual void KillTimer(); /** * @brief * Sets the animation timer. * @param nIDEvent Specifies a nonzero timer identifier. * @param uElapse Specifies the time-out value, in milliseconds. * @details * Called by the CXTPTrayIcon object to initialize and start the * animation timer. You can override this member to provide additional * functionality. */ virtual void SetTimer(UINT nIDEvent, UINT uElapse); protected: /** @cond */ DECLARE_MESSAGE_MAP() //{{AFX_VIRTUAL(CXTPTrayIcon) virtual LRESULT WindowProc(UINT message, WPARAM wParam, LPARAM lParam); virtual LRESULT OnTrayNotification(WPARAM wParam, LPARAM lParam); //}}AFX_VIRTUAL //{{AFX_MSG(CXTPTrayIcon) afx_msg void OnTimer(UINT_PTR nIDEvent); afx_msg void OnSettingChange(UINT uFlags, LPCTSTR lpszSection); afx_msg LRESULT OnTaskbarCreated(WPARAM wParam, LPARAM lParam); //}}AFX_MSG /** @endcond */ private: BOOL Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID, CCreateContext* pContext = NULL); bool CanAnimate() const; static BOOL CALLBACK FindTrayWnd(HWND hWnd, LPARAM lParam); bool GetTrayWindowRect(CRect& rect); bool SetShellTooltip(LPCTSTR lpszTipText); protected: UINT m_uFlags; /**< Style settings for icon restore. */ UINT m_nIconID; /**< Resource ID for the default icon. */ UINT m_nIDEvent; /**< Timer event ID. */ UINT m_nCounter; /**< Holds the current position in the timer loop. */ UINT m_uDefMenuItemID; /**< Default pop-up menu item ID. */ bool m_bDefMenuItemByPos; /**< Determines if the default menu item is a command or index. */ bool m_bHidden; /**< State of the icon. true to indicate that the icon is hidden. */ bool m_bRemoved; /**< true if the icon has been removed from the system tray. */ bool m_bShowPending; /**< true if the icon display is pending. */ HWND m_hWndNotify; /**< Handle to the window that receives command notifications. */ CWnd m_wndMinimize; /**< Hidden window used during minimize and restore functions. */ size_t m_iMaxTipSize; /**< Maximum size for a tooltip string. */ CString m_strToolTip; /**< Tooltip for the default icon. */ CXTPIconHandle m_hIcon; /**< Default icon. */ CTrayIconList m_arTrayIcons; /**< Array of icons and text that are displayed during animation. */ NOTIFYICONDATAEX m_niData; /**< Tray icon structure. See NOTIFYICONDATA. */ }; const TCHAR XTPTRAYICON_CLASSNAME[] = _T("XTPTrayIcon"); ////////////////////////////////////////////////////////////////////// /** @cond */ AFX_INLINE bool CXTPTrayIcon::Create(LPCTSTR lpszCaption, DWORD /*dwStyle*/, CWnd* pParentWnd, UINT nIconID) { return Create(lpszCaption, pParentWnd, nIconID); } AFX_INLINE void CXTPTrayIcon::SetTooltip(LPCTSTR strToolTip) { SetTooltipText(strToolTip); } AFX_INLINE void CXTPTrayIcon::SetTrayIcon(UINT nIcon, DWORD /*dwMessage*/) { SetIcon(nIcon); } AFX_INLINE void CXTPTrayIcon::SetAnimationIcons(const UINT* lpIDArray, const CString* lpStrTipArray, int nIDCount) { SetAnimationIcons(lpIDArray, nIDCount, lpStrTipArray); } AFX_INLINE void CXTPTrayIcon::KillTimer() { StopAnimation(); } AFX_INLINE void CXTPTrayIcon::SetTimer(UINT nIDEvent, UINT uElapse) { m_nIDEvent = nIDEvent; StartAnimation(uElapse); } AFX_INLINE BOOL CXTPTrayIcon::Create(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID, CCreateContext* pContext) { return CWnd::Create(lpszClassName, lpszWindowName, dwStyle, rect, pParentWnd, nID, pContext); } /** @endcond */ # include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h" /** @cond */ #endif // #if !defined(__XTPTRAYICON_H__) /** @endcond */