TdxCustomLayoutItem.OnHyperlinkClick Event

Allows you to respond to a click on a hyperlink or prevent hyperlink activation.

Declaration

property OnHyperlinkClick: TdxHyperlinkClickEvent read; write;

Remarks

A click on a hyperlink defined as a part of a formatted layout item caption invokes the default application associated with the hyperlink’s URI scheme (a browser for HTTP/HTTPS, a mail client for MAILTO, etc.)

You can handle the OnHyperlinkClick event to execute custom code in response to a click on a hyperlink in the layout item’s caption or prevent hyperlink activation depending on certain conditions in your application.

Event Occurrence

The OnHyperlinkClick event occurs every time a user clicks a hyperlink in the layout item’s caption, before the OnCaptionClick event.

Event Parameters

The following parameters are accessible within an OnHyperlinkClick event handler:

Sender

Provides access to the layout item that raised the hyperlink click event.

AArgs

Provides access to information related to the hyperlink click event that occurred and allows you to prevent hyperlink activation. You can use AArgs.Button and AArgs.Shift properties to identify the clicked mouse button and the state of modifier keys at the moment of event occurrence.

Refer to TdxHyperlinkClickEvent and TdxHyperlinkClickEventArgs type descriptions for detailed information on all options available within an OnHyperlinkClick event handler.

Code Examples

Prevent MAILTO Hyperlink Activation in Layout Items

The code example in this section demonstrates OnHyperlinkClick and OnCreate event handlers. The OnHyperlinkClick event handler prevents users from activating a hyperlink that contains the MAILTO URI scheme. The OnCreate event handler associates the OnHyperlinkClick event handler with all layout items at startup.

This scenario can be useful if you define layout item captions at runtime.

Delphi

uses
  System.StrUtils;  // Declares the ContainsText global function
// ...

procedure TMyForm.dxLayoutControl1Item1HyperlinkClick(Sender: TObject;
  AArgs: TdxHyperlinkClickEventArgs);
begin
  if ContainsText(AArgs.URI, 'mailto') then  // If the clicked hyperlink contains the "mailto" URI scheme
    AArgs.Handled := True;  // Prevents hyperlink activation
end;

procedure TMyForm.FormCreate(Sender: TObject);  // Associates all layout items with the declared handler
var
  I: Integer;
begin
  for I := 0 to dxLayoutControl1.AbsoluteItemCount - 1 do  // Iterates through all layout items
    dxLayoutControl1.AbsoluteItems[I].OnHyperlinkClick := dxLayoutControl1Item1HyperlinkClick;
end;

C++

#include "System.StrUtils.hpp" // Declares the ContainsText global function
// ...

void __fastcall TMyForm::dxLayoutControl1Item1HyperlinkClick(TObject* Sender,
  TdxHyperlinkClickEventArgs *AArgs)
{
  if(ContainsText(AArgs->URI, "mailto"))  // If the clicked hyperlink contains the "mailto" URI scheme
    AArgs->Handled = true;  // Prevents hyperlink activation
}

void __fastcall TMyForm::FormCreate(TObject *Sender)  // Associates all layout items with the declared handler
{
  for(int i = 0; i < dxLayoutControl1->AbsoluteItemCount; i++)  // Iterates through all layout items
    dxLayoutControl1->AbsoluteItems[i]->OnHyperlinkClick = dxLayoutControl1Item1HyperlinkClick;
}

Prevent Accidental Hyperlink Activation in Layout Items

The code example in this section demonstrates OnHyperlinkClick and OnShowHyperlinkHint event handlers. The OnHyperlinkClick handler requires a user to hold down the Ctrl key to activate a hyperlink. The OnShowHyperlinkHint event handler changes all hyperlink hints to prompt a user to hold the Ctrl key for hyperlink activation.

Delphi

procedure TMyForm.dxLayoutControlItem1HyperlinkClick(Sender: TObject;
  AArgs: TdxHyperlinkClickEventArgs);
begin
  if AArgs.Shift <> [ssCtrl] then  // If the Ctrl key is not held down
    AArgs.Handled := True; // Prevents hyperlink activation
end;

procedure TMyForm.dxLayoutControl1Item1ShowHyperlinkHint(Sender: TObject;
  AArgs: TdxShowHyperlinkHintEventArgs);
var
  AHintPrefix, AHintURI: string;
begin
  AHintPrefix := 'Ctrl-click to navigate to ';
  AHintURI := AArgs.URI.Remove(0, 8);  // Removes the URI scheme from the hyperlink hint
  AArgs.Hint := AHintPrefix + AHintURI;  // Redefines the hyperlink hint
end;

C++

void __fastcall TMyForm::dxLayoutControl1Item1HyperlinkClick(TObject *Sender,
  TdxHyperlinkClickEventArgs *AArgs)
{
  if(AArgs->Shift != (TShiftState() << [ssCtrl]))  // If the Ctrl key is held down
    AArgs->Handled = true;  // Prevents hyperlink activation
}

void __fastcall TMyForm::dxLayoutControl1Item1ShowHyperlinkHint(TObject *Sender,
  TdxShowHyperlinkHintEventArgs *AArgs)
{
  UnicodeString AHintPrefix, AHintURI;
  AHintPrefix = "Ctrl-click to navigate to ";
  AHintURI = AArgs->URI.Remove(0, 8);  // Removes the URI scheme from the hyperlink hint
  AArgs->Hint = AHintPrefix + AHintURI;  // Redefines the hyperlink hint
}