Graphics

Function Handle Callbacks

Handle Graphics objects have a number of properties for which you can define callback functions. When a specific event occurs (e.g., a user clicks on a push button or deletes a figure), the corresponding callback function executes. You can specify the value of a callback property as a

• String that is a MATLAB command or the name of an M-file
• Cell array of strings
• Function handle or a cell array containing a function handle and additional arguments

This section illustrates how to define function handle callbacks for Handle Graphics objects. For information on function handles and how to use them, see the function handle reference page.

Function Handle Syntax

In Handle Graphics, functions that you want to use as function handle callbacks must define at least two input arguments in the function definition:

• The handle of the object generating the callback
• The event data structure (currently empty)

MATLAB passes these two arguments implicitly whenever the callback executes. For example, consider the following statements that are contained in a single M-file.

• function myGui
  % Create a figure and specify a callback
  figure('WindowButtonDownFcn',@myCallback)
              .
              .
              .
  % Callback subfunction header defines two input arguments
  function myCallback(obj,eventdata)
  

The first statement creates a figure and assigns a function handle to its WindowButtondownFcn property (created by using the @ symbol before the function name). This function handle points to the subfunction myCallback. The definition of myCallback must specify the two required input arguments in its function definition line.

Passing Additional Input Arguments

You can define the callback function to accept additional input arguments by adding them to the function definition. For example,

• function myCallback(obj,eventdata,arg1,arg2)
  

When using additional arguments for the callback function, you must set the value of the property to a cell array (i.e., enclose the function handle and arguments in curly braces). For example,

• figure('WindowButtonDownFcn',{@myCallback,arg1,arg2})
  

Defining Callbacks as a Cell Array of Strings -- Special Case

Defining a callback as a cell array of strings is a special case because MATLAB treats it differently from a simple string. Setting a callback property to a string causes MATLAB to evaluate that string in the base workspace when the callback is invoked. However, setting a callback to a cell array of strings behaves as follows:

• The cell array must contain the name of an M-file that is on the MATLAB path as the first string element.
• The M-file callback must define at least two arguments (the handle of the callback object and an empty matrix).
• Any additional strings in the cell array are passed to the M-file callback as arguments.

For example,

• figure('WindowButtonDownFcn',{myCallback,arg1})
  

requires you to define a function M-file that uses three arguments,

• function myCallback(obj,eventdata,arg1)
  

Callback Properties for Graphics Objects

Why Use Function Handle Callbacks