"""
设备操作接口定义。
"""
from typing import Protocol, Optional, Union, TYPE_CHECKING

if TYPE_CHECKING:
    from ..models import OSType

from ..models import DeviceButton


class IDeviceOperations(Protocol):
    """
    设备操作接口协议。
    
    Agent 需要的设备操作方法接口定义。
    Device 类需要实现此协议的所有方法。
    """
    
    def screenshot_base64(
        self,
        crop: Optional[tuple] = None,
        trace_id: Optional[str] = None
    ) -> str:
        """
        对设备当前画面进行截图，返回base64编码的图片数据。
        
        Args:
            crop: 裁剪参数（可选），可以是 Tuple[Union[int, float], ...] 格式
            trace_id: 追踪ID（可选）
        
        Returns:
            str: 图片base64编码字符串
        """
        ...
    
    def current_app(self, trace_id: Optional[str] = None) -> str:
        """
        获取当前应用。
        
        Args:
            trace_id: 追踪ID（可选）
        
        Returns:
            str: 当前应用的包名或bundle ID
        """
        ...
    
    def start_app(self, pkg: str, clear_data: bool = False, trace_id: Optional[str] = None, **kwargs) -> bool:
        """
        启动应用。
        
        Args:
            pkg: 应用包名或bundle ID
            clear_data: 是否清除应用数据（可选）
            trace_id: 追踪ID（可选）
            **kwargs: 其他扩展参数
        
        Returns:
            bool: 启动是否成功
        """
        ...
    
    def click_pos(self, pos: Union[list, tuple], duration: float = 0.05, times: int = 1, trace_id: Optional[str] = None) -> bool:
        """
        基于坐标进行点击操作。
        
        Args:
            pos: 坐标 [x, y]
            duration: 点击持续时间（秒）
            times: 点击次数
            trace_id: 追踪ID（可选）
        
        Returns:
            bool: 点击是否成功
        """
        ...
    
    def input_text(self, text: str, timeout: int = 30, depth: int = 10, trace_id: Optional[str] = None) -> bool:
        """
        向设备输入文本内容。
        
        Args:
            text: 待输入的文本
            timeout: 超时时间
            depth: source tree 的最大深度值
            trace_id: 追踪ID（可选）
        
        Returns:
            bool: 输入是否成功
        """
        ...
    
    def slide_pos(
        self,
        pos_from: Union[list, tuple],
        pos_to: Optional[Union[list, tuple]] = None,
        down_duration: float = 0,
        slide_duration: float = 0.3,
        trace_id: Optional[str] = None
    ) -> bool:
        """
        基于坐标执行滑动操作。
        
        Args:
            pos_from: 滑动起始坐标 [x, y]
            pos_to: 滑动结束坐标 [x, y]
            down_duration: 起始位置按下时长（秒）
            slide_duration: 滑动时间（秒）
            trace_id: 追踪ID（可选）
        
        Returns:
            bool: 滑动是否成功
        """
        ...
    
    def press(self, name: DeviceButton, trace_id: Optional[str] = None) -> bool:
        """
        执行设备功能键操作。
        
        Args:
            name: 设备按键类型
            trace_id: 追踪ID（可选）
        
        Returns:
            bool: 操作是否成功
        """
        ...
    
    @property
    def os_type(self) -> "OSType":
        """
        获取设备操作系统类型。
        
        Returns:
            OSType: 设备操作系统类型（ANDROID、IOS 或 HM）
        """
        ...