U PeZ@sdZdZddlmZddlmZddlmZddlmZddl m Z ddl m Z m Z mZdd lmZmZmZmZdd lmZd ZGd d d eZGddde ZdS)a Gesture Surface =============== .. versionadded:: 1.9.0 .. warning:: This is experimental and subject to change as long as this warning notice is present. See :file:`kivy/examples/demo/multistroke/main.py` for a complete application example. )GestureSurfaceGestureContainer)random)EventDispatcher)ClockVector) FloatLayout)ColorLine Rectangle)NumericPropertyBooleanProperty DictProperty ColorProperty) hsv_to_rgb皙?cseZdZdZedZedZedZedZ e e de de de ddZ edZ edZfdd Zd d Zd d ZdddZddZddZddZddZZS)raOContainer object that stores information about a gesture. It has various properties that are updated by `GestureSurface` as drawing progresses. :Arguments: `touch` Touch object (as received by on_touch_down) used to initialize the gesture container. Required. :Properties: `active` Set to False once the gesture is complete (meets `max_stroke` setting or `GestureSurface.temporal_window`) :attr:`active` is a :class:`~kivy.properties.BooleanProperty` `active_strokes` Number of strokes currently active in the gesture, ie concurrent touches associated with this gesture. :attr:`active_strokes` is a :class:`~kivy.properties.NumericProperty` `max_strokes` Max number of strokes allowed in the gesture. This is set by `GestureSurface.max_strokes` but can be overridden for example from `on_gesture_start`. :attr:`max_strokes` is a :class:`~kivy.properties.NumericProperty` `was_merged` Indicates that this gesture has been merged with another gesture and should be considered discarded. :attr:`was_merged` is a :class:`~kivy.properties.BooleanProperty` `bbox` Dictionary with keys minx, miny, maxx, maxy. Represents the size of the gesture bounding box. :attr:`bbox` is a :class:`~kivy.properties.DictProperty` `width` Represents the width of the gesture. :attr:`width` is a :class:`~kivy.properties.NumericProperty` `height` Represents the height of the gesture. :attr:`height` is a :class:`~kivy.properties.NumericProperty` TrFinfz-inf)minxminymaxxmaxyc sh|ddddg|_tt|jf|t|j|_t |_ d|_ d|_ d|_ d|_i|_||dS)Ncolor?r)poprsuperr__init__struididrget_time _create_time _update_time _cleanup_time _cache_time_vectors_strokes update_bbox)selftouchkwargs __class__;/tmp/pip-unpacked-wheel-xzebddm3/kivy/uix/gesturesurface.pyrds  zGestureContainer.__init__c Ks~|j|jkr|ds|jSg}|j}|jD]:\}}|j}|ddt|ddd|dddDq0||_|j|_|S)aReturn strokes in a format that is acceptable for `kivy.multistroke.Recognizer` as a gesture candidate or template. The result is cached automatically; the cache is invalidated at the start and end of a stroke and if `update_bbox` is called. If you are going to analyze a gesture mid-stroke, you may need to set the `no_cache` argument to True.no_cachecSsg|] }t|qSr-r).0Zptsr-r-r. sz0GestureContainer.get_vectors..N) r$r"getr%appendr&itemspointszip)r(r*Zvecsr5tuidlZlptsr-r-r. get_vectors}s .zGestureContainer.get_vectorscCs|js dSt|j|jkS)z6Returns True if this container handles the given touchF)activerrr&)r(r)r-r-r.handlesszGestureContainer.handlesr3cCs|js dSt|j||jkS)z=Returns True if this container can accept `count` new strokesT) max_strokeslenr&)r(countr-r-r. accept_strokeszGestureContainer.accept_strokecCs|j|j}}|j}||dkr(||d<||dkr<||d<||dkrP||d<||dkrd||d<|d|d|_|d|d|_t|_dS)z+Update gesture bbox from a touch coordinaterrrrN)xybboxwidthheightrr r")r(r)rBrCbbr-r-r.r's    zGestureContainer.update_bboxcCs,t|_||jt|j<|jd7_dS)zAssociate a list of points with a touch.uid; the line itself is created by the caller, but subsequent move/up events look it up via us. This is done to avoid problems during merge.r3N)rr r"r&rractive_strokes)r(r)liner-r-r. add_strokes zGestureContainer.add_strokecCst|_|jd8_dS)zCalled on touch up events to keep track of how many strokes are active in the gesture (we only want to dispatch event when the *last* stroke in the gesture is released)r3N)rr r"rH)r(r-r-r.complete_strokes z GestureContainer.complete_strokecCs,|jD]\}}t|jdkr dSq dS)zReturns True if the gesture consists only of single-point strokes, we must discard it in this case, or an exception will be raisedr2FT)r&r6r?r7)r(r9r:r-r-r.single_points_testsz#GestureContainer.single_points_test)r3)__name__ __module__ __qualname____doc__rr<r rHr> was_mergedrfloatrDrErFrr;r=rAr'rJrKrL __classcell__r-r-r+r.r s&:  rcseZdZdZedZedZedZedZedZ e ddddgZ e dZ e dZed Zfd d Zd d ZddZddZddZddZddZddZddZddZddZd d!Zd"d#Zd$d%Zd&d'Zd(d)Zd*d+Z d,d-Z!Z"S).raSimple gesture surface to track/draw touch movements. Typically used to gather user input suitable for :class:`kivy.multistroke.Recognizer`. :Properties: `temporal_window` Time to wait from the last touch_up event before attempting to recognize the gesture. If you set this to 0, the `on_gesture_complete` event is not fired unless the :attr:`max_strokes` condition is met. :attr:`temporal_window` is a :class:`~kivy.properties.NumericProperty` and defaults to 2.0 `max_strokes` Max number of strokes in a single gesture; if this is reached, recognition will start immediately on the final touch_up event. If this is set to 0, the `on_gesture_complete` event is not fired unless the :attr:`temporal_window` expires. :attr:`max_strokes` is a :class:`~kivy.properties.NumericProperty` and defaults to 2.0 `bbox_margin` Bounding box margin for detecting gesture collisions, in pixels. :attr:`bbox_margin` is a :class:`~kivy.properties.NumericProperty` and defaults to 30 `draw_timeout` Number of seconds to keep lines/bbox on canvas after the `on_gesture_complete` event is fired. If this is set to 0, gestures are immediately removed from the surface when complete. :attr:`draw_timeout` is a :class:`~kivy.properties.NumericProperty` and defaults to 3.0 `color` Color used to draw the gesture, in RGB. This option does not have an effect if :attr:`use_random_color` is True. :attr:`color` is a :class:`~kivy.properties.ColorProperty` and defaults to [1, 1, 1, 1] (white) .. versionchanged:: 2.0.0 Changed from :class:`~kivy.properties.ListProperty` to :class:`~kivy.properties.ColorProperty`. `use_random_color` Set to True to pick a random color for each gesture, if you do this then `color` is ignored. Defaults to False. :attr:`use_random_color` is a :class:`~kivy.properties.BooleanProperty` and defaults to False `line_width` Line width used for tracing touches on the surface. Set to 0 if you only want to detect gestures without drawing anything. If you use 1.0, OpenGL GL_LINE is used for drawing; values > 1 will use an internal drawing method based on triangles (less efficient), see :mod:`kivy.graphics`. :attr:`line_width` is a :class:`~kivy.properties.NumericProperty` and defaults to 2 `draw_bbox` Set to True if you want to draw bounding box behind gestures. This only works if `line_width` >= 1. Default is False. :attr:`draw_bbox` is a :class:`~kivy.properties.BooleanProperty` and defaults to True `bbox_alpha` Opacity for bounding box if `draw_bbox` is True. Default 0.1 :attr:`bbox_alpha` is a :class:`~kivy.properties.NumericProperty` and defaults to 0.1 :Events: `on_gesture_start` :class:`GestureContainer` Fired when a new gesture is initiated on the surface, i.e. the first on_touch_down that does not collide with an existing gesture on the surface. `on_gesture_extend` :class:`GestureContainer` Fired when a touch_down event occurs within an existing gesture. `on_gesture_merge` :class:`GestureContainer`, :class:`GestureContainer` Fired when two gestures collide and get merged to one gesture. The first argument is the gesture that has been merged (no longer valid); the second is the combined (resulting) gesture. `on_gesture_complete` :class:`GestureContainer` Fired when a set of strokes is considered a complete gesture, this happens when `temporal_window` expires or `max_strokes` is reached. Typically you will bind to this event and use the provided `GestureContainer` get_vectors() method to match against your gesture database. `on_gesture_cleanup` :class:`GestureContainer` Fired `draw_timeout` seconds after `on_gesture_complete`, The gesture will be removed from the canvas (if line_width > 0 or draw_bbox is True) and the internal gesture list before this. `on_gesture_discard` :class:`GestureContainer` Fired when a gesture does not meet the minimum size requirements for recognition (width/height < 5, or consists only of single- point strokes). g@g@r2rFrc sXtt|jf|g|_|d|d|d|d|d|ddS)Non_gesture_starton_gesture_extendon_gesture_mergeon_gesture_completeon_gesture_cleanupon_gesture_discard)rrr _gesturesZregister_event_type)r(r*r+r-r.rBs     zGestureSurface.__init__cCst||j|jsdS||||}d}|dkrB||}d}||||rb|d||n|d||dS)zWhen a new touch is registered, the first thing we do is to test if it collides with the bounding box of another known gesture. If so, it is assumed to be part of that gesture. NFTrVrW) collide_pointrBrCZgrabfind_colliding_gesture init_gesture init_strokedispatch)r(r)gnewr-r-r. on_touch_downPs    zGestureSurface.on_touch_downcCs|j|k rdS||j|js"dS||}||}|dk r|t|jr| ||}|j rp| d||n| d|||}n | ||jt |jj|j|jf7_|jr||dS)zWhen a touch moves, we add a point to the line on the canvas so the path is updated. We must also check if the new point collides with the bounding box of another gesture - if so, they should be merged.NrXT) grab_currentr]rBrC get_gesturer^rAr?r&merge_gesturesrQrar'rrr7 draw_bbox_update_canvas_bbox)r(r)rbZ collisionmerger-r-r. on_touch_movels"     " zGestureSurface.on_touch_movecCs\|j|k rdS||||}||s>|dn|jdkrXt|j|jdS)Nr) reZungrabrfrKrA_complete_dispatchertemporal_windowr schedule_oncer(r)rbr-r-r. on_touch_ups     zGestureSurface.on_touch_upc Cs|j}|jrttdd}t||j|d}|jr|j}|jdt |d|d|d|j d|j dt |j |d|d f|d |d|d |d fd |_ W5QRX|j||S) z~Create a new gesture from touch, i.e. it's the first on surface, or was not close enough to any existing gesture (yet)r)r>rrr3r2Zrgbamodegrouprrrr)rspossize)ruse_random_colorrrrr>rhrDcanvasr bbox_alpharr _bbrectr\r5)r(r)colrbrGr-r-r.r_s& zGestureSurface.init_gesturecCs|j|jg}|j}t||j|jd}||jt|j<|jrn|j j }|t |d|d|dd|jd||| ||j r|||||dS)Nr7rErsrr3r2rgbrq)rBrCrr line_widthrr&rrrwaddr r'rhrirJ)r(rbr)r7rznew_lineZ canvas_addr-r-r.r`s  $  zGestureSurface.init_strokecCs:|jD]}|jr||r|Sqtdt|jdS)z4Returns GestureContainer associated with given touchz!get_gesture() failed to identify N)r\r<r= Exceptionrrror-r-r.rfs  zGestureSurface.get_gesturec Cs|j\}}|jD]}|jr||s|r|j}|j}|d|}|d|}|d|} |d|} ||kr|| krnq||kr| krnq|SqdS)zChecks if a touch x/y collides with the bounding box of an existing gesture. If so, return it (otherwise returns None) rrrrN)rtr\r<r=rArD bbox_margin) r(r)Ztouch_xZtouch_yrbrGmarginrrrrr-r-r.r^s      0 z%GestureSurface.find_colliding_gesturec CsT|j|jk}|r|p|}|r |p"|}|j}|j}|d|dkrL|d|d<|d|dkrh|d|d<|d|dkr|d|d<|d|dkr|d|d<|j}|j} |j} |j} |j|j|jj} |j D]P\} }t |j |j | d}||| <| r| t | d| d| dd | d | |qd |_d |_|j|j7_t|_|S) zMerges two gestures together, the oldest one is retained and the newer one gets the `GestureContainer.was_merged` flag raised.rrrrr{rr3r2r|rqFT)r!rDr&r}rrrw remove_groupr~r6r r7rEr r<rQrHrr r")r(rbotherZswapabZabboxZbbboxZastrokesZlwZa_idrzZcanv_addroldrr-r-r.rgsD       "  zGestureSurface.merge_gesturescCsPt|dsdS|j}|d|df|j_|d|d|d|df|j_dS)Nryrrrr)hasattrrDryrtru)r(rbrGr-r-r.ris z"GestureSurface._update_canvas_bboxc Csd}|j}|j}|j}tj}t|D]\}}|jr:||=q$|jr$|jdkrLq$|j |} |t } | rp| | kr$d} |j dkr|j dkrd} n |rd} d}d|_|||_| r|d|q$|d|q$|rt|j|dS)zThis method is scheduled on all touch up events. It will dispatch the `on_gesture_complete` event for all completed gestures, and remove merged gestures from the internal gesture list.FrTr[rYN)r\ draw_timeoutrmrr enumeraterQr<rHr"UNDERSHOOT_MARGINrArErFrLr#rarn_cleanup) r(dtZ need_cleanupZgesttimeoutZtwinr idxrbt1t2discardr-r-r.rl&s6   z#GestureSurface._complete_dispatchercCsbt}|jj}|j}t|D]B\}}|jdkr.q|jt|kr||j||=| d|qdS)zThis method is scheduled from _complete_dispatcher to clean up the canvas and internal gesture list after a gesture is completed.NrZ) rrwrr\rr#rr rra)r(rmZrgZgesturesrrbr-r-r.rSs  zGestureSurface._cleanupcGsdSNr-r(r:r-r-r.rVaszGestureSurface.on_gesture_startcGsdSrr-rr-r-r.rWdsz GestureSurface.on_gesture_extendcGsdSrr-rr-r-r.rXgszGestureSurface.on_gesture_mergecGsdSrr-rr-r-r.rYjsz"GestureSurface.on_gesture_completecGsdSrr-rr-r-r.r[msz!GestureSurface.on_gesture_discardcGsdSrr-rr-r-r.rZpsz!GestureSurface.on_gesture_cleanup)#rMrNrOrPr rmrr>rr}rrrrvrhrxrrdrkrpr_r`rfr^rgrirlrrVrWrXrYr[rZrSr-r-r+r.rs8p  /-rN)rP__all__rZ kivy.eventrZ kivy.clockrZ kivy.vectorrZkivy.uix.floatlayoutr Z kivy.graphicsr r r Zkivy.propertiesr rrrZcolorsysrrrrr-r-r-r.s      '