Main Content

press

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

Perform press gesture on UI component

Description

example

press(testCase,comp) performs a press gesture on the UI component comp.

example

press(testCase,comp,location) specifies the location to press within the component. You can only specify location with five of the available components: axes, UI axes, polar axes, panel, and UI figure. If you do not specify the location, MATLAB® presses at the center of comp.

example

press(testCase,spn,direction) specifies whether to press the 'up' or 'down' direction button in the spinner spn.

example

press(testCase,compst,'SelectionType',type) uses the specified mouse selection type type to perform a press gesture on the component compst.

example

press(testCase,compst,location,'SelectionType',type) specifies the location to press within the component using the specified mouse selection type.

Input Arguments

expand all

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

Component to press during the test, specified as a UI component object that supports a press gesture. Components that support press gestures include images, buttons, check boxes, switches, menus, axes, and figures.

Supported ComponentTypical Creation Function
Axesaxes
Buttonuibutton
Check Boxuicheckbox
Hyperlinkuihyperlink
Imageuiimage
Menuuimenu
Paneluipanel
Polar Axespolaraxes
Push Tooluipushtool
Radio Buttonuiradiobutton
State Buttonuibutton
Switch (Rocker, Slider, Toggle)uiswitch
Toggle Buttonuitogglebutton
Toggle Tooluitoggletool
UI Axesuiaxes
UI Figureuifigure

Location to press, specified as the coordinates of the point:

  • Axes and UI Axes — A 1-by-2 or 1-by-3 numeric array containing x-, y-, and optionally z-coordinates.

  • Polar Axes — A 1-by-2 numeric array containing θ- and r-coordinates.

  • Panel and UI Figure — A 1-by-2 numeric array containing x- and y-coordinates. Specify the coordinates of the point to press as measured in pixels from the lower-left corner of the component.

Example: [32.5 13 0.25] (UI axes)

Example: [pi/2 0.5] (Polar axes)

Example: [100 200] (UI figure)

Spinner component to press during the test, specified as a matlab.ui.control.Spinner object. Spinner components are typically created with the uispinner function.

Direction of change for the spinner, specified as 'up' or 'down'. To increment the value of the spinner, use 'up'. To decrement the value, use 'down'.

Data Types: char | string

Component to press during the test using a given mouse selection type, specified as a matlab.graphics.axis.Axes, matlab.ui.control.UIAxes, or matlab.ui.Figure object.

Supported ComponentTypical Creation Function
Axesaxes
UI Axesuiaxes
UI Figureuifigure

Mouse selection type, specified as 'normal', 'extend', 'alt', or 'open'. This input provides information about how the mouse button is pressed in the component. For more information, see UI Figure Properties.

This table lists the possible selection type values and the actions that correspond to these values.

Value

Corresponding Action

'normal'

Click the left mouse button.

'extend'

Shift-click the left mouse button.

'alt'

Click the right mouse button.

'open'

Double-click any mouse button.

Data Types: char | string

Attributes

Sealedtrue

To learn about attributes of methods, see Method Attributes.

Examples

expand all

Create a slider switch.

s = uiswitch('slider');

A figure with a slider switch in the 'Off' state

Create an interactive test case and press the switch. A blue dot representing the programmatic push gesture appears and then disappears at the center of the switch. The switch moves from 'Off' to 'On'.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.press(s);

A figure with a slider switch in the 'On' state

Create UI axes and an interactive test case instance.

ax = uiaxes;
tc = matlab.uitest.TestCase.forInteractiveUse;

Press the center of the axes. A blue dot representing the programmatic push gesture appears and then disappears at the center of the axes.

tc.press(ax)

Press the axes at the coordinates (0.85, 0.2). A blue dot representing the programmatic push gesture appears and then disappears at the specified axes coordinates.

tc.press(ax,[0.85 0.2])

Create a state button.

b = uibutton('state');

Create an interactive test case and verify that the value of the state button is false.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyFalse(b.Value)
Verification passed.

Press the button and verify the state changes to true. A blue dot representing the programmatic push gesture appears and then disappears on the button.

tc.press(b)
tc.verifyTrue(b.Value)
Verification passed.

Create a spinner with an initial value of 42.

s = uispinner('Value',42);
initVal = s.Value;

Create an interactive test case and increment the spinner. Verify that the new value of the spinner is the initial value plus the spinner step value.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.press(s,'up')
tc.verifyEqual(s.Value,initVal+s.Step)
Verification passed.

Decrement the value of the spinner and verify that the value of the spinner is equal to the initial value again.

tc.press(s,'down')
tc.verifyEqual(s.Value,initVal)
Verification passed.

Create a UI figure and an interactive test case instance.

f = uifigure;
tc = matlab.uitest.TestCase.forInteractiveUse;

Test a right-click at the center of the UI figure. A blue dot representing the programmatic push gesture appears and then disappears at the center of the figure.

tc.press(f,'SelectionType','alt')

Test a double-click on the UI figure at the coordinates (100, 200). A blue dot representing the programmatic push gesture appears and then disappears at the specified location.

tc.press(f,[100 200],'SelectionType','open')

Since R2023b

Perform a gesture on a component that is not in the viewable area of a figure by automatically scrolling to the component.

Create a scrollable figure with a state button that is outside the viewable area of the figure.

fig = uifigure("Scrollable","on");
b = uibutton(fig,"state","Position",[fig.Position(3)+100 100 100 22]);

Create a test case for interactive testing, and verify the initial state of the button.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyFalse(b.Value)
Verification passed.

Press the button and verify that its state changes. Because the figure is scrollable, the app testing framework automatically scrolls to the button before performing the gesture.

tc.press(b)
tc.verifyTrue(b.Value)
Verification passed.

Version History

Introduced in R2018a

expand all