Documentation

The Handle Superclass

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:

  • matlab.mixin.SetGet — Provides set and get methods to access property values. See Implementing a Set/Get Interface for Properties for information on subclassing matlab.mixin.SetGet.

  • 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.

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  

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.

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.

Testing Handle Validity

Use the isvalid handle class method to determine if you have a valid handle object. For example, in this statement:

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. B is always the same size as H.

Handle Class or Graphics Object Handle

Use the isa function to determine if a handle is of class handle, or is a Java® or Handle Graphics® handle. For example, consider the button class, which derives from the handle class:

classdef button < handle
   properties
      UiHandle
   end
   methods
      function obj = button(pos)
         if nargin > 0
            if length(pos) == 4
               obj.UiHandle = uicontrol('Position',pos,'Style','pushbutton');
            else
               error('Improper position')
            end 
         end 
      end 
   end
end

Create a button object by passing a position vector to the button constructor:

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

Determine the difference between the graphics object handle (stored in the UiHandle property) and the handle class object, h. Use ishandle to test the validity of Handle Graphics object handles:

% h is a handle object
>> isa(h,'handle')
ans =
     1

% The uicontrol object handle is not a handle object
>> isa(h.UiHandle,'handle')
ans =
     0

% The button object is not a graphics object
>> ishandle(h)
ans =
     0

% The uicontrol is a graphics object handle
>> ishandle(h.UiHandle)
ans =
     1

If you close the figure, the ishandle function determines that the Handle Graphics handle is not valid:

>> close
>> ishandle(h.UiHandle)

ans =

     0

h is still of class handle and is still a valid handle object:

>> isa(h,'handle')

ans =

     1
>> isvalid(h)

ans =

     1

h is also of class button:

>> isa(h,'button')

ans =

     1

When MATLAB Destroys Objects

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

  • Function execution 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. You can define a delete method in your handle subclass for these purposes.

See Handle Class Destructor for more information.

Was this topic helpful?