Microsoft® Windows® Script Component
Exposing Events
 Script Component Tutorial
Previous
Next

See Also


To add event capability to a Windows® 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.

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:

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>