Hyperlinks

Certain texts can be interactive in WPTools - this means the text can be automatically highlighted when the mouse is moved over it (hover or "hot" effect) or an event can be triggered when the user clicks on it.

The standard interactive texts are hyperlinks.

Hyperlinks in WPTools 5 start with a hyperlink start tag <a> and end with a closing tag </a>. All these tags are represented by TWPTextObj instances. (These tags can be made visible using the 'FormatOptions'!) To read the hyperlinks URL use obj.Source, to modify the visible text change obj.EmbeddedText!

This code can be used to create a hyperlink:

WPRichText1.InputHyperlink('WPTOOLS','BOOK1').

Since hyperlinks are marked with paired TWPTextObj instances it is also possible to create those tags directly by code. This is very useful if you are creating the text using the low level paragraph procedures:

var par : TParagraph;

   link_tag : TWPTextObj;

begin

par := WPRichText1.ActiveText.AppendNewPar();

par.Append('This is a link: ');                              // Some Text

// Create a link

link_tag := par.AppendNewObjectPair(wpobjHyperlink,'WPCubed GmbH');

link_tag.Source := 'http://www.wpcubed.com';

// to display:

WPRichText1.Refresh;

end;

Note: The above code uses the function AppendNewObjectPair´. This function internally executes code similar to this example:

startobj := par.AppendNewObject(wpobjHyperlink,true,false);  // Opening

par.Append('WPCubed GmbH');          // some text

endobj   := par.AppendNewObject(wpobjHyperlink,true,true);   // Closing

endobj.SetTag(startobj.NewTag);      // Link Opening<->Closing

startobj.Source := 'http://www.wpcubed.com';                 // The URL

Hyperlink tags can have a style attached. This style can be a paragraph style:

startobj.StyleName := ParStyleName; // set a reference to a paragraph style

If no style name was specified the list of paragraph styles will be searched for a style with the name "A".

Alternatively the style can be defined directly in the TWPTextObj instance:

startobj.MakeStyle(true);

startobj.Style.ASet(WPAT_CharFontSize, 2200);     // create a large font

startobj.Style.ASetColor(WPAT_CharColor, clRed);  // as red text

startobj.Style.ASetColor(WPAT_CharBGColor, clYellow); // on yellow background

startobj.Style.ASetFontName('Courier New');

Please note that these style definitions have a lower priority than the text attributes defined for the enclosed characters (this are the attributes which have been assigned to the text) and the attributes defined in the property AutomaticTextAttr. They are only loaded and saved in the WPTOOLS format, not in RTF format.

React on the click on hyperlinked text: Event OnClickHotText

procedure TForm1.WPRichText1HyperLinkEvent(Sender: TObject; text,

url: String; IgnoredNumber: Integer);

begin

if Pos('http:',url)>0 then

   ShellExecute(Handle, 'open', PChar(url), '', '', SW_SHOW        );

end;

This event is executed after a dounble click on hyperlinked text. It will be triggered after a single click if the property 'OneClickHyperlink' has been set to true.

React on the click on hyperlinked text: Event OnClickHotText

procedure TForm1.WPRichText1ClickHotText(Sender: TObject; par: TParagraph;

posinpar, X, Y: Integer; Button: TMouseButton; Shift: TShiftState;

TxtObj: TWPTextObj);

begin

if TxtObj.ObjType=wpobjHyperlink then

begin

   WPRichText1.BookmarkMoveTo(TxtObj.Source);

end;

end;

this bookmark was created with WPRichText1.BookmarkInput('BOOK1');

Which types of text objects are clickable is always controlled by property ClickableCodes. This means the event can be also created for text which has been wrapped by merge fileds, bookmarks or span codes. The event OnClickHotText is always triggered by a single click.

Please note that in WPTools 5 hyperlinks are not represented by text with a certain attribute (asfHyperlink) followed by hidden text (afsHidden) as it was in WPTools 4 and before!

How to display visited hyperlinks in a different color:

We use the property

WPRichText1.HyperlinkTextAttr.UseOnGetAttrColorEvent := TRUE;

and a string list:

FVisitedHyperlinks := TStringList.Create;

In the hyperlink event we add URLs to the stringlist to know later if the link was already clicked:

procedure TForm1.WPRichText1HyperLinkEvent(Sender: TObject; text,

url: string; IgnoredNumber: Integer);

begin

FVisitedHyperlinks.Add(url);

if Pos('www', url) > 0 then

   ShellExecute(Handle, 'open', PChar(url), '', '', WM_SHOWWINDOW);

end;

Now we can use the OnGetAttributeColor event to modify the special text attribute 'on the fly':

procedure TForm1.WPRichText1GetAttributeColor(Sender: TObject;

var CharStyle: TCharacterAttr; par: TParagraph; posinpar: Integer);

var txtobj : TWPTextObj;

begin

txtobj := WPRichText1.CodeInsideOf(par,posinpar,wpobjHyperlink);

if txtobj<>nil then

begin

    if FVisitedHyperlinks.IndexOf(txtobj.Source)>=0 then

         CharStyle.TextColor := clGreen;

end;

end;

The reference CharStyle: TCharacterAttr which is passed to the event is a reference to a copy of the HyperlinkTextAttr property object. We can modify it without any sideffect to the other links in the text. But please do not modify the reference, just the properties of this object!

This technique can be also used for other 'special texts' - but the property UseOnGetAttrColorEvent must be always set to true to activate the feature.