event.ClassInstanceEvent class

Package: event
Superclasses: event.EventData

Event data for InstanceCreated and InstanceDestroyed events

Description

This class defines the event data that is passed to listeners of the meta.class InstanceCreated and InstanceDestroyed events.

The event.ClassInstanceEvent class is a handle class.

Class Attributes

Sealed	true
ConstructOnLoad	true
HandleCompatible	true
RestrictsSubclassing	true

For information on class attributes, see Class Attributes.

Creation

MATLAB^® creates an event.ClassInstanceEvent object when triggering a InstanceCreated or InstanceDestroyed event.

Properties

Instance — Object being created or deleted

object

Object being created or deleted.

Attributes:

GetAccess	public
SetAccess	private
GetObservable	true
SetObservable	true

Data Types: object

Source — meta.class object that is the source of the event

meta.class

meta.class object that is the source of the event, returned as a meta.class object.

Attributes:

GetAccess	public
SetAccess	private
GetObservable	true
SetObservable	true

Data Types: meta.class

EventName — Name of the event

character vector

Name of the event, returned as a character vector that is either InstanceCreated or InstanceDestroyed.

Attributes:

GetAccess	public
SetAccess	private
GetObservable	true
SetObservable	true

Data Types: char

Examples

Count Number of Instances

Use meta.class events to count the number of instances as objects are created and destroyed.

Create a class with a callback function for the InstanceCreated and InstanceDestroyed events. The eventCallback static method uses a persistent variable to store the number of instances of the class that exist. The addEventListeners method adds the listeners to the meta.class object for the CountInstances class.

classdef CountInstances
    methods (Static)
        function eventCallback(~,eventData)
            % Callback for InstanceCreated and InstanceDestroyed
            persistent instanceCount
            if ~isempty(instanceCount)
                switch eventData.EventName
                    case "InstanceCreated"
                        instanceCount = instanceCount + 1;
                    case "InstanceDestroyed"
                        if ~instanceCount == 0
                            instanceCount = instanceCount - 1;
                        end
                end
            else
                instanceCount = 1;
            end
            fprintf('%s %d \n',...
                'Number of Instances: ',instanceCount)
        end
        function addEventListeners(mc)
            % Add listeners
            addlistener(mc,"InstanceCreated",...
                @(src,evnt)CountInstances.eventCallback(src,evnt));
            addlistener(mc,"InstanceDestroyed",...
                @(src,evnt)CountInstances.eventCallback(src,evnt));
        end
    end
end

Create a meta.class object for the CountInstances class and add listeners for the InstanceCreated and InstanceDestroyed events. This example uses the same callback for both events.

mc = ?CountInstances;
CountInstances.addEventListeners(mc)

Whenever you create or destroy an object of the CountInstances class, the event causes an update to the instanceCount persistent variable.

obj1 = CountInstances;

Number of Instances:  1

obj2 = CountInstances;

Number of Instances:  2 

clear obj1

Number of Instances:  1 

Observe Creation and Destruction Events

Use meta.class events to observe the creation and destruction of objects

Create a class with a callback function for the InstanceCreated and InstanceDestroyed events. The eventCallback static method serves as the callback function for both events. The addEventListeners method adds the listeners to the meta.class object for the ClassInstanceEvent class.

classdef ClassInstanceListeners
    properties
        Prop
    end
    methods
        function obj = ClassInstanceListeners(p)
            obj.Prop = p;
        end
    end
    methods (Static)
        function eventCallback(~,eventData)
            % Callback for InstanceCreated and InstanceDestroyed
            I = eventData.Instance;
            S = eventData.Source;
            E = eventData.EventName;
            dashLine = sprintf('%s\n','--------------------');
            fprintf('%s',dashLine)
            fprintf('%s \n',['Class: ',class(I)])
            fprintf('%s %d \n',[S.PropertyList.Name ': '],I.Prop)
            fprintf('%s%s \n','Event: ', E)
            fprintf('%s',dashLine)
        end
        function addEventListeners(mc)
            % Add listeners
            addlistener(mc,"InstanceCreated",...
                @(src,evnt)ClassInstanceListeners.eventCallback(src,evnt));
            addlistener(mc,"InstanceDestroyed",...
                @(src,evnt)ClassInstanceListeners.eventCallback(src,evnt));
        end
    end
end

Create a meta.class object for the CreateInstanceListeners class and add listeners for the InstanceCreated and InstanceDestroyed events. This example uses the same callback for both events. Construct an instance of the CreateInstanceListeners class and assign an identifier to the property Prop.

mc = ?ClassInstanceListeners;
ClassInstanceListeners.addEventListeners(mc)
obj = ClassInstanceListeners(1334);

--------------------
Class: ClassInstanceListeners 
Prop:  1334 
Event: InstanceCreated 
--------------------

Constructing another instance that is assigned to the same variable creates a new object and destroys the old object.

obj = ClassInstanceListeners(7335);

--------------------
Class: ClassInstanceListeners 
Prop:  7335 
Event: InstanceCreated 
--------------------
--------------------
Class: ClassInstanceListeners 
Prop:  1334 
Event: InstanceDestroyed 
--------------------

If you modify the class definition, MATLAB deletes the meta.class object because it is no longer a valid description of the class. After modifying the class, you must create a new meta.class object and add listeners to it.