Exposing Events

 

To add event capability to a Windows Script Component:

• Declare each event that you want to be able to fire.

• Call a function to fire the event as required in the script component.

Some host environments also require that you generate a type library which they use to bind to events. For details, see Creating a Script Component Type Library.

Note

The Behavior handler exposes events in a slightly different way. For details, see Exposing Custom Events in Behavior Script Components.

Declaring Events

Each event you want to be able to fire must be individually declared.

To declare an event

1. Create a <public> element as a child of the <component> element.

2. In the <public> element, include an <event> element for each event you want to declare.

3. For example, the following script component fragment shows how to expose two events:

   <public>
      <property name="sname"/>
      <method name="factorial"/>
      <event name="namechanged"/>
      <event name="querydone"/>
   </public>
   

Specifying Dispatch Identifiers

COM programming provides event notification via dispatch identifiers (each referred to as a dispid), which are integer values that identify a component's events. The dispid is compiled into the component's type library and then used by the host application to bind to events.

The process of creating a type library for script components automatically generates dispids for your script component's events. However, if you prefer, you can specify your own dispids. Doing so allows you to:

• Guarantee that events in your script component will always have the same dispid. If the type library generator assigns dispids, they can change each time the library is generated.

• Map events in your script component to dispids with specific numbers. For example, if you want to fire a standard COM event such as an error notification, you can map your event to the values used by convention in COM.

To specify a dispid for an event, include the dispid attribute in the <event> element, as in the following example:

<public>
   <event name="namechanged" dispid="22">
</public>

Dispids must be unique within the script component. You can specify a negative value for a dispid to map to conventional events, but must use only specified ranges, such as -999 to -500 for controls. For details about reserved dispid ranges, refer to documentation for DISPID in the MSDN library.

Note

The dispid number zero is used to identify a default method or property. For more details, see Exposing Methods and Exposing Properties.

Firing an Event

You can fire an event by calling the fireEvent method, specifying the name of the event to fire. You cannot fire events that you did not expose in the <implements> element. You can fire an event in any script in your script component file. For example, the following illustrates how you can fire an event when a property value changes.

<script language="VBScript">
<![CDATA[
Sub put_lowercaseName(newLCName)
   name = newLCName
   fireEvent("namechanged")
End Sub
]]>
</script>

See Also

Exposing Custom Events in Behavior Script Components
Exposing Methods
Exposing Properties
Handling Script Component Events in the Host Application
Script Component File Contents