WinMFCControlHyperlink.cpp

// MFC static control that behaves like a hyperlink.
// It handles cursor changes and click actions for links shown in the dialogs.

#include "stdafx.h"

#include "WinMFCControlHyperlink.h"


// #defines
// --------

#ifdef _DEBUG
#define new DEBUG_NEW
#endif


// Message Map
// -----------

BEGIN_MESSAGE_MAP(CHyperlink, CStatic)
	ON_CONTROL_REFLECT(STN_CLICKED, OnClicked)
	ON_WM_CTLCOLOR_REFLECT()
	ON_WM_ERASEBKGND()
	ON_WM_MOUSEMOVE()
	ON_WM_MOUSELEAVE()
	ON_WM_SETCURSOR()
END_MESSAGE_MAP()


// Creates a static control that behaves like a hyperlink.  The HWND does not
// exist yet, so this constructor only sets state and default colours; tooltip,
// cursor, and font setup happen in PreSubclassWindow().
CHyperlink::CHyperlink()
{
	// Use a quiet blue for normal links, a brighter blue for hover, and leave the
	// visited colour matching normal links unless the caller changes it.
	LinkColor = RGB(2, 83, 146);
	HoverColor = RGB(0, 0, 255);
	VisitedColor = LinkColor;

	// The control paints transparent text, so it also owns the background colour
	// used by OnEraseBkgnd().
	BackgroundColor = RGB(231, 231, 231);

	// Start as a direct URL-opening hyperlink with no tooltip or hover state.
	FireChild = false;
	ToolTipEnabled = false;
	MouseInside = false;
	TrackingMouseLeave = false;
	Visited = false;
	m_bDisableHoverColor = false;

	// The cursor is loaded once the application object is available during
	// subclassing.
	HandCursor = NULL;
}


// Destroys the hyperlink control.  MFC member objects such as CFont and
// CToolTipCtrl release their own handles, so no explicit cleanup is needed here.
CHyperlink::~CHyperlink()
{
}


// Enables click notifications, captures the initial text, and creates the
// tooltip/cursor resources.  This is the first point where the control has a
// real HWND, so font and tooltip setup belongs here rather than in the
// constructor.
void CHyperlink::PreSubclassWindow()
{
	// Static controls only send STN_CLICKED when SS_NOTIFY is present.
	ModifyStyle(0, SS_NOTIFY);

	// Capture the dialog-resource text as the initial link text, then create an
	// underlined version of the current control font.
	GetWindowText(LinkText);
	CreateLinkFont();

	// Use the standard Windows hand cursor so the control feels like a normal
	// hyperlink.
	HandCursor = AfxGetApp()->LoadStandardCursor(IDC_HAND);

	// The tooltip covers the whole static control and starts inactive.  Callers
	// opt in later through ActiveToolTip().
	if (ToolTip.Create(this, TTS_ALWAYSTIP))
	{
		CRect ClientRect;

		GetClientRect(&ClientRect);
		ToolTip.AddTool(this, _T(""), ClientRect, 1);
		ToolTip.Activate(FALSE);
	}

	// Let the base CStatic finish its subclass initialization.
	CStatic::PreSubclassWindow();
}


// Relays mouse messages to the tooltip before normal static-control processing.
// Tooltips need these relayed messages because this control is not using a
// dialog-level tooltip manager.
BOOL CHyperlink::PreTranslateMessage(MSG *Message)
{
	// Relay only after the tooltip HWND exists; before subclassing there is
	// nothing to update.
	if (ToolTip.GetSafeHwnd()) ToolTip.RelayEvent(Message);

	// Preserve the normal static-control message preprocessing.
	return CStatic::PreTranslateMessage(Message);
}


// Opens the link URL or notifies the parent, then marks the link as visited.
// Parent notification is used for application actions that look like links but
// are not URLs.
void CHyperlink::OnClicked()
{
	// FireChild mode reports the click to the parent dialog with the control ID
	// in WPARAM, letting the dialog decide what action to take.
	if (FireChild)
	{
		CWnd *Parent = GetParent();

		if (Parent && Parent->GetSafeHwnd()) Parent->SendMessage(_HYPERLINK_EVENT, (WPARAM)(GetDlgCtrlID()), 0);
	}
	else if (!LinkUrl.IsEmpty())
	{
		// Direct-link mode opens URLs and mailto links through the shell.
		GoToLinkUrl(LinkUrl);
	}

	// Once clicked, repaint so a custom visited colour can take effect.
	Visited = true;
	RedrawLink();
}


// Supplies transparent text painting with the current link colour.  This keeps
// standard static painting but changes the foreground colour based on hover and
// visited state.
HBRUSH CHyperlink::CtlColor(CDC *DC, UINT ControlColor)
{
	// The reflected handler does not need the MFC control-type value because this
	// class only handles static controls.
	UNREFERENCED_PARAMETER(ControlColor);

	// Paint text in the link state colour and leave the background transparent.
	DC->SetTextColor(CurrentTextColor());
	DC->SetBkMode(TRANSPARENT);

	// The background is supplied by OnEraseBkgnd(), so return a null brush here.
	return (HBRUSH)(::GetStockObject(NULL_BRUSH));
}


// Paints the control background so transparent text has a stable base.  Without
// this, transparent static text can leave artefacts when hover colour changes
// trigger repeated invalidation.
BOOL CHyperlink::OnEraseBkgnd(CDC *DC)
{
	CRect ClientRect;

	// Fill the whole client area with the configured background colour.
	GetClientRect(&ClientRect);
	DC->FillSolidRect(ClientRect, BackgroundColor);

	// Return TRUE because the background has been fully erased.
	return TRUE;
}


// Tracks hover entry so the link can repaint with the hover colour.  Mouse-leave
// tracking is requested only once per hover because Windows sends a single
// WM_MOUSELEAVE notification for each tracking request.
void CHyperlink::OnMouseMove(UINT Flags, CPoint Point)
{
	// The point is not needed; only entry/leave state matters.
	UNREFERENCED_PARAMETER(Point);

	// On first movement inside the control, start leave tracking and repaint if
	// hover colouring is enabled.
	if (!MouseInside)
	{
		MouseInside = true;
		BeginTrackingMouseLeave();
		if (!m_bDisableHoverColor) RedrawLink();
	}

	// Preserve the base static-control mouse behaviour.
	CStatic::OnMouseMove(Flags, Point);
}


// Clears the hover state when the mouse leaves the link and repaints back to the
// normal or visited colour.
void CHyperlink::OnMouseLeave()
{
	// The previous TrackMouseEvent request has now been consumed.
	MouseInside = false;
	TrackingMouseLeave = false;

	// Restore the non-hover colour when hover colouring is enabled.
	if (!m_bDisableHoverColor) RedrawLink();

	// Preserve the base static-control leave handling.
	CStatic::OnMouseLeave();
}


// Shows a hand cursor over the hyperlink.  If the hand cursor was not available
// for any reason, the base class chooses the cursor.
BOOL CHyperlink::OnSetCursor(CWnd *Window, UINT HitTest, UINT Message)
{
	// The custom cursor does not depend on the hit-test details.
	UNREFERENCED_PARAMETER(Window);
	UNREFERENCED_PARAMETER(HitTest);
	UNREFERENCED_PARAMETER(Message);

	// Use the cached hand cursor while it is available.
	if (HandCursor)
	{
		::SetCursor(HandCursor);
		return TRUE;
	}

	// Fall back to standard static-control cursor handling.
	return CStatic::OnSetCursor(Window, HitTest, Message);
}


// Chooses whether clicks are opened directly or forwarded to the parent dialog.
// Non-zero values enable parent notification mode.
void CHyperlink::SetFireChild(int Fire)
{
	// Store as a bool while keeping the original int-style public API.
	FireChild = (Fire != 0);
}


// Returns the text currently displayed by the hyperlink.  The value mirrors the
// last dialog-resource text captured at subclassing or SetLinkText() call.
CString CHyperlink::GetLinkText()
{
	// Return the cached value instead of querying the window each time.
	return LinkText;
}


// Returns the URL opened when the link is clicked in direct-link mode.
CString CHyperlink::GetLinkUrl()
{
	// The URL may be empty for parent-notification links.
	return LinkUrl;
}


// Opens a URL or mailto link using the Windows shell.  ShellExecute returns a
// value greater than 32 on success.
bool CHyperlink::GoToLinkUrl(CString Link)
{
	HINSTANCE Result;

	// Delegate protocol handling to Windows so http, https, mailto, and file
	// associations all use the user's configured handlers.
	Result = ShellExecute(NULL, _T("open"), Link, NULL, NULL, SW_SHOWNORMAL);

	// ShellExecute uses small integer values for errors, encoded as HINSTANCE.
	return reinterpret_cast<INT_PTR>(Result) > 32;
}


// Sets the colour used while the mouse is over the link.
void CHyperlink::SetHoverColor(COLORREF Color)
{
	// Store and repaint so the new colour is visible immediately if hovered.
	HoverColor = Color;
	RedrawLink();
}


// Sets the colour used after the link has been clicked.
void CHyperlink::SetVisitedColor(COLORREF Color)
{
	// Store and repaint so already-visited links update immediately.
	VisitedColor = Color;
	RedrawLink();
}


// Sets the URL opened by direct-click hyperlinks.
void CHyperlink::SetLinkUrl(CString Url)
{
	// Store the raw string; ShellExecute handles the actual protocol.
	LinkUrl = Url;
}


// Sets the tooltip background colour.  Calls made before the tooltip HWND exists
// are ignored, matching the old control behaviour.
void CHyperlink::SetToolTipBgColor(COLORREF Color)
{
	// CToolTipCtrl owns the colour once the tooltip is created.
	if (ToolTip.GetSafeHwnd()) ToolTip.SetTipBkColor(Color);
}


// Sets the tooltip text colour.  Calls made before the tooltip HWND exists are
// ignored because the tooltip is created during subclassing.
void CHyperlink::SetToolTipTextColor(COLORREF Color)
{
	// CToolTipCtrl owns the colour once the tooltip is created.
	if (ToolTip.GetSafeHwnd()) ToolTip.SetTipTextColor(Color);
}


// Sets the visible link text and repaints the control.  The cached text stays in
// sync with the real window text so GetLinkText() remains cheap.
void CHyperlink::SetLinkText(CString Text)
{
	// Store the new text and update the underlying static control.
	LinkText = Text;
	SetWindowText(Text);

	// Repaint so the new text appears with the current link colour.
	RedrawLink();
}


// Sets the tooltip text.  The misspelled function name is kept for compatibility
// with existing dialog code.
void CHyperlink::SetTootTipText(LPCTSTR Text)
{
	// Accept NULL as an empty tooltip string.
	ToolTipText = Text ? Text : _T("");

	// Update the live tooltip if subclassing has already created it.
	if (ToolTip.GetSafeHwnd()) ToolTip.UpdateTipText(ToolTipText, this, 1);
}


// Enables or disables the tooltip.  The desired state is stored even if the
// tooltip window does not exist yet.
void CHyperlink::ActiveToolTip(int Enable)
{
	// Store as a bool while preserving the int-style public API.
	ToolTipEnabled = (Enable != 0);

	// Apply the state to the live tooltip when available.
	if (ToolTip.GetSafeHwnd()) ToolTip.Activate(ToolTipEnabled ? TRUE : FALSE);
}


// Sets the normal, unvisited link colour.
void CHyperlink::SetLinkColor(COLORREF Color)
{
	// Store and repaint so unvisited links update immediately.
	LinkColor = Color;
	RedrawLink();
}


// Sets the background colour used behind the transparent link text.
void CHyperlink::SetBkgndColor(COLORREF Color)
{
	// Store and repaint so OnEraseBkgnd() uses the new colour.
	BackgroundColor = Color;
	RedrawLink();
}


// Rebuilds the underlined font used by the hyperlink.  PointSize <= 0 keeps the
// current font size; Bold < 0 keeps the current font weight.
void CHyperlink::SetHyperlinkFont(int PointSize, int Bold)
{
	// Build a new underlined font from the current control font.
	CreateLinkFont(PointSize, Bold);

	// Repaint so the new font metrics and style are visible.
	RedrawLink();
}


// Asks Windows to send WM_MOUSELEAVE for this control.  Tracking is one-shot, so
// the flag is reset in OnMouseLeave() after Windows sends the notification.
void CHyperlink::BeginTrackingMouseLeave()
{
	TRACKMOUSEEVENT Tracking;

	// Avoid duplicate tracking requests and skip work before the HWND exists.
	if (TrackingMouseLeave || !GetSafeHwnd()) return;

	// Request only a leave notification for this control.
	ZeroMemory(&Tracking, sizeof(Tracking));
	Tracking.cbSize = sizeof(Tracking);
	Tracking.dwFlags = TME_LEAVE;
	Tracking.hwndTrack = GetSafeHwnd();

	// Remember whether Windows accepted the tracking request.
	TrackingMouseLeave = (_TrackMouseEvent(&Tracking) != FALSE);
}


// Creates an underlined version of the current control font.  Optional arguments
// let callers override the point size and bold state while preserving all other
// font attributes from the existing dialog font.
void CHyperlink::CreateLinkFont(int PointSize, int Bold)
{
	CFont *CurrentFont;
	LOGFONT FontDescription;

	// Start from the current font so the link matches the surrounding dialog.
	CurrentFont = GetFont();
	if (!CurrentFont) return;

	// Copy the current font description before changing only the hyperlink parts.
	ZeroMemory(&FontDescription, sizeof(FontDescription));
	if (!CurrentFont->GetLogFont(&FontDescription)) return;

	// Hyperlinks are underlined by default.
	FontDescription.lfUnderline = TRUE;

	// Optionally override the font weight.
	if (Bold >= 0) FontDescription.lfWeight = Bold ? FW_BOLD : FW_NORMAL;

	// Optionally convert a point size to a logical font height for this display.
	if (PointSize > 0)
	{
		CClientDC DC(this);

		FontDescription.lfHeight = -MulDiv(PointSize, DC.GetDeviceCaps(LOGPIXELSY), 72);
	}

	// Replace any previous custom font before creating the new one.
	if (LinkFont.GetSafeHandle()) LinkFont.DeleteObject();

	// Apply the new font immediately when creation succeeds.
	if (LinkFont.CreateFontIndirect(&FontDescription)) SetFont(&LinkFont, TRUE);
}


// Repaints the hyperlink if its window has been created.  The erase flag is TRUE
// because the control uses transparent text over its own background fill.
void CHyperlink::RedrawLink()
{
	// Before subclassing there is no HWND to repaint.
	if (!GetSafeHwnd()) return;

	// Repaint both the background and text.
	Invalidate(TRUE);
}


// Chooses the colour to use for the current hover/visited state.  Hover feedback
// takes precedence over visited colour so the link still visibly responds under
// the mouse after it has been clicked.
COLORREF CHyperlink::CurrentTextColor() const
{
	// Hover feedback can be disabled for controls that do not repaint cleanly.
	if (MouseInside && !m_bDisableHoverColor) return HoverColor;

	// After a click, use the visited colour until the caller changes state.
	if (Visited) return VisitedColor;

	// The normal unvisited colour is the default.
	return LinkColor;
}