Documentation

Write Callbacks Using the GUIDE Workflow

Callbacks for Different User Actions

UI and graphics components have certain properties that you can associate with specific callback functions. Each of these properties corresponds to a specific user action. For example, a uicontrol has a property called Callback. You can set the value of this property to be a handle to a callback function, an anonymous function, or a string containing MATLAB® commands. Setting this property makes your GUI respond when the user interacts with the uicontrol. If the Callback property has no specified value, then nothing happens when the end user interacts with the uicontrol.

This table lists the callback properties that are available, the user actions that trigger the callback function, and the most common UI and graphics components that use them.

Callback Property

User Action

Components That Use This Property

ButtonDownFcn

End user presses a mouse button while the pointer is on the component or figure.

axes, figure, uibuttongroup, uicontrol, uipanel, uitable,

Callback

End user triggers the component. For example: selecting a menu item, moving a slider, or pressing a push button.

uicontextmenu, uicontrol, uimenu

CellEditCallback

End user edits a value in a table whose cells are editable.

uitable

CellSelectionCallback

End user selects cells in a table.

uitable

ClickedCallback

End user clicks the push tool or toggle tool with the left mouse button.

uitoggletool, uipushtool

CloseRequestFcn

The figure closes.

figure

CreateFcn

Callback executes when MATLAB creates the object, but before it is displayed.

axes, figure, uibuttongroup, uicontextmenu, uicontrol, uimenu, uipushtool, uipanel, uitable, uitoggletool, uitoolbar

DeleteFcn

Callback executes just before MATLAB deletes the figure.

axes, figure, uibuttongroup, uicontextmenu, uicontrol, uimenu, uipushtool, uipanel, uitable, uitoggletool, uitoolbar

KeyPressFcn

End user presses a keyboard key while the pointer is on the object.

figure, uicontrol, uipanel, uipushtool, uitable, uitoolbar

KeyReleaseFcn

End user releases a keyboard key while the pointer is on the object.

figure, uicontrol, uitable

OffCallback

Executes when the State of a toggle tool changes to 'off'.

uitoggletool

OnCallback

Executes when the State of a toggle tool changes to 'on'.

uitoggletool

SizeChangedFcn

End user resizes a button group, figure, or panel whose Resize property is 'on'.

figure, uipanel, uibuttongroup

SelectionChangedFcn

End user selects a different radio button or toggle button within a button group.

uibuttongroup

WindowButtonDownFcn

End user presses a mouse button while the pointer is in the figure window.

figure

WindowButtonMotionFcn

End user moves the pointer within the figure window.

figure

WindowButtonUpFcn

End user releases a mouse button.

figure

WindowKeyPressFcn

End user presses a key while the pointer is on the figure or any of its child objects.

figure

WindowKeyReleaseFcn

End user releases a key while the pointer is on the figure or any of its child objects.

figure

WindowScrollWheelFcn

End user turns the mouse wheel while the pointer is on the figure.

figure

GUIDE-Generated Callback Functions and Property Values

How GUIDE Manages Callback Functions and Properties

After you add a uicontrol, uimenu, or uicontextmenu component to your GUI, but before you save it, GUIDE populates the Callback property with the value, %automatic. This value indicates that GUIDE will generate a name for the callback function.

When you save your GUI, GUIDE adds an empty callback function definition to your GUI code file, and it sets the control's Callback property to be an anonymous function. This function definition is an example of a GUIDE-generated callback function for a push button.

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)

end

If you save this GUI with the name, mygui, then GUIDE sets the push button's Callback property to the following value:

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

This is an anonymous function that serves as a reference to the function, pushbutton1_Callback. This anonymous function has four input arguments. The first argument is a string containing the name of the callback function. The last three arguments are provided by Handle Graphics®, and are discussed in the section, GUIDE Callback Syntax.

    Note:   GUIDE does not automatically generate callback functions for other UI components, such as tables, panels, or button groups. If you want any of these components to execute a callback function, then you must create the callback by right-clicking on the component in the layout, and selecting an item under View Callbacks in the context menu.

GUIDE Callback Syntax

All callbacks in a GUIDE GUI must accept at least three input arguments:

  • hObject — Handle to the UI component that triggered the callback.

  • eventdata — A variable that contains detailed information about specific mouse or keyboard actions.

  • handles — A struct that contains handles to all the objects in the GUI. GUIDE uses the guidata function to store and maintain this structure.

For the callback function to accept additional arguments, you must put the additional arguments at the end of the argument list in the function definition.

The eventdata Argument

The eventdata argument provides detailed information to certain callback functions. For example, if the end user triggers the KeyPressFcn, then MATLAB provides information regarding the specific key (or combination of keys) that the end user pressed. If eventdata is not available to the callback function, then MATLAB passes it as an empty array. The following table lists the callbacks and components that use eventdata.

Callback Property NameComponent
WindowKeyPressFcn
WindowKeyReleaseFcn
WindowScrollWheel
figure
KeyPressFcnfigure, uicontrol, uitable
KeyReleaseFcnfigure, uicontrol, uitable
SelectionChangedFcnuibuttongroup
CellEditCallback
CellSelectionCallback
uitable

Renaming and Removing GUIDE-Generated Callbacks

Renaming Callbacks

GUIDE creates the name of a callback function by combining the component's Tag property and the callback property name. If you change the component's Tag value, then GUIDE changes the callback's name the next time you save the GUI.

If you decide to change the Tag value after saving the GUI, then GUIDE updates the following items (assuming that all components have unique Tag values).

  • Component's callback function definition

  • Component's callback property value

  • References in the code file to the corresponding field in the handles structure

To rename a callback function without changing the component's Tag property:

  1. Change the name in the callback function definition.

  2. Update the component's callback property by changing the first argument passed to the anonymous function. For example, the original callback property for a push button might look like this:

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

    In this example, you must change the string, 'pushbutton1_Callback' to the new function name.

  3. Change all other references to the old function name to the new function name in the GUI code file.

Deleting Callbacks

You can delete a callback function when you want to remove or change the function that executes when the end user performs a specific action. To delete a callback function:

  1. Search and replace all instances that refer to the callback function in your code.

  2. Open the GUI in GUIDE and replace all instances that refer to the callback function in the Property Inspector.

  3. Delete the callback function.

More About

Was this topic helpful?