Documentation

addlistener

Class: handle

Create event listener

Syntax

lh = addlistener(Hsource,EventName,callback)
lh = addlistener(Hsource,property,EventName,callback)

Description

lh = addlistener(Hsource,EventName,callback) creates a listener for the specified event when triggered on the source object.

If Hsource is not scalar, the listener responds to the named event on any object in the Hsource array.

lh = addlistener(Hsource,property,EventName,callback) creates a listener for one of the predefined property events. There are four predefined property events:

Event NameEvent 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

Tips

  • To remove a listener, delete the listener object returned by addlistener. For example,

    delete(lh)

    calls the handle class delete method to delete the object from the workspace and remove the listener.

  • Redefining or clearing the variable containing the handle of the listener (for example, lh) 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.

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

Input Arguments

collapse all

Hsource — Event sourcehandle 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 eventcharacter array

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

property — Name of propertystring

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

  • A scalar meta.property object

  • An array or a cell array of meta.property objects

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

    You can listen to property events on dynamic properties only If Hsource is scalar. If Hsource is non-scalar, then the properties must belong to the class of Hsource and can not 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 callbackfunction handle

Listener callback specified as a function handle

Data Types: function_handle

Output Arguments

collapse all

lh — listenerevent.listener or event.proplistener

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

Attributes

Accesspublic

To learn about attributes of methods, see Method Attributes in the MATLAB® Object-Oriented Programming documentation.

Alternatives

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

Was this topic helpful?