The handle class is the superclass for all classes that follow handle semantics. A handle is a reference to an object. If you copy an object's handle, MATLAB copies only the handle and both the original and copy refer to the same object data. If a function modifies a handle object passed as an input argument, the modification affects the original input object.

In contrast, nonhandle objects (that is, value objects) are not references. Functions must return modified value objects to the caller to cause change to the object outside of the function's workspace.

See Modifying Objects for information on passing objects to functions.

Handle object behavior is like that of Handle Graphics objects, where the handle of a graphics object always refers to a particular instance regardless of whether you save the handle when you create the object, store it in another variable, or obtain it with convenience functions like findobj, gca, and so on.

If you want to create a class that defines events, you must derive that class from the handle class.

The handle class is an abstract class, so you cannot create an instance of this class directly. You use the handle class to derive other classes, which can be concrete classes whose instances are handle objects. See Value or Handle Class — Which to Use for information on using handle classes.

Handle Class Methods

When you derive a class from the handle class, your class inherits the following methods.

Method	Purpose
`addlistener`	Creates a listener for the specified event and assigns a callback function to execute when the event occurs.
`notify`	Broadcast a notice that a specific event is occurring on a specified handle object or array of handle objects.
`delete`	Handle object destructor method that is called when the object's lifecycle ends.
`disp`	Handle object `disp` method which is called by the `display` method. See the MATLAB `disp` function.
`display`	Handle object `display` method called when MATLAB software interprets an expression returning a handle object that is not terminated by a semicolon. See the MATLAB `display` function.
`findobj`	Finds objects matching the specified conditions from the input array of handle objects.
`findprop`	Returns a `meta.property` objects associated with the specified property name.
`fields`	Returns a cell array of string containing the names of public properties.
`fieldnames`	Returns a cell array of string containing the names of public properties. See the MATLAB `fieldnames` function.
`isvalid`	Returns a logical array in which elements are true if the corresponding elements in the input array are valid handles. This method is `Sealed` so you cannot override it in a handle subclass.
eq ne lt le gt ge `relationaloperators`	Relational functions return a logical array of the same size as the pair of input handle object arrays. Comparisons use a number associated with each handle. You can assume that the same two handles will compare as equal and the repeated comparison of any two handles will yield the same result in the same MATLAB session. Different handles are always not-equal. The order of handles is purely arbitrary, but consistent.
`ctranspose` `transpose`	Transposes the elements of the handle object array.
`permute`	Rearranges the dimensions of the handle object array. See the MATLAB `permute` function.
`reshape`	Changes the dimensions of the handle object array to the specified dimensions. See the MATLAB `reshape` function.
`sort`	Sort the handle objects in any array in ascending or descending order. The order of handles is purely arbitrary, but reproducible in a given MATLAB session. See the MATLAB `sort` function.

Handle Class Events

The handle class defines one event:

ObjectBeingDestroyed

This event is triggered when the handle object is about to be destroyed. If you define a listener for this event, its callback executes before MATLAB destroys the handle object.

You can add a listener for this event using the addlistener method. See Events and Listeners — Syntax and Techniques for more information on using events and listeners.

You can define a delete method for a handle subclass that MATLAB calls when the object is destroyed. See Handle Class Destructor.

Handle Subclasses

There are two abstract handle subclasses that you can use to derive handle classes:

hgsetget – use when you want to create a handle class that inherits set and get methods having the same behavior as Handle Graphics set and get functions.
dynamicprops – use when you want to create a handle class that allows you to add instance data (dynamically defined properties) to objects.
matlab.mixin.Copyable – use to add a copy method to a handle subclass.

Useful Functions

properties — list the class public properties
methods — list the class methods
events — list the events defined by the class

Note that ishandle does not test for handle class objects. Use isa instead.

Free MATLAB Interactive Kit

Explore how to use MATLAB to make advancements in engineering and science.

Download free kit

Trials Available

Try the latest version of MATLAB and other MathWorks products.

Get trial software