|On this page…|
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.
Components That Use This Property
End user presses a mouse button while the pointer is on the component or figure.
End user triggers the component. For example: selecting a menu item, moving a slider, or pressing a push button.
End user edits a value in a table whose cells are editable.
End user selects cells in a table.
End user clicks the push tool or toggle tool with the left mouse button.
The figure closes.
Callback executes when MATLAB® creates the object, but before it is displayed.
Callback executes just before MATLAB deletes the figure.
End user presses a keyboard key while the pointer is on the object.
End user releases a keyboard key while the pointer is on the object.
Executes when the State of a toggle tool changes to 'off'.
Executes when the State of a toggle tool changes to 'on'.
End user resizes a button group, figure, or panel whose Resize property is 'on'.
End user selects a different radio button or toggle button within a button group.
End user presses a mouse button while the pointer is in the figure window.
End user moves the pointer within the figure window.
End user releases a mouse button.
End user presses a key while the pointer is on the figure or any of its child objects.
End user releases a key while the pointer is on the figure or any of its child objects.
End user turns the mouse wheel while the pointer is on the figure.
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:
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.
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 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 Name||Component|
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:
Change the name in the callback function definition.
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:
In this example, you must change the string, 'pushbutton1_Callback' to the new function name.
Change all other references to the old function name to the new function name in the GUI code file.
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:
Search and replace all instances that refer to the callback function in your code.
Open the GUI in GUIDE and replace all instances that refer to the callback function in the Property Inspector.
Delete the callback function.