Listener Callback Syntax

R2026b

Listener callbacks execute when a listener receives notification of an event. When creating a listener with addlistener or listener, pass a function handle referencing the callback as an input argument.

Syntaxes for Listener Callbacks

When you create a listener, you can specify different types of callbacks. For example:

• Function:

  addlistener(eventSourceObj,"EventName",@functionName)

• Ordinary method called with an object of a class:

  addlistener(eventSourceObj,"EventName",@obj.methodName)

• Static method of ClassName:

  addlistener(eventSourceObj,"EventName",@ClassName.methodName)

• Namespace function:

  addlistener(eventSourceObj,"EventName",@nspname.functionName)

Input Arguments for Callback Functions

All callbacks have access to at least two input arguments:

• src — The handle of the object that is the source of the event.

• evnt — An event.EventData object or an object that is derived from the event.EventData class.

Define a callback function to accept both arguments.

function callbackFunction(src,evnt)
   ...
end

The syntax for a callback method is similar, with the addition of the object of the class that defines the method as input.

methods
   function callbackMethod(obj,src,evnt)
      ...
   end
end

If you do not need the information about the event source and event data arguments, you can define the listener and the callback function to ignore these arguments.

addlistener(eventSourceObj,"EventName",@(~,~)callbackFunction)

function callbackFunction
   ...
end

Additional Arguments for Callback Functions

You can pass arguments other than the source and event objects to a callback function. The input arguments must be defined in the context in which you call addlistener.

For example, this example shows the syntax for creating a listener that passes two additional arguments, arg1 and arg2, to the function callbackFunction.

arg1 = 1;
arg2 = 2;
addlistener(src,"EventName",@(src,evnt)callbackFunction(src,evnt,arg1,arg2))

function callbackFunction(src,evnt,arg1,arg2)
   ...
end

Example of a Callback Method

The ClassWithWeakHandleProperty class defines one property, WeakProperty, which is a weak reference to a 1-by-n array of handle objects. The class defines a listener for the ObjectBeingDestroyed event for the object stored in WeakProperty. The callback method, respondToWeakPropertyDestruction, displays a message when that object is destroyed.

classdef ClassWithWeakHandleProperty < handle
    properties (WeakHandle)
        WeakProperty (1,:) handle = matlab.lang.HandlePlaceholder.empty
    end
    methods
        function obj = ClassWithWeakHandleProperty(weakProp)
            if (~isvalid(weakProp))
                error("Input must be a valid handle object.")
            end
            obj.WeakProperty = weakProp;
            addlistener(weakProp,"ObjectBeingDestroyed",@(~,~)obj.respondToWeakPropertyDestruction);
        end
    end
    methods (Access=private)
        function respondToWeakPropertyDestruction(obj)
            disp("WeakProperty destroyed.")
        end
    end
end

Create h, an instance of matlab.lang.HandlePlaceholder, and use it as the argument to the constructor for ClassWithWeakHandleProperty. When you clear h, the ObjectBeingDestroyed event is triggered.

h =  matlab.lang.HandlePlaceholder;
cwhp = ClassWithWeakHandleProperty(h);
clear h

WeakProperty destroyed.