Immersion in Visual Basic

Immersion TouchSense technology brings the sense of touch to games, applications, and websites. Developers can make use of TouchSense technology in their Visual Basic applications via the Immersion Web ActiveX Control. The API of the Immersion Web ActiveX Control is fully documented in the Immersion Web Plugin Reference.

This document describes how you can easily include and call the Immersion Web ActiveX Control in your Visual Basic 6 application.

Adding the Plugin to the Controls Palette and a Form

VB Sample #1: "Hello VB TouchSense!"

VB Sample #2: Choose an IFR and Effect

VB Sample #3: Hello revisited (Dynamic OCX Binding)

Please send all questions and feedback to developer@immersion.com.

Last updated 2/5/01


Adding the Plugin to the Controls Palette and a Form

Install the Immersion Web Plugin on your system by visiting www.immersion.com/plugins/install_plugins.html with your favorite web browser. The plugin will be installed automatically on your system.

In VB6, select Project | Components...

Choose the Controls tab.

Scroll down in the list to "Immersion Web Type Library" and check the adjacent checkbox.

Click Apply and then OK/Close.

The Immersion Web Plugin should now appear on your VB controls palette along with all the standard controls as shown on the left.

To place an instance of the Plugin on your form, click the hand icon on the controls palette, then drag out an area on your form where the instance should be placed, as with any other VB control. The instance of the Immersion Web Plugin has no visual component during run time, so you will only see it appear on your form during design time. Give the instance a Name, and use this Name when calling methods of the plugin in your code. See the sample code for more details.

See a sample -->

Back to Index


VB Sample #1: "Hello VB TouchSense!"

See the "Sample1" directory. This sample demonstrates how to play an effect from an .IFR resource file. A vibration effect is played whenever the Play button is clicked. The following steps can be used to recreate this sample.

Create a new project by selecting "Standard EXE" in VB's New Project dialog. Change the caption of the dialog to Hello VB TouchSense!

Add the Immersion Web Plugin control to the dialog as described here.

Add a Button and name it Play

Now it's time to add the code. When the form loads we want to open the IFR file containing our touch effect. This is achieved through the OpenForceResource method of the Immersion Web Control:

Dim glngReference As Long

Private Sub Form_Load()
    glngReference = ImmWebControl1.OpenForceResource(App.Path & "\Hello.ifr")
End Sub

The return value stored in glngReference is the ID that we will use to refer to the IFR file.

Next we add Play_Click procedure to play our touch effect when the Play button is clicked. Our effect is called "MyEffect".

Private Sub Play_Click()
    If (glngReference >= -1) Then
        success = ImmWebControl1.StartEffect("MyEffect", glngReference)
    End If
End Sub

That's all -- now we're done!

Sample #2 -->

Back to Index


VB Sample #2: Choose an IFR and Effect

See the "Sample2" directory. This sample program is a much more advanced version of the first sample. The user can choose IFR files to load and then select from a list which effects in the IFR file he wants to play. This sample shows how effect names from an IFR file can be displayed and how effects from an IFR file can be started and stopped.

To use run VBSample2.exe and follow these instructions:

  1. On the right side of the form which appears, use the file browser to select an IFR file whose effects will be tested. When the desired IFR file is clicked and highlighted in the bottom right list box, its name appears in the top left edit field on the form.
  2. Click the Load IFR button next to the edit field. The effects in this IFR file are listed in the list box below the edit field.
  3. Select any effect in the list box by clicking it. Play and stop the effect by clicking the Play the Effect and Stop the Effect buttons respectively. To stop a particular playing effect, that effect must be selected in the list box.
  4. Repeat the above steps to load and test the contents of another IFR file.
Dim glngReference As Long 'Reference to effect resource file
Dim gstrIFRPath As String 'Path to directory containing file

Private Sub DirList_Change()
    FileList.Path = DirList.Path
End Sub

Private Sub DriveList_Change()
    DirList.Path = DriveList.Drive
End Sub

Private Sub FileList_Click()
    gstrIFRPath = FileList.Path
    IFRPath.Text = (FileList.FileName)
End Sub

Private Sub IFRPath_Change()
    EffectName.Clear 'Clear the EffectName list
End Sub

Private Sub LoadIFRButton_Click()
    If IFRPath.Text <> "" And Left(IFRPath.Text, 1) <> "<" Then
        EffectName.Clear 'Clear the EffectName list

        'Open the chosen effect resource file
        glngReference = ImmWebControl1.OpenForceResource(gstrIFRPath + "\" + IFRPath.Text)
        If glngReference >= 0 Then

            'Populate the EffectName list
            numEffects = ImmWebControl1.GetNumberOfEffects(glngReference)
            For Counter = 0 To (numEffects - 1)
                EffectName.AddItem (ImmWebControl1.GetNameOfEffect(Counter, glngReference))
            Next
        End If
    End If
End Sub

Private Sub PlayButton_Click()
    'Play the effect selected in the list box
    success = ImmWebControl1.StartEffect(EffectName.Text, glngReference)
End Sub

Private Sub StopButton_Click()
    'Stop playing the effect selected in the list box
    success = ImmWebControl1.StopEffect(EffectName.Text, glngReference)
End Sub

Sample #3 -->

Back to Index


VB Sample #3: Hello Revisited (Late Binding)

VB Sample #3: Hello Revisited (Dynamic OCX Binding)

For the next example (see the "Sample3" directory) we'll revisit the original "Hello VB TouchSense!" sample #1 and change the method of instantiating the Immersion Web ActiveX control.

The previous samples both used the Immersion Web control by placing it inside a Form window at design-time. This method of instantiating the control assumes that the user of your VB executable already has the Immersion Web control successfully installed and registered on his machine. If it turns out that this is not the case, however, the VB application won't be able to instantiate the control and will crash rather ungracefully after popping up an error message that looks like this:

Ideally, a VB program should be able to check that all necessary components for running the program are present on the system, and give a user options or informative messages if that's not the case. Luckily, it's possible to dynamically create an Immersion Web control object in your code during run-time. To do this, first declare the variable you want to use. In this case we'll call our variable ImmWebControl1:

Dim ImmWebControl1 As Object

Declaring an object variable with the As Object clause creates a variable that can contain a reference to any type of object. However, access to the object through that variable is late bound; that is, the binding occurs when your program is run.

Next, the Immersion web control object must be created. This is done like this:

Set ImmWebControl1 = CreateObject("Immersion.ImmWebControl")

Note that it is not guaranteed that ImmWebControl1 was successfully created. If the Immersion Web control is installed on the user's system, then ImmWebControl1 will contain a reference to the Immersion Web control, and the methods of the control can be called. If the control is not installed, then ImmWebControl1 will contain Nothing, and calling the control's methods will lead to errors. To check for this possibility, add the following conditional statement:

If ImmWebControl1 Is Nothing Then
  ' write code to inform the user that the object is not currently
  ' installed, and perhaps provide object installation options

Once you have made sure that your user's system contains the necessary components for running your program, you are ready to call the methods of the Immersion Web control as in Samples #1 and #2. After the check for an installed control has been made, this Sample #3 behaves just like Sample #1.

To test the dynamic checks in this sample, try the following test cases, independently:

  • Unregister (using the regsvr32 utility with the /u option) and rename the Immersion Web control (immweb.ocx), to simulate the situation where a user does not have immweb.ocx installed.
  • Detach your TouchSense device from the USB port, to simulate the situation where a user does not have a TouchSense device attached.

Below is the revised sample code in its entirety. Read the comments to understand what each section does.

' FROM MSDN WEBSITE: http://support.microsoft.com/support/kb/articles/Q174/1/56.ASP

Private Const SW_SHOW = 5       ' Displays Window in its current size
                                ' and position

Private Const SW_SHOWNORMAL = 1 ' Restores Window if Minimized or
                                ' Maximized

Private Declare Function ShellExecute Lib "shell32.dll" Alias _
  "ShellExecuteA" (ByVal hwnd As Long, ByVal lpOperation As _
  String, ByVal lpFile As String, ByVal lpParameters As String, _
  ByVal lpDirectory As String, ByVal nShowCmd As Long) As Long

Private Declare Function FindExecutable Lib "shell32.dll" Alias _
  "FindExecutableA" (ByVal lpFile As String, ByVal lpDirectory As _
  String, ByVal lpResult As String) As Long

'END FROM MSDN WEBSITE

Dim ImmWebControl1 As Object
Dim glngReference As Long

Private Sub Form_Load()

  ' The following line is required to avoid "couldn't make object" errors
  On Error Resume Next

  ' Dynamically create Immersion Web ActiveX Control object
  Set ImmWebControl1 = CreateObject("Immersion.ImmWebControl")

  ' Check if object was created successfully
  ' If not, let user know and give the option to install from the web
  If ImmWebControl1 Is Nothing Then

    Dim Msg, Style, Title, Help, Ctxt, Response, MyString
    Msg = "This program requires the Immersion Web Plugin to run properly." & _
          Chr(13) & Chr(13) & "Would you like to download the Immersion Web Plugin now?" ' Define message.
    Style = vbYesNo + vbExclamation + vbDefaultButton1 ' Define buttons.
    Title = "Immersion Web Plugin Not Found" ' Define title.
    Response = MsgBox(Msg, Style, Title, Help, Ctxt)
    If Response = vbYes Then ' User chose Yes.

      ' Open the Immersion Web ActiveX control download page in a browser
      ' FROM MSDN WEBSITE: http://support.microsoft.com/support/kb/articles/Q174/1/56.ASP
      Dim FileName, Dummy As String
      Dim BrowserExec As String * 255
      Dim RetVal As Long
      Dim FileNumber As Integer
      ' First, create a known, temporary HTML file
      BrowserExec = Space(255)
      FileName = "C:\temphtm.HTM"
      FileNumber = FreeFile ' Get unused file number
      Open FileName For Output As #FileNumber ' Create temp HTML file
      Write #FileNumber, "<HTML> <\HTML>" ' Output text
      Close #FileNumber ' Close file
      ' Then find the application associated with it
      RetVal = FindExecutable(FileName, Dummy, BrowserExec)
      BrowserExec = Trim(BrowserExec)
      ' If an application is found, launch it!
      If RetVal <= 32 Or IsEmpty(BrowserExec) Then ' Error
        MsgBox "Could not find associated Browser", vbExclamation, _
               "Browser Not Found"
      Else
        RetVal = ShellExecute(Me.hwnd, "open", BrowserExec, _
                 "http://www.immersion.com/plugins/install_plugins.html", Dummy, SW_SHOWNORMAL)
        If RetVal <= 32 Then ' Error
          MsgBox "Web Page not Opened", vbExclamation, "URL Failed"
        End If
      End If
      Kill FileName ' delete temp HTML file
    'END FROM MSDN WEBSITE

    End If
    ' If the object wasn't created, there's no point in continuing, so close the app
    Unload Form1
  End If

  If Not (ImmWebControl1 Is Nothing) Then
    ImmForceOn = ImmWebControl1.TouchSenseDeviceAttached()

    If ImmForceOn Then
      ' TouchSenseDeviceAttached() returned true; no worries.
    Else
      MsgBox "You must have an Immersion TouchSense pointing device attached to feel this application."
      ' If a device isn't attached, there's no point in continuing, so close the app
      Unload Form1
    End If

  ' If the object was created and a device is attached, open the
  ' IFR file containing your sensations by calling OpenForceResource().
  glngReference = ImmWebControl1.OpenForceResource(App.Path & "\Hello.ifr")
  End If

End Sub

Private Sub Play_Click()
  If (glngReference >= -1) Then
    success = ImmWebControl1.StartEffect("MyEffect", glngReference)
  End If
End Sub

Back to Index