MATLAB Function Reference

unregisterevent - Unregister event handler for COM object event at run-time

Syntax

h.unregisterevent(event_handler) unregisterevent(h, event_handler)

Description

h.unregisterevent(event_handler) unregisters certain event handler routines with their corresponding events. Once you unregister an event, the object no longer responds to any further occurrences of the event.

unregisterevent(h, event_handler) is an alternate syntax for the same operation.

You can unregister events at any time after a control has been created. The event_handler argument, which is a cell array, specifies both events and event handlers. For example:

h.unregisterevent({'event_name',@event_handler});

See "Writing Event Handlers" in the External Interfaces documentation.

You must specify events in the event_handler argument using the names of the events. Strings used in the event_handler argument are not case sensitive. Unlike actxcontrol and registerevent, unregisterevent does not accept numeric event identifiers.

Examples

Control Example

Create an mwsamp control and register all events with the same handler routine, sampev. Use eventlisteners to see the event handler used by each event. In this case, each event, when fired, calls sampev.m:

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

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

Unregister just the dblclick event. Now, when you list the registered events using eventlisteners, dblclick is no longer registered and the control does not respond when you double-click the mouse over it:

h.unregisterevent({'dblclick' 'sampev'});
h.eventlisteners
ans = 
    'click'        'sampev'
    'mousedown'    'sampev'

This time, register the click and dblclick events with a different event handler for myclick and my2click, respectively:

h.unregisterallevents;
h.registerevent({'click' 'myclick'; ...
                 'dblclick' 'my2click'});
h.eventlisteners
ans = 
    'click'       'myclick' 
    'dblclick'    'my2click'

You can unregister these same events by specifying event names and their handler routines in a cell array. eventlisteners now returns an empty cell array, meaning no events are registered for the mwsamp control:

h.unregisterevent({'click' 'myclick'; ...
                   'dblclick' 'my2click'});
h.eventlisteners
ans = 
     {}

In this last example, you could have used unregisterallevents instead:

h.unregisterallevents;

Workbook Events Example

Create a Microsoft^® Excel^® Workbook object:

myApp = actxserver('Excel.Application'); 
wbs = myApp.Workbooks; 
wb = wbs.Add;

wb.registerevent({'Activate' 'EvtActivateHndlr'; ...
                  'Deactivate' 'EvtDeactivateHndlr'})
wb.eventlisteners

MATLAB^® shows the events with the corresponding event handlers.

ans = 

    'Activate'      'EvtActivateHndlr'  
    'Deactivate'    'EvtDeactivateHndlr'

Next, unregister the Deactivate event handler.

wb.unregisterevent({'Deactivate' 'EvtDeactivateHndlr'})
wb.eventlisteners

MATLAB shows the remaining registered event (Activate) with its corresponding event handler.