Mechanisms for Managing Data :: Managing and Sharing Application Data in GUIDE (MATLAB®)

MATLAB^®

Mechanisms for Managing Data

On this page…
Overview GUI Data Application Data UserData Property

On this page…

Overview

Most GUIs generate or use data specific to the application. This section describes the following mechanisms that provide a way to manage application defined data, stored within a GUI:

GUI Data: use the guidata function to manage GUI data. This function can store a single variable as GUI data. The is also used to retrieve the value of the stored variable.
Application Data: provides a way for applications to save and retrieve data associated with a specified object. For a GUI, this is usually the GUI figure, but it can also be any component. The data is stored as name/value pairs. Application data enables you to create what are essentially user-defined properties for an object.
UserData Property: is a user assigned MATLAB^® workspace value to GUI components.

GUI Data

Use the guidata function to manage GUI data. This function can store a single variable as GUI data. The GUI data is also used to retrieve the value of that variable.

About GUI Data

GUI data is always associated with the GUI figure and is available to all callbacks of all the GUI components. If you specify a component handle when you save or retrieve GUI data, MATLAB software automatically associates the data with the component's parent figure.

GUI data can contain only one variable at a time. Threfore, GUI data is usually defined as a structure to which you can add fields as necessary.

GUI data provides application developers with a convenient interface to a figure's application data:

You can access the data from within a callback routine using the component's handle, without having to find the figure handle.
You do not need to create and maintain a hard-coded name for the data throughout your source code.

GUI Data in GUIDE

GUIDE uses guidata to create and maintain the handles structure. The handles structure contains the handles of all GUI components. GUIDE automatically passes the handles structure to every callback as an input argument.

In a GUI created using GUIDE, you cannot use guidata to manage any variable other than the handles structure. If you do, you can overwrite the handles structure and your GUI will not work. To use GUI data to share application-defined data among callbacks, you must save the data in fields that you add to the handles structure.

The GUIDE templates use the handles structure to store application-defined data. See Selecting a GUI Template for information about the templates.

Note For more information, see handles Structure.

Adding Fields to the handles Structure

To add a field to the handles structure, which is passed as an argument to every callback in GUIDE take these steps:

Assign a value to the new field. This adds the field to the structure. For example:
```
handles.number_errors = 0;
```
adds the field number_errors to the handles structure and sets it to 0.
Use the following command to save the data:
```
guidata(hObject,handles)
```
where hObject is the handle of the component for which the callback was triggered. GUIDE then automatically passes the hObject to every callback.

Changing GUI Data in an M-File Generated by GUIDE

In a GUIDE-generated M-file, the handles structure always represents GUI data. The next example updates the handles structure and then saves it.

Assume that the handles structure contains an application-defined field handles.when whose value is 'now'.

Change the value of handles.when to 'later' in a GUI callback. This does not save the handles structure.
```
handles.when = 'later';
```
Save the changed version of the handles structure with the command
```
guidata(hObject,handles)
```
where hObject is the handle of the component for which the callback was triggered. If you do not save the handles structure with guidata, you lose the change you made to it in the previous step.

Application Data

The following table summarizes the functions that provide access to application data. For more details, see the individual function reference pages.

Functions for Managing Application Data

Function	Purpose
`setappdata`	Specify named application data for an object. (The object does not have to be a figure.) You can specify more than one named application data for an object. However, each name must be unique for that object and can be associated with only one value, usually a structure.
`getappdata`	Retrieve named application data. To retrieve named application data, you must know the name associated with the application data and the handle of the object with which it is associated.
`isappdata`	True if the named application data exists, false otherwise.
`rmappdata`	Remove the named application data.

Creating Application Data in GUIDE

Use the setappdata function to create application data. This example generates a 35-by-35 matrix of normally distributed random numbers in the opening function and creates application data mydata to manage it:

function mygui_OpeningFcn(hObject, eventdata, handles, varargin)
matrices.rand_35 = randn(35);
setappdata(hObject,'mydata',matrices);

Because this code appears in the opening function (mygui_OpeningFcn), hObject is the handle of the GUI figure, and the code associates mydata with the figure.

Adding Fields to an Application Data Structure in GUIDE

Application data is usually defined as a structure that enables you to add fields as necessary. In this example, a push button adds a field to the application data structure mydata created in the previous section.

Use getappdata to retrieve the structure.
The name of the application data structure is mydata. It is associated with the figure whose Tag is figure1. Since you pass the handles structure to every callback, the code specifies the figure's handle as handles.figure1:
```
function mygui_pushbutton1(hObject, eventdata, handles)
matrices = getappdata(handles.figure1,'mydata');
```
Create a new field and assign it a value:
```
matrices.randn_50 = randn(50);
```
adds the field randn_50 to the matrices structure and sets it to a 50-by-50 matrix of normally distributed random numbers.
Use setappdata to save the data. This command uses setappdata to save the matrices structure as the application data structure mydata:
```
setappdata(handles.figure1,'mydata',matrices);
```

UserData Property

All GUI components, including menus, and the figure have a UserData property. You can assign any valid MATLAB workspace value to the UserData property. To retrieve the data, a callback must know the handle of the component with which the data is associated.

In this example, an edit text component stores the user-entered string in its UserData property:

function mygui_edittext1(hObject, eventdata, handles)
mystring = get(hObject,'String');
set(hObject,'UserData',mystring);

A push button retrieves the string from the edit text component's UserData property. The callback uses the handles structure and the edit text's Tag property, edittext1, to specify the edit text handle"
```
function mygui_pushbutton1(hObject, eventdata, handles)
string = get(handles.edittext1,'UserData');
```

Managing and Sharing Application Data in GUIDE

Sharing Data Among a GUI's Callbacks