Using Notifications and Events

Navigator notifications and events may be used to alert the user or act upon specific predefined events. This section of the tutorial describes the use of notifications and events to alert the user about:

• traveling a certain distance
• an upcoming turn
• traveling off-course

This tutorial assumes basic knowledge of the GeoBase LabelBox class, covered in the Using a LabelBox tutorial.

Note
We will modify the sample application (created in The IGps Interface tutorial) to demonstrate Navigator notifications and events.

The use of notifications and events may be broken down into two components:

1. Creation of the Navigator

   The Navigator is responsible for identifying navigation events and calling the appropriate event handler

   Notifications are added to the Navigator using the AddNotification(Notification) method and events are created by adding a NotificationDelegate to the appropriate Navigator event

2. Creation of methods to handle the events

   Each notification or event should be handled by a method (a NotificationDelegate)

   The NotificationDelegate is passed the Navigator object and the next NavigationEvent

Copy the following code snippet over your UpdateLocation() method content. This ensures that the Navigator object is regularly updated with our current position.

 /* update current location of Navigator */
nav.AddPoint();
renderList.Add(new PushPin(nav.Gps.Position.location));
mapMain.Center = nav.Gps.Position.location;
mapMain.Heading = nav.Gps.Position.heading;

mapMain.Invalidate();
/* invalidating the map causes a redraw */

Remove the following line from your project.

IGps myGps;

Next, remove the GetGps() method in its entirety. This won't be needed for this example as we will create a new SimulatedGps in the buttonGo click event for our Navigator.

Modify your buttonGo click event code to match the code segment below. This code segment creates a new Navigator using a SimulatedGps with a set Destination . It also registers event handlers for the following events:

• AfterTurnDistanceNotification - used to remove the TurnBox alert after a turn
• BeforeTurnDistanceNotification - used to alert the user to an upcoming turn
• DistanceIntervalNotification - used to keep track of the number of miles traveled on the journey
• OffCourse - used to alert the user that an incorrect turn has been made
• Arrived - used to alert the user that the destination has been reached

Note
Note that the code also adds the Navigator object to the RendererList, using the line: C# Copy renderList.Add(nav); This will draw the Navigator object's current route on the map. This is often useful as a visual aid to the user.

private Navigator nav;
private LabelBox lBox = new LabelBox();

readonly private String LangsPath = Settings.GeoBasePath("langs");
readonly private LatLon StartLocation = new LatLon(33.65856, -117.75528);
readonly private LatLon DestinationLocation = new LatLon(33.65006, -117.75523);

private void buttonGo_Click(object sender, EventArgs e){
    lBox.Size = new System.Drawing.Size(200, 80);
    mapMain.Zoom = 0.5; /* zoom the map close */

    /* set up Navigator */
    nav = new Navigator(new SimulatedGps(StartLocation),LangsPath,System.Globalization.CultureInfo.CurrentCulture);
    nav.Destination = new RouteStop(DestinationLocation);
    nav.AddNotification(new AfterTurnDistanceNotification(new NotificationDelegate(AfterTurn)));
    nav.AddNotification(new BeforeTurnDistanceNotification(100, 0, DistanceUnit.METERS, new NotificationDelegate(UpcomingTurn)));
    nav.AddNotification(new DistanceIntervalNotification(0.1, DistanceUnit.MILES, new NotificationDelegate(Mile)));
    nav.OffCourse += new NotificationDelegate(OffCourse);
    nav.Arrived += new NotificationDelegate(Arrived);

    /* set items to render */
    mapMain.Renderer = renderList;
    renderList.Add(nav);
    renderList.Add(lBox);

    /* start a timer that fires every second, updating our map */
    Timer tim = new Timer();
    tim.Interval = 1000;
    tim.Tick += new EventHandler(UpdateLocation);
    tim.Start();
}

Each notification or event should be handled by a method. The following section of code contains five methods to alert the user to different events, using a LabelBox. These methods will be called when appropriate by the Navigator.

The UpcomingTurn() method uses the NavigationEvent (passed as an argument) to determine the name of the street to turn into (TargetStreet), and which direction the turn should be in (TurnDirection). Other useful properties of a NavigationEvent include:

• DirectionType - such as: turn, sharp turn, freeway exit
• DirectionQualifier - turn should be made at the traffic lights, or at the end of the street, or neither
• Number - the turn or exit number

Tip
These properties may be used to give the user detailed information on the nature of the upcoming turn event.

/* after a turn assume that we're on course */
private void AfterTurn(object sender, NavigationEvent e){
    lBox.MajorBrush = Brushes.Green;
    lBox.MajorText = "On Course";
}

/* alert user to an upcoming turn */
private void UpcomingTurn(object sender, NavigationEvent e){
    lBox.MajorBrush = Brushes.Orange;
    lBox.MajorText = String.Format("Turn into {0}", e.TargetStreet);
    if (e.TurnDirection != TurnDirection.None)
    {
        String direction = "Left";
        if (e.TurnDirection == TurnDirection.Right)
        {
            direction = "Right";
        }
        lBox.MinorText = String.Format("({0} Turn)", direction);
    }
}

/* warn that we're off course/re-routing */
private void OffCourse(object sender, NavigationEvent e){
    lBox.MajorBrush = Brushes.Red;
    lBox.MajorText = "Off Course! Re-routing...";
}

/* advise of arrival at the destination */
private void Arrived(object sender, NavigationEvent e){
    lBox.MajorBrush = Brushes.Green;
    lBox.MajorText = "Arrived at Destination!";
}

/* keep track of distance traveled */
int odometer = 0;
private void Mile(object sender, NavigationEvent e){
    lBox.MinorText = String.Format("Traveled {0} Miles", odometer++);
}

Run the sample application. After you click buttonGo your application will, before the selected events, provide an appropriate notification in the LabelBox.

Using an XmlWaveAnnouncer