External Interfaces

Control and Server Events

An event is typically some type of user-initiated action that takes place in a server application and often requires some type of reaction from the client. For example, a user clicking the mouse at a particular location in a server interface window might require that the client take some action in response. When an event is fired, the server communicates this occurrence to the client. If the client is listening to this particular type of event, it responds by executing a routine called an event handler.

The MATLAB client can listen to and respond to events fired by an ActiveX control or COM Automation server. You select which events you want the client to listen to by registering each event you want active along with the event handler to be used in responding to the event. When any registered event takes place in the control or server, the client is notified and responds by executing the appropriate handler routine. Event handlers in MATLAB are often implemented using M-files.

This section covers the following topics on registering and responding to events fired from an ActiveX control or Automation server:

• Functions for Working with Events
• How to Prepare for and Handle Events from a COM Server
• Example -- Responding to Events from an ActiveX Control
• Example -- Responding to Events from an Automation Server

Functions for Working with Events

Use these MATLAB functions to register and unregister events, to list all events, or to list just registered events for a control or server.

Function	Description
actxcontrol	Create a COM control and optionally register those events you want the client to listen to
eventlisteners	Return a list of events attached to listeners
events	List all events, both registered and unregistered, a control or server can generate
isevent	Determine if an item is an event of a COM object
registerevent	Register an event handler with a control or server event
unregisterallevents	Unregister all events for a control or server
unregisterevent	Unregister an event handler with a control or server event

When using these functions, enter event names and event handler names as strings or in a cell array of strings. These names are case insensitive, but cannot be abbreviated.

How to Prepare for and Handle Events from a COM Server

This section describes the basic steps you need to take in handling events fired by a COM control or server:

• Registering Those Events You Want to Respond To
• Identifying All Events and Registered Events
• Responding to Events As They Occur
• Unregistering Events You No Longer Want to Listen To

Registering Those Events You Want to Respond To.   Use the registerevent function to register those server events you want the client to respond to. There are two ways you can register events:

• If you have one function that handles all types of server events, you can register this common event handler to respond to all events fired by that server using the syntax

• h.registerevent('handler');
  

• If you have a separate event handler function for different types of events, you can register each event with its corresponding handler using the syntax

• h.registerevent({'event1' 'handler1'; 'event2' 'handler2'; 
  ...});
  

For ActiveX controls, you can also register events at the time you create the control using the actxcontrol function. This function returns a handle h to the newly created control object:

• To register a common event handler function to respond to all events, use

• h = actxcontrol('progid', position, figure, 'handler');
  

• To register a separate function to handle each type of event, use

• h = actxcontrol('progid', position, figure, ...
     {'event1' 'handler1'; 'event2' 'handler2'; ...});
  

The MATLAB client only listens to those events that you have registered.

Identifying All Events and Registered Events.   Use the events function to list all events the control or server is capable of responding to. This function returns a structure array, where each field of the structure is the name of an event handler and the value of that field contains the signature for the handler routine. To invoke events on an object with handle h, type

• S = h.events
  

The eventlisteners function lists only those events that are currently registered. This function returns a cell array, with each row representing a registered event and the name of its event handler. To invoke eventlisteners on an object with handle h, type

• C = h.eventlisteners
  

Responding to Events As They Occur.   Whenever a control or server fires an event that the client is listening to, the client responds to the event by invoking one or more event handlers that have been registered for that event. You can implement these routines in M-file programs that you write to handle events. Read more about event handlers in the section on Writing Event Handlers.

Unregistering Events You No Longer Want to Listen To.   If you have registered events that you now want the client to ignore, you can unregister them at any time using the functions unregisterevent and unregisterallevents as shown here:

• For a server with handle h, to unregister all events registered with a common event handling function handler, use

• h.unregisterevent('handler');
  

• To unregister individual events eventN, each registered with its own event handling function handlerN, use

• h.unregisterevent({'event1' 'handler1'; 'eventN' 'handlerN'});
  

• To unregister all events from the server regardless of which event handling function they are registered with, use

• h.unregisterallevents;
  

Example -- Responding to Events from an ActiveX Control

This example shows how to handle events fired by an ActiveX control. It uses a control called mwsamp2 that ships with MATLAB. The event handler routines for mwsamp2 are defined when you install MATLAB.

Parts of the example are

• Registering Control Events
• Listing Control Events
• Responding to Control Events
• Unregistering Control Events

Registering Control Events.   The actxcontrol function not only creates the control object, but can be used to register specific events as well. The code shown here registers two events (Click and MouseDown) and two respective handler routines (myclick and mymoused) with the mwsamp2 control.

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

If, at some later time, you want to register additional events, use the registerevent function:

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

You can view the event handler code written for the mwsamp2 control in the section Sample Event Handlers.

Unregister the DblClick event before continuing with the example:

• h.unregisterevent({'DblClick' 'my2click'});
  

Listing Control Events.   At this point, only the Click and MouseDown events should be registered. To see all events that the control can fire, use the events function. This function returns a structure array, where each field of the structure is the name of an event handler and the value of that field contains the signature for the handler routine.

To list all events, whether registered or not, use

• S = h.events
  S = 
           Click: 'void Click()'
        DblClick: 'void DblClick()'
       MouseDown: 'void MouseDown(int16 Button, int16 Shift,
                   Variant x, Variant y)'
      Event_Args: [1x101 char]
  
  S.Event_Args
  ans =
     void Event_Args(int16 typeshort, int32 typelong, 
          double typedouble, string typestring, bool typebool)
  

To list only those events that are currently registered with the control, use the eventlisteners function. This function returns a cell array, with each row representing a registered event and the name of its event handler.

Use eventlisteners to list registered event names and their handler routines:

• h.eventlisteners
  ans = 
      'click'        'myclick' 
      'mousedown'    'mymoused'
  

Responding to Control Events.   When MATLAB creates the mwsamp2 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 see a report in the MATLAB Command Window of the X and Y position of the mouse.

Each time you press the mouse button, the MouseDown event fires, calling the mymoused function. This function prints the position values for that event to the MATLAB Command Window:

• 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 been unregistered.

Unregistering Control Events.   When you unregister an event, the client discontinues listening for occurrences of that event. When the event fires, the client does not respond. 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:

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

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

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

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

• h.eventlisteners
  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 MATLAB 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:

• h.unregisterallevents
  
  h.eventlisteners
  ans = 
       {}
  

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

If you have events that are registered with a common event handling routine, such as sampev.m used in the example below, you can use unregisterevent to unregister all of these events in one operation. The example that follows first registers all events from the server with a common handling routine sampev. MATLAB now handles any type of event from this server by executing sampev:

• h.registerevent('sampev');
  

Verify the registration by listing all event listeners for that server:

• h.eventlisteners
  ans = 
      'click'        'sampev'
      'dblclick'     'sampev'
      'mousedown'    'sampev'
  

Now unregister all events for the server that use the sampev event handling routine:

• h.unregisterevent('sampev');
  h.eventlisteners
  ans = 
       {}
  

Example -- Responding to Events from an Automation Server

The next example shows how to handle events fired by an Automation server. It creates a server running Internet Explorer, registers a common handler for all events, and then has you fire events by browsing to Web sites using the Internet Explorer application.

Parts of the example are

• Registering Server Events
• Listing Server Events
• Responding to Server Events
• Unregistering Server Events
• Closing the Application

Registering Server Events.   This example registers all events fired by an Automation server and, unlike the example above, registers the same handler routine, serverevents, to respond to all types of events. Since this example does not ship with MATLAB, you will have to create the event handler routine yourself. Create the file serverevents.m, inserting this code:

• function serverevents(varargin)
  
  % Display incoming event name
  eventname = varargin{end}
  
  % Display incoming event args
  eventargs = varargin{end-1}
  

Next, in your MATLAB session, use the following commands to create your Automation server application and register this handler routine for all events from the server:

• % Create a server running Internet Explorer.
  h = actxserver('internetexplorer.application');
  
  % Make the server application visible.
  h.set('Visible', 1);
  
  % Register all events from the server with a common event
  % handler routine.
  h.registerevent('serverevents');
  

Listing Server Events.   Use the events function to list all events the control or server is capable of responding to, and eventlisteners to list only those events that are currently registered:

• h = actxserver('internetexplorer.application');
  h.Visible = 1;
  
  h.events
     StatusTextChange = void StatusTextChange(string Text)
     ProgressChange = void ProgressChange(int32 Progress, 
        int32 ProgressMax)
     CommandStateChange = void CommandStateChange(int32 Command,
        bool Enable)
            :
            :
  
  % No events are registered at this time, so eventlisteners 
  % returns an empty cell array.
  h.eventlisteners
  ans = 
       {}
  
  h.registerevent('serverevents');
  h.eventlisteners
  ans = 
      'statustextchange'      'serverevents'
      'progresschange'        'serverevents'
      'commandstatechange'    'serverevents'
               :                     :
               :                     :
  

Responding to Server Events.   At this point, all events have been registered. If any event fires, the common handler routine defined in serverevents.m executes to handle that event. Use the Internet Explorer application to browse your favorite Web site, or enter the following command in the MATLAB Command Window:

• h.Navigate2('http://www.mathworks.com');
  

You should see a long series of events displayed in your client window.

Unregistering Server Events.   Use the unregisterevent function to remove specific events from the registry. Specify each event that you want unregistered along with its handler function in a cell array of strings:

• h.unregisterevent({'event1', 'handler1'; ...
     'event2', 'handler2', ...});
  

If the events were registered with a common handler, as in this example, specify the name of the common routine with each event that you want removed from the event registry for that object:

• h.unregisterevent({'event1', 'commonhandler'; ...
     'event2', 'commonhandler', ...});
  

Continuing with this example, unregister the progresschange and commandstatechange events:

• h.unregisterevent({'progresschange', 'serverevents'; ...
     'commandstatechange', 'serverevents'});
  

To unregister all events for an object, use unregisterallevents. These two commands unregister all the events that had been registered for the Internet Explorer application and then registers only a single event:

• h.unregisterallevents;
  h.registerevent({'TitleChange', 'serverevents'});
  

If you now browse with Internet Explorer, MATLAB only responds to the TitleChange event.

Closing the Application.   It is always advisable to close a server application when you no longer intend to use it. You can unregister all events and close the application used in this example by typing

• h.unregisterallevents;
  h.Quit;
  h.delete;
  

Object Properties

Writing Event Handlers

© 1994-2005 The MathWorks, Inc.