Callback Conventions in GUIDE :: Working with Callbacks (Draft) (Creating Graphical User Interfaces)

Creating Graphical User Interfaces

Callback Conventions in GUIDE

GUIDE defines conventions for callback syntax and arguments. These conventions enable GUIDE to provide commonly used information to each callback automatically.

Syntax and Arguments

The GUIDE template for a component callback is similar to this one for a uicontrol of style pushbutton.

% --- Executes on button press in pushbutton1.
function pushbutton1_Callback(hObject, eventdata, handles) %#ok
% 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. Other comments describe the input arguments.

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

The template also includes the function definition. Insert your code after the last comment.

Function Definition. GUIDE 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. See Associating Callbacks with Components for more information.

Input Arguments. All callbacks in the GUI M-file have the following input arguments:

hObject -- Handle of the object for which the callback was triggered.
eventdata -- Reserved for later use.
handles -- Structure that contains the handles of all the objects in the figure. It may also contain application-defined data.

The Handles Structure. For a GUI that contains an edit text, a uipanel, a pop-up menu, and a push button, the handles structure that GUIDE creates originally looks similar to this. GUIDE uses a 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 stores and maintains the handles structure. If you change any of these variables, or make explicit changes to the handles structure, you must save the handles structure before exiting the callback. To do this, you must use the command

```
guidata(hObject,handles);
```

See Managing GUI Data with the Handles Structure and the guidata reference page for general information about the handles structure.

See Managing Application-Defined Data for information about using the handles structure.

Note The guidata function can manage only one variable. For GUIs created with GUIDE, this is the handles structure. If your GUI M-file was created by GUIDE, do not call guidata with any data other than handles. If you do, you will overwrite handles and your GUI will not work. If you need to store other data with your GUI, you can add it to the handles structure. See Adding Fields to a Data Structure for information about adding fields to this structure.

Changing Callback Names Assigned by GUIDE

You can change callback names assigned by GUIDE in either of the following ways:

In either case, see Setting Component Properties -- The Property Inspector for information about using the Property Inspector to change property values.

Changing the Tag Property. You can change a Tag property to give a component's callbacks a more meaningful name, e.g., you might change the Tag property from pushbutton1 to closebutton. If possible, change the Tag property before saving the GUI, then GUIDE automatically uses the new value when it names the callbacks. However, if you change the 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 Input Arguments for more information about the handles structure.

Changing the Callback Property. To rename a particular callback subfunction without changing the Tag property,

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 an untitled GUI is

mygui('pushbutton1_Callback',gcbo,[],guidata(gcbo))

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

Update all instances of the callback function name in the M-file.
Update references in the M-file to the field of the handles structure that contains the component's handle. See Input Arguments for more information about the handles structure.

Component and Figure Callbacks Callbacks in Programmatically Created GUIs