The Script Component Wizard

The opening screen of the Script Component Wizard is shown in Figure 9-1. Although the dialog contains a number of text boxes, it is only necessary to enter the component name in the Name text box. The Script Component Wizard will then automatically use this information to complete theFilename and Prog ID text boxes. However, each of these text boxes, as well as theVersion and Location text boxes, can be manually overridden. The text boxes are described in the following list:

Name

The name of the component.

Filename

The Windows Script Component (.wsc) file containing the component definition. If you specify an existing filename, WSC will overwrite it with the new component definition.

Prog ID

The component's programmatic identifier. The programmatic identifier can be any string and is defined in the system registry. Typically, it consists of two substrings separated by a period. For instance, the VBScript CreateObject function, which creates a new instance of an object, takes a programmatic identifier as an argument.

Version

The version number of the component. This has the format MajorVersion.MinorVersion.

Location

The path to the directory in which the .wsc file resides.

WSC allows you to define multiple components within a single .wsc file. This feature is not supported, however, by the Script Component Wizard; if you attempt to assign a new component to an existing .wsc file, the wizard overwrites the file containing the original component. If you do want to create multiple components, you can use the wizard to define the first component, and then use a text editor to define all remaining components.

Figure 9-1. The component definition dialog of the Script Component Wizard

For our example, we'll name the component MathLib. Figure 9-2 shows the completed dialog after we enter the component name.

Figure 9-2. The component definition dialog for the MathLib component

The second screen, which is shown in Figure 9-3, allows you to define the general characteristics of the component, such as its scripting language, the interface handlers it uses, and whether error checking and debugging are available for the component at runtime.

By default, WSC supports three interface handlers: COM automation, ASP, and DHTML. Support for COM automation is automatically added whenever you define a property, method, or event for the component. If the component is to be used within Microsoft Internet Explorer, support for DHTML can be added by checking the "Use this scriptlet with DHTML behaviors" check box. If the component is to be used in generating ASP pages, check the Support Active Server Pages check box.

The runtime options check boxes allow you to determine whether any debugging features are enabled at runtime. The "Error checking" check box allows the component to display a descriptive error message should an error occur in the component when it is used. Ordinarily, the component will not display an error message, since recognizing and handling the error is the responsibility of the client that instantiates the component. The Debugging check box allows the Script Debugger to be launched if an error occurs. If this option is disabled, a runtime error simply terminates the program or script without prompting the user to open the Script Debugger.

Figure 9-3. The component characteristics dialog of the Script Component Wizard

In the case of our component, we'll uncheck the "Do you want special implements support" box to turn off support for the ASP and DHTML interface handlers. And we'll leave error checking and debugging enabled.

The third screen, which is shown in Figure 9-4, allows you to define componentproperties. Properties are attributes or descriptions of the state of component. Along with the property's name, you indicate whether the property is read/write, read-only, or write-only. In addition, you can assign an optional default value to the property. For our example MathLib component, define the properties as shown in Figure 9-4.

Figure 9-4. The properties definition dialog of the Script Component Wizard

The fourth screen, which is shown in Figure 9-5, allows you to define component methods, along with their parameters. Each parameter is specified as a simple parameter name. Multiple parameters are separated from each other by commas. The methods for our example MathLib component are shown in Figure 9-5.

Figure 9-5. The methods definition dialog of the Script Component Wizard

The fifth screen, shown in Figure 9-6, allows you to define theevents raised by the component. This simply requires that you enter the name of the event. In the case of our example, we'll define one event, DivByZero. The sixth and final screen simply summarizes the information that you've entered about thecomponent. Figure 9-7 shows the summary dialog for our MathLib component.

Figure 9-6. The events definition dialog of the Script Component Wizard

Figure 9-7. The summary dialog of the Script Component Wizard

When you click the Finish button, the wizard generates the .wsc file that contains the skeleton code needed by your component. All that you have to do is to write the script required by your component's properties, methods, and events. In order to do this, however, it is useful to know something about the format of a .wsc file.

The MathLib.wsc file produced by the Script Component Wizard is shown in Example 9-1. It begins with an tag, which is automatically inserted by the wizard and is required if the file is to be edited using an XML editor; otherwise, it is optional. Its presence indicates that the file is to be parsed using strict XML syntax.

Example 9-1. The MathLib.wsc file

Note that the beginning and end of our MathLib component definition is signaled by the and tags. If multiple components are stored in a single file, and tags that surround all component definition tags are required. The ?> tag defines attributes for runtime error handling. It is only inserted by the wizard if either runtime error handling or debugging are enabled; otherwise, it is omitted. If you've selected the defaults and nevertheless want to add it, it takes the following form:

The ... tag provides the registration information needed to identify and create an instance of the component. This includes a description or friendly name for the component, its programmatic identifier and version number, and finally a globally unique identifier (GUID) that uniquely identifies the component. Eventually, the information provided by the tag is entered into the system registry.

The ... tag defines a component's public interface. Information on all of the properties (indicated by the tag), methods (indicated by the tag), and events (indicated by the tag, which is not shown in Example 9-1) exposed by the component is stored here. The presence of the tag also indicates that the component will use the COM automation interface handler.

The tag has a name attribute that defines the property name, as well as one or two subelements. If the property is read-only, it has a element, which indicates that a property value can be retrieved. If the property is write-only, it has a element, which indicates that a property value can be assigned. And if the property is read-write, it has both a and a element.

The tag has a name attribute as well as zero, one, or more subelements that indicate the names of the method parameters.

The tag can also have one or more subelements that indicate the event name. This syntax means, incidentally, that we cannot define events that supply arguments to event handlers. But although we've defined an event for our MathLib component, as Figure 9-6 shows, the element has not been added to our .wsc file. If we want our component to fire events, we have to add the element manually.

The and elements are responsible for defining the public interface members of a component, but they do not provide an implementation. The actual operation of properties and methods is determined by code within the tags. As Example 9-1 shows, in addition to providing the tags, the Script Component Wizard creates a template for each of the component's properties and methods. Both member types, however, are implemented in code as methods. Property accessor methods (that is, methods responsible for retrieving a property value) are named by prepending the string get_ to the property name. Property mutator methods (methods responsible for assigning a value to a property) are named by prepending the string put_ to the property name. The value to be assigned to a property is represented by the newValue parameter.

In addition to providing a template in which we can supply code to define the operation of our component's public methods, the Script Component Wizard also handles defining a default value to a property. In the case of our read-only Pi property, for instance, it defines a variable named Pi (which is not the same as the Pi property) to which it assigns the default value 3.14159.

In the next section, we'll complete our component by writing the code for its public members. In the process, we'll look at some of the issues involved in developing components using WSC.

9 2 Writing Component Code