An improved hyperlink control

The CHyperlink example project dialog  Download Source Code and Demo


After having tried some hyperlink controls, I felt the necessity to write my own control that was more flexible and had a more consistent programming interface. My intention was to create an hyperlink that could be used not only with text but also with icons and bitmaps, and that supported dynamic modification of its style and font. Moreover, I wanted that my control had the look and feel of an usual web page hyperlink. Why cannot hyperlinks have the input focus? Why cannot I move the focus from an hyperlink to another using the "tab" key as if they were normal dialog buttons and activate them pressing the spacebar?

Well, here is an hyperlink control that makes all these beautiful things possible. It was realized with the help of some articles written by Paul DiLascia on MSJ and Stuart Patterson on Windows Developer's Journal. It's rightful to tell that I think at my control as an improvement of the homonymous control developed by Chris Maunder, whose work was excellent.

Comparison with existing hyperlinkcontrols

In this section, I summarize the main features that distinguish my control from other similar controls you can find in this site. I hope this will help you to decide which code suits your needs better.

  • You can set the hyperlink on any type of static control (bitmaps and icons above all!).
  • The hyperlink can get the input focus (a special color is used to show the focus state) and can be activated with the spacebar like normal dialog buttons.
  • The hyperlink maintains the correct aspect when you change its style, text or font.
  • Control resizing works correctly even if it has a nonclient border.
  • Simplified programming interface.

Using the control

To use the hyperlink control, first create a static control with your resource editor (text, icon, or bitmap), then give it a control ID (e.g. IDC_HYPERLINK). If you want your control to be able to get the focus, you have to set the "tabstop" style, since for static controls it is not the default. I advice to set it only with text controls, which can change color when focused. Then, attach it to a member variable of type CHyperLink (ClassWizard makes this very simple). Don't forget to include the "HyperLink.h" file in your dialog class implementation file. The member function SetURL() allows to specify the link URL. However, setting an explicit URL is not obligatory for text controls: if you specify a caption text, this is taken as URL. Vice versa, if you don't specify a caption text, but 'manually' set the URL with SetURL(), then the text is set equal to the URL. For all other types of static controls instead, you have the responsibility to set the URL using SetURL() (usually in the OnInitDialog() member function of your dialog class), or otherwise a debug assertion will occur. The default link colors are blue, dark cyan, purple and red, respectively for normal, focused, visited and "cursor over" states.

Customizing the hyperlink

The hyperlink styles are static class constants. They are shown in the following table

Style Meaning Default
StyleUnderline The link is underlined YES
StyleAutoSize The control resizes itself automatically when text or font changes YES
StyleUseHover The link use the "hand over" color NO
StyleDownClick The link is activated when mouse button "goes down" NO
StyleGetFocusOnClick The link gets the input focus when clicked NO
StyleNoHandCursor The link doesn't use the default hand cursor NO
StyleNoActiveColor The link doesn't change color when activated (i.e. when it get the focus) NO
  • To modify link style call the member function ModifyLinkStyle(dwRemove, dwAdd) where dwRemove is a bitwise OR of the styles you want to remove and dwAdd is a bitwise OR of the styles you want to add (strange but true!).

Setting the StyleAutoSize, the control will automatically resize itself to fit the size of the caption (even while it is visible!). The resizing occurs also if you set a new window caption text or font. Remember that this style applies to text controls only. For icons and bitmaps, auto-resizing is a default characteristic, and StyleAutoSize becomes meaningless. The resizing will honour the SS_CENTERIMAGE, SS_LEFT, SS_RIGHT and SS_CENTER static control flags. If you don't want the style change to be dinamically applied to the control, ModifyLinkStyle() has a third optional boolean parameter: just set it to FALSE (the default is TRUE).

  • To mark/unmark a link as visited call the SetVisited() member function.
  • To modify link colors, call the SetColors() member function, in the following way:
    SetColors(crLinkColor, crActiveColor, crVisitedColor, crHoverColor);

The last parameter is optional: if not specified the system default highlight color will be used. Alternatively, fill a HYPERLINKCOLORS structure (a typedef defined in "HyperLink.h") and pass it to the overloaded version of SetColors(). This structure is also used by GetColors() to retrieve the current link colors.
SetColors() is a static member function: the color change has effect on all instances of CHyperLink and you need to redraw your control in order that the new colors to be applied.

  • To set a mouse cursor different from the default hand, call SetLinkCursor(). This function requires a unique argument: the handle of a new cursor. It is a static function and has effect on all hyperlinks, just like SetColors().

All the "set" functions above have their natural "get" counterparts. See the following section.

Operations for CHyperLink:

Here is an excerpt from the class declaration

// Operations
	static void GetColors(HYPERLINKCOLORS& linkColors);

	static HCURSOR GetLinkCursor();
	static void SetLinkCursor(HCURSOR hCursor);
	static void SetColors(COLORREF crLinkColor, COLORREF crActiveColor, 
	   		   COLORREF crVisitedColor, COLORREF crHoverColor = -1);
	static void SetColors(HYPERLINKCOLORS& colors);

	void SetURL(CString strURL);
	CString GetURL() const;

	DWORD GetLinkStyle() const;
	BOOL ModifyLinkStyle(DWORD dwRemove, DWORD dwAdd, BOOL bApply=TRUE);	
	void SetWindowText(LPCTSTR lpszText);
	void SetFont(CFont *pFont);
	BOOL IsVisited() const;
	void SetVisited(BOOL bVisited = TRUE);
	// Use this if you want to subclass and also set different URL
	BOOL SubclassDlgItem(UINT nID, CWnd* pParent, LPCTSTR lpszURL=NULL) {
		m_strURL = lpszURL;
		return CStatic::SubclassDlgItem(nID, pParent);

Implementation details

Some notes about implementation. I used the MFC message reflection to set the text color for the control (see the ON_WM_CTLCOLOR_REFLECT() macro in the message map). Message reflection can be a very complicated argument. Briefly, many controls notifies some event messages to their parent window, so that the latter has a chance to handle them. When the parent window sends back the message to the control we have the so-called message reflection. This mechanism is well implemented in MFC. Reflected messages appear preceded by an equal sign in ClassWizard.

Reading the code, you may be surprised that the control works without the SS_NOTIFY style. Normally, a static control does not get mouse events unless it has the SS_NOTIFY style. However, as Paul DiLascia asserts, handling the WM_NCHITTEST message and making the OnNcHitTest() functions returns the hit-test value HTCLIENT achieves the same effect as SS_NOTIFY, but requires fewer lines of code and is more reliable than turning on SS_NOTIFY in OnCtlColor because Windows doesn't send WM_CTLCOLOR to bitmap static controls.

For dynamic text and font modification I supplied special versions of SetFont() and SetWindowText() functions. These functions perform their operations while the window is kept hidden to maintain the correct link aspect.

Author's note

I'm continuously working to improve this control. I'll be grateful to you if you mail me your comments, advices, or bug apparition reports!.

Latest additions

  • Link styles are now static class constants.
  • Colors and cursor and their relative get/set functions, are now static class members.
  • Many bug fixes in resizing and color management.

What's new in this release

This release was compiled and tested with Visual C++ 5.00. Uwe Kleim reported me a bug in the ModifyLinkStyle() member function and now it has been fixed. Thanks Uwe!

Last updated: 11 November 1998