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:[email protected]

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:
       [email protected]

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


___

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.