DRAFT Navigation Events

What is navigation events?

Navigation event mechanism provides basic navigation concepts (ex. remaining distance to the next edge) and is useful to provide navigation instruction to users and to build customized user interface easily.

• Events are generated based on a route and current location
• Event type does not ask developer to build any specific user interaction.

Event type

Event Type	Event Object	Description
navigationWillBegin	NavigationEvent	occurred before showing view
navigationDidBegin	NavigationEvent	occurred when navigation is ready
navigationWillEnd	NavigationEvent	occurred when navigation is reached to the destination
navigationDidEnd	NavigationEvent	occurred after view is set down
edgeBegin edgeEnter?	EdgeEvent	occurred when user is going to start following the edge
edgeLocation*	EdgeEvent	occurred when user is reached to the registered location on the edge
edgeEnd edgeExit?	EdgeEvent	occurred when user reached the end of the edge
nodeEnter?	EdgeEvent	occurred when user is getting closer to the node
nodeExit?	EdgeEvent	occurred when user is going to leave the node
turnBegin	EdgeEvent	occurred when user is going to start turning
turnEnd	EdgeEvent	occurred when the turn condition is satisfied
locationChanged	LocationEvent	low level event to handle location, heading. Called whenever location or heading is changed.

• *edgeLocation events are issued for registered locations.

Typical Events Flow

1. navigationWillBegin
2. navigationDidBegin
3. edgeBegin, nodeExit
4. edgeLocation, edgeLocation, edgeLocation, ....
5. edgeEnd, nodeEnter, turnBegin
6. turnEnd, nodeExit, edgeBegin
7. edgeLocation, edgeLocation, edgeLocation, ...
8. edgeEnd, nodeEnter, navigationWillEnd
9. navigationDidEnd

Event Objects

NavigationEvent

• route: array of edges representing the route
• length: total length of the route
• from: start node
• to: destination node

EdgeEvent

• source: node / edge
• edge: the edge where user is going to be navigated
• if multiple edges are combined, edge has an array combinedEdges containing all combined edges
• next: next edge (to know next action)
• turnAngle: turn angle
• length: length of the edge in the system unit (feet / meter)
• ratio: projected normalized position on the edge (0.0 - 1.0)
• heading: user's heading
• data: raw location data if available
• location: raw location from localizer
• locationType: type of localization (1d/2d)

LocationEvent

• location
• locationType
• heading

Event registration

addEventListener:(NSString*)type options:(NSDictionary*) options callback:(void(^)(EdgeEvent*))handler;
addEventListenerOnce:(NSString*)type options:(NSDictionary*) options callback:(void(^)(EdgeEvent*))handler;

• params is only for edgeLocation event
• remaining, edge
• or time_interval (and/or) distance_interval

Sample Code

[navi addEventListener:@"edgeBegin" options:nil callback:^(EdgeEvent* e) { 
  NSString *turnStr = util.angleToString(e.turnAngle);
  [tts speak:[NSString stringWithFormat:@"%.0f meters and turn %@", e.length, turnStr]]

  [navi addEventListenerOnce:@"edgeLocation" options:{remaining: 5, edge:e.edge} callback:^(EdgeEvent *e){
    [tts speak:[NSString stringWithFormat:@"approaching to turn %@", turnStr]]
  }];
}]