Main Content

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

expand all

Object being created or deleted.

Attributes:

GetAccess
public
SetAccess
private
GetObservable
true
SetObservable
true

Data Types: object

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

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

collapse all

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 

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.

Introduced in R2008a