MATLAB COM Builder

Adding Events to COM Builder Objects

MATLAB COM Builder supports events, or callbacks, through a simple MATLAB language pragma. You simply provide a MATLAB function stub that serves as the prototype for the event, and then provide an implementation of the function in your client code (Visual Basic, C++, etc.). The net effect is that when any other MATLAB function calls the event function, the call is dispatched to the "event handler" in the client code.

You can turn a MATLAB function into an event function by placing a %#event pragma into the code. MATLAB interprets this statement as a comment. When you include the same function as a method on a COM Builder object, the compiler generates an "outgoing interface" for the method, which identifies the method as an event. This outgoing interface is then implemented by the client code. Some examples of how you might use callbacks in your code are

• To give a client application periodic feedback during a long-running calculation. For example, if you have a task that requires n iterations, you might signal an event to increment a progress bar in the user interface on each iteration.
• ·To signal a warning during a calculation but continue execution of the task.
• To return intermediate results of a calculation to the user and continue execution of the task.

The next example illustrates using a callback in conjunction with a Visual Basic ProgressBar control. The MATLAB function iterate runs through n iterations and fires an event every inc iterations. When the function ends, it returns a single output. To simulate actually doing something, place a pause statement in the main loop so that the function waits for 1 second in each iteration.

Consider the MATLAB functions iterate.m and progress.m.

iterate.m

• function [x] = iterate(n,inc)
      %initialize x
      x = 0;
      % Run n iterations, callback every inc time
      k = 0;
      for i=1:n
          k = k + 1;
          if k == inc
              progress(i);
              k = 0;
          end;
          % Do some work on x...
          x = x + 1;
          % We will just pause for 1 second to simulate doing 
          % something
          pause(1);
      end;
  

progess.m

• function progress(i)
      %#event
      i
  

The iterate function runs through n iterations and calls the progress function every inc iterations, passing the current iteration number as an argument. When this function is executed in MATLAB, the value of i is displayed each time the progress function gets called. Suppose you create a COM Builder component that has these two functions included as class methods. This example assumes a component with a single class named myclass. The resulting COM class has a method iterate and an event progress. To receive the event calls implement a "listener" in your Visual Basic code. The VB syntax for the event handler needed for this example is

• Sub aClass_progress(ByVal i As Variant)
  

where aClass is the variable name used for your class instance. The ByVal qualifier is used on all input parameters of an event function. To enable the listening process, dimension the aClass variable with the WithEvents keyword. Refer to the Visual Basic documentation for a complete discussion of VB event processing.

This example is based on a simple VB form with three TextBox controls, one CommandButton control, and one ProgressBar control. The first text box, Text1, inputs the number of iterations, stored in the form variable N. The second text box, Text2, inputs the callback increment, stored in the variable Inc. The third text box, Text3, displays the output of the function when it finishes executing. The command button, Command1, executes the iterate method on your class when pressed. The progress bar control, ProgressBar1, updates itself in response to the progress event.

• 'Form Variables
  Private WithEvents aClass As myclass    'Class instance
  Private N As Long                       'Number of iterations
  Private Inc As Long                     'Callback increment
  Private Sub Form_Load()
  'When form is loaded, create new myclass instance
      Set aClass = New myclass
      'Initialize variables
      N = 2
      Inc = 1
  End Sub
  Private Sub Text1_Change()
  'Update value of N from Text1 text whenever it changes
      On Error Resume Next
      N = CLng(Text1.Text)
      If Err <> 0 Then N = 2
      If N < 2 Then N = 2
  End Sub
  Private Sub Text2_Change()
  'Update value of Inc from Text2 text whenever it changes
      On Error Resume Next
      Inc = CLng(Text2.Text)
      If Err <> 0 Then Inc = 1
      If Inc <= 0 Then Inc = 1
  End Sub
  Private Sub Command1_Click()
  'Execute function whenever Execute button is clicked
      Dim x As Variant
      On Error GoTo Handle_Error
      'Initialize ProgressBar
      ProgressBar1.Min = 1
      ProgressBar1.Max = N
      Text3.Text = ""
      'Iterate N times and call back at Inc intervals
      Call aClass.iterate(1, x, CDbl(N), CDbl(Inc))
      Text3.Text = Format(x)
      Exit Sub
  Handle_Error:
      MsgBox (Err.Description)
  End Sub
  Private Sub aClass_progress(ByVal i As Variant)
  'Event handler. Called each time the iterate function
  'calls the progress function. Progress bar is updated
  'with the value passed in, causing the control to advance.
      ProgressBar1.Value = i
  End Sub
  

Adding Class Properties to COM Builder Objects

Creating an Instance of a Class