:mod:`dip.automate`
===================
.. module:: dip.automate

The :mod:`dip.automate` module contains a collection of classes that allow
a PyQt application to be automated.

At the moment support is limited to programmatically simulating the actions of
a user so automation scripts must be developed manually.  However the
simulation is defined at a very abstract level and is independent of any
particular :term:`toolkit`.


:class:`AutomationCommands`
---------------------------
.. class:: AutomationCommands

    Base class: :class:`~dip.model.Model`

    The AutomationCommands class is the base class for recording a sequence
    of commands to automate part of an application.

    .. attribute:: sequence = Int()

        The sequence number that defines the order in which this instance was
        created relative to other instances.  This is used to ensure that
        automation commands defined in the same .py file are applied in the order
        that they are created in the file.

    .. attribute:: value = Any()

        An optional value that can be passed to __init__ and used by record().

    .. method:: AutomationCommands.__init__(value=None)

        Initialise the object. 

    .. method:: AutomationCommands.record(robot)

        Record a sequence of automation commands for a user interface using
        a robot.
        
        :param robot:
            is the :class:`~dip.automate.Robot` to use to record the commands.


:exc:`AutomationError`
----------------------
.. exception:: AutomationError

    Base exception: :class:`~builtins.Exception`

    The AutomationError exception is raised when an automated command
    cannot be executed.


:class:`IAutomated`
-------------------
.. class:: IAutomated

    Base class: :class:`~dip.model.Interface`

    The IAutomated interface is the base interface for all interfaces that
    define the APIs of automated items.


:class:`IAutomatedActionTrigger`
--------------------------------
.. class:: IAutomatedActionTrigger

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedActionTrigger interface defines the API of automated
    widgets that trigger actions.

    .. method:: IAutomatedActionTrigger.simulate_trigger(id, delay, action_id)

        Simulate the user triggering an action.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param action_id:
            is the identifier of the action.


:class:`IAutomatedDialog`
-------------------------
.. class:: IAutomatedDialog

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedDialog interface defines the API of automated dialogs.
        

    .. method:: IAutomatedDialog.simulate_click(id, delay, button)

        Simulate the user clicking a button.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param button:
            is the button to click.


:class:`IAutomatedEditor`
-------------------------
.. class:: IAutomatedEditor

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedEditor interface defines the API of automated editors.
        

    .. method:: IAutomatedEditor.simulate_set(id, delay, value)

        Simulate the user setting the editor value.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param value:
            is the value to set.


:class:`IAutomatedListEditor`
-----------------------------
.. class:: IAutomatedListEditor

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedListEditor interface defines the API of automated editors
    that handle lists.

    .. method:: IAutomatedListEditor.simulate_select(id, delay, index)

        Simulate the user selecting an item.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param index:
            is the index of the item.

    .. method:: IAutomatedListEditor.simulate_set(id, delay, value, index=None)

        Simulate the user setting the editor value for an item.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param value:
            is the value to set.
        :param index:
            is the index of the item.  If this is ``None`` then it is assumed
            that an editor has already been opened for the item.


:class:`IAutomatedShell`
------------------------
.. class:: IAutomatedShell

    Base class: :class:`~dip.automate.IAutomatedActionTrigger`

    The IAutomatedShell interface defines the API of automated shells. 


:class:`IAutomatedTableEditor`
------------------------------
.. class:: IAutomatedTableEditor

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedTableEditor interface defines the API of automated
    editors that handle tables.

    .. method:: IAutomatedTableEditor.simulate_select(id, delay, row, column)

        Simulate the user selecting an item.
        
        :param id:
            is the (possibly scoped) identifier of the widget.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param row:
            is the row of the item.
        :param column:
            is the column of the item.

    .. method:: IAutomatedTableEditor.simulate_set(id, delay, value, row=None, column=None)

        Simulate the user setting the editor value for an item.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param value:
            is the value to set.  If this is a list or a tuple, and the
            ``column`` parameter is not set, then it is assumed to contain the
            values for the whole row.
        :param row:
            is the row of the item.  If it is ``None`` then it is assumed that
            an editor has already been opened for the item.
        :param column:
            is the column of the item.


:class:`IAutomatedTrigger`
--------------------------
.. class:: IAutomatedTrigger

    Base class: :class:`~dip.automate.IAutomated`

    The IAutomatedTrigger interface defines the API of automated editors
    that handle triggers.

    .. method:: IAutomatedTrigger.simulate_trigger(id, delay)

        Simulate the user pulling the trigger.
        
        :param id:
            is the (possibly scoped) identifier of the widget.  This is
            normally used in exceptions.
        :param delay:
            is the delay in milliseconds between simulated events.


:class:`Robot`
--------------
.. class:: Robot

    Base class: :class:`~dip.model.Model`

    The Robot class manages the automation commands that can be executed by
    a user interface.

    .. attribute:: delay = Int(-1)

        The default delay in milliseconds between the playing of individual
        automation commands.

    .. attribute:: timeout = Int(-1)

        The default time in milliseconds to wait for a user interface widget to
        be visible.

    .. method:: Robot.clear()

        Any recorded automation commands are discarded. 

    .. method:: Robot.play(after=-1)

        Any recorded automation commands are executed.
        
        :param after:
            is the delay in milliseconds after the start of an event loop
            before the commands are executed.  If the value is negative then
            the commands are played immediately without waiting for an event
            loop to start.

    .. method:: Robot.record(id, command, *command_args, delay=-1, timeout=-1)

        Record an automation command.
        
        :param id:
            is the (possibly scoped) identifier of the widget to apply the
            command to.
        :param command:
            is the name of the command to record.
        :param \*command_args:
            are the commands's arguments.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param timeout:
            is the time in milliseconds to wait for the user interface widget
            to become visible.

    .. staticmethod:: Robot.simulate(id, command, *command_args, delay=-1, timeout=-1)

        Immediately execute an automation command.
        
        :param id:
            is the (possibly scoped) identifier of the widget to apply the
            command to.
        :param command:
            is the name of the command to execute.
        :param \*command_args:
            are the command's arguments.
        :param delay:
            is the delay in milliseconds between simulated events.
        :param timeout:
            is the time in milliseconds to wait for the user interface widget
            to become visible.
