External Interfaces/API

COM Control Events

Use these MATLAB functions on a control to find out what events the control generates, and to enable or disable handler routines to respond to those events.

Function	Description
eventlisteners	Return a list of events attached to listeners
events	List all events registered for a control
registerevent	Register an event handler with a control's event
unregisterallevents	Unregister all events for a control
unregisterevent	Unregister an event handler with a control's event

COM controls listen to events initiated by users of the control. An example of an event is clicking a mouse button in a window. If a handler routine for the event has been written and registered with the control, then the control responds to the event by executing the event handler routine.

Registering Events with the Control

You can register event handler routines with their associated events either when you create the control, using actxcontrol, or any time afterwards, using the registerevent function.

This example registers two events (Click and MouseDown) and two respective handler routines (myclick and mymoused) with the mwsamp control at the time the control is created. Event handlers for the mwsamp control are defined in the section, Sample Event Handlers:

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

You could have also used the following registerevent call at any time after creating the control:

• registerevent(h, {'Click' 'myclick'; 'MouseDown' 'mymoused'});
  

Listing a Control's Events

Use the events function to list all events the control is capable of responding to. Note that events lists both registered and unregistered events. In this example, the DblClick event is not registered at this time:

• events(h)
     Click = void Click()
     DblClick = void DblClick()
     MouseDown = void MouseDown(int16 Button, int16 Shift, 
        Variant x, Variant y)
  

To list only those events that are currently registered with the control, use the eventlisteners function. This function lists both the event names and their handler routines:

• eventlisteners(h)
  ans = 
      'click'        'myclick' 
      'mousedown'    'mymoused'
  

Firing an Event

When MATLAB creates the mwsamp control, it also displays a figure window showing a label and circle at the center. If you click on different positions in this window, you will see a report of the X and Y position of the mouse in the MATLAB command window. MATLAB is responding to the MouseDown event:

• The X position is: 
  ans = 
      [122]
  The Y position is: 
  ans = 
      [63]
  

You also see the following line reported in response to the Click event:

• Single click function
  

Double-clicking the mouse does nothing different, since the DblClick event has yet to be registered.

Unregistering Events

Use the unregisterevent function to unregister an event handler with an event. For example, if you unregister the MouseDown event, you will notice that MATLAB no longer reports the X and Y position when you click in the window:

• unregisterevent(h, {'MouseDown' 'mymoused'});
  

Now, register the DblClick event, connecting it with handler routine my2click:

• registerevent(h, {'DblClick', 'my2click'});
  

If you call eventlisteners again, you will see that the registered events are now Click and DblClick:

• eventlisteners(h)
  ans = 
      'click'       'myclick' 
      'dblclick'    'my2click'
  

When you double-click the mouse button, MATLAB responds to both the Click and DblClick events by displaying the following in the command window:

• Single click function
  Double click function
  

An easy way to unregister all events for a control is to use the unregisterallevents function. When there are no events registered, eventlisteners returns an empty cell array:

• unregisterallevents(h)
  
  eventlisteners(h)
  ans = 
       {}
  

Clicking the mouse in the control window now does nothing since there are no active events.

Invoking Methods

Identifying Objects