addlistener

Class: handle

Create event listener bound to event source

Syntax

el = addlistener(hSource,EventName,callback)
el = addlistener(hSource,PropertyName,EventName,callback)
addlistener(___)


Description

el = addlistener(hSource,EventName,callback) creates a listener for the event EventName when triggered on the source object, hSource.

If hSource is an array, the listener responds to the named event on any object in the hSource array. callback is a function handle referencing the callback function.

el = addlistener(hSource,PropertyName,EventName,callback) creates a listener for one of the predefined property events. There are four predefined property events.

Event Name	Event Occurs
PreSet	Immediately before the property value is set, before calling its set access method
PostSet	Immediately after the property value is set
PreGet	Immediately before a property value query is serviced, before calling its get access method
PostGet	Immediately after returning the property value to the query

addlistener(___) creates a listener object without a handle. You can use this syntax with any of the previous input syntaxes.

Input Arguments

hSource — Event source

handle array

Event source is the object that is source of the event, or an array of source objects, specified as a handle array.

EventName — Name of event

character vector | string scalar

Name of event that is triggered on the source objects, specified as case-sensitive, quoted text. For property events, the event name is one of the four predefined property events.

Data Types: char | string

PropertyName — Name of property

character vector | string | matlab.metadata.Property object

Name of the property whose property event triggers your listener, specified as one of these values:

• A character vector or a cell array of character vectors, where each character vector is the name of a property defined for the objects in hSource

• A string or a string array, where each string is the name of a property defined for the objects in hSource

• A scalar matlab.metadata.Property object or an array of matlab.metadata.Property objects corresponding to properties defined for the objects in hSource

You can attach listeners to property events on dynamic properties only when hSource is scalar. If hSource is non-scalar, then the properties must belong to the class of hSource and cannot include dynamic properties (which are not part of the class definition).

The class defining the source property must set the GetObservable and SetObservable property attributes to enable you to listen to the property events.

callback — Listener callback

function handle

Listener callback specified as a function handle

Data Types: function_handle

Output Arguments

el — Listener object

event.listener or event.proplistener

Listener object created by addlistener, specified as the handle to an listener or an event.proplistener object.

Examples

Create Listener

Create a property listener for the Color property of a graphics figure window.

fig = figure;
propListener = addlistener(fig,'Color','PostSet',@(src,evnt)disp('Color changed'));

Set the value of the Color property to yellow. Setting the property triggers the PostSet property event on the figure. The event source object is the specific figure referenced by the handle fig.

set(fig,'Color','yellow')

Tips

• Redefining or clearing the variable containing the handle of the listener (for example, el) does not delete the listener. The event object (hSource) still has a reference to the event.listener object. addlistener ties the listener's lifecycle to the object that is the source of the event.

• Although the listener is bound to the lifecycle of the event source, the listener continues to exist after the event source is destroyed when:

  • One or more references to the listener are in other variables, including the handle of the listener if one was specified at creation.

  • The listener is tied to other event sources.

• To remove a listener, delete the listener object returned by addlistener. For example, delete(el) calls the handle class delete method to delete the listener object.

• To define a listener that is not tied to the event object, use the event.listener constructor directly to create the listener.

Alternatives

When you need the lifecycle of the listener object to be independent of the source object lifecycle, use listener to create listeners.

Extended Capabilities

Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

Introduced in R2008a