THyperLink – Documentation

Version 1.3
Overview

THyperLink is a TCustomLabel descendant which can display any hyperlink. There are some service types 
predefined such as http, telnet, news, email etc. 
There are some important differences between THyperLink and other components which seemes to be very like 
THyperLink:
? You can add a custom service which is used by all THyperLink components in the current application
? you can display either the address of the link or just an alias name.
? you can decide what hint or tooltip is displayed but you can also leave the hint property empty so that the 
link displays the current address automatically as hint
? the component executes automatically any application associated with the current service. The address will 
be sent directly to the Shell via the SellExecute function or what is new: NEW! Associate another application 
for the specific service. See revision history. You can also use another custom based application and decide 
whether a click on the link is automatically executed or not
? Use definable colors for links and visited links. The color change will be automatically handled
? NEW! You can display either text or any bitmap (transparent) for the hyperlink
? NEW! There is an application-wide communication between all THyperLink- Instances. All links that points 
to the same address will change automatically its visited state if you visit the address
? NEW! You can get an application-wide list of all visited and not-yet-visited links. This list can be 
automatically saved to disk
? There is global instance which provides you all informations about all current Links in the application. So 
you may maintain and track changes of all lists
? NEW! Added telnet service 
? NEW! Enhanced context menu. So all THyperLink instances contains a context menu with the following 
menuitems: 
	Open 
		Just the same than clicking on the THyperLink
	Open With
		Select another application than the associated one to open the
		THyperLink (only in the registered version)
	Copy Url to Clipboard
		Copies the address of the THyperLink to the  clipboard
	Properties
		Opens a properties dialog which displays all informations about the current 
		THyperLink
Revision History:
Version 1.0
Initial Revision. Very simple component.
Version 1.1
	Internal Revision. Fixed some minor bugs. Completely rewritten demo-application. 
Version 1.2
Internal Revision. Added some enhancements. Display of bitmap instead of text. Added application-wide 
communication between all THyperLink instances.
Version 1.3
Second official release. Completely rewritten documentation, demo-application. Enhanced the features: 
Added global instance UrlBase and its provided functions, Added new context menu functions, Added 
properties dialog window.
Changed the state of THyperLink from Freeware to Shareware. The class does not anymore contain the 
source code. All functions but the ‘Open With’ all full functioned. There are no nag-screens or dialog 
boxes. But any user can open the context menu and chose the about item which displays a version and 
state message box.
Requirements
You need Borland C++ Builder 1.0, Delphi 2.0 or Delphi 3. You can use THyperLink with either Windows 95 (98)  
and NT (4.0, 5.0).
 
Copyright
THyperLink is Shareware. You can use it under the following restrictions:
	THyperLink is copyright © 1998 by H.P.G

You may use the THyperLink class for Free (unregistered version) for non-commercial software only. 
This means: 
	Freeware, 
	Public Domain Software (If there is any),
	For your personal use (and some friends ?) only.
You get the archive with the demo application as is. The archive includes the same than the Shareware archiv.

If you want to use the THyperLink in your Shareware or low-cost-applications (upto a price of 20 US$ per Copy) 
you have to pay 20 US$. This includes the class as compiled units, object-codes, the full source code (well-
documented) demo-application, the manual as Word and text file and 1 year free support and bugs fixes (If any 
needed). You got also a special price for upgrading the component if there are new version available. You will be 
added to the new THyperLink mailing list which automatically informs you about any new version available.

If you want use the THyperLink in your commercial software (price more or equal than 20 US$ per Copy) you can 
get two different packages.
Standard
	This includes the same than the Shareware archive version.
	Price:  50 US$

Professional
	This includes the same than the Shareware archive but also the full class source. You 	will be added to 
the mailing list too. Any bug fixed version can be delivered via email 	automatically (only if you want)
	Price: 100 US$

For all archive types you have to include a note about the author in the credits section of your manual like:
This application uses the THyperLink component © 1998 by H.P.G. 
Further classes and informations are available via 
HTTP://members.aol.com/hpgue or 
mailto:hpgue@aol.com

I will accept only:
	Cash in US$ or German DM‘s

	Euro-Checks drawn in German DM‘s
	
International money orders drawn on a German bank like ‚Deutsche Bank‘ in German 
	DM‘s

Order your copy today. Include the following informations for the fastest possible response:
	Type of platform to used (C++Builder, Delphi 2.0 or Delphi 3)
	Type of archive to pay for (Shareware, Standard or Professional)
	Your email address for the archive to send to (I will send the archive only via email!)
	Cash, EuroCheck or Money Order

Installation
C++ Builder:
	Copy the following files to your components directory:
		hyperlnk.hpp
		hyperlnk.obj
		hyperlnk..res
		hyperlnk.dcr
	Select from the C++Builder's menu Component->Install. Enter hyperlnk
	and press Enter. Rebuild the library. Done.
	You should now have a new component tab 'HPG' with THyperLink on it.

Delphi 2.0:
	Copy the following files to your components directory:
		hyperlnk.dcu
		hyperlnk.res
		hyperlnk.dcr
	Select from the menu Component->Install. Enter hyperlnk
	and press Enter. Rebuild the library. Done.
	You should now have a new component tab 'HPG' with THyperLink on it.

Delphi 3:
	Copy the following files to your imports and/or components directory:
		_hyperlnk.dpl
		_hyperlnk.dcp
		_hyperlnk.res
		hyperlnk.dcu
		hyperlnk.res
		hyperlnk.dcr
	Install the package like usual. Done.

Usage
THyperLink provides most properties a TLabel also provides. Some are quiet useless for the Link so I left it 
protected. I will here only describe the additional properties that has been added

I use one manual for both Delphi and C++ Builder version of the component.
So the properties are declared here 1st for Delphi and then for C++.
Component
TUrlBase – class documentation

The class modul contains two class definitions and one global instance. The first class is the TUrlBase. This class 
is used to maintain all links of the THyperLink instances. One instance of the TUrlBase is declared public: 
UrlBase. Don’t use any other instance nor try to delete the instance. The UrlBase is created via the initialization 
section (#pragma startup) and freed in the finalization section (#pragma exit). Each THyperLink instance attached 
its link address to the UrlBase. If any THyperLink executes the link the state of the THyperLink itself and the link 
changes. All other THyperLink instances in the application will be automatically informed about any change of its 
Urls.

UrlBase : TUrlBase 
TUrlBase *UrlBase;
This is the first and only instance of the TUrlBase class. The UrlBase is available only at runtime.

Properties

? VisitedUrlList : TStringList 
TStringList *VisitedUrls
Read only. This is the list of all current links in the application which are flagged as visited. Each time you execute 
the Reset() method or add a new THyperLink component this list changes its contents.

? OtherUrls : TStringList 
TStringList *OtherUrls
Read only. This is the list of all not yet visited links in the application.

? App[index : Integer] : String 
AnsiString App[int index]
Read only. This gives you easy access to the applications associated with the current THyperLinkType. Index 
may contain any value between ltEmail and ltCustom. If you do not change the Associated application of a 
service the standard value is empty which means the THyperLinks use the associated application (by Registry) 
else the executable is returned.
See SetApp() method

Methods

? constructor Create 
TUrlBase()
Standard constructor of the UrlBase

? destructor Destroy 
~TUrlBase()
Standard destructor of the UrlBase

? procedure SaveToFile(fall : Boolean; FileName : String);
virtual void __fastcall SaveTofile(bool fall, AnsiString FileName);
This function saves the contents of either the VisitedUrls or the OtherUrls to the given FileName. If fall is set to 
true the OtherUrls will be saved else if fall is set to false the VisitedUrls will be saved.

? function SetApp(fWhat : TLinkType; App : String) : String;
virtual AnsiString __fastcall Setapp(TLinkType fWhat, AnsiString App);
This function overwrites the associated application for the specified service application-wide. If you want to 
change the application for a service back to the associated application by Registry let App empty. The function 
returns the previous associated application for the service. 

	FWhat 
	may contains any value between ltEmail and ltCustom

	App
	Contains the new associated application for fWhat

? procedure Reset; 
virtual void __fastcall Reset();
This function resets the state of all visited Urls to not-visisted.

THyperLink – class documentation
Use the THyperLink for all Link types. Add a custom service if you want to use any other service than the 
provided ones. Set the layout either to text or Bitmap. If you want to create dynamically-created THyperLink 
instances make shure the Loaded (public) Method will be called after the Parent is set
Example:

procedure ButtonCreateHLDynamicOnClick(Sender : TObject)
var
	HL : THyperLink;
begin
	HL:=THyperLink.Create(MyForm); // Create the hyperlink
	HL.LinkType:=ltHttp; // Http hyperlink
	HL.Parent:=MyForm; // Display it in MyForm
	HL.Caption:=’www.borland.com’; // Link it to Borland 
HL.Loaded(); 
// This is important. The Url will be added to the global Urls and 
the Component 
// will be automatically attached to the UrlBase
ShowMessage(UrlBase.OtherUrls.Text);
// You should see now www.borland.com in the list ?
end;

virtual void __fastcall 	ButtonCreateHLDynamicOnClick(TObject *Sender)
{
THyperLink *HL;
	HL=new THyperLink(MyForm); // Create the hyperlink
	HL->LinkType=ltHttp; // Http hyperlink
	HL->Parent=MyForm; // Display it in MyForm
	HL->Caption=”www.borland.com”; // Link it to Borland
HL->Loaded(); 
// This is important. The Url will be added to the global Urls and 
the Component 
// will be automatically attached to the UrlBase
ShowMessage(UrlBase->OtherUrls->Text);
// You should see now www.borland.com in the list ?
}


Properties:
? About : TAboutHyperLinkProperty 
TAboutHyperLinkProperty *About
Displays a Status message box about the current version and state of the THyperLink class

? Alias : TString
AnsiString Alias
This is the string which will be displayed in the THyperLink. If you leave this blank the Address (property 
Caption) will be displayed instead

? Bitmap : Graphics.TBitmap
Graphics::TBitmap *Bitmap
This is the Bitmap which will be used if you set the Layout to llyBitmap. Note: The bitmap will be displayed 
transparent. The left most upper pixel is used as transparent color.

? Caption : TCaption 
TCaption Caption
This string is used to build the address which is executed when the user clicks on the link. the address is built 
with the Service Prefix (property LinkType) and the Caption. If you specify no Alias the full address Prefix and 
Caption will be displayed as hint.

? Cursor : TCursor
TCursor Cursor
This is the cursor the THyperLink uses. For default a cursor is added at creation time to the Screen.Cursors[] 
property. Do not modify this setting. Default is –21 which is filled with the Hand-Cursor.

? CustomPrefix : String
AnsiString CustomPrefix

This string is used instead of the predefined Service Prefixes if you set the LinkType to ltCustom. Set this to 
'https://' and the link will automatically execute the application that is associated with https:// service if any. All 
THyperLink components of the current application share the same CustomPrefix (this example has only an effect if 
their LinkType properties are set to ltCustom ;-)

? LinkColor, VisitedColor : TColor 
TColor LinkColor, VisitedColor

LinkColor is the Color of the THyperLink which will be displayed if the Visited flag is set to false (default). If the 
user clicks on the link the visited flag will be changed (for default) to true and the VisitedColor property will then 
be used for the THyperLink alias or caption.

? LinkLayout TLinkLayoutType
enum TLinkLayoutType LinkLayout

This decides whether text is displayed or the given bitmap (if any) is used to display the HyperLink. For the 
default LinkLayout is to llyText.
TLinkLayoutType is defined as followed:

TLinkLayoutType=(llyText, llyBitmap);
Enum TLinkLayout
{
	llyText,
	llyBitmap
};

Setting this property at run-time will not affect the layout of the THyperLink. Set this property at design time. If 
you use a dynamically created THyperLink instance set this property before the call to the Loaded() method.

? LinkType : TLinkType 
enum TLinkType LinkType

Defintion of TLinkType:

    TLinkType=(
ltEmail,
ltFile,
ltGopher,
ltHttp,
ltNews,
ltWais,
ltTelnet,
ltFtp,
ltCustom); 

enum TLinkType
{
ltEmail,
ltFile,
ltGopher,
ltHttp,
ltNews,
ltWais,
ltTelnet,
ltFtp,
ltCustom
};
		
LinkType specifies which Service Prefix the link uses. E.g. ltEmail uses the
Service Prefix "mailto:". If you set LinkType to ltCustom the CustomPrefix
will be used instead (see property CusotmPrefix). You can change the associated application by using the 
UrlBase.SetApp() function.

? MenuItems : TLinkMenuItems 
TLinkMenuItems MenuItems
Definition of TLinkMenuItems:

TLinkMenuItemOptions=
(
lmnuOpen, 
lmnuCopyUrl, 
lmnuOpenWith, 
lmnuProperty
);
  	TLinkMenuItems=set of TLinkMenuItemOptions;

	enum TLinkMenuItemOptions
{
lmnuOpen, 
lmnuCopyUrl, 
lmnuOpenWith, 
lmnuProperty
};
	typedef Set <TLinkMenuItems,lmnuOpen,lmnuProperty> TLinkMenuItems;

These options defines which context menu items should be displayed. Set any option to false and the menu item 
disappears.

Menuitems:	
lmnuOpen
Opens the link. This is the same than clicking on the ThyperLink with the left mouse button

lmnuCopyUrl
Copies the HyperLinks Service Prefix and Address to the clipboard

lmnuOpenWith,
opens a dialog box which lets the user chose another application for the hyperlink and executes the given 
application with the links‘ address.
NOTE: This feature is for the registered version only. In the un registered version a Shareware message box 
will be opened.

lmnuProperty
open a properties dialog which informs the user about the current HyperLink, its address, its service etc..

Note: In the un-registered  version only there is another menuitem which cannot be disabled About. If the suer 
selects about a Shareware message dialog will be opened. The registered version do not contain this menu item.

? Visited : Boolean
bool Visited
This flag decides which color will be used for the displayed text. Default this is set to false. If the user executed 
the link (see also Events section) this flag is toggled to false and the VisitedColor property will be used. You can 
also set Visited at design and runtime manually

Events:

? OnBeforeExecuted : TBeforeExecuteEvent
TBeforeExecuteEvent OnBeforeExecuted
Definition:
TBeforeExecuteEvent=procedure (Sender: TObject;var ExecuteIt: boolean 
) of object;
typedef void __fastcall (__closure   
*TBeforeExecuteEvent)(System::TObject* Sender,		bool 
&ExecuteIt);

This event occurs when the user clicks on the link first. All other events are fired after this event. If you set the 
ExecuteIt parameter to false the THyperLink will not be executed and no other event will be fired. Use this to 
temporary disable the execution of the link.

? OnExecute : TExecuteEvent 
Hyperlnk::TExecuteEvent 
Definition:
TExecuteEvent=procedure (Sender: TObject;var ExecuteIt: boolean ) of 
object;
typedef void __fastcall (__closure *TExecuteEvent)(System::TObject* 
Sender,
		bool &ExecuteIt);

This event is fired if the user clicks on the link and no OnBeforeExecute event is defined or the OnBeforeExecute 
event sets the ExecuteIt parameter to true (default). If you set the ExecuteIt parameter to false the ShellExecute 
function will not be called but the OnAfterExecute event will be fired, the Visited flag will be set to true and the 
VisitedColor will be used for  the displayed text. Use this if you want to start another application for the link as the 
currently associated one or to include a timeout function.

? OnAfterExecuted : TAfterExecuteEvent 
TAfterExecuteEvent OnAfterExecuted
Definition:
TAfterExecuteEvent=procedure (Sender: TObject;Reslt: longint ) of 
object;
typedef void __fastcall (__closure 
*TAfterExecuteEvent)(System::TObject* Sender,
		long Result);
	
This occurs if the link has been executed or better when the function call to the WINAPI ShellExecute returns. 
The return code of the call is submitted in the Result (Reslt) parameter. If you set the ExecuteIt paramater in the 
OnExecute event to false the Result is always 33; If Result is smaller than 32 then an error occured and the kind of 
error can be retrieved with a call to the WINAPI function GetLastError() Use this to find out when the 
ShellExecute function returns or whether the function has been correctly worked.


Author
If you have any questions, suggestions or want to contact me send a message to the following address:
	hpgue@aol.com

Visit also my home page at
	http://members.aol.com/hpgue/hpgintl.htm


___