Comet Hyperlinks

From CometWiki

Revision as of 18:11, 4 June 2010

Overview

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 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 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).

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:

(HyperLinkColor=Red,Green,Blue,mouseoverRed,mouseoverGreen,mouseoverBlue)

where:

• The first three parameters (Red, Green, Blue) determine the color of the link text
• The remaining three parameters (mouseoverRed, mouseoverGreen, mouseoverBlue) determine the color of the text on a mouseover
• All of these parameters must be in the range 0 (minimum color intensity) to 255 (maximum color intensity). Thus, there are more than 16.7 million color combinations available.

Notes:

• If you are using Comet windows, this mnemonic applies only to the window where it is issued. If you are not using Comet windows, this mnemonic applies to the whole Comet screen.
• Once changed, the new hyperlink colors remain in effect until (1) changed again, or (2) the session is exited from and restarted.
• Each Comet/CometAnywhere session starts with the default colors (from COSW.INI).

Example:

Suppose you want to create link text that is red (normal color) and blue (mouseover color). Here is the appropriate mnemonic:

(HyperLinkColor=255,0,0,0,0,255)

where:

• 255,0,0 specifies maximum red, no green, and no blue (result: link text is red)
• 0,0,255 specifies no red, no green, and maximum blue (result: mouseover text is blue)

To restore the initial default colors, use the following settings:

(HyperLinkColor=255,255,255,255,255,255)

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 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 T   P R O C E S S I N G   S 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:

Print @(40,3);"Run your favorite utility program"
Print @(40,4);(Hyperlink="Spooler","LINK7",1)
Print @(40,5);(Hyperlink="Comet Editor","LINK8",1)
Print @(40,6);(Hyperlink="Utility menu","LINK9",1)
! 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 T   P R O C E S S I N G   S 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 "LINK7"
            TempProg$ = "QSPOOL"
         Case "LINK8"
            TempProg$ = "CED"
         Case "LINK9"
            TempProg$ = "QTILITY"
    ...
    Endselect
! Pass result back to main-line program and exit input
    If (TempProg$ NE "")
          Print (SatisfyInput = TempProg$)
EndIf
! re-set Eventsub trap
EVENTSUB GetEvent,Event$,Source$
RETURN

The EVENTWAIT statement

The EVENTWAIT statement causes Comet to wait for an event to occur. In effect, this statement is like the WAIT statement, although without any screen interaction.

The following code segment shows how EVENTWAIT can be used to display a screen with multiple hyperlinks and no INPUT or WAIT statement:

Print (Hyperlink=...)
Print (Hyperlink=...)
Print (Hyperlink=...)
...
EVENTSUB GetEvent,Event$,Source$
...
EVENTWAIT
...
GetEvent:
...
EVENTSUB GetEvent,Event$,Source$
RETURN