Documentation

Initialize a GUIDE GUI

Opening Function

The opening function is the first callback in every GUI code file. It is executed just before the GUI is made visible to the user, but after all the components have been created, i.e., after the components' CreateFcn callbacks, if any, have been run.

You can use the opening function to perform your initialization tasks before the user has access to the GUI. For example, you can use it to create data or to read data from an external source. GUI command-line arguments are passed to the opening function.

Function Naming and Template

GUIDE names the opening function by appending _OpeningFcn to the name of the GUI. This is an example of an opening function template as it might appear in the mygui code file.

% --- Executes just before mygui is made visible.
function mygui_OpeningFcn(hObject, eventdata, handles, varargin)
% This function has no output args, see OutputFcn.
% hObject    handle to figure
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)
% varargin   command line arguments to mygui (see VARARGIN)
 
% Choose default command line output for mygui
handles.output = hObject;
 
% Update handles structure
guidata(hObject, handles);
 
% UIWAIT makes mygui wait for user response (see UIRESUME)
% uiwait(handles.mygui);

Input Arguments

The opening function has four input arguments hObject, eventdata, handles, and varargin. The first three are the same as described in GUIDE Callback Syntax. the last argument, varargin, enables you to pass arguments from the command line to the opening function. The opening function can take actions with them (for example, setting property values) and also make the arguments available to callbacks by adding them to the handles structure.

For more information about using varargin, see the varargin reference page and Support Variable Number of Inputs.

Passing Object Properties to an Opening Function.  You can pass a property name/value pair for any component as two successive command line arguments and set that value in the opening function. If you are setting a figure property, GUIDE handles this automatically. 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 (in character units, the default).

You can define new names for properties or combinations of them. For example, you can make your GUI accept an alias for a figure property as a convenience to the user. For example, you might want the user to be able to open the GUI with a Title argument instead of calling it Name, which is the property that specifies the name on the GUI's title bar. To do this, you must provide code in its OpeningFcn to set theName figure property. The following example illustrates how to do this.

If you pass an input argument that is not a valid figure property, your code must recognize its name and use the name/value pair to set the appropriate property on the correct object. Otherwise, the argument is ignored. The following example is from the opening function for the Modal Question Dialog GUI template, available from the GUIDE Quick Start dialog box. The added code opens the modal dialog with a message, specified from the command line or by another GUI that calls this one. For example,

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

displays the text 'Do you want to exit?' on the GUI. To do this, you need to customize the opening function because 'String' is not a valid figure property, it is a static text property. The Modal Question Dialog template file contains the following code, which

  • Uses the nargin function to determine the number of user-specified arguments (which do not include hObject, eventdata, and handles)

  • Parses varargin to obtain property name/value pairs, converting each name string to lower case

  • Handles the case where the argument 'title' is used as an alias for the figure Name property

  • Handles the case 'string' , assigning the following value as a String property to the appropriate static text object

function modalgui_OpeningFcn(hObject, eventdata, handles, varargin)
.
.
.
% Insert custom Title and Text if specified by the user
% Hint: when choosing keywords, be sure they are not easily confused 
% with existing figure properties.  See the output of set(figure) for
% a list of figure properties.
if(nargin > 3)
    for index = 1:2:(nargin-3),
        if nargin-3==index, break, end
        switch lower(varargin{index})
         case 'title'
          set(hObject, 'Name', varargin{index+1});
         case 'string'
          set(handles.text1, 'String', varargin{index+1});
        end
    end
end
.
.
.

The if block loops through the odd elements of varargin checking for property names or aliases, and the case blocks assign the following (even) varargin element as a value to the appropriate property of the figure or one of its components. You can add more cases to handle additional property assignments that you want the opening function to perform.

Initial Template Code

Initially, the input function template contains these lines of code:

  • handles.output = hObject adds a new element, output, to the handles structure and assigns it the value of the input argument hObject, which is the handle of the figure, i.e., the handle of the GUI. This handle is used later by the output function.

  • guidata(hObject,handles) saves the handles structure. You must use the guidata function to save any changes that you make to the handles structure. It is not sufficient just to set the value of a handles field.

  • uiwait(handles.mygui), initially commented out, blocks GUI execution until uiresume is called or the GUI is deleted. Note that uiwait allows the user access to other MATLAB® windows. Remove the comment symbol for this statement if you want the GUI to be blocking when it opens.

Output Function

The output function returns, to the command line, outputs that are generated during its execution. It is executed when the opening function returns control and before control returns to the command line. This means that you must generate the outputs in the opening function, or call uiwait in the opening function to pause its execution while other callbacks generate outputs.

Function Naming and Template

GUIDE names the output function by appending _OutputFcn to the name of the GUI. This is an example of an output function template as it might appear in the mygui code file.

% --- Outputs from this function are returned to the command line.
function varargout = mygui_OutputFcn(hObject, eventdata,...
                     handles)
% varargout  cell array for returning output args (see VARARGOUT);
% hObject    handle to figure
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)
 
% Get default command line output from handles structure
varargout{1} = handles.output;

Input Arguments

The output function has three input arguments: hObject, eventdata, and handles. They are the same as described in GUIDE Callback Syntax.

Output Arguments

The output function has one output argument, varargout, which it returns to the command line. By default, the output function assigns handles.output to varargout. So the default output is the handle to the GUI, which was assigned to handles.output in the opening function.

You can change the output by taking one of these actions:

  • Change the value of handles.output. It can be any valid MATLAB value including a structure or cell array.

  • Add output arguments to varargout. The varargout argument is a cell array. It can contain any number of output arguments. By default, GUIDE creates just one output argument, handles.output. To create an additional output argument, create a new field in the handles structure and add it to varargout using a command similar to

    varargout{2} = handles.second_output;
Was this topic helpful?