choose

Class: matlab.uitest.TestCase
Namespace: matlab.uitest

Perform choose gesture on UI component

Syntax

choose(testCase,comp,option)

choose(testCase,compNoOpts)

choose(testCase,uit,indices)

choose(testCase,uit,indices,option)

choose(testCase,uit,indices,'SelectionMode',mode)

Description

choose(testCase,comp,option) performs a choose gesture on the specified item on the UI component comp.

choose(testCase,compNoOpts) performs a choose gesture on a UI component that does not require additional information, such as a tab or a tree node. For example, use this syntax to choose a specific tab, but use the previous syntax to choose a particular tab from a tab group.

choose(testCase,uit,indices) performs a choose gesture on the uneditable table cell specified by indices within the table UI component uit.

choose(testCase,uit,indices,option) performs a choose gesture on the editable table cell specified by indices. The method uses option to modify the contents of the cell.

choose(testCase,uit,indices,'SelectionMode',mode) uses the given selection mode to choose multiple cells specified by indices within the table UI component uit.

Input Arguments

testCase — Test case

matlab.uitest.TestCase object

Test case, specified as a matlab.uitest.TestCase object.

comp — Component to choose

UI component object

Component to choose during test, specified as a UI component object that supports a choose gesture. Components that support choose gestures include check boxes, knobs, switches, and drop-down lists.

Supported Component	Typical Creation Function
Button Group	uibuttongroup
Check Box	uicheckbox
Discrete Knob	uiknob
Drop Down	uidropdown
Knob	uiknob
List Box	uilistbox
Radio Button	uiradiobutton
Slider	uislider
State Button	uibutton
Switch (Rocker, Slider, Toggle)	uiswitch
Tab Group	uitabgroup
Toggle Button	uitogglebutton
Toggle Tool	uitoggletool

option — Item to choose within component

depends on component

Item to choose within the UI component. The data type of option depends on the type of component being tested. For example, if the component is a switch, option is a text or numeric value from the Items property of the switch. If the component is a check box or toggle tool, option is a logical value. For a table UI component with editable cells, option could be a logical value or a drop-down item corresponding to the data contained in the cell.

When a component has an Items property, option can be the value of an element in Items or an index to an element in Items. For example, for a default discrete knob, you can choose 'Medium' using a value for option that is either 'Medium' or 3.

compNoOpts — Component to choose without options

UI component object

Component to choose, specified as a UI component object that supports a choose gesture and does not require additional information. Components that support choose gestures include tabs and tree nodes.

Supported Component	Typical Creation Function
Tab	uitab
Tree Node	uitreenode

uit — Target table UI component

matlab.ui.control.Table object

Target table UI component, specified as a matlab.ui.control.Table object. Table UI components are created with the uitable function.

indices — Indices of table cells to choose

N-by-2 array

Indices of table cells to choose, specified as an N-by-2 array. The shape of indices depends on the type of cell selection:

• Discontiguous selection of one or more cells — An N-by-2 matrix, where N is the number of cells to choose. Each matrix row corresponds to the row and column indices of a cell to choose.

• Contiguous selection of multiple cells — A 2-by-2 matrix specifying the boundaries of the block of cells to choose. Each matrix row corresponds to the row and column indices of a cell. The app testing framework performs a choose gesture on the specified cells as well as all cells between them.

Example: [1 2] (single cell selection)

Example: [2 3; 2 4; 5 1] (discontiguous selection of three cells)

Example: [1 1; 3 3] (contiguous selection of nine cells)

mode — Cell selection mode

'discontiguous' (default) | 'contiguous'

Cell selection mode, specified as 'discontiguous' or 'contiguous'. This input provides information about how cells are chosen within the table UI component:

• 'discontiguous' — The app testing framework performs a choose gesture on only the cells specified by the indices input argument.

• 'contiguous' — The app testing framework performs a choose gesture on the cells specified by the indices input argument and all cells between them.

For more information about table cell selection, see Table.

Attributes

Sealed

true

To learn about attributes of methods, see Method Attributes.

Examples

Choose Value on Discrete Knob

Create a discrete knob.

knob = uiknob('discrete');

Create an interactive test case and choose the 'High' knob value. An animated blue dot performs the programmatic choose gesture.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(knob,'High')

View the value of the Items property on the knob.

knob.Items

ans =

  1×4 cell array

    {'Off'}    {'Low'}    {'Medium'}    {'High'}

Choose the 'Low' knob value by index. The knob moves from 'High' to 'Low'.

tc.choose(knob,2)

Choose Multiple Items in List Box

Create a list box and enable multiple node selection.

listbox = uilistbox('Multiselect','on')

listbox = 

  ListBox (Item 1) with properties:

              Value: {'Item 1'}
              Items: {'Item 1'  'Item 2'  'Item 3'  'Item 4'}
          ItemsData: []
        Multiselect: 'on'
    ValueChangedFcn: ''
           Position: [100 100 100 74]

  Show all properties

Create an interactive test case and choose items 1 through 3.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(listbox,1:3)

Choose items 1 and 3 using the values of the Items property.

tc.choose(listbox,{'Item 1','Item 3'})

Choose Slider Value and Verify Change

Create a slider.

s = uislider;

Create an interactive test case and verify that the value of the slider button is 0.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyEqual(s.Value,0)

Verification passed.

Choose a new slider value and verify the slider value changes. Since the framework mimics a user manipulating the component to an arbitrarily precisioned value, it is a best practice to use a tolerance to compare the actual and expected slider values.

expVal = 42;
tc.choose(s,expVal)
tc.verifyEqual(s.Value,expVal,'AbsTol',0.1)

Verification passed.

Choose Tab from Group and Verify Change

Create a figure with two tabs.

fig = uifigure;
group = uitabgroup(fig);
tab1 = uitab(group,'Title','Tab #1');
tab2 = uitab(group,'Title','Tab #2');

Create an interactive test case and verify that the selected tab title contains the substring '#1'.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifySubstring(group.SelectedTab.Title,'#1')

verification passed.

Choose tab 2 and verify that the selected tab changes.

tc.choose(group,'Tab #2')
tc.verifyEqual(group.SelectedTab,tab2)

Verification passed.

Choose a Single Table Cell

Create a table UI component that contains a mixture of different data types. Set the ColumnEditable property so that users can edit the data in the last column.

fig = uifigure;
uit = uitable(fig);
d = {'Male',52,true;'Male',40,true;'Female',25,false};
uit.Data = d;
uit.ColumnName = {'Gender','Age','Authorized'};
uit.ColumnEditable = [false false true];

Create an interactive test case and choose the table cell with indices (2,2).

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(uit,[2 2])

Clear the check box in the table cell with indices (1,3).

tc.choose(uit,[1 3],false)

Choose Multiple Table Cells

Create a table UI component that displays a 10-by-3 array of random integers.

fig = uifigure;
uit = uitable(fig,'Data',randi(100,10,3));

Create an interactive test case and choose the cells with indices (1,1) and (3,3).

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(uit,[1 1; 3 3],'SelectionMode','discontiguous')

Now, choose the cells with indices (1,1) and (3,3) and all cells in between these cells.

tc.choose(uit,[1 1; 3 3],'SelectionMode','contiguous')

Version History

Introduced in R2018a

R2024a: Node expanded callback executes when gestures programmatically expand tree nodes

To better mimic a user who must expand tree nodes to interact with a nested node, the node expanded callback executes when you perform a gesture on a collapsed tree node by using the choose method. You can specify the callback by setting the NodeExpandedFcn property of the tree.

For example, perform a choose gesture on a nested node in a tree, and display the text of any programmatically expanded nodes.

fig = uifigure;
t = uitree(fig);
t.NodeExpandedFcn = @(src,event) disp(event.Node.Text);

parent = uitreenode(t,"Text","Runners");
child1 = uitreenode(parent,"Text","Joe");
child2 = uitreenode(parent,"Text","Linda");

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.choose(child2)

If you do not want the callback to execute, preserving the behavior in R2023b and earlier, expand the tree node before performing the gesture. In this code, the callback does not execute.

fig = uifigure;
t = uitree(fig);
t.NodeExpandedFcn = @(src,event) disp(event.Node.Text);

parent = uitreenode(t,"Text","Runners");
child1 = uitreenode(parent,"Text","Joe");
child2 = uitreenode(parent,"Text","Linda");

testCase = matlab.uitest.TestCase.forInteractiveUse;
expand(parent)
testCase.choose(child2)

R2021a: Perform gestures on table UI components

You can perform choose gestures in tests on table UI components. The choose method has new syntaxes to test a choose gesture on a single table cell or multiple table cells.

R2020b: Perform gestures on toggle tools

You can perform choose gestures in tests on toggle tools.

R2020b: Indexing order has changed in choose gestures within button groups

When you choose a radio button or toggle button using an index, the app testing framework indexes into the Buttons property of the ButtonGroup object. In previous releases, the framework indexes into the Children property of the ButtonGroup object. For example, create a button group that has six toggle buttons:

f = uifigure;
bg = uibuttongroup(f);
tb1 = uitogglebutton(bg,'Position',[11 165 140 22],'Text','One');
tb2 = uitogglebutton(bg,'Position',[11 140 140 22],'Text','Two');
tb3 = uitogglebutton(bg,'Position',[11 115 140 22],'Text','Three');
tb4 = uitogglebutton(bg,'Position',[11 90 140 22],'Text','Four');
tb5 = uitogglebutton(bg,'Position',[11 65 140 22],'Text','Five');
tb6 = uitogglebutton(bg,'Position',[11 40 140 22],'Text','Six');

This table shows the outcome of the choose gesture on a toggle button that is specified with index 2:

Test	Starting in R2020b	R2020a and Earlier
tc = matlab.uitest.TestCase.forInteractiveUse; tc.choose(bg,2)	MATLAB® chooses toggle button tb2, which is the second element of the bg.Buttons array. The tc.choose(bg,2) syntax is equivalent to tc.choose(bg,'Two').	MATLAB chooses toggle button tb5, which is the second element of the bg.Children array. The tc.choose(bg,2) syntax is equivalent to tc.choose(bg,'Five').