|On this page…|
GUIDE defines conventions for callback syntax and arguments and implements these conventions in the callback templates it adds to the GUI code. Each template is like this one for the Callback local function 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.
|GUI Component||Callbacks with Event Data||Property Reference Pages|
KeyPressFcn, KeyReleaseFcn, WindowKeyPressFcn, WindowKeyReleaseFcn, WindowScrollWheel
|User interface control (uicontrol)|
|Button group (uibuttongroup)|
The previous callback example includes the following function definition:
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 code 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 that 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.
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 code 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 code file in the MATLAB® Editor and positions the cursor at the first line of the callback. When GUIDE defines the function in the file as:
function pushbutton1_Callback(hObject, eventdata, handles)
then the function signature for the Callback property, shown in the Property Inspector, is
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 file in which the callback function resides ('mygui')
The name of the callback function within the file ('pushbutton1_Callback')
The argument list to pass to the callback function:
hObject — The handle of the component issuing the callback (a push button, in this case)
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)
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 GUIDE Callback Arguments for details about GUIDE-generated callbacks.
All callbacks in a GUIDE-generated GUI code 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.
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
This particular code changes the text of the object to display the current date.
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 for Presenting Data in Multiple, Synchronized Displays (GUIDE) and the programmatic uitable example GUI for Presenting Data in Multiple, Synchronized Displays.
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 adding fields to the handles structure and instructions for correctly saving the structure, see Adding Fields to the handles Structure and Changing GUI Data in a Code File Generated by GUIDE.
As described in Callback Names and Signatures in GUIDE, GUIDE generates a name for a callback by concatenating 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 GUI code file
The value of the component's callback properties, which you can view in the Property Inspector
References in the code 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
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 code 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 code 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 code file if you change its signature in the Property Inspector unless you are pointing a callback to another function that exists in that file. For example, you might want several toggle buttons or menu items to use the same callback.