handle class

Superclass of all handle classes

Description

The handle class is the superclass for all classes that follow handle semantics. A handle is a variable that refers to an object of a handle class. Multiple variables can refer to the same object.

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.

To define a handle class, derive your class from handle using the syntax in the following classdef code.

classdef MyHandleClass < handle
    ...
end

Deriving from the handle class enables your subclass to:

• Inherit several useful methods (Handle Class Methods)

• Define events and listeners (Events and Listeners Syntax)

• Define dynamic properties (Dynamic Properties — Adding Properties to an Instance)

• Implement set and get methods (Implement Set/Get Interface for Properties)

• Customize copy behavior (Implement Copy for Handle Classes)

For information about using handle classes, see Handle Classes

Class Attributes

Abstract	true
ConstructOnLoad	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Methods

Public Methods

addlistener	Create event listener bound to event source
listener	Create event listener without binding to event source
notify	Notify listeners that event is occurring
findobj	Find handle objects
findprop	Find meta.property object
delete	Delete handle object
isvalid	Determine valid handles
relationaloperators	Determine equality or sort handle objects
empty	Create empty array of specified class

Events

Event Name	Trigger	Event Data	Event Attributes
ObjectBeingDestroyed	Triggered when the handle object is about to be destroyed, but before calling the delete method.	event.EventData	NotifyAccess: private ListenAccess: public

Examples

Derive Class from handle

The MySubclass class derives from the handle class. The property set method does not return the object passed to the method, as is required by a value class:

classdef MySubclass < handle
   properties
      Client tcpclient
   end
   methods
      function set.Client(obj,c)
         if isa(c,'tcpclient')
            obj.Client = c;
         end
      end
   end
end

Create an object of MySubclass and assign a tcpclient object to the Client property.

t = MySubclass;
t.Client = tcpclient('www.mathworks.com', 80);

More About

Handle Object Copy Behavior

Copying a handle object does not copy the underlying data associated with the object. The copy is another handle referring to the same object. Therefore, if a function modifies a handle object passed as an input argument, the modification affects the original input object in the caller's workspace.

In contrast, nonhandle objects (that is, value objects) associate data with a particular variable. Functions must return modified value objects to change the object outside of the function's workspace.

For information on passing objects to functions, see Object Modification and Handle Object Behavior.

Destroying Handle Objects

MATLAB^® destroys handle objects when there are no references to the object. You can explicitly remove a handle object by calling its delete method. The handle class enables you to control what happens when handle objects are destroyed, either implicitly when no references exist or explicitly when you delete the object.

For more information, see Handle Class Destructor.

Create Listener for ObjectBeingDestroyed Event

Any code can respond to the pending deletion of a handle object by defining a listener for that object’s ObjectBeingDestroyed event. MATLAB triggers this event before calling the object’s delete method.

For more information on using events and listeners, see Events and Listeners Syntax.

Version History

Introduced in R2008a