Programming QB Damage Points in VBA, HTML/VBScript/JScript

This page describes basic principles on how to program QB Damage Points with VBA and HTML/VBScript/JScript (MSIE4+). This assumes you have properly installed QB Damage Points ActiveX Control (NOT the preview) and know a bit about programming in these languages.

Events

When QB Damage Points is hosted on a HTML page, on a form or any document that receives ActiveX controls (Word, Excel,...), it sends certain signals called events to the navigator to inform that certain actions must be taken. A tutorial showing the main events sent to a navigator is provided with the QB Damage Points installer. Sample VB projects with code are also provided.

In order to personalize how damage points are managed, you must respond to such events by writing code. If no code is provided, no specific action will take place.

The Impact Event: The Heart of QB Damage Points.

If there were only one event to take care of, it's this one!

The most important event you must handle is the Impact event. It occurs whenever a missile explodes (reaches its target). This event gives you the opportunity to compute the damage points incurred by a unit. If no code is found for this event, nothing will happen when a missile reaches its target.

This example subtracts points according to the data found in the first custom attribute of the weapon. You can use it directly in an HTML page, or in a VB form. It assumes you have on your form/page/document a QB Damage Points control named "QBDMap1" (this is usually the default name)

VBScript example:

<script language="VBScript">
Sub QBDMap1_Impact(ByVal Range, ByVal Sender, ByVal Target, ByVal Weapon)
QBDMap1.DamageUnit Target, 0, Weapon.Data(0)

End Sub
</script>

VBA example:

Private Sub QBDMap1_Impact(ByVal Range As Long, ByVal Sender As Unit, ByVal Target As Unit, ByVal Weapon As Weapon)
With QBDMap1.Configuration
If .UnitGauges > 0 And .WeaponAttributes > 0 Then
   QBDMap1.DamageUnit Target, 0, Weapon.Data(0)
End If
End With

End Sub

JScript example:

<script language="JavaScript" for="QBDMap1" event="Impact(Range, Sender, Target, Weapon)">
Target.Gauges(0).Decrease(Weapon.Data(0));
</script>

You can see from the previous example that an event code is simply a procedure called by the host application or the navigator each time an event (the Impact event here) is fired. In order to work properly, the procedure accepts 4 arguments you can directly use:

Range: this argument contains the distance, in cells, a unit is located from the missile impact point. If the missile explodes just on the unit, Range is zero. If the missile exploded 1 cell away, Range is 1, etc.
Sender: which Unit sent the missile (the Attacker)
Target: the unit being targeted by the missile
Weapon: the weapon used to fire the missile

You will need the data available for each unit in order to compute the damage points. To access a custom attribute, use the Data property of the Target, Sender and Weapon. The first custom attribute is accessed by Data(0) in any object, the second with Data(1) etc. The maximum index for custom attributes depends on the configuration you are using. It is n-1 if n is the number of custom attributes for an object. Please be aware that an error in the index of the Data property may crash your application.

To apply the damage points to the unit, you have 2 options:

Use the DamageUnit method of the QB Damage Points Control (QBDMap). The QB Damage Points control is usually available as a global variable. Its name is the name defined in the <object> tag of the HTML page, or the one defined by the forms editor.
DamageUnit takes 3 arguments: (1) the unit from which you subtract points, (2) the approriate index of the Gauge (energy bar), and (3) the amount to be subtracted. To subtract points, use a positive number. To add points, use a negative number.

Otherwise use the Increase or Decrease methods of any Gauge/energy bar of the Target. These 2 methods take only one argument, the amount the Gauge will be increased or decreased.

Example (VBA/VBScript): If the QB Damage Points control is named QBDMap1, if your third weapon attribute is named "Damage" and you want to subtract it from the second Target gauge, use :

QBDMap1.DamageUnit Target, 1, Weapon.Data(2)

Target.Gauges(1).Decrease Weapon.Data(2)

To subtract a fixed amount each time, 7 points for instance, simply write:

QBDMap1.DamageUnit Target, 1, 7

Target.Gauges(1).Decrease 7

For JScript code, add the necessary parentheses and semicolons;. Please be aware that some functions may not work with JScript. In such a case, consider mixing VBScript and JScript in the page.

More on handling events

In order to handle events in HTML pages:

VBScript: go to a VBScript section and insert the following lines.

Sub MyObject_MyEvent(Arg1, Arg2)
' Insert event code here...
End Sub

MSIE/JScript: Insert this script tag

<script for="MyObject" event="MyEvent(Arg1, Arg2)">
// Insert event code here...
</script>

where MyObject is the name of the QB Damage Points component (QBDMap1 by default), MyEvent is the name of the event which arguments are Arg1, Arg2, Arg3,...

More resources

The intelligent features of the code editor in VS/MSE or VBA offer a great help when coding. Take advantage of them! They give you the function syntax and number of arguments. They display the list of all properties and methods available for an object.

The object browser is also a great companion for complete object reference.