handle

Abstract class for deriving handle classes

Syntax

classdef MyHandleClass < handle

Description

classdef MyHandleClass < handle makes MyHandleClass a subclass of the handle class.

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 Handle Classes for information on using handle classes.

Handle Class Methods

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

MethodPurpose

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.

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.

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
Relational Operators

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.

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

You can use the following abstract handle subclasses to derive more specialized handle classes:

  • matlab.mixin.SetGet – use when you want to create a handle class that inherits set and get methods having the same behavior as the MATLAB 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.

Was this topic helpful?