Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Write Callbacks Using the GUIDE Workflow

Callbacks for Different Triggering 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 object has a property called Callback. You can set the value of this property to be a reference to a callback function, in the form of a function handle or an anonymous function. This relationship between the Callback property and the callback function makes your GUI respond when the end user triggers the uicontrol. If the Callback property is empty, then nothing happens when the end user interacts with the uicontrol.

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

Callback Property

Triggering 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

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

ResizeFcn

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

uibuttongroup, figure, uipanel

SelectionChangeFcn

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 Callbacks

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 populates the control's Callback property with a reference to the callback 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 callback 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, Required Callback Arguments.

    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 trigger a callback, 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.

Required Callback Arguments

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 struct in some cases, that contains detailed information about specific mouse or keyboard actions. MATLAB passes eventdata as an empty array to callbacks that do not support it.

  • 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
KeyPressFcn
KeyReleaseFcn
WindowKeyPressFcn
WindowKeyReleaseFcn
WindowScrollWheel
Figure
KeyPressFcnuicontrol
SelectionChangeFcnuibuttongroup
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?