Exposing Events in DHTML Scriptlets

See Also

When you use a DHTML scriptlet in your host application, the application can be notified about events that occur in the scriptlet. A DHTML scriptlet can expose two types of events:

• Standard DHTML events, such as the onclick event and the onkeypress event.
  
  
• Custom events, which are events that you define or DHTML events not provided as standard events. For example, the scriptlet can fire an event when a property value changes.

Handling Standard Events

A DHTML scriptlet can expose these standard DHTML events:

Tip   You can define a context menu that is displayed when the user right-clicks the scriptlet at run time. For details, see the setContextMenu method.

Events that occur in the scriptlet are not automatically sent to the host application. To trap standard events in the host application, you must write handlers in two places: one in the scriptlet to trap and forward the event, and another in the host application to capture the event.

To pass an event from the scriptlet to the host application

1. Attach an event handler script to the event that you want to pass.
   
   
2. Within the event handler script, call the bubbleEvent method to forward the event to the host application.

   Note   Before passing events to the container object, you can check the scriptlet's frozen property to be sure that the container object is ready to handle events.

If the scriptlet does not include an event handler for a specific event, that event will not be passed to the host application. Similarly, if the scriptlet includes a handler for the event but does not call the bubbleEvent method, the event will not be visible to the host application.

Note   The scriptlet container object exposes all standard events at design time, even if the scriptlet does not contain a script that passes the standard event to the application. For example, in Microsoft^® Visual Basic^®, the code window for the scriptlet container lists all standard events, even if not all are available in a specific scriptlet.

The following scriptlet script shows how you can pass a text box's onkeyup event to the host application:

<INPUT TYPE=text ONKEYUP="passKeyUp()" NAME="t1" VALUE="">
<SCRIPT LANGUAGE="JavaScript">
function passKeyUp() {
   // script statements here if required
    window.external.bubbleEvent();
   // further script statements here if required
}
</SCRIPT>

Note   When a standard event occurs, the host application sees the corresponding event triggered for the scriptlet container object as a whole. For example, the scriptlet might contain several buttons. If a user clicks one of the buttons (and if the scriptlet is forwarding the event), the host application receives only a general click event.

To pinpoint which control in the scriptlet triggered the event, you can create a custom event in the scriptlet that contains additional information about the event. For details, see "Creating and Handling Custom Events" below.

Additional information about a standard event, such as the location of the mouse pointer or the state of keys at the time the event was triggered, is available in the script container object's event property. For example, the following Visual Basic subroutine shows how you would capture the scriptlet's onkeypress event and display the key code of a character typed in a scriptlet textbox:

Sub ScriptContainer1_onkeyup()
   MsgBox "The character typed was " & ScriptContainer1.event.keyCode
   MsgBox "The shift state was " & ScriptContainer1.event.shiftKey
End Sub

In Microsoft^® Internet Explorer, the following script does the same thing:

<SCRIPT LANGUAGE=JavaScript FOR=document EVENT=onkeyup>
   alert("Key code = " + window.event.keyCode)
   alert("Shift status  = " + window.event.shiftKey)
</SCRIPT>

Creating and Handling Custom Events

You can expose custom events in either DHTML or automation scriptlets. Custom events allow you to:

• Send more detail about a standard event that occurred — for example, which of several buttons in the scriptlet was clicked.
  
  
• Notify the host application about non-standard changes in the scriptlet, such as when the value of a property changes.
  
  
• Notify the host application about DHTML events that are not among the standard events handled by the bubbleEvent method.

As with standard events, you must send the event from the scriptlet and capture the event in the host application.

To send a custom event in the scriptlet

• Call the scriptlet's raiseEvent method.

  Note   Before passing events to the container object, you can check the scriptlet's frozen property to be sure that the container object is ready to handle events.

For example, the following shows how you can send a custom event called oncolorchange whenever the scriptlet's backgroundColor property is reset. The second parameter is an object reference to the window.event object, which will allow the container handler to get information about the object that fired the event.

<SCRIPT LANGUAGE="JavaScript">
function public_put_backgroundColor(value)
{
   window.document.bgColor = value;
   window.external.raiseEvent("event_onbgcolorchange",window.event);
}
</SCRIPT>

To handle a custom event in the host application

• Create an event handler for the onscriptletevent event.

The following is an example in Visual Basic that shows how you can determine what control triggered an event:

Sub ScriptletContainer1_onscriptletevent( ByVal txtTitle As String, _
      ByVal eventData As Variant)
   objName = eventData.srcElement.id
   MsgBox "The event " & txtTitle & " occurred in " & objName
End Sub

If your host application is Internet Explorer, use a script such as the following to capture the scriptlet event:

<SCRIPT LANGUAGE="JavaScript" 
      FOR="s1" 
      EVENT="onscriptletevent (event, obj)">
   msg = "Event fired in the scriptlet was " + event
   msg = msg + "\nand the ID of the object was " + obj.srcElement.id
   alert(msg);
</SCRIPT>

You can use a Select Case structure in the onscriptletevent event to take different actions based on different events.