Output Function

The output function returns output arguments to the command line. This is particularly useful if you want to return a variable to another GUI. For an example, see Example: Using the Modal Dialog to Confirm an Operation.

GUIDE generates the following lines of code in the output function:

% --- Outputs from this function are returned to the command line.

function varargout = my_gui_OutputFcn(hObject, eventdata,

handles)

% Get default command line output from handles structure

varargout{1} = handles.output;

If the GUI is not blocking -- in other words, if the M-file does not contain the command uiwait -- the output is simply the handle to the GUI, which is assigned to handles.output in the opening function.

To make the GUI return a different output -- for example, if you want it to return the result of a user response, such as pressing a push button -- do the following:

• Add the command uiwait; to the opening function to make the M-file halt execution until a user activates a component in the GUI.

• For each component of the GUI where you expect a user response, make the callback update the value of handles.output, and execute uiresume.

For example, if the GUI contains a push button whose String property is 'Yes', add the following code to its callback to make the GUI return 'Yes' when the user presses the push button: handles.output = 'Yes';

guidata(hObject, handles);

uiresume;

See the section Managing GUI Data with the Handles Structure for more information about passing data with the handles structure.

When the GUI is called with the command

OUT = my_gui

and a user presses the Yes push button, the GUI returns the output

OUT = 'Yes' to the command line.

The output varargout, which is a cell array, can contain any number of output arguments. By default, GUIDE creates just one output argument, handles.output. To create a second output argument, add the command

varargout{2} = handles.second_output;

to the output function. You can set the value of handles.second_output in any callback and then save it with the guidata command.

If you want, you can choose more descriptive names than output or second_output for the fields of the handles structure corresponding to the output arguments.

Callbacks

When a user activates a component of the GUI, the GUI executes the corresponding callback. The name of the callback is determined by the component's Tag property and the type of callback. For example, a push button with the Tag print_button executes the callback function

print_button_Callback(hObject, eventdata, handles)

Input and Output Arguments

The following examples illustrate various ways to call a GUI named my_gui with different arguments. All arguments are passed to the opening function in the GUI M-file.

• Calling my_gui with no arguments opens my_gui.

• Calling H = my_gui opens my_gui and returns the handle to my_gui.

• Calling my_gui('Property', Value,...), where 'Property' is a valid figure property, opens my_gui using the given property-value pair. You can call the GUI with more than one property-value pair. 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. See the reference page for figure for a list of figure properties.

• Calling my_gui('My_function', hObject, eventdata, handles,...) calls the subfunction My_function in the GUI M-file with the given input arguments.

• Calling my_gui('Key_word', Value,...), where 'Key_word' is any string that is not a valid figure property or the name of a subfunction, creates a new my_gui, and passes the pair 'Key_word', Value to the opening function in the GUI M-file via varargin. You can use this calling syntax to pass arguments that are not figure properties to the GUI. For example, my_gui('Temperature', 98.6) opens the GUI and passes the vector ['Temperature', 98.6] to the opening function.

See An Address Book Reader for an example that uses this syntax. The example creates a GUI called address_book. Calling the GUI with the syntax address_book('book', my_contacts) opens the GUI with the MAT-file my_contacts, which contains a list of names and addresses you want to display. Note that you can use any string that is not a valid figure property or the name of a callback in place of the string 'book'. See the reference page for figure for a list of figure properties.

Note If you call a GUI with multiple property value pairs, all the pairs that correspond to valid figure properties must precede all the pairs that do not correspond to valid figure properties in the sequence of arguments.