Learn more about MATLAB

The Handle Superclass

On this page…
Building on the Handle Class Handle Class Methods Relational Methods Testing Handle Validity Handle Class Delete Methods

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. It 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 (that is, 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  

Static Methods:

empty 

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, these functions return a logical array of the same size. 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 whether 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]);

There is a difference between the Handle Graphics object handle (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

If you implement a delete method (the class destructor) for your handle class, MATLAB calls this delete method when destroying the object. MATLAB destroys objects in the workspace of a function when the function:

• Reassigns an object variable to a new value

• Does not use an object variable for the remainder of a function

• The function ends

When MATLAB destroys an object, it also destroys values stored in the properties of the object and returns any computer memory associated with the object to MATLAB or the operating system.

You do not need to free memory in handle classes. However, there can be other operations that you want to perform when destroying an object. For example, closing a file or shutting down an external program that the object constructor started.

Once deleted, any handles to that object in any workspace become invalid. Attempting to access the content of a deleted object produces an error. Variables previously referencing the deleted value become unassigned and inaccessible.

When to Define a Delete Method for Your Class

Perform any necessary cleanup operations in a special optional method having the name delete (sometimes called a destructor method). The delete method signature is,

function delete(h)

where h is a scalar handle.

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

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 the lifecycle of an object ends. The lifecycle of an object 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 exists 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.

A variable goes out of scope when you explicitly cleared it or when its function ends. When a variable goes out of scope, if its value belongs to a class that defines a delete method, MATLAB calls that method. MATLAB defines no ordering among variables in a function. Do not assume that MATLAB destroys one value before another value when the same function contains both values.

Sequence During Handle Object Destruction

MATLAB invokes the delete methods in the following sequence when destroying an object:

1. The delete method for the class of the object

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 as the order specified in the class definition. For example, the following class definition specifies supclass1 before supclass2 so MATLAB calls the delete function of supclass1 before the delete function of supclass2.

classdef myClass < supclass1 & supclass2

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

After calling each delete method, MATLAB destroys the property values belonging exclusively to the class whose method was called. The destruction of property values that contain other handle objects causes MATLAB to call the delete methods for those objects.

Restricting Object Deletion

A class can prevent explicit destruction of objects by setting its delete method Access attribute to private. MATLAB issues an error if you call delete on a handle object whose delete method is private, unless one of its own class methods calls delete.

Similarly, if the class delete method Access attribute has a value of protected, only methods of the class and any subclasses can explicitly delete objects of that class.

Deleting Subclass Objects

Declaring a private delete method does not prevent MATLAB from explicitly destroying subclass objects. A subclass has its own delete method, which can be public, either declared explicitly or provided implicitly by MATLAB. When MATLAB destroys an object, it checks the Access attribute of the delete method of only the direct class of the object. Therefore, a private delete method of a superclass does not prevent the destruction of an object of a subclass.

This behavior differs from the normal behavior of an overridden method. MATLAB executes each delete method of each base class of an object upon destruction, even if that delete method is not public.

Declaring a private delete method probably makes sense only for sealed classes (Sealed attribute set to true). If you design a class that you will subclass, declaring its delete method to be protected prevents objects of all subclasses from destruction by a call to delete from outside the class.

Even when you declare a delete method to be protected, MATLAB calls the delete method of each superclass when destroying the object.

Back to Top

Which Kind of Class to Use

Finding Handle Objects and Properties

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS