MATLAB®

Callback Syntax and Arguments

Callback Templates

GUIDE defines conventions for callback syntax and arguments and implements these conventions in the callback templates it adds to the M-file. Each template is similar to this one for the Callback subfunction for a push button.

% --- Executes on button press in pushbutton1.
function pushbutton1_Callback(hObject, eventdata, handles)
% hObject    handle to pushbutton1 (see GCBO)
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)

...

The first comment line describes the event that triggers execution of the callback. This is followed by the function definition line. The remaining comments describe the input arguments. Insert your code after the last comment.

Certain figure and GUI component callbacks provide event-specific data in the eventdata argument. As an example, this is the template for a push button KeyPressFcn callback.

% --- Executes on key press with focus on pushbutton1
function pushbutton1_KeyPressFcn(hObject, eventdata, handles)
% hObject    handle to pushbutton1 (see GCBO)
% eventdata  structure with the following fields (see UICONTROL)
%	 Key: name of the key that was pressed, in lower case
%	 Character: character interpretation of the key(s) that was pressed
%	 Modifier: name(s) of the modifier key(s)(i.e., control, shift) 
% pressed
% handles structure with handles and user data (see GUIDATA)

Callbacks that provide event data and the components to which they apply are listed in the following table. See the appropriate property reference pages for detailed information.

Note   You can avoid automatic generation of the callback comment lines for new callbacks. In the Preferences dialog box, select GUIDE and uncheck Add comments for newly generated callback functions.

Back to Top

Naming of Callback Functions

The previous callback example includes the following function definition:

function pushbutton1_Callback(hObject,eventdata,handles)

When GUIDE generates the template, it creates the callback name by appending an underscore (_) and the name of the callback property to the component's Tag property. In the example above, pushbutton1 is the Tag property for the push button, and Callback is one of the push button's callback properties. The Tag property uniquely identifies a component within the GUI.

The first time you save the GUI after adding a component, GUIDE adds callbacks for that component to the M-file and generates the callback names using the current value of the Tag property. If you change the default Tag for any component, make sure you have not duplicated any other component's Tag value before you save your GUI. GUIDE issues a warning if it determines that duplicate tags exist.

See Changing Callbacks Assigned by GUIDE and Associating Callbacks with Components for more information.

Callback Function Signatures

A function signature itemizes a function's name, the number, order, and types of its parameters, and any qualifiers that apply to the function. When you use the Property Inspector to view a component of a GUI that you have saved at least once, you see that its Callback property is already set. When GUIDE saves a GUI, it

• Generates a callback signature and assigns it as the value of the Callback property

• Adds to the GUI M-file a template for the function to which the signature point

The component may have other callbacks, for example a CreateFcn or a DeleteFcn, which GUIDE populates the same way. It is up to you to add code to the template to make a callback do something.

For example, if you click the pencil-and-paper icon for a push button's Callback property in the Property Inspector, GUIDE presents the GUI's M-file in the MATLAB Editor and positions the cursor at the first line of the callback. When GUIDE defines the function in the M-file as:

function pushbutton1_Callback(hObject, eventdata, handles)

then the function signature for the Callback property, shown in the Property Inspector, is

@(hObject,eventdata)mygui('pushbutton1_Callback',hObject,eventdata,guidata(hObject))

The syntax @(hObject,eventdata) indicates that this is an anonymous function. The signature enables MATLAB to execute the right callback when the user clicks this push button by providing the following information.

• The name of the M-file in which the callback function resides ('mygui')

• The name of the callback function within the M-file ('pushbutton1_Callback')

• The argument list to pass to the callback function:

  1. hObject — The handle of the component issuing the callback (a push button, in this case)

  2. eventdata — A structure containing event data generated by the component (for push buttons and other components that generate no event data, this argument contains an empty matrix)

  3. guidata(hObject) — The handles Structure for the GUI, used to communicate component handles between callbacks

The following figure illustrates how these elements relate to one another.

See Input Arguments for details about GUIDE-generated callbacks.

Back to Top

Changing Callbacks Assigned by GUIDE

As described in Naming of Callback Functions, GUIDE generates a name for a callback by concatenates the component's Tag property (checkbox1) and its callback type. Although you cannot change a callback's type, you can change its Tag, which will change the callback's name the next time you save the GUI.

Change a component's Tag property to give its callbacks more meaningful names; for example, you might change the Tag property from checkbox1 to warnbeforesave. If possible, change the Tag property before saving the GUI to cause GUIDE to automatically create callback templates having names you prefer. However, if you decide to change a Tag property after saving the GUI, GUIDE updates the following items according to the new Tag, provided that all components have distinct tags:

• The component's callback functions in the M-file

• The value of the component's callback properties, which you can view in the Property Inspector

• References in the M-file to the field of the handles structure that contains the component's handle. See handles Structure for more information about the handles structure.

To rename a particular callback function without changing the Tag property,

• In the Property Inspector, replace the name string in the callback property with the new name. For example, if the value of the callback property for a push button in mygui is

  mygui('pushbutton1_Callback',hObject,eventdata,guidata(hObject))

  the string pushbutton1_Callback is the name of the callback function. Change the name to the desired name, for example, closethegui.

• As necessary, update instances of the callback function name in the M-file (for example, to function closethegui in its function definition).

After you alter a callback signature, whenever you click its pencil-and-paper icon to go to the function definition in the GUI M-file, GUIDE presents a dialog box for you to confirm the changes you made.

Click Yes to revert to the GUIDE auto-generated callback. click No to keep the modified callback.

Note   Remember to change the callback function definition in the GUI M-file if you change its signature in the Property Inspector unless you are pointing a callback to another function that exists in the M-file. For example, you might want several toggle buttons or menu items to use the same callback.

Back to Top

Input Arguments

All callbacks in a GUIDE-generated GUI M-file have the following standard input arguments:

• hObject — Handle of the object, e.g., the GUI component, for which the callback was triggered. For a button group SelectionChangeFcn callback, hObject is the handle of the selected radio button or toggle button.

• eventdata — Sequences of events triggered by user actions such as table selections emitted by a component in the form of a MATLAB struct (or an empty matrix for components that do not generate eventdata)

• handles — A MATLAB struct that contains the handles of all the objects in the GUI, and may also contain application-defined data. See handles Structure for information about this structure.

Object Handle

The first argument is the handle of the component issuing the callback. Use it to obtain relevant properties that the callback code uses and change them as necessary. For example,

theText = get(hObject,'String');

places the String property (which might be the contents of static text or name of a button) into the local variable theText. You can change the property by setting it, for example

set(hObject,'String',date)

This particular code changes the text of the object to display the current date.

Event Data

Event data is a stream of data describing user gestures, such as key presses, scroll wheel movements, and mouse drags. The auto-generated callbacks of GUIDE GUIs can access event data for Handle Graphics^® and uicontrol and uitable object callbacks. The following ones receive event data when triggered:

• CellEditCallback in a uitable

• CellSelectionCallback in a uitable

• KeyPressFcn in uicontrols and figures

• KeyReleaseFcn in a figure

• SelectionChangeFcn in a uibuttongroup

• WindowKeyPressFcn in a figure or any of its child objects

• WindowKeyReleaseFcn in a figure or any of its child objects

• WindowScrollWheelFcn in a figure

Event data is passed to GUIDE-generated callbacks as the second of three standard arguments. For components that issue no event data the argument is empty. For those that provide event data, the argument contains a structure, which varies in composition according to the component that generates it and the type of event.

For example, the event data for a key-press provides information on the key(s) currently being pressed. Here is a GUIDE-generated KeyPressFcn callback template:

% --- Executes on key press with focus on checkbox1 and none of its controls.
function checkbox1_KeyPressFcn(hObject, eventdata, handles)
% hObject    handle to checkbox1 (see GCBO)
% eventdata  structure with the following fields (see UICONTROL)
%	         Key: name of the key that was pressed, in lower case
%	   Character: character interpretation of the key(s) that was pressed
%	    Modifier: name(s) of the modifier key(s) (i.e., control, shift) pressed
% handles    structure with handles and user data (see GUIDATA)

The eventdata structure passed in has three fields, identifying the Character being pressed (such as '='), the key Modifier (such as 'control'), and the Key name (spelled out, such as 'equals').

Components that provide event data use different structures with event-specific field names to pass data. Callbacks with event data usually are repeatedly issued as long as the event persists or sometimes at the beginning of an event and thereafter only when its values change.

Learn how callbacks use event data by looking at the GUIDE uitable example GUI to Interactively Explore Data in a Table and the programmatic uitable example GUI that Displays and Graphs Tabular Data.

handles Structure

GUIDE creates a handles structure that contains the handles of all the objects in the figure. For a GUI that contains an edit text, a panel, a pop-up menu, and a push button, the handles structure originally looks similar to this. GUIDE uses each component's Tag property to name the structure element for its handle.

handles = 
        figure1: 160.0011
          edit1: 9.0020
       uipanel1: 8.0017
     popupmenu1: 7.0018
    pushbutton1: 161.0011
         output: 160.0011

GUIDE creates and maintains the handles structure as GUI data. It is passed as an input argument to all callbacks and enables a GUI's callbacks to share property values and application data.

For information about GUI data, see Mechanisms for Managing Data and the guidata reference page.

For information about adding fields to the handles structure and instructions for correctly saving the structure, see Managing Application-Defined Data.

Back to Top

Associating Callbacks with Components

Initialization Callbacks