[This is preliminary documentation and subject to change.]
You can add custom data strings to an event. These strings can be used either as comments or to store custom syntax to be processed internally by your authoring tool. The stream compiler objects delete these user-defined strings when the stream is converted to low-level syntax or saved to a file.
User-defined strings are stored in the event as microevents. A microevent is an event within an event.
For example, the following example adds an event that contains two microevents. The first microevent specifies that a file be downloaded, and the second stores a user-defined string. Note that the keyword userdef identifies the second microevent as a user-defined string. To locate more information about userdef and other stream compiler syntax, see Further Information on Data Services for the Client.
evs.AddText("0:32.0 { file1.htm userdef ""This is a user-defined string"" };")
You can access microevents using the EnhEvent.Attr and EnhEvent.Opcode properties. EnhEvent.Attr contains a collection of the microevent's text. For example, the following example extending the preceding one displays two message boxes, each containing the text of a microevent.
Dim e As IEnhEvent
Set e = evs.LastAdd()
Msgbox e.Attr(0) 'Displays "file1.htm"
Msgbox e.Attr(1) 'Displays "This is a user-defined string"
You can set or retrieve the type of microevents using EnhEvent.Opcode. This property contains a collection of flags identifying the microevent types. The preceding example sets e.Opcode(0) to EVOPdownload and e.OpCode(1) to EVOPuserdef. EVOPdownload is a numerical flag that specifies that the microevent is to download a file, and EVOPuserdef specifies a user-defined string.
If you change the type of a microevent, you typically must also change the corresponding text. This requirement comes from the fact that different stream compiler syntax is required for different kinds of events. To locate more information on stream compiler syntax, see Further Information on Data Services for the Client.
The number of microevents available in a event is enumerated by the property EnhEvent.AttrCount. In the previous example, e.AttrCount returns 2.
You can add a microevent to an event using either EnhEvent.Attr or EnhEvent.Opcode. To do so, set the value of a microevent with an index equal to the value of EnhEvent.AttrCount. Because microevent collections are zero-based, this index value is one greater than the value of the last microevent. Setting a value to this index adds a new microevent and increments EnhEvent.AttrCount. Note that you cannot add microevents at indexes greater than EnhEvent.AttrCount. You can only add one microevent at a time.
The following example adds a microevent to the event created preceding.
index = e.AttrCount
'Create a new microevent of type EVOPuserdef
'and increment e.AttrCount by 1.
e.Opcode(index) = EVOPuserdef
'Set the text of the new microevent
e.Attr(index) = "This is another user-defined string"
Note Microevents that follow user-defined strings should only other be user-defined strings. In other words, you should not follow a user-defined string microevent by a microevent of any other type. The stream compiler objects return a syntax error if the microevents following a comment are anything but additional user-defined strings.
For example, the following causes the stream compiler objects to return a syntax error because the second file transmission, File2.htm, microevent occurs after user comment.
evs.AddText("0:32.0 { file1.htm userdef ""A user comment"" file2.htm};")
Both of the following examples, however, are syntactically correct.
evs.AddText("0:32.0 { file1.htm file2.htm userdef ""A user comment"" };")
evs.AddText("0:32.0 { file1.htm userdef ""A user comment"" userdef ""Another comment""};")