Introduction
This is my implementation of a (hyper)link control. I have been sitting
on it for a while, and finally decided to release it. While there are may
other implementations of link controls out there, none of the ones that I have
found really act like the ones used in Internet Explorer�. For
example, many of them are based on the Static
control, and as such are unable to
be focused using the keyboard, which means that they are useless without a mouse
(accessibility issue), and have incorrect click behavior.
My implementation of the link control offers some features not commonly found in
other implementations:
- It is based on (subclasses) the Button control, so it can be focused and
navigated just like any other control
- It can be activated by the keyboard (using the
<ENTER>
key)
- It correctly activates on the Button-Up, not the Button-Down
- It contains a built-in ToolTip
- It draws and behaves correctly when disabled
- Its colors and fonts are completely customizable
- It supports the ability to launch both URLs and the contents of a
SHELLEXECUTEINFO
structure (see below)
- It can be dragged and dropped just like a link in Internet Explorer (try
dragging it from the demo application to an instance of IE or the Desktop)
- It uses
WM_NOTIFY
-based notification messages (the Win32 way) to notify the
parent of mouse activity, and gives the parent the ability to deny an
activation request, or cancel a Drag-n-Drop operation, etc.
Background
To fully understand the benefits this implementation of the hyperlink control
has to offer, experiment with the links on this page using your browser.
Can you navigate them using the mouse and keyboard? How do you activate
the control with the mouse; on the Button-Down or the Button-Up? What
happens when you Button-Down over the control, but move the mouse off of it and
then Button-Up? What happens when you Button-Down somewhere else, but then
Button-Up over the control? Etc.
Using The Control
The code for the CJRTSLinkCtrl
class is wrapped up in the
JRTSLinkCtrl.cpp
and JRTSLinkCtrl.h
files. The
CJRTSLinkCtrl
class is used to subclass an existing Button control, just
as you would normally use the CButton
class. For best ease of
use, rebuild your ClassWizard database and include the code for this
class when you do. That way, you will be able to bind a
CJRTSLinkCtrl
class from within ClassWizard.
Now, let us explore
the class by going through its header file from top to bottom. We will
start with the WM_NOTIFY
-based Notification Messages and
the
NMHDR
-Based Notification Structure.
const UINT NMLC_DBLCLICK = NM_DBLCLK;
const UINT NMLC_SETFOCUS = NM_SETFOCUS;
const UINT NMLC_KILLFOCUS = NM_KILLFOCUS;
const UINT NMLC_RCLICK = NM_RCLICK;
const UINT NMLC_RDBLCLICK = NM_RDBLCLICK;
const UINT NMLC_ACTIVATE = ( NM_FIRST - 90 );
const UINT NMLC_MOUSEENTER = ( NM_FIRST - 89 );
const UINT NMLC_MOUSEHOVER = ( NM_FIRST - 88 );
const UINT NMLC_MOUSELEAVE = ( NM_FIRST - 87 );
const UINT NMLC_BEGINDRAG = ( NM_FIRST - 86 );
const UINT NMLC_ENDDRAG = ( NM_FIRST - 85 );
const UINT NMLC_BEGINRDRAG = ( NM_FIRST - 84 );
const UINT NMLC_ENDRDRAG = ( NM_FIRST - 83 );
const UINT NMLC_MCLICK = ( NM_FIRST - 82 );
const UINT NMLC_MDBLCLICK = ( NM_FIRST - 81 );
struct NMLINKCTRL
{
NMHDR m_hdr;
DWORD m_dwRetVal;
DWORD m_dwFlags;
POINT m_ptWhere;
};
All of these notification messages are handled using CWnd::OnNotify(...)
or by using the ON_NOTIFY(...)
message map macros. The
NMLINKCTRL
structure is the NMHDR
-based structure that is
passed in the NMHDR
pointer argument to the handler
functions.
Notification
Message |
Description |
NMLC_DBLCLICK
|
This notification message is used to notify the parent that a
Double-Click has occurred in the Link Control.
|
NMLC_SETFOCUS
|
This notification message
is used to notify the parent that the Link Control has gained the input focus.
|
NMLC_KILLFOCUS
|
This notification message is used to notify the
parent that the Link Control has lost the input focus.
|
NMLC_RCLICK
|
This notification message
is used to notify the parent that a Right-Click has occurred in the Link
Control.
|
NMLC_RDBLCLICK
|
This notification message is used to notify the
parent that a Double-Right-Click has occurred in the Link Control
|
NMLC_ACTIVATE
|
This notification message is used to
notify the parent that the Link Control is about to be activated. This
also gives the Parent control a last chance to set/change the Target of the
link, or to deny activation: upon return of the notification call, if
m_dwRetVal is set to FALSE , the link will not be
activated.
|
NMLC_MOUSEENTER
|
This notification message is used to
notify the parent that the mouse has entered the Link Control's client area.
|
NMLC_MOUSEHOVER
|
This notification message is used to notify the
parent that the mouse has hovered over the Link Control's client area.
(Note that this does not use the standard NM_HOVER message.
This is because the standard NM_HOVER notification supports
preventing a "hover-action" from taking place, and the Link Control does not
support that functionality.)
|
NMLC_MOUSELEAVE
|
This notification message is used to notify the parent that the mouse has
left the Link Control's client area
|
NMLC_SETFOCUS
|
This notification message
is used to notify the parent that the Link Control has gained the input focus.
|
NMLC_KILLFOCUS
|
This notification message is used to notify the
parent that the Link Control has lost the input focus.
|
NMLC_BEGINDRAG
|
This notification message is used to notify the
parent that a Drag-n-Drop operation is about to begin. This also gives
the Parent control a last chance to prevent the initiation of the Drag-n-Drop
operation: upon return of the notification call,
if m_dwRetVal is set to FALSE , the Drag-n-Drop
operation will not be initiated.
|
NMLC_ENDDRAG
|
This notification
message is used to notify the parent that a Drag-n-Drop Operation has
completed. The m_dwRetVal member of the
NMLINKCTRL structure contains the result of the Drag-n-Drop operation,
which will be one of the DROPEFFECT_* values.
|
NMLC_BEGINRDRAG
|
This notification message is used to notify the
parent that a Right-Button Drag-n-Drop operation is about to begin. This also gives
the Parent control a last chance to prevent the initiation of the Drag-n-Drop
operation: upon return of the notification call,
if m_dwRetVal is set to FALSE , the Drag-n-Drop
operation will not be initiated.
|
NMLC_ENDRDRAG
|
This notification
message is used to notify the parent that a Right-Button Drag-n-Drop Operation has
completed. The m_dwRetVal member of the
NMLINKCTRL structure contains the result of the Drag-n-Drop operation,
which will be one of the DROPEFFECT_* values.
|
NMLC_MCLICK
|
This notification message
is used to notify the parent that a Middle-Click has occurred in the Link
Control.
|
NMLC_MDBLCLICK
|
This notification message is used to notify the
parent that a Double-Middle-Click has occurred in the Link Control
|
All of the Notification Messages support the following Flags.
The Flags are used to indicate which usual keyboard modifiers are down at
the time that the message was sent. The Right and Left-specific
flags are only supported on platforms that can distinguish between them.
The last three Flags are Left/Right neutral, so when it doubt, use them:
const DWORD LCF_RCTRL = 0x00000001;
const DWORD LCF_LCTRL = 0x00000002;
const DWORD LCF_RSHIFT = 0x00000004;
const DWORD LCF_LSHIFT = 0x00000008;
const DWORD LCF_RALT = 0x00000010;
const DWORD LCF_LALT = 0x00000020;
const DWORD LCF_CTRL = 0x00000040;
const DWORD LCF_SHIFT = 0x00000080;
const DWORD LCF_ALT = 0x00000100;
Next, let us look
at the styles supported by the control:
const DWORD LCS_HOTTRACK = 0x00000001;
const DWORD LCS_DRAGDROP = 0x00000002;
const DWORD LCS_VISITED = 0x00000004;
const DWORD LCS_TOOLTIPS = 0x00000010;
Style |
Description |
LCS_HOTTRACK
|
This style enables Hot-Tracking for the control.
|
LCS_DRAGDROP
|
This style enables the Drag-n-Drop feature of the
control. Drag-n-Drop operations can only be initiated from the Link
Area of the control, not just the Client Area. That is the tradeoff
that I decided on between the behavior of a (checkbox-style) button
and an actual Link control.
|
LCS_VISITED
|
This
style sets the "Visited" flag for the Link. "Visited" links are shown in
a different color. Normally, links become "Visited" the first time they
are Activated.
|
LCS_TOOLTIPS
|
This style enables the control's
built-in ToolTip.
|
All of the style bits can be turned on or off at any time and will have a
more-or-less immediate effect.
There are also other style bits in the header
file that are prefixed with LCS_I_
. These are internally
used style bits, and cannot be set/reset externally.
Now we come to the fun
stuff... The public class members:
public:
void SetTarget( LPCTSTR cpTarget );
void SetTarget( const SHELLEXECUTEINFO &seiSEI );
void SetDisplay( LPCTSTR cpDisplay );
void SetToolTip( LPCTSTR cpToolTip );
void SetNormalFont( const LOGFONT &lfNormalFont );
void SetULFont( const LOGFONT &lfULFont );
DWORD GetLastActivateError( void );
public:
void Activate( void );
DWORD ModifyLCStyle( DWORD dwRemove, DWORD dwAdd );
void SetTarget( LPCTSTR cpTarget )
void SetTarget( const SHELLEXECUTEINFO &seiSEI )
These functions set the Target of the link or the "action to be taken place
when the link is Activated". The first version of the function takes a
string in a URL format. No validation is done on the string (this allows
you to have your own internal format/actions). The
second version of the function takes a SHELLEXECUTEINFO
object. When the
second version is used, the contents of the passed SHELLEXECUTEINFO
object are
passed the to ShellExecuteEx(...)
function. This allows you to have the
link do just about anything you want when it is Activated.
void SetDisplay( LPCTSTR cpDisplay )
This function sets the Display string of the link. This is the string that
is shown to the user.
void SetToolTip( LPCTSTR cpDisplay )
This function sets the ToolTip for the link.
void SetNormalFont( const LOGFONT &lfNormalFont )
This function sets the "normal" font for the control. The font can be
changed at any time.
void SetULFont( const LOGFONT &lfULFont )
This function sets the "underline" font for the control. The font can
be changed at any time.
DWORD
GetLastActivateError(
void )
This function returns the error code (if any) from the last time the
control was Activated.
void Activate( void )
This function gives the developer a way to externally Activate the link.
DWORD ModifyLCStyle( DWORD dwRemove, DWORD dwAdd
)
This function allows the developer to modify the style bits of the control.
It is obviously modeled after a CWnd
function of a similar name.
History
Version 1.0 Initial public release to
The Code Project. (~12/30/02)
Version 1.1 Double-click bug fix and
additional features. (~1/13/03)