TdxHyperlinkClickEventArgs.Handled Property

Specifies if built-in hyperlink activation routines are disabled.

Declaration

delphi

property Handled: Boolean read; write;

Property Value

Type	Description
Boolean	`False` Default. A click on the hyperlink opens its target in the corresponding default application.`True`

Built-in hyperlink activation routines are disabled.

Tip

Use this option if you need to prevent hyperlink activation or execute a custom operation instead of hyperlink activation.

Remarks

Set the Handled property to True if you need to prevent hyperlink activation.

Code Examples

Prevent 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
C++

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;

cpp

#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 Formatted Labels

The code example in this section demonstrates handlers of OnHyperlinkClick and OnShowHyperlinkHint events. The OnHyperlinkClick event 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
C++

delphi

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

procedure TMyForm.dxFormattedLabel1PropertiesShowHyperlinkHint(Sender: TObject;
  AArgs: TdxShowHyperlinkHintEventArgs); // Changes all hyperlink hints
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;

cpp

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

void __fastcall TMyForm::dxFormattedLabel1PropertiesShowHyperlinkHint(TObject *Sender,
  TdxShowHyperlinkHintEventArgs *AArgs) // Changes all hyperlink hints
{
  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
}