Documentation Center

  • Trial Software
  • Product Updates

Handle Objects

What Is a Handle Object?

Certain kinds of MATLAB® objects are handles. When a variable holds a handle, it actually holds a reference to the object.

Handle objects enable more than one variable to refer to the same information. Handle-object behavior affects what happens when you copy handle objects and when you pass them to functions.

Copying Handles

All copies of a handle object variable refer to the same underlying object. This means that if h identifies a handle object, then,

h2 = h;

Creates another variable, h2, that refers to the same object as h.

For example, the MATLAB audioplayer function creates a handle object that contains the audio source data to reproduce a specific sound segment. The variable returned by the audioplayer function identifies the audio data and enables you to access object functions to play the audio.

MATLAB software includes audio data that you can load and use to create an audioplayer object. This sample load audio data, creates the audio player, and plays the audio:

load gong Fs y
gongSound = audioplayer(y,Fs);
play(gongSound)

Suppose you copy the gongSound object handle to another variable (gongSound2):

gongSound2 = gongSound;

The variables gongSound and gongSound2 are copies of the same handle and, therefore, refer to the same audio source. Access the audioplayer information using either variable.

For example, set the sample rate for the gong audio source by assigning a new value to the SampleRate property. First get the current sample rate and then set a new sample rate:

sr = gongSound.SampleRate

sr =

        8192
gongSound.SampleRate = sr*2;

You can use gongSound2 to access the same audio source:

gongSound2.SampleRate

ans =

        16384

Play the gong sound with the new sample rate:

play(gongSound2)

Modifying Handle Objects in Functions

When you pass an argument to a function, the function copies the variable from the workspace in which you call the function into the parameter variable in the function's workspace.

Passing an ordinary (nonhandle) variable to a function does not affect the original variable. For example, myFunc modifies a local variable called var, but when the function ends, the local variable var no longer exists:

function myFunc(var)
   var = var + 1;
end

Define a variable and pass it to myfunc:

x = 12;
myFunc(x)

The value of x has not changed after executing myFunc(x):

x

x =

        12

The myFunc function can return the modified value, which you could assign to the same variable name (x) or another variable.

function out = myFunc(var)
   out = var + 1;
end

Modify a value in myfunc:

x = 12;
x = myFunc(x)
x

ans =

        13

When the argument is a handle variable, the function copies only the handle, not the object identified by that handle. Both handles (original and local copy) refer to the same object.

When the function modifies the data referred to by the object handle, those changes are accessible from the handle variable in the calling workspace without the need to return the modified object.

For example, the modifySampleRate function changes the audioplayer sample rate:

function modifySampleRate(audioObj,sr)
   audioObj.SampleRate = sr;
end

Create an audioplayer object and pass it to the modifySampleRate function:

load gong Fs y
gongSound = audioplayer(y,Fs);
gongSound.SampleRate

ans =

       8192

modifySampleRate(gongSound,16384)
gongSound.SampleRate

ans =

       16384

The modifySampleRate function does not need to return a modified gongSound object because audioplayer objects are handle objects.

How to Know if an Object Is a Handle

Handle objects are members of the handle class. Therefore, you can always identify an object as a handle using the isa function. isa returns logical true (1) when testing for a handle variable:

load gong Fs y00
gongSound = audioplayer(y,Fs);
isa(gongSound,'handle')

ans =

     1

To determine if a variable is a valid handle object, use isa and isvalid:

if isa(gongSound,'handle') && isvalid(gongSound)
   ...
end

Deleted Handle Objects

When a handle object has been deleted, the handle variables that referenced the object can still exist. These variables become invalid because the object they referred to no longer exists. Calling delete on the object removes the object, but does not clear handle variables.

For example, create an audioplayer object:

load gong Fs y
gongSound = audioplayer(y,Fs);

The output argument, gongSound, is a handle variable. Calling delete deletes the object along with the audio source information it contains:

delete(gongSound)

However, the handle variable still exists:

gongSound

gongSound = 

  handle to deleted audioplayer

The whos command shows gongSound as an audioplayer object:

whos
  Name               Size             Bytes  Class          Attributes

  Fs                 1x1                  8  double                   
  gongSound          1x1                104  audioplayer              
  y              42028x1             336224  double      

The handle gongSound no longer refers to a valid object:

isvalid(gongSound)

ans =

     0

You cannot call functions on the invalid handle variable:

play(gongSound)
Invalid or deleted object.

You cannot access properties with the invalid handle variable:

gongSound.SampleRate
Invalid or deleted object.

To remove the variable, gongSound, use clear:

clear gongSound
whos
  Name          Size             Bytes  Class     Attributes

  Fs            1x1                  8  double              
  y         42028x1             336224  double   
Was this topic helpful?