Compose-6000: Use UI Control Functions

Tutorial Level: Intermediate

Overview

In this tutorial, the UI control feature is introduced.

It will show how to create various control objects in Figure UI and link the objects to events using callback functions. This tutorial will build up a script step by step. Therefore, all edits should be made in the edit window so that when the script is run, all edits are considered.

Note: Be sure to use Command Window when requested and Editor Window when requested as this tutorial mixes the use of both.

Open a New .oml File

Use the close all and clear lines to close all figures and clear the Variable Browser.

clc; clear all; close all;

Initialize the Figure Window

Create a figure to host the UI using figure.

  1. Create and position the plot using axes. position sets the size and position of the objects, and the value is specified as a vector of the form: [left top width height]. 
    %Step 2: Initialize the figure window
fig = figure('Name', 'GUI Tutorial','numbertitle','off','units','normalized','Position', [0,0,0.6,0.6]);
handles.ax = axes('units','normalized','Position', [0.25,0.05,0.75,0.8]);
  2. Run the script.
    You should see a figure initialized as in the following image.
    Figure 1. Figure Window


Add a Pushbutton in the UI

Add and use a pushbutton.

  1. Use uicontrol to add a button element.
    Since button is the default style in uicontrol, you don’t need to specify the style in this argument. The value of 'String' describes the text shown on the button in the UI. 
    %Step 3: Add a pushbutton in UI
handles.btn = uicontrol('Parent', fig, 'Style', 'pushbutton','units','normalized', 'Position', [0.02,0.05,0.2,0.05], 'String', 'Plot Sine Wave', ...
         'Callback', 'plotSineWave');
  2. Define the callback function plotSineWave. Input of the callback function should follow the signature format, [handle, callbackdata]. This function plots a default sine wave at 1Hz. 
    function plotSineWave(handle,d)
	t_s = -2:0.005:2;
	plot(t_s,sin(t_s*2*pi));
	disp(handle)
end
  3. Run the script.
  4. Click the pushbutton you just created. A sine wave should be generated.
    Figure 2. Sinewave Generated by Pressing the Pushbutton


Add a Slider in the UI

Add and use a slider.

  1. Add a slider to the figure UI. Set the 'style' property to be slider.
    Tip: 'Max' and 'Min' point to the range of the slider. 'Value' represents the initial position of the slider.
    % add a slider in the UI
handles.slider = uicontrol('Parent', fig, 'Style', 'slider','units','normalized', 'Position', [0.02,0.2,0.16,0.05],'max',10,'min',1,'value',1,... 
'Callback', 'slider_callback');
  2. Add text to the UI to describe the slider. Set the 'style' property to text. 
    handles.text1 = uicontrol('Parent', fig, 'Style', 'text','units','normalized', 'Position', [0.02,0.13,0.16,0.05],'string','Frequency(Hz)');
handles.text2 = uicontrol('Parent', fig, 'Style', 'text','units','normalized', 'Position', [0.02,0.17,0.16,0.03],'string','1');
handles.text3 = uicontrol('Parent', fig, 'Style', 'text','units','normalized', 'Position', [0.17,0.17,0.05,0.03],'string','10');
  3. Define the callback function 'slider_callback.' This function should plot a sine wave according to the frequency set up by the user on the slider. get(handle,’value’) gets the slider position value from UI. 
    function slider_callback(handle,d)
	value = get(handle,'value');
	t = -2:0.001:2;
	plot(t,sin(2*t*pi*value));
end
  4. Run the OML file and check the result.
    The Figure Window should look similar to the following. Interact with the button and slider to check if they are functional.
    Figure 3. Slider Added to Figure Window


Add a Checkbox in the UI to Toggle Grids

Add a checkbox.

  1. Add a checkbox to the figure UI. Set the 'style' property to be 'checkbox.' 'Value' represents the initial state of the checkbox. Define the text (string) to display. 
    handles.checkbox = uicontrol('Parent', fig, 'Style', 'checkbox','units','normalized', 'Position', [0.02,0.27,0.16,0.035],'string','Grid ON','value',0, 'Callback', 'checkbox_callback');
  2. Define the callback function 'check_callback.' This function should read the value from the checkbox and toggle the grid accordingly. 
    function checkbox_callback(handle,d)
	if get(handle,'value')
		grid on;
	else
		grid off;
	end
end
  3. Run the OML script and check the result. The Figure Window should look similar to the following image.
    Figure 4. Checkbox Added to Figure Window


Add a Text Editor in the UI to Change Plot Title

Add a text editor.

  1. Add one line of text to describe the text editor. 
    handles.text = uicontrol('Parent', fig, 'Style', 'text','units','normalized', 'Position', [0.02,0.38,0.16,0.05],'string','Plot Title');
  2. Add a text editor to the figure UI. Set the 'style' property to be 'edit.' 'String' defines the initial text in the text field. 
    handles.edit = uicontrol('Parent', fig, 'Style', 'edit','units','normalized', 'Position', [0.02,0.42,0.16,0.05],'string','The Plot Title','callback','edit_callback');
  3. Define the callback function 'check_callback.' This function should read the string from the text field and update the plot title. 
    function edit_callback(handle,d)
	t = get(handle,'string');
	title(t);
end
  4. Run the OML script and check the result. Change the text in the text field and press Enter.
    Figure 5. Text Editor Added to Figure Window


Add a Toggle Button in the UI

This section implements the same feature as the checkbox, but with a different control object.

  1. Add one line of text to describe the toggle button. 
    handles.texttoggle = uicontrol('Parent', fig, 'Style', 'text','units','normalized', 'Position', [0.02,0.52,0.16,0.05],'string','Grid Toggle State');
  2. Add a toggle button to the figure UI. Set the 'style' property to be 'toggle.' 'String' defines the text displayed on the button. 'Value' is initialized to one, which refers to 'grid off' in this example. 
    handles.toggle = uicontrol('Parent', fig, 'Style', 'toggle','units','normalized', 'Position', [0.02,0.57,0.16,0.05],'string','Grid ON','value',1,'callback','toggle_callback');
  3. Define the callback function 'toggle_callback.' This function should read the value from the button and toggle the plot title. 
    function toggle_callback(handle,d)
	if get(handle,'value')
		grid on;
		set(handle,'string','Grid OFF');
	else
		grid off;
		set(handle,'string','Grid ON');
	end
end
  4. Run the OML script and check the result.
    Figure 6. Toggle Button Added to Figure Window


Add a Button Group in the UI to Set Axes Color

In this section, a control object that groups radio buttons is created to set the axes colors.

  1. Call function uibuttongroup to create a button group. 'string' defines the text to be displayed on the head of the button group. The callback function in uibuttongroup usually refers to the default setup, which will be called during the initialization of the figure UI. 
    handles.bg = uibuttongroup('Parent', fig,'units','normalized', 'Position', [0.02,0.65,0.16,0.15],'string','Axes Color');
  2. Define the callback function 'bg_callback.' Use gca to get the handle of the current axes. Use set() to change the color of the current axes. 'b' refers to the color code of blue. 
    function bg_callback(handle,d)
	a=gca;
	set(a,'xcolor','b','ycolor','b');
end
    Tip: The two radio buttons in the button group will call the same function 'AxesColor.' Radio 1 should pass string 'Blue' to the function and Radio 2 should pass string 'Red' to the function. The callback function sets the axes color according to the string passed into the function. 
    handles.radio1 = uicontrol('Parent', handles.bg, 'Style', 'radio', 'Position', [10 20 100 20],'string','Blue','value',0,'callback','AxesColor');
handles.radio2 = uicontrol('Parent', handles.bg, 'Style', 'radio', 'Position', [10 40 100 20],'string','Red','value',0,'callback','AxesColor');
  3. Define the callback function 'AxesColor.' Use gca to get the handle of the current axes. Variable 'color' stores the string passed by uicontrol. Use strcmp to compare the color strings and set up the axes color correspondingly. 
    function AxesColor(handle,d)
	a=gca;
	color = get(handle,'string');
	if strcmp(color,'Blue')
		set(a,'xcolor','b','ycolor','b');
	elseif strcmp(color,'Red')
		set(a,'xcolor','r','ycolor','r');
	end
end
  4. Run the OML script and check the result.
    Figure 7. Radio Buttons Added to Figure Window


Add a File Selection Dialog in the UI to Set Axes Color

In this section, a control object is created to save the current figure under a user-defined directory.

  1. Add a button as in Add a Pushbutton in the UI. 
    handles.pushbutton = uicontrol('Parent', fig, 'Style', 'pushbutton','units','normalized', 'Position', [0.02,0.8,0.16,0.05],'string','Save Figure as PNG','value',1,'callback','savefile');
  2. Define the callback function 'savefile.' Use uiputfile to open a file selection dialog. This function returns the file name and path of the targeting figure. 'SinePlot.png' defines the default filename and format. Use gcf to get the handle of the current figure. Us saveas to save the figure with the filename and path given by user. disp displays a message in the OML command window. 
    function savefile(handle,d)
	[name,filepath,index] = uiputfile('SinePlot.png');
	f = gcf;
	saveas(f,fullfile(filepath,name),'png');
	msgbox('Finished', 'Save plot');
end
  3. Run the OML script and click the Save Figure as PNG button. A Save As dialog will be displayed. Enter a file name and check if the figure has been saved locally.
    Figure 8. Save As Dialog