Comet Hyperlinks

Overview

Starting with Build 309 of
Comet2002, you can include hyperlinks on your Comet and CometAnywhere screen
displays.

These hyperlinks have the same
"look and feel" as hyperlinks on a web page. The link text is
displayed in color (the default color is blue), plus you have the option of
adding an underline to the link text (a feature that is set by your program).
When the user positions the mouse cursor over the hyperlink, the link text is
displayed in a different color (the default color is orange-red), which
provides instant visual feedback.

When the user clicks on a Comet
hyperlink, your program is notified via another new Comet2002 programming
feature: an event handling subroutine. The easy-to-understand logic of this
structure gives your program a quick way to determine what action to take when
someone clicks on a hyperlink.

These two features go hand-in-hand,
and we will describe them as follows. To implement Comet hyperlinks, you must:

·Display the link text on the screen

·Write the code that determines what to do when someone
clicks on a hyperlink

The HYPERLINK Mnemonic

The HYPERLINK mnemonic, available
in REL Version 02.03 and greater, displays a hyperlink on the screen. The
syntax is:

(HyperLink = LinkText$, LinkAction$, Style)

where:

·LinkText$ is the text that is displayed on the screen

·LinkAction$ is a string value (254 bytes
maximum) that is passed to the event handling subroutine when the user clicks
on a hyperlink. Note: This is an internal value only; the end-user does not see
this string. See the EVENTSUB statement for more information.

·Style is a numeric value that determines if the
link text is underlined (0 = not underlined, 1 = underlined).

Example:

Print @(0,3);"What is your favorite
flavor?"

Print
@(0,4);(Hyperlink="Chocolate","LINK1",0)

Print
@(0,5);(Hyperlink="Vanilla","LINK2",0)

Print
@(0,6);(Hyperlink="Strawberry","LINK3",0)

Print @(0,7);(Hyperlink="Chocolate
chip","LINK4",0)

This program displays several
hyperlinks on the Comet/CometAnywhere screen. If the user clicks on the any of
these links, the associated LinkAction$ value is passed to the event handling
subroutine. For example, if the user clicks on the "Chocolate chip"
hyperlink, "LINK4" is passed to the event handling subroutine.

Notice that all of the above
hyperlinks are displayed without an underline (Style = 0).

Note: The above code segment comes
from the HyprLink.ibs demo program (available in the DMW release, version 02.01
and greater).

Hyperlink Colors

Comet hyperlinks are displayed in
color. As mentioned above, the default color for the link text is blue. When
the user positions the mouse cursor over the link text (an action hereinafter
referred to as a "mouseover"), the link text changes color. The
default mouseover color is orange-red.

You can change these colors via:

·a mnemonic in your application, or

·a setting in the COSW.INI file

At the application level, the
(HyperLinkColor) mnemonic changes the hyperlink colors. The syntax is:

In addition to the (HyperLinkColor)
mnemonic, you can also change the hyperlink colors via a setting in the
COSW.INI file (which is located in the main Windows directory). The setting in
this file takes the same form as the mnemonic and acts as the default setting
for the Comet/CometAnywhere workstation.

The following segment shows the
initial default for Comet hyperlinks. The link text is blue (0,0,255) and the
mouseover text is orange-red (255,0,69):

.

.

[Terminal]

HyperLinkColor=0,0,255,255,0,69

.

.

The EVENTSUB Statement

The EVENTSUB statement, available
in Comet2002 Build 309 and greater, defines an event handling subroutine. Such
a routine provides a way for your program to determine what to do when an event
occurs. In the context of this discussion, an event occurs when the user clicks
on the Comet hyperlink.

The syntax is:

EVENTSUB
StatementLabel,EventString$,SourceString$

where:

·StatementLabel is the label of a statement in
the current program where control is transferred when an event occurs. In this
regard, the EVENTSUB statement is similar to the MESSAGESUB, ERRORSUB, and
ESCAPTESUB statements.

·EventString$ is a string variable whose value is
assigned by the object that caused the action to occur. In this context, it's
the value of the LinkAction$ field in a hyperlink.

·SourceString$ is reserved for future use

To remove an eventsub trap, issue
the statement without parameters, as follows:

EVENTSUB

Example:

The following code segment shows a
Comet hyperlink and a related EVENTSUB statement. When the user clicks on the
hyperlink, the program branches to the GetEvent label and assigns
"LINK1" to Event$. The event handling subroutine then determines what
action to take, which in this case is a Print statement. Notice that the
EVENTSUB statement is re-issued at the bottom of the routine, just prior to the
Return statement.

Print
@(0,4);(Hyperlink="Chocolate","LINK1",0)

EVENTSUB
GetEvent,Event$,Source$

.

.

.

GetEvent:

If Event$ = "LINK1" Then

Print
(WC);"Chocolate is a very good flavor."

Endif

EVENTSUB GetEvent,Event$,Source$

Return

Here is an extended version of the
sample code (from HyprLink.ibs in the DMW directory):

Print
@(0,4);(Hyperlink="Chocolate","LINK1",0)

Print
@(0,5);(Hyperlink="Vanilla","LINK2",0)

Print
@(0,6);(Hyperlink="Strawberry","LINK3",0)

Print
@(0,7);(Hyperlink="Chocolate chip","LINK4",0)

Print
@(0,8);(Hyperlink="Mint chocolate chip","LINK5",0)

Print
@(0,9);(Hyperlink="Rocky Road","LINK6",0)

!
set EVENTSUB trap

EVENTSUB
GetEvent,Event$,Source$

!
MainLineProcessing

Input @(34,20),Program$

ProgEnd:

if (Program$ EQ "") Then_

Program$ = "QMONITOR"

Print (WC);(BF)

Run Program$

! =
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

!

!E V E N TP R O C E S S I N GS U B R O U
T I N E

!

!
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

GetEvent:

Print (WC);(BF)

! make processing decisions based on the
value of the EventString$

Select Case Event$

Case "LINK1"

Print (WC);"Chocolate is
a very good flavor."

Case "LINK2"

Print (WC);"For some
reason, a lot of people choose vanilla."

Case "LINK3"

Print (WC);"Strawberry is
delicious."

Case "LINK4"

Print (WC);"Mmmmm, my
favorite flavor is also chocolate chip."

.

.

.

Endselect

! re-set Eventsub trap

EVENTSUB
GetEvent,Event$,Source$

RETURN

Some important notes:

·Notice that the event handling subroutine ends with a
RETURN statement. This returns the program to the statement that was being
executed when the event (mouse click on hyperlink) occurred. In the above
sample program, that statement is the INPUT statement in the MainLineProcessing
section (shown in bold face). Thus, the normal program flow is maintained after
an event has been processed.

·When your program is in an event handling subroutine,
it can still receive events (i.e., the user can click on a second hyperlink
while your program is still processing their first click). These events are
queued by Comet. When your program re-sets the eventsub trap, it immediately processes
any events that have been added to the queue. For this reason, we recommend re-setting
the eventsub trap just prior to the Return statement.

·If your program executes an EVENTSUB statement without
parameters, event handling is disabled and Comet purges all events that are in
the event queue.

·It's acceptable to code multiple event handling
subroutines in your program, although only one can be in effect at any given time.
An event handling subroutine takes effect when the EVENTSUB statement is
executed.

The (SatisfyInput) Mnemonic

Typically, your program will be
positioned at an INPUT statement when the user clicks on a hyperlink. When the
event handling subroutine concludes, it returns to the same INPUT statement
(assuming that you've concluded the subroutine with a RETURN statement).

The (SatisfyInput) mnemonic
provides a way for the event handling subroutine to supply input data to the
original INPUT statement. Here's an outline of the process:

1.display
a Comet hyperlink

2.set
an eventsub trap

3.go
to the main processing section of your program, which includes an INPUT
statement

4.in the eventsub routine, use the
(SatisfyInput) mnemonic to assign input data that will be fed to the INPUT
statement when someone clicks on a hyperlink

Thus, when the user clicks on the
hyperlink, the program will branch to the event handing subroutine, where it
will provide the input data to the original data entry field. This is a perfect
solution for a menu display, where the user can either type the response or
click on a hyperlink.

The following code segment (from
HyprLink.ibs) demonstrates this programming technique: