drag
Class: matlab.uitest.TestCase
Namespace: matlab.uitest
Perform drag gesture on UI component
Description
Input Arguments
testCase
— Test case
matlab.uitest.TestCase
object
Test case, specified as a matlab.uitest.TestCase
object.
comp
— Component to drag
UI component object
start
— Start value
numeric scalar | 1-by-2 or 1-by-3 numeric array
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
— Stop value
numeric scalar | 1-by-2 or 1-by-3 numeric array
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)
compst
— Component to drag using mouse selection type
matlab.graphics.axis.Axes
object | matlab.ui.control.UIAxes
object | matlab.ui.Figure
object
type
— Mouse selection type
'normal'
(default) | 'extend'
| 'alt'
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 |
---|---|
| Click the left mouse button. |
| Shift-click the left mouse button. |
| Click the right mouse button. |
Data Types: char
| string
Examples
Drag Knob Between Values
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)
Drag Slider and Verify Stop Value
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.
testCase = matlab.uitest.TestCase.forInteractiveUse; testCase.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;
testCase.drag(slider,-val,val)
testCase.verifyEqual(slider.Value,val,"AbsTol",0.1)
Verification passed.
Drag on Figure with Specified Selection Type
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 R2018aR2024b: Specify location of gesture on figures that use nonpixel units
You 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"
.
R2024b: Specifying location of gesture on axes or UI axes with active right y-axis is not supported
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.
R2021b: Perform gestures on axes and figures with different selection types
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.
R2020b: Perform gestures on axes and UI axes
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: .
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)