MATLAB®

Events and Listeners — Concepts

The Event Model

Events represent changes or actions that occur within class instances. For example,

• Modification of class data

• Execution of a method

• Querying or setting a property value

• Destruction of an object

Basically, any activity that can be detected programmatically can generate an event and communicate information to other objects.

MATLAB^® classes define a process that communicates the occurrence of events to other objects that need to respond to the events. The event model works this way:

• A handle class declares a name used to represent an event. Naming Events

• After an instance of the event-declaring class is created, you can attach listener objects to it. Creating Listeners

• A class method call broadcasts a notice of the event to listeners and the class user is responsible for determining when to declare that the event has occurred. Triggering Events

• Listeners execute a callback function when notified that the event has occurred. Defining Listener Callback Functions

• Listeners can be bound to the lifecycle of the object that defines the event or limited to the existence and scope of a listener object. Creating Listeners

The following diagram illustrates the event model.

Back to Top

Default Event Data

Events provide information to listener callbacks by passing an event data argument to the callback function. By default, the MATLAB runtime passes an event.EventData object to the listener callback. This object has two properties:

• EventName — The event name as defined in the class event block

• Source — The object that is the source of the event

Customizing Event Data

You can create a subclass of the event.EventData class to provide additional information to listener callback functions. The subclass would define properties to contain the additional data and provide a method to construct the derived event data object so it can be passed to the notify method.

Defining Event-Specific Data provides an example showing how to customize this data.

Back to Top

Events Only in Handle Classes

You can define events only in handle classes. This is because a value class is visible only in a single MATLAB workspace so no callback or listener can have access to the object that triggered the event. The callback could have access to a copy of the object, but this is not generally useful since it cannot access the current state of the object that triggered the event or effect any changes in that object.

Comparing Handle and Value Classes provides general information on handle classes.

Defining Events and Listeners — Syntax and Techniques shows the syntax for defining a handle class and events.

Back to Top

Property-Set and Query Events

There are four predefined events related to properties:

• PreSet — Triggered just before the property value is set, before calling its set access method

• PostSet — Triggered just after the property value is set

• PreGet — Triggered just before a property value query is serviced, before calling its get access method

• PostGet — Triggered just after returning the property value to the query

These events are triggered by the property objects and, therefore, are not defined in the class's event block.

When a property event occurs, the callback is passed an event.PropertyEvent object. This object has three properties:

• EventName — The name of the event described by this data object

• Source — The source object whose class defines the event described by the data object

• AffectedObject — The object whose property is the source for this event

This object has one property, AffectedObject, that contains the object whose property is the source for this event. (i.e., AffectedObject is the object whose property was either accessed or modified.)

You can define your own property-change event data by subclassing the event.EventData class. Note that the event.PropertyEvent class is a sealed subclass of event.EventData.

See Listening for Changes to Property Values for a description of the process for creating property listeners.

See Implementing the PostSet Property Event and Listener for an example.

See Controlling Property Access for information on methods that control access to property values.

Back to Top

Listeners

Listeners encapsulate the response to an event. Listener objects belong to the event.listener class, which is a handle class that defines the following properties:

• Source — Handle or array of handles of the object that generated the event

• EventName — Name of the event

• Callback — Function to execute with an enabled listener receives event notification

• Enabled — Callback function executes only when Enabled is true. See Enabling and Disabling the Listeners for an example.

• Recursive — Can listener cause same event that triggered the execution of the callback

  Recursive is true by default. It is possible create a situation where infinite recursion reaches the recursion limit and eventually triggers an error. If you set Recursive to false, the listener cannot execute recursively if the callback triggers its own event.

Creating Listeners provides more specific information.

Listener Order of Execution

The order in which listeners execute after the firing of an event is undefined. However, all listener callbacks execute synchronously with the event firing.

Back to Top

Events — Sending and Responding to Messages

Event Attributes