drag

Class: matlab.uitest.TestCase
Namespace: 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

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.

example

Input Arguments

expand all

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 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 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 Figure.

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

Attributes

Sealedtrue

To learn about attributes of methods, see Method Attributes.

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.

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

Programmatically drag on a slider UI component and verify the final value of the slider.

Create a slider with a minimum value of –10, a maximum value of 10, a step size of 0.1, and an initial value of 5. The Step name-value argument restricts the valid values to increments of the specified step size from the slider minimum. (since R2025a)

slider = uislider(Limits=[-10 10],Step=0.1,Value=5);

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

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.verifyEqual(slider.Value,5)
Verification passed.

Test a drag gesture on the slider and verify the final value. Because the framework mimics a user dragging the slider thumb to an arbitrarily precisioned value, it is a best practice to use a tolerance when comparing the actual and expected slider values.

x = 7.5;
testCase.drag(slider,-x,x)
testCase.verifyEqual(slider.Value,x,AbsTol=0.1)
Verification passed.
Open Live Script

Test a drag gesture on a figure whose background color changes based on the mouse selection type.

Create a UI figure whose background color changes when dragged on using a nondefault mouse selection type. To program the figure behavior, create a window button motion callback for the figure by specifying its WindowButtonMotionFcn callback property. See the code of the callback function changeColor, which is used to change the background color based on the selection type, at the end of this example.

fig = uifigure(Color="white", ...
    WindowButtonMotionFcn=@(src,~)changeColor(src));

Create an interactive test case, and use it to verify that the figure background color is white, or [1 1 1].

testCase = matlab.uitest.TestCase.forInteractiveUse;
testCase.verifyEqual(fig.Color,[1 1 1])
Verification passed.

Test a drag gesture on the figure from the point (100, 200) to the point (200, 300) using a right-click. The gesture sets the SelectionType property of the figure to 'alt'. The gesture also executes the callback, which sets the figure background color based on the SelectionType property value.

testCase.drag(fig,[100 200],[200 300],"SelectionType","alt")

Test if the background color is now green, or [0 1 0]. The test passes.

testCase.verifyEqual(fig.Color,[0 1 0])
Verification passed.

Callback Function

This code shows the callback function used in this example. The function queries the SelectionType property of the figure to identify the mouse selection type.

function changeColor(fig)
switch fig.SelectionType
    case 'extend'   % using shift-click to drag
        fig.Color = "red";
    case 'alt'  % using right-click to drag
        fig.Color = "green";
end
end

Version History

Introduced in R2018a

expand all

See Also

Functions

Topics