Guide me in the guide

Creating interfaces in Matlab is extremely easy. As easy as starting the GUIDE in the command line, dragging a button on a window and populating the button callback with you code. In less than a minute you can have a working interface.

For the purpose of this post, I am going to assume you have already played with GUIDE and you know how to use it.

The GUIDE has been designed to automatically populate the M-file with all the interface code so that you can focus on only the important part of your work. Still, you might want to understand what is going on in this M-file. Indeed, even for a very simple interface, the generated code is quite large. Surprisingly, there is little documentation on all these lines of code.

Let us go through a simple example. I prepared an interfaced called ‘SimpleGUI’ with only one pushbutton (whose tag is ‘OKButton’). As you can see below, the generated code, is quite long :

function varargout = SimpleGUI(varargin)
 % SIMPLEGUI MATLAB code for SimpleGUI.fig
 % SIMPLEGUI, by itself, creates a new SIMPLEGUI or raises the existing
 % singleton*.
 %
 % H = SIMPLEGUI returns the handle to a new SIMPLEGUI or the handle to
 % the existing singleton*.
 %
 % SIMPLEGUI('CALLBACK',hObject,eventData,handles,...) calls the local
 % function named CALLBACK in SIMPLEGUI.M with the given input arguments.
 %
 % SIMPLEGUI('Property','Value',...) creates a new SIMPLEGUI or raises the
 % existing singleton*. Starting from the left, property value pairs are
 % applied to the GUI before SimpleGUI_OpeningFcn gets called. An
 % unrecognized property name or invalid value makes property application
 % stop. All inputs are passed to SimpleGUI_OpeningFcn via varargin.
 %
 % *See GUI Options on GUIDE's Tools menu. Choose "GUI allows only one
 % instance to run (singleton)".
 %
 % See also: GUIDE, GUIDATA, GUIHANDLES

% Edit the above text to modify the response to help SimpleGUI

% Last Modified by GUIDE v2.5 22-Mar-2012 21:20:33

% Begin initialization code - DO NOT EDIT
 gui_Singleton = 1;
 gui_State = struct('gui_Name', mfilename, ...
 'gui_Singleton', gui_Singleton, ...
 'gui_OpeningFcn', @SimpleGUI_OpeningFcn, ...
 'gui_OutputFcn', @SimpleGUI_OutputFcn, ...
 'gui_LayoutFcn', [] , ...
 'gui_Callback', []);
 if nargin && ischar(varargin{1})
 gui_State.gui_Callback = str2func(varargin{1});
 end

if nargout
 [varargout{1:nargout}] = gui_mainfcn(gui_State, varargin{:});
 else
 gui_mainfcn(gui_State, varargin{:});
 end
 % End initialization code - DO NOT EDIT

% --- Executes just before SimpleGUI is made visible.
 function SimpleGUI_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 SimpleGUI (see VARARGIN)

% Choose default command line output for SimpleGUI
 handles.output = hObject;

% Update handles structure
 guidata(hObject, handles);

% UIWAIT makes SimpleGUI wait for user response (see UIRESUME)
 % uiwait(handles.figure1);

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

% --- Executes on button press in OKButton.
 function OKButton_Callback(hObject, eventdata, handles)
 % hObject handle to OKButton (see GCBO)
 % eventdata reserved - to be defined in a future version of MATLAB
 % handles structure with handles and user data (see GUIDATA)

The first thing you probably notice are those ‘DO NOT EDIT’ lines. Something important is going on here.
These lines execute when you start the function SimpleGUI. In other words, when you start the interface.
Apparently the function SimpleGUI starts by populating a structure called gui_State. This structure has 6 fields : gui_Name, gui_Singleton, gui_OpeningFcn, gui_OutputFcn, gui_LayoutFcn and gui_Callback.

The next part of the ‘DO NOT EDIT’ code is calling a function ‘gui_mainfcn’ with gui_State passed as a variable as well as the arguments passed to SimpleGUI. You can guess this the constructor function of the interface.

  • gui_Name is filled with mfilename. This is the current M-file so here ‘SimpleGUI’.
  • gui_Singleton is an option (0 or 1) that allows only one or several instance of your Gui to be started at the same time.
  • gui_OpeningFcn is filled with a function handle. It points at SimpleGUI_OpeningFcn. The function is here, just below. This function is being called as they say: ‘just before SimpleGUI is made visible’. And what this function does by default? It fills handles.output (the handles structure that is stored in your Gui) with the handle to your GUI. This is a very useful handle that is not really advertised by Matlab (so far). Useful because handles is available in all your callbacks!
  • gui_OutputFcn is filled similarly with another function that is here, just below. And, oh surprise, this function only send out handles.output in varargout. This varargout is transmitted via gui_mainfcn to the big varargout of SimpleGui. And here is why calling your Gui from the command line can send you back to handle to it (h=SimpleGui;).
  • gui_LayoutFcn is used when you actually don’t have an associated FIG file that stores all the objects on your interface. It would actually create the objects directly from the M-file. In this case, as we used the GUIDE, it is irrelevant (we have a FIG file) so it is empty.
  • gui_Callback is interesting. At first, it start empty and then there are these lines that fill it in case varargin{1} is a character. It took me a while to work it out but in fact, this is used to call some of your callback from outside! For instance, you can call OKButton via :
h=SimpleGUI();
SimpleGUI('OKButton',h,[],guidata(h));

h and guidata(h) are passed as well as these are the needed input to the callback OKButton. h is the handle to the Gui and guidata(h) is the struct of handle, referred as ‘handles’ throughout your Gui. It stores all the handles to the interface object.

Now that you know what is going on, please cross the border, EDIT this ‘DO NOT EDIT’ code. Change the name of both the OpeningFcn in the struct and at the function declaration and you will see that it still works!

This entry was posted in Advanced, Making interfaces. Bookmark the permalink.

3 Responses to Guide me in the guide

  1. DS says:

    Want to know about gui_Callback.

  2. crlab says:

    For this to work on 2012a I had to change
    h=SimpleGUI();
    SimpleGUI(‘OKButton’,h,[],guidata(h));
    to read
    h=SimpleGUI();
    SimpleGUI(‘OKButton_Callback’,h,[],guidata(h))

  3. Wenwu says:

    amzing! really lazy to dig out these things by myself. thanks

Leave a Reply

Your email address will not be published. Required fields are marked *