Main Content

choose

Class: matlab.uitest.TestCase
Package: matlab.uitest

Perform choose gesture on UI component

Description

example

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.

example

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

example

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

example

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

expand all

Instance of the test case, specified as a matlab.uitest.TestCase 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 ComponentTypical Creation Function
Button Groupuibuttongroup
Check Boxuicheckbox
Discrete Knobuiknob
Drop Downuidropdown
Knobuiknob
List Boxuilistbox
Radio Buttonuiradiobutton
Slideruislider
State Buttonuibutton
Switch (Rocker, Slider, Toggle)uiswitch
Tab Groupuitabgroup
Toggle Buttonuitogglebutton
Toggle Tooluitoggletool

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.

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 ComponentTypical Creation Function
Tabuitab
Tree Nodeuitreenode

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

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

  • Selection of a single cell — A 1-by-2 vector corresponding to the row and column indices of the 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.

  • Discontiguous selection of multiple 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.

Example: [1 2] (single cell selection)

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

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

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

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

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

For more information about table cell selection, see Table Properties.

Examples

expand all

Create a discrete knob.

knob = uiknob('discrete');

A figure with a discrete knob. The knob value is 'Off'.

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')

A figure with a discrete knob. The knob value is '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)

A figure with a discrete knob. The knob value is 'Low'.

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

A figure with a list box that has four items. Item 1 is chosen.

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

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

A figure with a list box that has four items. Items 1 through 3 are chosen.

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

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

A figure with a list box that has four items. Items 1 and 3 are chosen.

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.

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.

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)

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')

Compatibility Considerations

expand all

Behavior changed in R2020b

Introduced in R2018a