<commit_before>User Interface Classes
======================

The namespace libavg.ui contains python modules that expose higher-level user interface
functionality

.. automodule:: libavg.ui
    :no-members:

    .. inheritance-diagram:: DragRecognizer TapRecognizer TransformRecognizer DoubletapRecognizer HoldRecognizer
        :parts: 1

    .. inheritance-diagram:: Button ToggleButton Keyboard
        :parts: 1


    .. autoclass:: Button(upNode, downNode, [disabledNode=None, activeAreaNode=None, fatFingerEnlarge=False, clickHandler=None])

        A button that shows different user-supplied nodes depending on it's
        state. Possible button states are up, down and disabled. The nodes are attached
        as children to the Button on construction. For a simple button, image nodes can 
        be passed. Uses the :py:class:`TapRecognizer` to detect clicks.
        
        .. image:: ButtonStates.png

        :param avg.Node upNode: The node displayed when the button is not pressed.

        :param avg.Node downNode: The node displayed when the button is pressed.

        :param avg.Node disabledNode: The node displayed when the button is disabled.

        :param avg.Node activeAreaNode: 
        
            A node that is used only to determine if a click is over the button. Usually,
            this node is invisible. :py:attr:`activeAreaNode` is useful for small touch
            buttons, where the active area should be larger than the visible button to
            account for touch inaccuracies.

        :param bool fatFingerEnlarge:

            If this parameter is set to :py:const:`True`, the button generates it's own 
            internal :py:attr:`activeAreaNode` that is at least 20x20mm large. 
            :py:attr:`fatFingerEnlarge` is incompatible with a custom 
            :py:attr:`activeAreaNode`.

        **Callbacks:**

            .. py:method:: clickHandler(event)

                Called when the button is clicked.

        .. py:attribute:: enabled

            :py:const:`True` if the button accepts input. If the button is disabled,
            it shows the :py:attr:`disabledNode`.

        .. py:classmethod:: fromSrc(upSrc, downSrc[, disabledSrc=None, **kwargs]) -> Button

            Factory method that creates a button from filenames of the images to be
            displayed for different states.


    .. autoclass:: DoubletapRecognizer(node, [maxTime=MAX_DOUBLETAP_TIME, initialEvent=None, possibleHandler=None, failHandler=None, detectedHandler=None])

        A :py:class:`DoubletapRecognizer` detects doubletaps: Two short touches in quick
        succession without a large change of the cursor position.

        :param maxTime: The maximum time that each phase of the tap may take.


    .. autoclass:: DragRecognizer(eventNode, [coordSysNode=None, initialEvent=None, direction=ANY_DIRECTION, directionTolerance=DIRECTION_TOLERANCE, friction=-1, possibleHandler=None, failHandler=None, detectedHandler=None, moveHandler=None, upHandler=None, endHandler=None])

        A :py:class:`DragRecognizer` attaches itself to a node's cursor events and 
        delivers higher-level callbacks that can be used to implement dragging or 
        drag-like functionality.

        :py:class:`DragRecognizer` supports inertia after the node is released.
        
        :param avg.Node eventNode: 
        
            The node to attach to. The :py:class:`DragRecognizer` registers an event 
            handler to react to any contacts for this node. 
            
        :param avg.Node coordSysNode:    

            Used to determine the coordinate system for the offsets returned by the 
            callbacks. If :py:attr:`coordSysNode` is not given, :py:attr:`eventNode` is 
            used as default. The :py:class:`DragRecognizer` never modifies any nodes 
            itself. :py:attr:`coordSysNode` can be used to separate the node that
            is the 'handle' for the events from the node that is being moved - for 
            instance, to allow moving a window by dragging the title bar.

        :param direction:

            Can be used to constrain the recognizer to :py:const:`VERTICAL` or 
            :py:const:`HORIZONTAL` drags only. If one of these constants is passed as 
            :py:attr:`direction`, the recognizer invokes :py:meth:`onPossible`
            when the down event arrives, then determines whether the drag is a 
            predominantly horizontal or vertical drag and invokes either 
            :py:meth:`onDetected` or :py:meth:`onFail` depending on the result.

        :param float directionTolerance:

            A tolerance angle in radians for the detection of horizontal and vertical
            drags.

        :param float friction:

            If set, this parameter enables inertia processing. It describes how 
            quickly the drag comes to a stop after the cursor is released.

        :param moveHandler:

            A shortcut for 
            :samp:`Recognizer.subscribe(Recognizer.MOTION, moveHandler)`.

        :param upHandler:

            A shortcut for 
            :samp:`Recognizer.subscribe(Recognizer.UP, upHandler)`.

        **Messages:**

            To get these messages, call :py:meth:`Publisher.subscribe`.

            .. py:method:: Recognizer.MOTION(offset)

                Emitted when the drag should cause a position change. This usually happens
                in response to a :py:const:`CURSORMOTION` event, but may also happen
                because of inertia.

                :param event: 
                
                    The corresponding cursor motion event. If there was no event, 
                    this parameter is :py:const:`None`.

                :param avg.Point2D offset: 
                
                    The current offset from the start of the drag in coordinates relative
                    to the :py:attr:`coordSysNode`'s parent.

            .. py:method:: Recognizer.UP(offset)

                Emitted when the cursor is released. If inertia is enabled, there may be 
                move events after the up event.

                :param event: 
                
                    The corresponding :py:const:`CURSORUP` event.

                :param avg.Point2D offset: 
                
                    The current offset from the start of the drag in coordinates relative
                    to the :py:class:`coordSysNode`'s parent.

        .. py:method:: abort()

            Aborts the present recognized gesture and sliding caused by inertia

        .. py:method:: abortInertia()<commit_msg>Recognizer reference update (fixes #368).<commit_after>User Interface Classes
======================

The namespace libavg.ui contains python modules that expose higher-level user interface
functionality

.. automodule:: libavg.ui
    :no-members:

    .. inheritance-diagram:: DragRecognizer TapRecognizer TransformRecognizer DoubletapRecognizer HoldRecognizer
        :parts: 1

    .. inheritance-diagram:: Button ToggleButton Keyboard
        :parts: 1


    .. autoclass:: Button(upNode, downNode, [disabledNode=None, activeAreaNode=None, fatFingerEnlarge=False, clickHandler=None])

        A button that shows different user-supplied nodes depending on it's
        state. Possible button states are up, down and disabled. The nodes are attached
        as children to the Button on construction. For a simple button, image nodes can 
        be passed. Uses the :py:class:`TapRecognizer` to detect clicks.
        
        .. image:: ButtonStates.png

        :param avg.Node upNode: The node displayed when the button is not pressed.

        :param avg.Node downNode: The node displayed when the button is pressed.

        :param avg.Node disabledNode: The node displayed when the button is disabled.

        :param avg.Node activeAreaNode: 
        
            A node that is used only to determine if a click is over the button. Usually,
            this node is invisible. :py:attr:`activeAreaNode` is useful for small touch
            buttons, where the active area should be larger than the visible button to
            account for touch inaccuracies.

        :param bool fatFingerEnlarge:

            If this parameter is set to :py:const:`True`, the button generates it's own 
            internal :py:attr:`activeAreaNode` that is at least 20x20mm large. 
            :py:attr:`fatFingerEnlarge` is incompatible with a custom 
            :py:attr:`activeAreaNode`.

        **Callbacks:**

            .. py:method:: clickHandler(event)

                Called when the button is clicked.

        .. py:attribute:: enabled

            :py:const:`True` if the button accepts input. If the button is disabled,
            it shows the :py:attr:`disabledNode`.

        .. py:classmethod:: fromSrc(upSrc, downSrc[, disabledSrc=None, **kwargs]) -> Button

            Factory method that creates a button from filenames of the images to be
            displayed for different states.


    .. autoclass:: DoubletapRecognizer(node, [maxTime=MAX_DOUBLETAP_TIME, initialEvent=None, possibleHandler=None, failHandler=None, detectedHandler=None])

        A :py:class:`DoubletapRecognizer` detects doubletaps: Two short touches in quick
        succession without a large change of the cursor position.

        :param maxTime: The maximum time that each phase of the tap may take.


    .. autoclass:: DragRecognizer(eventNode, [coordSysNode=None, initialEvent=None, direction=ANY_DIRECTION, directionTolerance=DIRECTION_TOLERANCE, friction=-1, possibleHandler=None, failHandler=None, detectedHandler=None, moveHandler=None, upHandler=None, endHandler=None])

        A :py:class:`DragRecognizer` attaches itself to a node's cursor events and 
        delivers higher-level callbacks that can be used to implement dragging or 
        drag-like functionality.

        :py:class:`DragRecognizer` supports inertia after the node is released.
        
        :param avg.Node eventNode: 
        
            The node to attach to. The :py:class:`DragRecognizer` registers an event 
            handler to react to any contacts for this node. 
            
        :param avg.Node coordSysNode:    

            Used to determine the coordinate system for the offsets returned by the 
            callbacks. If :py:attr:`coordSysNode` is not given, :py:attr:`eventNode` is 
            used as default. The :py:class:`DragRecognizer` never modifies any nodes 
            itself. :py:attr:`coordSysNode` can be used to separate the node that
            is the 'handle' for the events from the node that is being moved - for 
            instance, to allow moving a window by dragging the title bar.

        :param direction:

            Can be used to constrain the recognizer to :py:const:`VERTICAL` or 
            :py:const:`HORIZONTAL` drags only. If one of these constants is passed as 
            :py:attr:`direction`, the recognizer invokes :py:meth:`onPossible`
            when the down event arrives, then determines whether the drag is a 
            predominantly horizontal or vertical drag and invokes either 
            :py:meth:`onDetected` or :py:meth:`onFail` depending on the result.

        :param float directionTolerance:

            A tolerance angle in radians for the detection of horizontal and vertical
            drags.

        :param float friction:

            If set, this parameter enables inertia processing. It describes how 
            quickly the drag comes to a stop after the cursor is released.

        :param moveHandler:

            A shortcut for 
            :samp:`Recognizer.subscribe(Recognizer.MOTION, moveHandler)`.

        :param upHandler:

            A shortcut for 
            :samp:`Recognizer.subscribe(Recognizer.UP, upHandler)`.

        **Messages:**

            To get these messages, call :py:meth:`Publisher.subscribe`.

            .. py:method:: Recognizer.MOTION(offset)

                Emitted when the drag should cause a position change. This usually happens
                in response to a :py:const:`CURSORMOTION` event, but may also happen
                because of inertia.

                :param avg.Point2D offset: 
                
                    The current offset from the start of the drag in coordinates relative
                    to the :py:attr:`coordSysNode`'s parent.

            .. py:method:: Recognizer.UP(offset)

                Emitted when the cursor is released. If inertia is enabled, there may be 
                move events after the up event.

                :param avg.Point2D offset: 
                
                    The current offset from the start of the drag in coordinates relative
                    to the :py:class:`coordSysNode`'s parent.

        .. py:method:: abort()

            Aborts the present recognized gesture and sliding caused by inertia

        .. py:method:: abortInertia()
{'fraction_non_alphanumeric': 0.06999152085099823, 'fraction_numerical': 0.0016187466276111925, 'mean_word_length': 2.336934156378601, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7082911', 'n_tokens_mistral': 3411, 'n_tokens_neox': 3083, 'n_words': 1291}