continued edits

Author: slackmoehrle

8.md

@@ -21,81 +21,95 @@ The basics:
 
 `EventListenerCustom` - responds to custom events
 
-## Creating a touch event
-FIXME: Introduce a very simple sample of touches, and the flow of the touch event... how it is handled by the different consumers
-
-FIXME: Then introduce the "swallow" property
+## FixedPriority vs SceneGraphPriority
 
-FIXME: Describe the chain of command.
+The *EventDispatcher* uses priorities to decide which listeners get delivered an
+event first.
 
-Touch events are the most important event in mobile gaming. They are easy to create
-and provide versatile functionality.
+`FixedPriority` is an integer value. Event listeners with lower Priority values
+get to process events before event listeners with higher Priority values.
+
+`SceneGraphPriority` is a pointer to a `Node`. Event listeners whose _Nodes_ have
+higher _z-order_ values (that is, are drawn on top) receive events before event
+listeners whose _Nodes_ have lower Z order values (that is, are drawn below).
+This ensures that touch events, for example, get delivered front-to-back, as you
+would expect.
+
+Remember Chapter 2? Where we talked about the _scene graph_ and we talked about
+this diagram?
+
+![](2/in-order-walk.png "in-order walk")
+
+Well, when use _SceneGraphPriority_ you are actually walking this above tree
+backwards... _H_, _I_, _G_, _F_, _E_, _D_, _C_, _B_, _A_. If an event is triggered,
+_H_ would take a look and either _swallow_ it (more on this below) or let is pass
+through to _I_. Same thing, _I_ will either _consume_ it or let is pass thought
+to _G_.. and so on until the event either _swallowed_ or it does not get answered.
+
+## Touch Events
+Touch events are the most important event in mobile gaming. They are easy to
+create and provide versatile functionality. Let's make sure we know what a touch
+event is. When you touch the screen of your mobile device, it accepts the touch,
+looks at where you touched and decides what you touched. Your touch is then answered.
+It is possible that what you touched might not be the responding object but perhaps
+something underneath it. Touch events are usually assigned a priority and the
+event with the highest priority is the one that answers. Here is how you create
+a basic touch event listener:
 ```cpp
 //  Create a "one by one" touch event listener
 // (processes one touch at a time)
 auto listener1 = EventListenerTouchOneByOne::create();
 
-// When "swallow touches" is true, then returning 'true' from the
-// onTouchBegan method will "swallow" the touch event, preventing
-// other listeners from using it.
-listener1->setSwallowTouches(true);
-
-// use a lambda!
+// trigger when you push down
 listener1->onTouchBegan = [](Touch* touch, Event* event){
-        // event->getCurrentTarget() returns the *listener's*
-        // sceneGraphPriority node.
-        auto target = static_cast<Sprite*>(event->getCurrentTarget());
-
-        //Get the position of the current point relative to the button
-        Point locationInNode = target->convertToNodeSpace(touch->getLocation());
-        Size s = target->getContentSize();
-        Rect rect = Rect(0, 0, s.width, s.height);
-
-        //Check the click area
-        if (rect.containsPoint(locationInNode))
-        {
-            log("sprite began... x = %f, y = %f", locationInNode.x, locationInNode.y);
-
-            return true;
-        }
-        return false;
-    };
-
-    // Trigger when moving touch
-    listener1->onTouchMoved = [](Touch* touch, Event* event){
-        auto target = static_cast<Sprite*>(event->getCurrentTarget());
-
-        // Note: touch->getDelta(); will provide change in movement.
-    };
-
-    // Process the touch end event
-    listener1->onTouchEnded = [=](Touch* touch, Event* event){
-        auto target = static_cast<Sprite*>(event->getCurrentTarget());
-        log("sprite onTouchesEnded.. ");
-    };
-```
+    // your code
+};
 
-As you can see there are 3 distinct events that you can act upon when using a touch event
-listener. They each have a distinct time in which they are called.
+// trigger when moving touch
+listener1->onTouchMoved = [](Touch* touch, Event* event){
+    // your code
+};
+
+// trigger when you let up
+listener1->onTouchEnded = [=](Touch* touch, Event* event){
+    // your code
+};
+
+// Add listener
+_eventDispatcher->addEventListenerWithSceneGraphPriority(listener1, this);
+```
+As you can see there are 3 distinct events that you can act upon when using a
+touch event listener. They each have a distinct time in which they are called.
 
 `onTouchBegan` is triggered when you press down.
 
-`onTouchMoved` is triggered if you move the object around while still pressing down.
+`onTouchMoved` is triggered if you move the object around while still pressing
+down.
 
 `onTouchEnded` is triggered when you let up on the touch.
 
-FIXME: Don't add obj-c code
+## Swallowing Events
+When you have a listener and you want an object to accept the event it was given
+you must _swallow_ it. In other words you _comsume_ it so that it doesn't get
+passed to other objects in highest to lowest priority. This is easy to do.
+```cpp
+// When "swallow touches" is true, then returning 'true' from the
+// onTouchBegan method will "swallow" the touch event, preventing
+// other listeners from using it.
+listener1->setSwallowTouches(true);
 
-Also, it is possible to enable *multi-touch*. This is the ability to touch the screen with
-multiple fingers at the same time and have every object you touch respond to its listeners.
-On iOS *multi-touch* is disabled by default. You will need to enable it by adding
-`[eaglView setMultipleTouchEnabled:YES];` in the `AppDelegate.mm` class. Andorid platforms
-have *milti-touch* turned on by default.
+// you should also return true in onTouchBegan()
 
+listener1->onTouchBegan = [](Touch* touch, Event* event){
+    // your code
+
+    return true;
+};
+```
 ## Creating a keyboard event
 For dekstop games, you might want find using keyboard mechanics useful.
 Cocos2d-x supports keyboard events. Just like with touch events above,
-keyboard events are wasy to create.
+keyboard events are easy to create.
 ```cpp
 // creating a keyboard event listener
 auto listener = EventListenerKeyboard::create();
@@ -117,17 +131,19 @@ void KeyboardTest::onKeyReleased(EventKeyboard::KeyCode keyCode, Event* event)
 ```
 
 ## Creating an accelerometer event
-Some mobile devices come equipped with an accelerometer. An accelerometer is a sensor
-that measures g-force as well as changes in direction. A use case would be needing to
-move your phone back and forth, perhaps to simulate a balancing act.
+Some mobile devices come equipped with an accelerometer. An accelerometer is a
+sensor that measures g-force as well as changes in direction. A use case would
+be needing to move your phone back and forth, perhaps to simulate a balancing act.
 Cocos2d-x also supports these events and creating them is simple.
 Before using accelerometer events, you need to enable them on the device:
 ```cpp
 Device::setAccelerometerEnabled(true);
 ```
 ```cpp
 // creating an accelerometer event
-auto listener = EventListenerAcceleration::create(CC_CALLBACK_2(AccelerometerTest::onAcceleration, this));
+auto listener = EventListenerAcceleration::create(CC_CALLBACK_2(
+AccelerometerTest::onAcceleration, this));
+
 _eventDispatcher->addEventListenerWithSceneGraphPriority(listener, this);
 
 // Implementation of the accelerometer callback function prototype
@@ -182,10 +198,10 @@ void MouseTest::onMouseScroll(Event *event)
 ```
 
 ## Creating a custom event listener
-The event types above are defined by the system, and the events are triggered by the system
-automatically. In addition, you can make your own custom events which are triggered by your
-code and not the system. These are called `Custom Events`. It is easy to use a `lambda` to
-house the functionality of these events.
+The event types above are defined by the system, and the events are triggered by
+the system automatically. In addition, you can make your own custom events which
+are triggered by your code and not the system. These are called `Custom Events`.
+It is easy to use a `lambda` to house the functionality of these events.
 
 ```cpp
 _listener = EventListenerCustom::create("game_custom_event1", [=](EventCustom* event){
@@ -216,35 +232,25 @@ _eventDispatcher->dispatchEvent(&event);
 
 CC_SAFE_DELETE_ARRAY(buf);
 ```
-<<<<<<< HEAD
-The above example creates an `EventCustom` object and sets its `UserData`. It is then 
-dispatched manually with `_eventDispatcher->dispatchEvent(&event);`. This triggers the 
-event handler for your custom event.
-=======
-The above example creates an `EventCustom` object and sets its `UserData`. It is then dispatched
-manually with `_eventDispatcher->dispatchEvent(&event);`. This triggers the event handler for your
-custom event.
->>>>>>> dd4d7b64e4ad973da07350f7333e4e3f940f31d1
+The above example creates an `EventCustom` object and sets its `UserData`. It is
+then dispatched manually with `_eventDispatcher->dispatchEvent(&event);`. This
+triggers the event handler for your custom event.
 
 ## Registering event with the dispatcher
-It is easy to register an event with the *Event Dispatcher*. Taking the sample touch
-event listener from above:
+It is easy to register an event with the *Event Dispatcher*. Taking the sample
+touch event listener from above:
 ```cpp
 // Add listener
 _eventDispatcher->addEventListenerWithSceneGraphPriority(listener1,
 sprite1);
 ```
-It is important to note that a touch event can only be reigstered once per object.
+It is important to note that a touch event can only be registered once per object.
 If you need to use the same listener for multiple objects you should
 use `clone()`.
 ```cpp
 // Add listener
-<<<<<<< HEAD
-_eventDispatcher->addEventListenerWithSceneGraphPriority(listener1, sprite1);
-=======
 _eventDispatcher->addEventListenerWithSceneGraphPriority(listener1,
 sprite1);
->>>>>>> dd4d7b64e4ad973da07350f7333e4e3f940f31d1
 
 // Add the same listener to multiple objects.
 _eventDispatcher->addEventListenerWithSceneGraphPriority(listener1->clone(),
@@ -253,36 +259,12 @@ _eventDispatcher->addEventListenerWithSceneGraphPriority(listener1->clone(),
 _eventDispatcher->addEventListenerWithSceneGraphPriority(listener1->clone(),
  sprite3);
 ```
-
-## FixedPriority vs SceneGraphPriority
-
-FIXME: Add graphics, explain that SceneGraph goes from foreground to background, reference Chapter 2, etc.
-
-The *EventDispatcher* uses priorities to decide which listeners get delivered an
-event first.
-
-`FixedPriority` is an integer value. Event listeners with lower Priority values get
-to process events before event listeners with higher Priority values.
-
-`SceneGraphPriority` is a pointer to a `Node`. Event listeners whose *Nodes* have higher
-Z order values (that is, are drawn on top) receive events before event listeners whose
-*Nodes* have lower Z order values (that is, are drawn below). This ensures that touch
-events, for example, get delivered front-to-back, as you would expect.
-
 ## Removing events from the dispatcher
 An added listener can be removed with following method:
 ```cpp
 _eventDispatcher->removeEventListener(listener);
 ```
-To remove all the listeners of the *event dispatcher*:
-```cpp
-_eventDispatcher->removeAllEventListeners();
-```
-
-FIXME: Say that some built-in nodes uses the event dispatcher, like Menu.
-
-FIXME: I don't know if we need to mention removeAllEventListener()
-
-When using `removeAllEventListeners()`, all the listeners for this node will be removed.
-Removing a specific listener is the recommended way. After using `removeAllEventListeners()`
-even `Menu` objects can not respond, because the events that are triggered are also removed.
+Although they may seem special, built-in `Node` objects use the _event dispatcher_
+in the same way we have talked out. Makes senese right? Take `Menu` for an example.
+When you have a `Menu` with `MenuItems` when you click them you are dispatching a
+event. You can also `removeEventListener()` on built-in `Node` objects.