6 Replies Latest reply: Sep 11, 2008 4:24 AM by Andrei1 RSS

    useCapture:  Why??

    sneakyimp Community Member
      I've been reading about event handling in AS 3 for hours and I still can't fully understand the reason for event flow. Under what circumstance would one want to add an event listener with useCapture = true?

        • 1. Re: useCapture:  Why??
          kglad CommunityMVP
          when you want to know if the currentTarget is the object (with the listener) or one of its children.
          • 2. Re: useCapture:  Why??
            sneakyimp Community Member
            I wasn't aware that events propagated to children as they move through an event flow path. I thought they came to the source object (the 'target') from its ancestors in the display list and then bubbled back up...something like:

            stage -> root --> targetObject --> root --> stage

            Also, the useCapture I was referring to is the third argument to the addEventListener method:
            addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

            It is supposed to indicate whether your event listener is executed in the 'capture' phase or during the 'target/bubble' phase. I can't understand why that sort of complexity is necessary.

            Perhaps you could give an example?
            • 3. Re: useCapture:  Why??
              kglad CommunityMVP
              :

              • 4. Re: useCapture:  Why??
                KEY_NYC Community Member
                This still does not answer the original question.

                Assume from the post that we fully understand HOW this works.

                The question is WHY or WHEN might we have need for the capture phase to be set to true or false.

                Does anyone have a use case scenario in which they have needed to use this?

                I too, have wondered.
                • 5. Re: useCapture:  Why??
                  Peter Lorent Community Member
                  You use a ancestor listener with useCapture=true to process an event BEFORE the event reaches the target.
                  Likewise you use an ancestor listener with bubbles=true to process an event after the event has reached the target.

                  Capture phase listeners are therefore mostly used to conditionally stop an event from reaching its target.
                  • 6. Re: useCapture:  Why??
                    Andrei1 Community Member
                    In addition to the previous replies one of the useful applications of the capture phase can be deep linking. Say you have a hierarchy of N nested objects (with parent/child relationships) and these object are branching. For instance:

                    parent --> child1 --> button1
                    parent --> child1 --> child2 -->childOfChild2 --> button2
                    parent --> child1 --> child3 --> childOfChild3 -->anotherChild -->button3

                    Let's assume you need to process clicks from all three buttons in one place in the parent. You can write a single click handler in the parent:

                    child1.addEventListener(e:MouseEvent.CLICK, clickHandler, true);

                    private function clickHandler(e:MouseEvent):void{
                    switch(e.currentTarget){
                    case button1:
                    // do whatever
                    break;
                    case button2:
                    // do whatever
                    break;
                    case button3:
                    // do whatever
                    break;
                    }
                    }

                    Now your buttons can exist independently and you don't have to care how deep they are in the hierarchy of child1 object.

                    Things are getting more interesting and efficient if the objects you are listening to are not buttons but different purpose entities that dispatch various events. You can process them in a single place as long as they are in the same display list. The great convenience is that you can write these objects as a well encapsulated and tested components with interfaces, reuse/abuse them and stop worrying about how they perform no matter your architecture changes because these objects always let the outside world know what they do by broadcasting events. This is one of the core AS3 aspects that make it shine.

                    Hope it helps.

                    Andrei