| MATLAB® | |
| On this page… |
|---|
The opening function is the first callback in every GUI M-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.
GUIDE names the opening function by appending _OpeningFcn to the name of the M-file. This is an example of an opening function template as it might appear in the mygui M-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);
The opening function has four input arguments hObject, eventdata, handles, and varargin. The first three are the same as described in Input Arguments. 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 in the MATLAB Programming Fundamentals documentation.
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 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.
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. For more information about the output function, see Output Function.
guidata(hObject,handles) saves the handles structure. You must use guidata to save any changes that you make to the handles structure. It is not sufficient just to set the value of a handles field. See handles Structure and GUI Data for more information.
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.
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.
GUIDE names the output function by appending _OutputFcn to the name of the M-file. This is an example of an output function template as it might appear in the mygui M-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;The output function has three input arguments: hObject, eventdata, and handles. They are the same as described in Input 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
Changing the value of handles.output. It can be any valid MATLAB value including a structure or cell array.
Adding output arguments to varargout.
varargout 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; | Callback Syntax and Arguments | Examples: Programming GUIDE GUI Components | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |