Creating Graphical User Interfaces Sharing Data with the Handles Structure

When you run a GUI, the M-file creates a handles structure that contains all the data for GUI objects, such as controls, menus, and axes. The handles structure is passed as an input to each callback. You can use the handles structure to

• Share data between callbacks

• Access GUI data

Sharing Data

To store data that is contained in a variable X, set a field of the handles structure equal to X and then save the handles structure with the guidata function:

handles.current_data = X;

guidata(hObject,handles)

You can retrieve the data in any other callback with the command

X = handles.current_data;

For an example of sharing data between callbacks, see Example: Passing Data Between Callbacks.

For more information about handles, see Managing GUI Data with the Handles Structure.

Accessing GUI Data

You can access any of the data for the GUI components from the handles structure. For example, suppose your GUI has a pop-up menu, whose Tag is my_menu, containing three items, whose String properties are chocolate, strawberry, and vanilla. You want another component in the GUI -- a push button, for example -- to execute a command on the currently selected menu item. In the callback for the push button, you can insert the command

all_choices = get(handles.my_menu, 'String')

current_choice = all_choices{get(handles.my_menu, 'Value')};

The command sets the value of current_choice to chocolate, strawberry, or vanilla, depending on which item is currently selected in the menu.

You can also access the data for the entire GUI from the handles structure. If the figure's Tag is figure1, then

handles.figure1

contains the figure's handle. For example, you can make the GUI close itself with the command

delete(handles.figure1)

For an example of closing a GUI with this command, look at the callback for the Close push button for the template described in GUI with Axes and Menu

Functions and Callbacks in the m-File

You can add code to the following parts of the GUI M-file:

• Opening function -- executes before the GUI becomes visible to the user.

• Output function -- outputs data to the command line, if necessary.

• Callbacks -- execute each time the user activates the corresponding component of the GUI.

Common Input Arguments

All functions in the M-file have the following input arguments corresponding to the handles structure:

• hObject -- the handle to the figure or Callback object

• handles -- structure with handles and user data (see guidata)

The handles structure is saved at the end of each function with the command

guidata(hObject, handles);

Additional arguments for the opening and output functions are described in the following sections.

Opening Function

The opening function contains code that is executed just before the GUI is made visible to the user. You can access all the components for the GUI in the opening function, because all objects in the GUI are created before the opening function is called. You can add code to the opening function to perform tasks that need to be done before the user has access to the GUI -- for example, creating data, plots or images, or making the GUI blocking with the uiwait command.

For a GUI whose file name is my_gui, the definition line for the opening function is

function my_gui_OpeningFcn(hObject, eventdata, handles,

varargin)

Besides the arguments hObject and handles (see Common Input Arguments preceding), the opening function has the following input arguments:

• eventdata -- reserved for a future version of MATLAB

• varargin -- command line arguments to untitled (see varargin)

All command line arguments are passed to the opening function via varargin. If you call the GUI with a property name/property value pair as arguments, the GUI opens with the property set to the specified value. For example, my_gui('Position', [71.8 44.9 74.8 19.7]) opens the GUI at the specified position, since Position is a valid figure property.

If the input argument is not a valid figure property, you must add code to the opening function to make use of the argument. For an example, look at the opening function for the modal question dialog template. The added code enables you to open the modal dialog with the syntax

my_gui('String','Do you want to exit?')

which displays the text 'Do you want to exit' on the GUI. In this case, it is necessary to add code to the opening function because 'String' is not a valid figure property.