a
    §ˆc×.  ã                   @   sv   d Z ddlmZ ddlZddlmZ ddlmZ	 ddl
mZ ddlmZmZ G dd	„ d	ƒZed
d„ ƒZedd„ ƒZdS )zÄ Define the top-level object which is responsible for dispatching testing
functionality for a given GUI object. The functionality is exposed via
``UITester``, which is a TraitsUI specific tester.
é    )ÚcontextmanagerN)Úreraise_exceptions)Úprocess_cascade_events)Úlocator)ÚInteractionNotSupportedÚLocationNotSupportedc                   @   s`   e Zd ZdZdddœdd„Zdd„ Zd	d
„ Zdd„ Zdd„ Zdd„ Z	dd„ Z
dd„ Zdd„ ZdS )Ú	UIWrappera©	  
    An ``UIWrapper`` has the following responsibilities:

    (1) Wraps a UI target.
    (2) Search for a nested UI target within the wrapped UI target.
    (3) Perform user interaction on the UI target, e.g. mouse click.

    A UI target is an object which can be searched for nested UI targets,
    either as intermediate things (like editors or a table widget), or as a
    leaf widget which can be operated upon (e.g. a mouse click).

    For example, a ``UIWrapper`` may wrap an instance of traitsui.ui.UI in
    which more UI targets can be located. A ``UIWrapper`` may also wrap a
    leaf widget on which user interactions can be performed.

    For locating a nested UI target, the ``locate`` method is provided.
    For simulating user interactions such as a mouse click or visual
    inspection, the ``perform`` and ``inspect`` methods are provided.

    Parameters
    ----------
    target : any
        An object on which further UI target can be searched for, or can be
        a leaf target that can be operated on.
    registries : list of AbstractTargetRegistry
        Registries of interaction for different target, in the order
        of decreasing priority.
    delay : int, optional
        Time delay (in ms) in which actions by the wrapper are performed. Note
        it is propagated through to created child wrappers. The delay allows
        visual confirmation test code is working as desired. Defaults to 0.
    auto_process_events : bool, optional
        Whether to process (cascade) GUI events automatically. Default is True.
        For tests that launch a modal dialog and rely on a recurring timer to
        poll if the dialog is closed, it may be necessary to set this flag to
        false in order to avoid deadlocks. Note that this is propagated
        through to created child wrappers.

    Attributes
    ----------
    delay : int
        Time delay (in ms) in which actions by the wrapper are performed. Note
        it is propagated through to created child wrappers. The delay allows
        visual confirmation test code is working as desired.
    _target : any
        The UI target currently wrapped for interactions or locating nested
        components. This is a protected attribute intended to be used for
        extending the testing API. Usage of this attribute may expose the
        software's internal structure to the tests, developers should use this
        attribute with discretion based on context.
    r   T)ÚdelayÚauto_process_eventsc                C   s   || _ || _|| _|| _d S )N)Ú_targetÚ_registriesÚ_auto_process_eventsr	   )ÚselfÚtargetÚ
registriesr	   r
   © r   úe/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/traitsui/testing/tester/ui_wrapper.pyÚ__init__U   s    zUIWrapper.__init__c                 C   s,  t ƒ }t ƒ }| jddd… D ]P}| | j¡D ]}|j| j|d�||< q,| | j¡D ]}|j| j|d�||< qRqtdƒ tdƒ t|t	d�D ],}tt	|ƒƒ tt
j|| dd	�ƒ tƒ  qŠ|sÊtd
ƒ tƒ  tdƒ tdƒ t|t	d�D ],}tt	|ƒƒ tt
j|| dd	�ƒ tƒ  qæ|�s(tdƒ tƒ  dS )zVPrint help messages.
        (This function is intended for interactive use.)
        Néÿÿÿÿ)r   Úinteraction_class)r   Úlocator_classZInteractionsz------------)Úkeyz    )ÚprefixzNo interactions are supported.Z	Locationsz	---------zNo locations are supported.)Údictr   Z_get_interactionsr   Z_get_interaction_docZ_get_locationsZ_get_location_docÚprintÚsortedÚreprÚtextwrapÚindent)r   Zinteraction_to_docZlocation_to_docÚregistryÚtype_Zinteraction_typeZlocator_typer   r   r   Úhelp]   sJ    þþÿÿÿzUIWrapper.helpc                 C   s   t |  |¡| j| j| jd�S )a*  Attempt to resolve the given location and return a new
        UIWrapper.

        Parameters
        ----------
        location : any
            An instance of a location type supported by the current target.
            e.g. ``traitsui.testing.api.Index(1)``

        Returns
        -------
        wrapper : UIWrapper
            A new UIWrapper for the given location.

        Raises
        ------
        LocationNotSupported
            If the given location is not supported.

        See Also
        --------
        UIWrapper.help
        )r   r   r	   r
   )r   Ú_get_next_targetr   r	   r   )r   Úlocationr   r   r   Úlocate‘   s    üzUIWrapper.locatec                 C   s   |   tj|d�¡S )a2  Find a target inside the current target using a name.

        This is equivalent to calling ``locate(TargetByName(name=name))``.

        Parameters
        ----------
        name : str
            A single name for retreiving a target on a UI.

        Returns
        -------
        wrapper : UIWrapper

        Raises
        ------
        LocationNotSupported
            If the current target does not support locating another target
            by a name.

        See Also
        --------
        traitsui.testing.tester.locator.TargetByName
        )Úname)r$   r   ZTargetByName)r   r%   r   r   r   Úfind_by_name°   s    zUIWrapper.find_by_namec                 C   s   |   tj|d�¡S )a'  Find a target inside the current target using an id.

        This is equivalent to calling ``locate(TargetById(id=id))``.

        Parameters
        ----------
        id : str
            Id for finding an item in the UI.

        Returns
        -------
        wrapper : UIWrapper

        Raises
        ------
        LocationNotSupported
            If the current target does not support locating another target
            by a unique identifier.

        See Also
        --------
        traitsui.testing.tester.locator.TargetById
        )Úid)r$   r   Z
TargetById)r   r'   r   r   r   Ú
find_by_idÊ   s    zUIWrapper.find_by_idc                 C   s   |   |¡ dS )aÞ  Perform a user interaction that causes side effects.

        Parameters
        ----------
        interaction : object
            An instance of an interaction type supported by the current target.
            e.g. ``traitsui.testing.api.MouseClick()``

        Raises
        ------
        InteractionNotSupported
            If the interaction given is not supported for the current UI
            target.

        See Also
        --------
        UIWrapper.help
        N©Ú_perform_or_inspect©r   Úinteractionr   r   r   Úperformä   s    zUIWrapper.performc                 C   s
   |   |¡S )a�  Return a value or values for inspection.

        Parameters
        ----------
        interaction : object
            An instance of an interaction type supported by the current target.
            e.g. ``traitsui.testing.api.DisplayedText()``

        Returns
        -------
        values : any
            Any values returned for the given inspection. The type should be
            documented by the interaction type object.

        Raises
        ------
        InteractionNotSupported
            If the interaction given is not supported for the current UI
            target.

        See Also
        --------
        UIWrapper.help
        r)   r+   r   r   r   Úinspectù   s    zUIWrapper.inspectc                 C   s¼   g }| j D ]˜}z|j| j|d�}W n< ty^ } z$| |j¡ W Y d}~q
W Y d}~q
d}~0 0 | jrjtnt}|ƒ � || |ƒW  d  ƒ   S 1 s˜0    Y  q
t| jj	|j	|d�‚dS )a°  Perform a user interaction or a user inspection.

        Parameters
        ----------
        interaction : instance of interaction type
            An object defining the interaction.

        Returns
        -------
        value : any

        Raises
        ------
        InteractionNotSupported
            If the given interaction does not have a corresponding
            implementation for the wrapped UI target.
        )r   r,   N)Útarget_classr   Ú	supported)
r   Ú_get_handlerr   r   Úextendr0   r   Ú_event_processedÚ_nullcontextÚ	__class__)r   r,   r0   r   ÚhandlerÚeÚcontextr   r   r   r*     s*    
þ
"ÿý.ýzUIWrapper._perform_or_inspectc                 C   s¶   t ƒ }| jD ]Œ}z|j| j|d�}W n2 tyV } z|t |jƒO }W Y d}~qd}~0 0 | jrŠtƒ � tƒ  W d  ƒ n1 s€0    Y  || |ƒ  S qt| jj	|j	t
|ƒd�‚dS )a¥  Return the next UI target from the given location.

        Parameters
        ----------
        location : instance of locator type
            A location for resolving the next target.

        Returns
        -------
        new_target : any

        Raises
        ------
        LocationNotSupport
            If no solver are provided for resolving the given location in the
            wrapped UI target.
        )r   r#   N)r/   r   r0   )Úsetr   Z_get_solverr   r   r0   r   Ú_reraise_exceptionsÚ_process_cascade_eventsr5   Úlist)r   r#   r0   r   r6   r7   r   r   r   r"   A  s$    
þ
$$ýzUIWrapper._get_next_targetN)Ú__name__Ú
__module__Ú__qualname__Ú__doc__r   r!   r$   r&   r(   r-   r.   r*   r"   r   r   r   r   r       s   5ÿ4+r   c                   c   sJ   t ƒ �0 tƒ  zdV  W tƒ  ntƒ  0 W d  ƒ n1 s<0    Y  dS )zbContext manager to ensure GUI events are processed upon entering
    and exiting the context.
    N)r:   r;   r   r   r   r   r3   i  s
    r3   c                   c   s
   dV  dS )z7Equivalent to contextlib.nullcontext() in Python >= 3.7Nr   r   r   r   r   r4   v  s    r4   )r@   Ú
contextlibr   r   Z$traitsui.testing._exception_handlingr   r:   Ztraitsui.testing._guir   r;   Ztraitsui.testing.testerr   Z"traitsui.testing.tester.exceptionsr   r   r   r3   r4   r   r   r   r   Ú<module>   s     K
