Merge pull request #5 from kkppa/master

Add swipe ext function

Author: codematrixer

README.md

@@ -375,7 +375,25 @@ d.swipe(x1, y1, x2, y2, spped)
 d.swipe(600, 2600, 600, 1200, speed=2000)  # 上滑
 d.swipe(0.5, 0.8, 0.5, 0.4, speed=2000)
 ```
-参数`x1`, `y1`表示滑动的起始点，`x2`, `y2`表示滑动的终点，`speed`为滑动速率, 范围:200~40000, 不在范围内设为默认值为2000, 单位: 像素点/秒
+- `x1`, `y1`表示滑动的起始点，`x2`, `y2`表示滑动的终点
+- `speed`为滑动速率, 范围:200~40000, 不在范围内设为默认值为2000, 单位: 像素点/秒
+
+#### 滑动 ext
+```python
+
+d.swipe_ext("up")  # 向上滑动，"left", "right", "up", "down"
+d.swipe_ext("right", scale=0.8)  # 向右滑动，滑动距离为屏幕宽度的80%
+d.swipe_ext("up", box=(0.2, 0.2, 0.8, 0.8))  # 在屏幕 (0.2, 0.2) -> (0.8, 0.8) 这个区域上滑
+
+# 使用枚举作为参数
+from hmdriver2.proto import SwipeDirection
+d.swipe_ext(SwipeDirection.DOWN)  # 向下滑动
+```
+- `direction`表示滑动方向，可以为`up`, `down`, `left`, `right`, 也可以为`SwipeDirection`的枚举值
+- `scale`表示滑动距离百分比，范围:0.1~1.0, 默认值为0.8
+- `box`表示滑动区域，格式为`(x1, y1, x2, y2)`, 表示滑动区域的左上角和右下角的坐标，可以为绝对坐标值，也可以为相当坐标（屏幕百分比）
+  
+Notes: `swipe_ext`和`swipe`的区别在于swipe_ext可以指定滑动区域，并且可以指定滑动方向，更简洁灵活
 
 #### 输入
 ```python
@@ -645,4 +663,4 @@ See [DEVELOP.md](/docs/DEVELOP.md)
 - https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ut-V5
 - https://github.com/codematrixer/awesome-hdc
 - https://github.com/openatx/uiautomator2
-- https://github.com/mrx1203/hmdriver
+- https://github.com/mrx1203/hmdriver

hmdriver2/_swipe.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+
+from typing import Union, Tuple
+
+from .driver import Driver
+from .proto import SwipeDirection
+
+
+class SwipeExt(object):
+    def __init__(self, d: Driver):
+        self._d = d
+
+    def __call__(self,
+                 direction: Union[SwipeDirection, str],
+                 scale: float = 0.8,
+                 box: Union[Tuple, None] = None,
+                 speed=2000):
+        """
+        Args:
+            direction (str): one of "left", "right", "up", "bottom" or SwipeDirection.LEFT
+            scale (float): percent of swipe, range (0, 1.0]
+            box (Tuple): None or (x1, x1, y1, x2, y2)
+            speed (int, optional): The swipe speed in pixels per second. Default is 2000. Range: 200-40000. If not within the range, set to default value of 2000.
+        Raises:
+            ValueError
+        """
+        def _swipe(_from, _to):
+            self._d.swipe(_from[0], _from[1], _to[0], _to[1], speed=speed)
+
+        if scale <= 0 or scale > 1.0 or not isinstance(scale, (float, int)):
+            raise ValueError("scale must be in range (0, 1.0]")
+
+        if box:
+            x1, y1, x2, y2 = self._validate_and_convert_box(box)
+        else:
+            x1, y1 = 0, 0
+            x2, y2 = self._d.display_size
+
+        width, height = x2 - x1, y2 - y1
+
+        h_offset = int(width * (1 - scale) / 2)
+        v_offset = int(height * (1 - scale) / 2)
+
+        if direction == SwipeDirection.LEFT:
+            start = (x2 - h_offset, y1 + height // 2)
+            end = (x1 + h_offset, y1 + height // 2)
+        elif direction == SwipeDirection.RIGHT:
+            start = (x1 + h_offset, y1 + height // 2)
+            end = (x2 - h_offset, y1 + height // 2)
+        elif direction == SwipeDirection.UP:
+            start = (x1 + width // 2, y2 - v_offset)
+            end = (x1 + width // 2, y1 + v_offset)
+        elif direction == SwipeDirection.DOWN:
+            start = (x1 + width // 2, y1 + v_offset)
+            end = (x1 + width // 2, y2 - v_offset)
+        else:
+            raise ValueError("Unknown SwipeDirection:", direction)
+
+        _swipe(start, end)
+
+    def _validate_and_convert_box(self, box: Tuple) -> Tuple[int, int, int, int]:
+        """
+        Validate and convert the box coordinates if necessay.
+
+        Args:
+            box (Tuple): The box coordinates as a tuple (x1, y1, x2, y2).
+
+        Returns:
+            Tuple[int, int, int, int]: The validated and converted box coordinates.
+        """
+        if not isinstance(box, tuple) or len(box) != 4:
+            raise ValueError("Box must be a tuple of length 4.")
+        x1, y1, x2, y2 = box
+        if not (x1 >= 0 and y1 >= 0 and x2 > 0 and y2 > 0):
+            raise ValueError("Box coordinates must be greater than 0.")
+        if not (x1 < x2 and y1 < y2):
+            raise ValueError("Box coordinates must satisfy x1 < x2 and y1 < y2.")
+
+        from .driver import Point
+        p1: Point = self._d._to_abs_pos(x1, y1)
+        p2: Point = self._d._to_abs_pos(x2, y2)
+        x1, y1, x2, y2 = p1.x, p1.y, p2.x, p2.y
+
+        return x1, y1, x2, y2

hmdriver2/driver.py

@@ -313,6 +313,11 @@ def swipe(self, x1, y1, x2, y2, speed=2000):
         api = "Driver.swipe"
         self._invoke(api, args=[point1.x, point1.y, point2.x, point2.y, speed])
 
+    @cached_property
+    def swipe_ext(self):
+        from ._swipe import SwipeExt
+        return SwipeExt(self)
+
     @delay
     def input_text(self, text: str):
         """