Main Content

drag

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

Perform drag gesture on UI component

expand all in page

Syntax

drag(testcase,comp,start,stop)
drag(testcase,compst,start,stop,'SelectionType',type)

Description

example

drag(testcase,comp,start,stop) performs a drag gesture from start to stop on the UI component comp.

example

drag(testcase,compst,start,stop,'SelectionType',type) uses the specified mouse selection type type to perform a drag gesture on the component compst.

Input Arguments

expand all

Instance of the test case, specified as a matlab.uitest.TestCase object.

Component to drag during the test, specified as a UI component object that supports a drag gesture. The components that support drag gestures are axes, continuous knobs, sliders, and figures.

Supported ComponentTypical Creation Function
Axesaxes
Knobuiknob
Slideruislider
UI Axesuiaxes
UI Figureuifigure

Start value of the drag gesture, specified as a numeric scalar or a 1-by-2 or 1-by-3 numeric array. The form of start depends on the UI component:

  • Knob and Slider — A numeric scalar within component limits. Limits are defined by the Limits property of the component.

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

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

Example: 20 (knob)

Example: [2.5 3 1.25] (UI axes)

Example: [100 200] (UI figure)

Stop value of the drag gesture, specified as a numeric scalar or a 1-by-2 or 1-by-3 numeric array. The form of stop depends on the UI component:

  • Knob and Slider — A numeric scalar within component limits. Limits are defined by the Limits property of the component.

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

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

Example: 30 (knob)

Example: [5 3 2.25] (UI axes)

Example: [200 300] (UI figure)

Component to drag 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', or 'alt'. 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.

Data Types: char | string

Examples

expand all

Create a knob.

knob = uiknob;

Create an interactive test case and drag the knob between two values. A blue dot representing the programmatic drag gesture appears and then disappears when the knob reaches the stop value.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.drag(knob,13,42)

Create a slider with a minimum value of -237, a maximum value of 237, and a starting value of 7.

slider = uislider('Limits',[-237 237],'Value',7);

Create an interactive test case and verify the initial value of the slider.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyEqual(slider.Value,7)
Verification passed.

Drag the slider between two values and verify the final value. 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.

val = 26.75;
tc.drag(slider,-val,val)
tc.verifyEqual(slider.Value,val,'AbsTol',0.1)
Verification passed.
Open Script

Create an axes within a UI figure and then plot a line into the axes. In this example, the plot sets both x- and y-axis limits to [1 10].

f = uifigure;
ax = axes(f);
plot(ax,1:10)

Create an interactive test case and drag from the point (3, 2) to the point (4, 2). A blue dot representing the programmatic drag gesture appears at the start value and then disappears when it reaches the stop value. The axis limits are updated based on the difference between the start and stop values.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.drag(ax,[3 2],[4 2])

Verify that the drag gesture reduced the x-axis limits by one unit. Since the framework mimics a user manipulating the component, using a tolerance to compare the actual and expected values is the recommended practice.

tc.verifyEqual(ax.XLim,[0 9],'AbsTol',0.1)

Verification passed.
Open Script

Create an axes within a UI figure and plot a surface into the axes using the peaks function. Then, call the view function to save the azimuth and elevation angles of the camera's line of sight for the axes.

f = uifigure;
ax = axes(f);
surf(ax,peaks)
xlabel(ax,'X')
ylabel(ax,'Y')
zlabel(ax,'Z')
[caz_before,cel_before] = view(ax);

Create an interactive test case and drag from the point (2, 2, -10) to the point (4, 4, 10). A blue dot representing the programmatic drag gesture appears at the start value and then disappears when it reaches the stop value. The view of the surface plot changes with the drag.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.drag(ax,[2 2 -10],[4 4 10])

Verify that the drag gesture changed the view of the surface plot.

[caz_after,cel_after] = view(ax);
tc.verifyNotEqual([caz_after cel_after],[caz_before cel_before])

Verification passed.
Open Live Script

Create an axes within a UI figure and then plot a line into the axes.

f = uifigure;
ax = axes(f);
plot(ax,1:10)

Create an interactive test case and drag on the figure from the point (100, 200) to the point (200, 300) using a right-click. A blue dot representing the programmatic drag gesture appears at the start value and then disappears when it reaches the stop value.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.drag(f,[100 200],[200 300],'SelectionType','alt')

Now, drag on the axes from the point (3, 2) to the point (4, 2) using a left-click. The axis limits are updated based on the difference between the start and stop values.

tc.drag(ax,[3 2],[4 2],'SelectionType','normal')

Version History

Introduced in R2018a

expand all

See Also

|

Topics