Documentation

Initialize UIs Created Using GUIDE

Opening Function

The opening function is the first callback in every UI code file. It is executed just before the UI 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 UI. For example, you can use it to create data or to read data from an external source. MATLAB® passes any command-line arguments to the opening function.

Function Naming and Template

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

% --- Executes just before myui is made visible.
function myui_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 myui (see VARARGIN)
 
% Choose default command line output for myui
handles.output = hObject;
 
% Update handles structure
guidata(hObject, handles);
 
% UIWAIT makes myui wait for user response (see UIRESUME)
% uiwait(handles.myui);

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 property name-value pairs as two successive command line arguments when you run your program. If you pass a name-value pair that corresponds to a figure property, MATLAB sets the property automatically. For example, my_gui('Color', 'Blue') sets the background color of the UI window to blue.

If you want your program to accept an input argument that is not a valid figure property, then your code must recognize and handle that argument. Otherwise, the argument is ignored. The following example is from the opening function for the Modal Question Dialog 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 program that calls this one. For example, this command displays the text, 'Do you want to exit?' on the window.

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

To accept this name-value pair, you must customize the opening function because 'String' is not a valid figure property. The Modal Question Dialog template file contains code to performs these tasks:

  • 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 figure object.

  • 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.myui), initially commented out, blocks program execution until uiresume is called or the window is closed. Note that uiwait allows the user access to other MATLAB windows. Remove the comment symbol for this statement if you want the UI 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 UI. This is an example of an output function template as it might appear in the myui code file.

% --- Outputs from this function are returned to the command line.
function varargout = myui_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.

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?