MATLAB®

The Handle Base Class

Building on the Handle Class

The handle class is an abstract class, which means you cannot create an instance of this class directly. Instead, you use this class as a superclass when you implement your own class. The handle class is the foundation of all classes that are themselves handle classes. When you define a class that is a subclass of handle, you have created a handle class. Therefore, all classes that follow handle semantics are subclasses of the handle class.

Handle Subclasses

There are two subclasses of the handle class that provide additional features when you derive your class from these subclasses:

• hgsetget — Provides set and get methods that enable you to implement a Handle Graphics™ style interface. See Implementing a Set/Get Interface for Properties for information on subclassing hgsetget.

• dynamicprops — Provides the ability to define instance properties. See Dynamic Properties — Adding Properties to an Instance for information on subclassing dynamicprops.

  Deriving from subclasses of the handle class means that your class is a handle class and inherits all the handle class methods, plus the special features provided by these subclasses.

Back to Top

Handle Class Methods

While the handle class defines no properties, it does define the methods discussed in this section. Whenever you create a handle class (i.e., subclass the handle class), your subclass inherits these methods.

You can list the methods of a class by passing the class name to the methods function:

>> methods('handle')

Methods for class handle:

addlistener  findobj      gt           lt           
delete       findprop     isvalid      ne           
eq           ge           le           notify  

Defining Events and Listeners — Syntax and Techniques provides information on how to use the notify and addlistener methods, which are related to the use of events.

Creating Subclasses — Syntax and Techniques provides general information on defining subclasses.

Back to Top

Relational Methods

function TF = eq(H1,H2)
function TF = ne(H1,H2)
function TF = lt(H1,H2)
function TF = le(H1,H2)
function TF = gt(H1,H2)
function TF = ge(H1,H2)

The handle class overloads these functions with implementations that allow for equality tests and sorting on handles. For each pair of input arrays, a logical array of the same size is returned where each element is an element-wise equality or comparison test result. The input arrays must be the same size or one (or both) can be scalar. The method performs scalar expansion as required.

Back to Top

Testing Handle Validity

The isvalid method enables you to determine if you have a valid handle.

function B = isvalid(H)

B is a logical array in which each element is true if, and only if, the corresponding element of H is a valid handle. If H is an array, then B is also an array. If H is not an array of handle objects, then every element in B is false.

Determining If a Handle Belongs to the Handle Class

You can use the isa function to determine if a handle belongs to the class handle, as opposed to being a Sun™ Java™ or Handle Graphics^® handle. For example, suppose you have the following class:

classdef button < handle
   properties
      UiHandle
   end
   methods
      function obj = button(pos))
         obj.UiHandle = uicontrol('Position',pos);
      end 
   end
end

Create a button object

h = button([50 20 50 20]);

The difference between the Handle Graphics object handle, which is stored in the UiHandle property and the handle class handle, h.

>> isa(h,'handle')
ans =
     1

>> isa(h.UiHandle,'handle')
ans =
     0

>> ishandle(h)
ans =
     0

>> ishandle(h.UiHandle)
ans =
     1

Back to Top

Handle Class Delete Methods

The MATLAB^® runtime destroys objects in the workspace of a function when:

• A variable is reassigned to a new value

• A variable is not used in the remainder of a function

• A function ends

When MATLAB destroys an object, values stored in the object's properties are also destroyed and any computer memory associated with the object is returned to MATLAB or the operating system. While you do not need to be concerned with freeing memory in handle classes, there might be other operations that you want to perform when an object is destroyed, such as closing a file or shutting down an external program that was started from the object's constructor function.

Once an object is deleted, any handles to that object in any workspace become invalid, which means they produce an error if an attempt is made to access their contents. Variables previously referencing the deleted value become unassigned and inaccessible.

When to Define a Delete Method for Your Class

You should perform any necessary cleanup operations in a special optional method having the name delete (sometimes called a destructor method). The delete method's signature is,

function delete(h)

where h is a scalar handle.

For example, you might want to close a file that you have opened for writing in your object's delete method. This function calls fclose on a file identifier that is stored in the object's FileID property:

function delete(obj)
   fclose(obj.FileID);
end 

Using Objects to Write Data to a File presents an example that uses this delete method.

Object Lifecycle

The MATLAB runtime invokes the delete method only when an object's lifecycle ends. An object's lifecycle ends when the object is:

• No longer referenced anywhere

• Explicitly deleted by calling delete on the handle

Inside a Function.   The lifecycle of an object referenced by a local variable or input argument is defined to exist from the time the variable is assigned until the time it is reassigned, cleared, or no longer referenced within that function or any handle array. If the variable is not cleared or reassigned, the lifecycle of an object ends sometime between the time its variable is no longer used inside the function and the end of the function. Within the time between a variable's last use and the end of function execution, the MATLAB runtime destroys the object to which the variable refers.

Sequence During Handle Object Destruction

When an object is destroyed (explicitly or because its lifecycle ended), MATLAB invokes the delete methods in the following sequence:

1. The delete method for the object's class

2. The delete method of each base class, starting with the immediate base classes and working up the hierarchy to the most general base classes

MATLAB invokes the delete methods of superclasses at the same level in the hierarchy in the order specified in the class definition. For example, the following class definition specifies supclass1 before supclass2 so the delete function of supclass1 is called before the delete function of supclass2.

classdef myClass < supclass1 < supclass2

Superclass delete methods cannot call methods or access properties belonging to a subclass.

After each delete method has been called, the property values belonging exclusively to the class whose method was just called are destroyed. The destruction of property values that contain other handle objects causes the delete methods for those objects to be called.

Restricting Object Deletion

A class can prevent explicit destruction of objects by setting its delete method's Access attribute to private. An error is issued if you call delete on a handle object whose delete method is private unless the call to delete is made from within one of its own class methods.

Similarly, if the class delete method's Access attribute is set to protected, explicitly deleting objects of that class is allowed only by methods of the class and any subclasses.

Back to Top

Which Kind of Class to Use

Finding Handle Objects and Properties