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; 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 ___