External Interfaces

Writing Event Handlers

This section covers the following topics on writing handler routines to respond to events fired from an ActiveX control or Automation server:

• Overview of Event Handling
• Arguments Passed to Event Handlers
• Event Structure
• Sample Event Handlers
• Writing Event Handlers Using M-File Subfunctions

Overview of Event Handling

An event is fired when a control or server wants to notify its client that something of interest has occurred. For example, many controls trigger an event when the user clicks somewhere in the interface window of a 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.

For controls, you can register your handler functions either at the time you create the control (using actxcontrol), or at any time afterwards (using registerevent). For servers, you must use the registerevent function to register those events you want the client to listen to. 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 mwsamp2 control, use

• f = figure ('position', [100 200 200 200]);
  h = actxcontrol ('mwsamp.mwsampctrl.2', [0 0 200 200], f);
  
  h.events
     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.	Event Arg N	As passed by the control

For example, when the MouseDown event of the mwsamp2 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('position', [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('position', [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 (strcmp(varargin{3}.Type, 'Click'))
     disp ('Single Click Event Fired')
  elseif (strcmp(varargin{3}.Type, 'DblClick'))
     disp ('Double Click Event Fired')
  elseif (strcmp(varargin{3}.Type, 'MouseDown'))
     disp ('Mousedown Event Fired')
  end
  

Writing Event Handlers Using M-File Subfunctions

Instead of having to maintain a separate M-file for every event handler routine you write, you can consolidate some or all of these routines into a single M-file using M-file subfunctions.

This example shows three event handler routines, (myclick, my2click, and mymoused) implemented as subfunctions in the file mycallbacks.m. The call to str2func converts the input string to a function handle:

• function a = mycallbacks(str) 
  a = str2func(str);
  
  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})
  

To register one of these events, you just call mycallbacks, passing the name of the event handler:

• h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], ...
      gcf, 'sampev')
  h.registerevent('Click', mycallbacks('myclick'));
  

Control and Server Events

Saving Your Work

© 1994-2005 The MathWorks, Inc.