Syntax

  Sub OnTouch(arX,arY,arIDs,arFlags,arMask,arTime,arXContacts,arYContacts)      …  End Sub  

arX

An array of integer values, from arX(0) to arX(n), providing the x-coordinates (in pixels from the left of the screen) of the currently active touch points.

arY

An array of integer values, from arY(0) to arY(n), providing the y-coordinates (in pixels from the top of the screen) of the currently active touch points.

arIDs

An array of integer values, from arIDs(0) to arIDs(n), providing the unique identifiers of the currently active touch points. Each discrete touch point receives its own identifier, even if it is the same finger touching, then lifting, then touching again. These identifiers are incremented from when the device is turned on, and they include all touches captured by the operating system, not just those captured by your project during run time.

arFlags

An array of integer values, from arFlags(0) to arFlags(n), where each value is a set of bit flags that specify various aspects of touch point press, release, and motion.

For more information about the bit flags and their possible values, go to “TOUCHINPUT structure” on the Microsoft Developer Network website at: msdn.microsoft.com/library/dd317334.aspx

arMask

An array of integer values, from arMask(0) to arMask(n), where each value is a set of bit flags that specify which of the optional parameters (i.e., arTime, arXContacts, arYContacts) contain valid information. The availability of valid information is device-specific; for example, for the parameter arTime, some devices provide only the time elapsed since the device was turned on, rather than the actual system time.

For more information about the bit flags and their possible values, go to “TOUCHINPUT structure” on the Microsoft Developer Network website at: msdn.microsoft.com/library/dd317334.aspx

arTime

An array of integer values, from arTime(0) to arTime(n), providing the timestamps (in milliseconds) of the currently active touch points.

arXContacts

An array of integer values, from arXContacts(0) to arXContacts(n), providing the widths (in hundredths of a pixel) of the contact areas of the currently active touch points. The contact area of a touch point is the area actually touched by the user’s fingertip.

arYContacts

An array of integer values, from arYContacts(0) to arYContacts(n), providing the heights (in hundredths of a pixel) of the contact areas of the currently active touch points. The contact area of a touch point is the area actually touched by the user’s fingertip.

Returned value

This is a sub-routine (as opposed to a function) in VBScript, so it does not return any value.

Notes

This sub-routine is based on the WM_TOUCH system message and the associated TOUCHINPUT data structure in the Windows API. For more information, go to “Windows Touch Input” on the Microsoft Developer Network website at: msdn.microsoft.com/library/dd317321.aspx

The sub-routine is executed continuously while the user is touching the project screen or screen object. There are no delta or cumulative values, so there is nothing to reset when the manipulation is completed. These are the raw data provided by the Windows API.

You are not required to use the received parameters in your code. They simply make the raw touch input data available to you, for you to use (or not) as you deem necessary.

In all of the parameters described above, the array elements represent the individual touch points on the screen, in the order that the user actually touches the screen. The first array element (position 0) is the first touch point, the second array element (position 1) is the second touch point, and so on up to the maximum number of touch points supported by the device.

  n = UBound(arX)    For i = 0 to n      $TouchX[i] = arX(i)      $TouchY[i] = arY(i)      $TouchID[i] = arIDs(i)      $TouchTime[i] = arTime(i)  Next  

The function UBound measures the current size of arX (although any of the parameters may be used), and then the For loop copies the values to appropriately named tag arrays (e.g., TouchX, TouchY) in your project tags database. Once this is done, you can reference the tag arrays rather than the parameters.

  s = $TouchX->Size    For i = (n+1) to s      $TouchX[i] = 0      $TouchY[i] = 0      $TouchID[i] = 0      $TouchTime[i] = 0  Next  

By this time, you may have noticed that there is no graceful way to handle the elimination of array elements from anything other than the highest array position. If the user touches the screen with two fingers and then lifts their second finger, the second element of the array (position 1) is eliminated without issues. But if the user touches the screen with two fingers and then lifts their first finger, the first element of the array (position 0) is eliminated and the second element (position 1) becomes the first element (position 0).

You can use the unique identifiers provided by arIDs, rather than the array positions that will change as the arrays are dynamically resized, to handle specific touch points over time. The exact method for doing that, however, depends on how you develop the rest of your project and therefore is beyond the scope of this documentation.