drag
Class: matlab.uitest.TestCase
Namespace: matlab.uitest
Perform drag gesture on UI component
Description
Input Arguments
Test case, specified as a matlab.uitest.TestCase
object.
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)
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 |
---|---|
| Click the left mouse button. |
| Shift-click the left mouse button. |
| Click the right mouse button. |
Data Types: char
| string
Examples
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.
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 R2018aYou can specify the location of the gesture on a UI figure that uses any unit of measurement.
In previous releases, the method lets you specify coordinates only for figures whose
Units
property is set to "pixels"
.
Specifying the location of the gesture on axes or UI axes with an active right y-axis is no longer supported. If your chart has two y-axes, activate the side associated with the left y-axis before performing the gesture. In previous releases, when you specify the location on axes or UI axes with an active right side, the app testing framework interprets that location with respect to the left y-axis, which can cause the gesture to occur at an unexpected location or fail.
You can perform drag gestures in tests on UI figures. Additionally, when you test
a drag gesture on an axes, UI axes, or UI figure component, you can specify the
mouse selection type. To specify the mouse selection type, use the type
input argument.
You can perform drag gestures in tests on axes and UI axes. When you test a drag gesture on an axes or UI axes component, the app testing framework mimics a user manipulating the component and adjusts the axes limits based on the difference between the start and stop values.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: United States.
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)