External Interfaces/API

Writing Event Handlers

An event is fired when a control wants to notify its container that something of interest has occurred. For example, many controls trigger an event when the user single-clicks on the control. In MATLAB, you can create and register your own M-file functions so that they respond to events when they occur. These functions serve as event handlers. You can create one handler function to handle all events or a separate handler for each type of event.

Register your handler functions either at the time you create the control (using actxcontrol), or at any time afterwards (using registerevent). Specify the event handler in the argument list, as shown below for actxcontrol. The event handler argument can be either the name of a single callback routine or a cell array that associates specific events with their respective event handlers:

• h = actxcontrol (progid, position, handle, ...
  callback | {event1 eventhandler1; event2 eventhandler2; ...})
  

When you specify the single callback routine, MATLAB registers all events with that one routine. When any event is fired, MATLAB executes the common callback routine.

You can list all the events that a COM object recognizes using the events function. For example, to list all events for the mwsamp control, use

• f = figure ('pos', [100 200 200 200]);
  h = actxcontrol ('mwsamp.mwsampctrl.2', [0 0 200 200], f);
  
  events(h)
     Click = void Click()
     DblClick = void DblClick()
     MouseDown = void MouseDown(int16 Button, int16 Shift, 
        Variant x, Variant y)
  

Arguments Passed to Event Handlers

When a registered event is triggered, MATLAB passes information from the event to its handler function as shown in this table.

Arguments Passed by MATLAB

Arg. No.	Contents	Format
1	Object Name	MATLAB com class
2	Event ID	double
3	Start of Event Arg. List	As passed by the control
end-2	End of Event Arg. List (Arg. N)	As passed by the control
end-1	Event Structure	structure
end	Event Name	char array

When writing an event handler function, use the Event Name argument to identify the source of the event. Get the arguments passed by the control from the Event Argument List (arguments 3 through end-2). All event handlers must accept a variable number of arguments:

• function event (varargin)
  if (varargin{end}) == 'MouseDown')      % Check the event name
      x_pos = varargin{5};              % Read 5th Event Argument
      y_pos = varargin{6};              % Read 6th Event Argument
  end
  

Note    The values passed vary with the particular event and control being used.

Event Structure

The second to last argument passed by MATLAB is the Event Structure, which has the following fields.

Fields of the Event Structure

Field Name	Description	Format
Type	Event Name	char array
Source	Control Name	MATLAB com class
EventID	Event Identifier	double
Event Arg Name 1	Event Arg Value 1	As passed by the control
Event Arg Name 2	Event Arg Value 2	As passed by the control
etc.

For example, when the MouseDown event of the mwsamp control is triggered, MATLAB passes this Event Structure to the registered event handler:

•     Type: 'MouseDown'
    Source: [1x1 COM.mwsamp.mwsampctrl.2]
   EventID: -605
    Button: 1
     Shift: 0
         x: 27
         y: 24
  

Sample Event Handlers

Specify a single callback, sampev:

• f = figure('pos', [100 200 200 200]);
  h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], ...
      gcf, 'sampev')
  h =
      COM.mwsamp.mwsampctrl.2
  

Or specify several events using the cell array format:

• h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], f, ...
      {'Click' 'myclick'; 'DblClick' 'my2click'; ...
      'MouseDown' 'mymoused'});
  

The event handlers, myclick.m, my2click.m, and mymoused.m, are

• function myclick(varargin)
  disp('Single click function')
  
  function my2click(varargin)
  disp('Double click function')
  
  function mymoused(varargin)
  disp('You have reached the mouse down function')
  disp('The X position is: ')
  double(varargin{6})
  disp('The Y position is: ')
  double(varargin{7})
  

Alternatively, you can use the same event handler for all the events you want to monitor using the cell array pairs. Response time will be better than using the callback style.

For example:

• f = figure('pos', [100 200 200 200]);
  h = actxcontrol('mwsamp.mwsampctrl.2', ...
  [0 0 200 200], f, {'Click' 'allevents'; ...
  'DblClick' 'allevents'; 'MouseDown' 'allevents'})
  

where allevents.m is

• function allevents(varargin)
  if (varargin{3} = 'Click')
     disp ('Single Click Event Fired')
  elseif (varargin{3} = 'DblClick')
     disp ('Double Click Event Fired')
  elseif (varargin{3} = 'MouseDown')
     disp ('Mousedown Event Fired')
  end
  

Releasing COM Interfaces and Objects

Examples of MATLAB as an Automation Client