C++ Builder Developer's Journal / Creating a URL label

December 1998

Creating a URL label

C++Builder programming
version markers: 1.0, 3.0

by Kent Reisdorph

You can download sample files from our Web site as part of the file dec98.zip. Visit www.zdjournals.com/cpb and click on the Source Code hyperlink.

A Web site is a great way to promote your company. If you have a Web site, you want your users to be able to get to it with the minimum amount of effort. A URL label in your application's About dialog box allows your users to quickly and easily connect to your Web site from your application. In this article, we'll show you how you can create a URL label.

What's a URL label?

A URL label is nothing more than a regular Label component that, when clicked, starts a Web browser and connects to a Web site. A URL label has the following characteristics:

	The label's caption is a URL.
	The URL appears in blue text, to indicate that it can be clicked.
	Your cursor changes to a pointing hand when it moves over the label.
	When you click on the label, it spawns a Web browser.

For example, Figure A shows the URL label in our sample application's About dialog box.

Figure A: Users can click on a URL label to quickly go to a Web site.
[ Figure A ]

Most of the steps required to fulfill this feature list are easy to perform--you certainly don't need any help to drop a label on a form, change the Caption property, and change the font's color. The rest, though, requires some explanation.

Creating and implementing the cursor

A URL label should make the cursor change to a pointing hand, so the user can tell that the label is more than just colored text. You can easily create a pointing hand cursor using the Image Editor (or any other resource editor you're familiar with).

Using Image Editor, create a resource file (RES) and then create a cursor resource within that resource file. Name the cursor resource something appropriate (WEBPOINTER would be a good name). Save the resource file and close Image Editor. Now, choose C++Builder's Project | Add To Project menu item and add the resource file to your project.

Next, you need to load the cursor resource so that it's available to the URL label. Put this code in your main form's OnCreate event handler:


Screen->Cursors[1] =
  LoadCursor(HInstance, "WEBPOINTER");

The cursor will be loaded when the application starts and will be ready for you to use. Notice that the code loads the cursor into array index 1 of the Cursors array. To assign the new cursor to the URL label, simply change the label's Cursor property to 1. You can do this either at design time or at runtime.

Starting the Web browser

At this point, you have a label that looks good but doesn't do anything. You need to write code so that the Web browser starts when you click on the URL label. If you think this step is going to be difficult, you might be surprised at how easy it actually is. The key is the Win32 API ShellExecute function. Before you can use ShellExecute, you need to include the SHELLAPI.H header in your application. Place this line near the top of the header for any units that call ShellExecute:


#include <ShellApi.h>

Now that you've included the header, you can call ShellExecute. Here's the code:


ShellExecute(0, "open",
  "http://www.turbopower.com", "", "",
  SW_SHOWNORMAL);

ShellExecute will open a document based on the document's extension. In order for this function to work, the filename extension must be registered with Windows. A browser document is a special case: Windows recognizes the document name as a URL, automatically executes the default Web browser, and loads the document. If ShellExecute fails, it returns a value of 32 or fewer. You should write your code to account for an error. For example:


int result =(int)ShellExecute(0, "open",
  "http://www.turbopower.com", "", "",
  SW_SHOWNORMAL);
if (result <= 32)
  ShowMessage("Unable to start web browser.");

All you have to do now is add this code to the OnClick event handler for the URL label. Double-click on the label, and C++Builder will create an event handler for the OnClick event. Enter code similar to the above code snippet, and you're all set.

But wait, there's more!

Not only can you start a Web browser with ShellExecute, you can also use it to let your users send you E-mail. It's just a matter of changing things a little:


int result =(int)ShellExecute(0, "open",
  "mailto:freddy@kreuger.com", "", "", 
  SW_SHOWNORMAL);
if (result <= 32)
  ShowMessage(
    "Unable to start mail client.");

Notice that the document string in this example includes mailto: rather than a URL. When this code executes, Windows will start the mail client registered on the user's system and fill in the To field with the E-mail address passed in ShellExecute.

Conclusion

Allowing your users quick access to you via the Internet is a great way to increase your business. In this article, we've shown you how to let users easily access your Web site from an application's About dialog box.