Introduction to the Visual C++ Annotated Travel Log Starter Kit
Visual Studio 2005
Summary: Describes how the Visual C++ Annotated Travel Log Starter Kit works, and provides guidance on how you can customize it using Visual C++. (31 printed pages)
The Visual C++ Annotated Travel Log Starter Kit is a travel planning and tracking application that comes ready to compile and run. The planning component allows users to plan their travel by selecting an area on a map, defining intermediate points en route, and provides functionality to add media (images and videos) at particular locations. The tracking component then enables the user to add media points, associate a number of media files with each of the media points, and track the user's current location within the travel plan.
This document describes how one can build and make use of both components to perform each of the tasks mentioned above. The document also provides an overview of the architecture of the sample, which will help acquaint you with the overall functionality of the component.
The project comes ready to compile and run, and is easy to customize with only a little extra C++ programming. The section Extending the Annotated Travel Log contains a list of customizations you might make. You are also free to use the accompanying source code as the basis for your own travel planning projects, and share your work with others or upload it to the Internet.
Note This documentation assumes that you have a basic knowledge of C++ programming concepts and the Visual Studio 2005 environment.
After reading through this starter kit documentation you will understand how the Annotated Travel Log program works, and a few ways in which you can customize it using Visual C++.
The sample contains two solutions, TravelLog and Journey.
TravelLog is the planning component that contains two projects:
- TravelLog—This is a Windows Forms desktop application used for planning a trip. It implements logic for managing travel plans and importing and exporting to a handheld device. It can also export your plan as HTML, which can assist in easy blogging. It depends on ActiveSync (described below) to synchronize with a handheld device.
- ActiveSync—This is a Win32 (native) component and is responsible for copying files from your desktop/computer to your device and vice versa. The component makes extensive use of the RAPI library, which can be found in the installation folder of the Windows Mobile 5.0 Pocket PC SDK. The same can be downloaded from the Windows Mobile Web site.
Journey is the tracking component that contains one project:
- Journey—This is a Win32 (native) component used for tracking a trip. It implements logic for managing a travel plan on a PDA device running on the Windows Mobile 5.0 Pocket PC operating system.
Building and Running an Annotated Travel Log
Both of the components should be compiled separately. The sample contains two components, the planning component and the tracking component.
Planning Component (TravelLog): Before you open the solution you need to have Windows Mobile 5.0 SDK for Pocket PC installed on your machine. Once you have installed the SDK, open the solution in Microsoft Visual Studio 2005. You need to configure include and library paths for rapi.h and rapi.lib files as follows:
- In Visual Studio 2005, go to Tools->Options.
- In the Options dialog navigate to Projects and Solutions, then select the VC++ Directories node.
- From the Platform drop-down menu select Win32.
- For configuring the include files in the Show Directory drop down, select Include Files. Add a new line and browse to the installation folder
Windows Mobile 5.0 Pocket PC SDKand select the
- For configuring the library files in the Show Directory drop down, select Library Files. Add a new line and browse to the installation folder
Windows Mobile 5.0 Pocket PC SDKand select the
- Click OK.
After creating these settings, you will be able to build your solution successfully.
The TravelLog project has a Web reference to the staging environment of MapPoint Web services, which is used for testing and evaluation. If you have a MapPoint Web service evaluation account, you can access only the staging environment. Before deploying the Web service reference can be changed from staging to a production environment (fully scaled). More information can be found at MSDN.
Note If timing out is an issue for Web service calls (at the time of execution), then it can be configured at the source-code level in Resource.resx by changing the TIMEOUT (string resource) value. It takes an integer value in milliseconds. Modifying this value requires the solution to be rebuilt.
Tracking Component (Journey): Once the required prerequisites are installed, simply build the attached solution using Visual Studio 2005 with the target device set to Windows Mobile 5.0 Pocket PC Emulator and deploy it [
Build->Deploy Solution]. The Framework will take care of launching the emulator.
Note In order to port to a PDA device, build the application using Windows Mobile 5.0 Pocket PC Device as the target device. The application can be ported only to a device with Windows Mobile 5.0 installed on it.
Using the planning component
Typically, you can follow the sequence below in order to use most of the features provided by the application.
- Load the world map.
- The user finds his intended location using search functionality.
- The user navigates within the map (using Zoom, Move, Drag).
- Freeze the map.
- Create a route by defining waypoints on the map.
- A waypoint can have map and route, recursively.
- Data can be exported to an XML file (Map, Route Info).
- User can import data (visited route) from XML.
- User can add/edit media files to plan.
- Export to HTML for blogging.
The following is an explanation of these features.
Running the application for the first time shows the Settings window as shown below. This is one-time activity that is required to be configured for the application to start. This setting can be changed later from File>Settings menu.
Here the MapPoint Subscription Details consist of the username and password for accessing MapPoint Web services. A free evaluation account can be obtained here. If you are accessing the Internet through a proxy server, configuration can be done from this dialog. The proxy server address and port should be entered as shown in the example. Remove saved info deletes any saved settings on that machine.
After the settings are successfully created, the application starts and the following window displays. Here users can search for a location, find a map for it. or navigate through maps for further details.
The user inputs the location name in the search pane and clicks on the search button. The list box is populated with the results of the searched location. The number of results found is displayed in the status bar. Double-clicking a particular result in the list box in order to load the map for the clicked location.
The user can navigate through the loaded map using the navigation panel. It provides the functionality of moving the map in all four directions. You can also navigate through the map by dragging it in the desired direction. This pane also allows zooming in/out for the current view. The zoom in button zooms in by 30% of the current view.
After users have navigated to a desired location, they need to freeze the map (using the Freeze button in the left pane) before they can start creating the actual route. This is the first top-level map and should cover the entire plan. You cannot point outside this defined view. Unfreezing allows users to change or enlarge navigation functionality, provided that there are no waypoints or mediapoints defined. If so, the users need to manually delete those waypoints and mediapoints.
After freezing the map, users can create a route by defining intermediate points. These points are called waypoints. To define a waypoint on a particular location, simply right-click on a location on map and select Add waypoint.
The next dialog enables users to enter waypoint information such as name, description, arrival date, and departure date. A waypoint must have name and arrival and departure date-time, where arrival date-time must be less than departure date-time.
To edit an existing waypoint, right-click to enable the Edit waypoint option in the context menu and to invoke a dialog similar to that of Add waypoint.
When users select Remove waypoint they are asked for confirmation for doing the same.
A mediapoint is a set of media files associated with a particular location on the map. The files might have been recorded by a user during her trip or may be files on her computer. To add a media point it, is necessary for the current view to be frozen.
Define a mediapoint on a particular location by right-clicking a location on the map and selecting Add mediapoint.
A media point must have a name and at least one media file. To add a file to a mediapoint users must provide a title, a file path, and its type (Image / Audio / Video) and then click Add. This file is copied to the current directory named Media in the base folder of application. A mediapoint is displayed in red on the map. When the user hovers the mouse over the mediapoint, a tool tip shows details for it.
Edit mediapoints in the same way as you edit waypoints: right-click and select Edit mediapoint from the context menu. When the user selects Remove mediapoint he is asked for confirmation for doing the same. Note that the files added to that mediapoint are not deleted from the disk.
On double-clicking a waypoint user are asked whether they want to have waypoints within this waypoint. In other words, a waypoint can further contain a set of other waypoints. This is will create a parent-child (in a tree-like structure) relationship for these two waypoints. On selecting Yes the zoomed map for that location is displayed and the parent waypoint's location is centered. The Previous button in the left pane is enabled so that you can return to the parent map.
Note When a waypoint is added to second level (or higher) map, its arrival and departure date and time must fit within the parent's schedule.
Set the current plan as default: This functionality sets currently opened plan as default. The next time the user opens the application it loads at startup. After you set the default it displays the following dialog.
You can fetch the latest data from MapPoint Web services by choosing Refresh. The keyboard shortcut is F5.
Export to HTML
This feature exports the current plan to HTML to the specified folder. The file that initially opens is index.htm. On the HTML pages waypoints and mediapoints are authored with tooltips. If a waypoint has a detailed plan there is a link pointing to it. All mediapoints and files are linked in separate HTML file.
When the user selects Synchronize desktop from the menu, the application asks him for both the source folder on the computer and then the destination folder on the device/PDA. In this way you can copy files from the folder on your computer to the device.
Similarly, you can synchronize the destination folder on the computer and source folder on the device. It confirms successful synchronization.
Note The PDA device must be connected for synchronize to work properly. When the PDA is connected for the first time on a computer, it should be configured first through the Microsoft ActiveSync 3.8 application.
Using the tracking component
Before we go ahead, let's first get acquainted with the basic screen of the application.
The various icons on the screen have been numbered. The following table gives an overview of their functionality:
|1||Media||Allows the addition of mediapoints. The mediapoints may be added at a location specified by the user or at the current location of the user.|
|Zoom in, Zoom out||Used for zooming in and out of the map image.|
|Navigator||Used to go to the previous map of the current plan.|
|Menu||Provides the following options:
|5||Mediapoint||Represents a mediapoint on the Plan. Provides options for mediapoint management.|
|6||Waypoint||Represents a waypoint and provides options for viewing waypoint details.|
|7||Start Tracking||Makes use of the GPS device to plot the actual route taken by the user during his travel.|
Importing a Travel Plan
Once the PDA device has been synchronized with the desktop component, one can ensure that the Travel Plan made on the desktop is available on the PDA device by synchronizing the two using ActiveSync.
While using the Emulator, however, one will have to share folders between the desktop and the Emulator. Here is how this is done:
- Once the emulator is launched, select File, the click Configure.
- In the Emulator Properties dialog displayed after choosing to configure, one can select the General tab and browse to the folder on the desktop that one wishes to share with the emulator.
By following the above-mentioned steps, one can ensure that the travel plans and media files present on the desktop are also found on the emulator, simply by sharing the appropriate desktop folder with the emulator.
The travel plans can now be consumed by the PDA component simply by using the Import option under the Menu tab and selecting the required XML plan.
If the image corresponding to the plan is present on the PDA device/emulator, the application takes care of loading the plan.
Note One can only import plans that have been made by the desktop or PDA component of Travel Log.
Green pins: Waypoints placed during the planning phase.
Red Pins: Mediapoints placed while planning or during travel
Green Route: Route planned on the desktop component
Red Route: Route plotted during travel after using the Start Tracking option
Adding a mediapoint
In order to add a mediapoint, choose the media option on the tool bar. The user is then provided with the following options:
- Add to the current location: The current location is obtained from the GPS device or an internal file, depending on how the GPS intermediate driver is configured.
- Add to a specified location: The user is expected to provide appropriate latitude and longitude values. The user has to ensure that the values specified lie within the range of the map provided.
On selecting a mediapoint on the plan, the user is provided with an Update Media Point dialog. Here one will find the following options that enable one to manage media points:
- Add File: To add a new file to the mediapoint
- Remove File: To remove the media file from the mediapoint
- Delete Point: To remove the mediapoint. Once this is done the point will no longer be visible on the plan.
- Update Point: To change the mediapoint name or its description
On selecting the Add File option, the user can browse and select a media file to be associated with the mediapoint.
Similarly, one can remove media files by selecting the Remove File button on Update Media Point dialog and selecting the file to be removed.
Viewing waypoint details
On selecting a waypoint, the WayPoint Details dialog box is shown. This may be used for two purposes:
- View details of a waypoint: name, description, and so on
- View a detailed map associated with the waypoint, if one exists
Partial plan management
During travel, after having added a few mediapoints, the user may want to stop the Travel Log application and resume some time later. In such a situation, the user can save his partial plan and open it later. This is achieved by using the Open and Save options on the Menu tab.
The user can start tracking his route by clicking on the track icon on the toolbar. No dialog box is displayed but the user's path is traced every minute. Of course, the user can continue performing other tasks synchronously.
Note In order to use this feature, it is required that the PDA be connected to a GPS device or that the device driver is configured for using a file instead. If not, the application will display an error message.
In order to communicate with the GPS device, the application makes use of the GPS Intermediate Driver provided by the Windows Mobile 5.0 SDK. The GPS Intermediate Driver uses the registry for two basic types of configuration information:
- Connecting the GPS Intermediate Driver to GPS hardware
- Providing data to applications that use the GPS Intermediate Driver
Using a Local File as the Source of Data for the GPS Intermediate Driver
As mentioned earlier, the GPS Intermediate Driver can be configured to use a GPS device or a file as the source of data. This section of the document will describe how the driver can be configured for using a file. In order to configure the driver we need to provide appropriate registry settings. Note that here we are looking at the Emulator's registry settings and not those of your desktop. In order to access the registry editor of the emulator, use the following path:
Programs->Microsoft Visual Studio 2005->Visual Studio Remote Tools->Remote Registry Editor
Here select the appropriate emulator—Windows Mobile 5.0 Pocket PC Emulator, in our case:
The editor then takes care of connecting to the emulator. We can then use this editor just as we would use the desktop editor for configuring the driver. The following steps will guide you through the process.
_LOCAL_MACHINE->System->CurrentControlSet, you find the key
GPSIntermediateDriver. Here's where we will start configuring our driver.
- Add the DWORD key
GPSIntermediateDriver. Let its value be 1. This indicates that the device is enabled.
GPSIntermediateDriverswe have another key called Drivers. Here we will add a string value called
CurrentDriverand assign any string value to it. In our example it is
TestFile. We then add another key with this value (
TestFile) to Drivers.
Under this new key (
TestFile) we will add the following values:
|File1||String||The location where the file can be found on the emulator.|
|InterfaceType||String||File: Default value indicating that the source is of the type "File".|
|FriendlyName||String||Any string value indicating an alternate name to the file.|
|Iterations||Sword||Any number indicating the number of times the driver will iterate through the file.|
Use GPS Intermediate Driver Registry Settings to configure the driver for use with the GPS hardware.
Sharing Your Version of Annotated Travel Log with Friends
You can customize this program and share it with your friends and family. Please note that this application uses the .NET Framework version 2.0, so any computer running it needs to have this version of the .NET Framework installed on it.
Annotated Travel Log Architecture
Planning Component Layer Details
This layer interacts with MapPoint Web services. It provides functionality for searching, fetching maps, and converting latitude and longitude to (x,y) points and vice versa.
The Import/Export layer provides the following features:
- After the user has created the plan it can be exported to XML so that the tracking component can consume it. Similarly, it provides import functionality.
- Once the tracking has been done this plan can be exported to HTML format with all media files. These HTML files can be used for blogging purposes.
Application logic layer
This layer holds the core functionality of Travel Log, the Desktop Component. It provides classes and structures for storing and manipulating data. It interacts with the MapPoint layer and the UI layer.
It interacts with the Application logic layer and displays data using UI controls. It contains classes for creating Windows forms and provides functionality for managing waypoints and mediapoints and displaying maps to the user.
Recording Component Layer Details
The Import/Export layer provides the following features:
- Having finalized a plan on the desktop component of Travel Log, this layer allows one to consume that plan on the PDA component.
- On extension of a plan on the PDA, this layer allows one to convert the plan into a form (XML) that can then be consumed by the desktop component.
Thus, after a user has decided his waypoints for a trip and finalized his plan on the desktop, he can use that plan on his PDA and after having added a few mediapoints to the plan during his journey, he can port the plan back to his desktop with the help of the Import/Export layer. In simpler words, this layer facilitates interaction between the desktop component and the PDA component of Travel Log.
Application logic layer
This layer holds the core functionality of Travel Log, the PDA Component. It provides the following features:
- Addition, deletion, and updating of mediapoints
- Addition and deletion of media files
- Addition of actual route points
- Tracking of the user's path
In order to perform the above-mentioned tasks, the layer interacts with the Import/Export layer, the UI layer, and the GPS layer.
This layer takes care of interaction with the GPS device. For this purpose it makes use of GPS APIs provided by Windows Mobile 5.0 Pocket PC SDK. However, in order to make use of this layer, it is important that the GPS Intermediate Driver be configured properly.
The basic functionality provided by this layer is to start up the GPS device and get the current location whenever required by the Business Logic layer.
The UI layer is responsible for exposing the Travel Log, or the PDA Component features, to the user. It interacts with the Business Logic layer for the same. This layer allows the user to:
- Import a travel plan
- Export a travel plan
- Save and Open a partial plan
- View a plan
- Add and remove mediapoints
- Add and remove media files from a mediapoint
- View waypoint details
Travel Log solution files (planning component):
This solution contains two projects containing C++ source-code and graphics used by the starter kit. The source-code files perform the following functions:
|Contains the Main( ) method—the location where the program begins execution. It loads MainForm windows.|
MainForm.h / MainForm.resx
|These files contain the definition and implementation of MainForm, which is the main window of the application.|
WayPointDetails.h / WayPointDetails.resx
|These files contain definition and implementation for the WayPoint dialog for adding and editing waypoint details.|
MediaPointDetails.h / MediaWayPointDetails.resx
|These files contain definition and implementation for the MediaPoint dialog for adding and editing mediapoint details.|
Settings.h / Settings.resx
|These files contain definition and implementation for the Settings dialog used to take input from users.|
InputBox.h / InputBox.resx
|These files contain definition and implementation for a customized input box that enables the user to enter a folder path on the device.|
|Application Logic Layer|
|Stores found results returned by the FindMap class.|
MapController.h / MapController.cpp
|Stores the entire travel plan. The class MapController defines the travel plan.|
Route.h / Route.cpp
|Stores the planned route containing waypoints.|
|Stores the actual route visited by the user. This route may have mediapoints.|
|Used for serializing/deserializing the MapController object to provide functionality for saving/opening the current plan.|
|Stores details of found results.|
|Stores latitude and longitude of a location on earth.|
WayPoint.h / Waypoint.cpp
|Stores an intermediate point en route.|
|Stores the view for a map. View in terms of latitude and longitude bounds and height/width.|
|Stores collection of media files associated with a certain location.|
|Stores details of a media file.|
|Thrown by MapController.Move() when MapController is already frozen.|
|Thrown by MapController.RefreshMapWithRoute() when MapController is already frozen.|
|Thrown by MapController.Freeze() if tries to unfreeze and route is not empty.|
|Thrown by MapController.Move() when parent waypoint is out of current view.|
|Thrown by MapController.Zoom() when current zoom level becomes less than parent's zoom level.|
|Thrown if fewer than 2 waypoints are created and route is finalized.|
|Holds all required constants.|
|The FindMap class is used to interact with MapPoint Web services for searching a particular location.|
|RenderMap.h / RenderMap.cpp|
|This class is used to interact with MapPoint Web services for fetching map and converting points for (x,y) to LatLog and vice versa.|
|Import Export Layer|
|This class provides functionality for importing and/or exporting from XML and HTML formats.|
|This file has the functionality for copying files from desktop to device and vice-versa.|
|Holds string table and image files as resources for assembly.|
|Explains classes and files in this project.|
Journey Solution Files (tracking component)
|ImportExport.cpp / ImportExport.h|
|Contains code for interpreting details from an XML-based file obtained from the desktop component and filling in local structures with appropriate information for use by the PDA component. Also contains code for formatting the details present in the local structure back into an XML file for use by the desktop component.|
Business Logic Layer
|ActualRoute.cpp / ActualRoute.h|
|Contains code for managing internal structures holding mediapoint details, mediafile details, and actual route details. Also contains code for interacting with the GPS layer for tracking the user's path.|
|MapController.cpp / MapController.h|
|Acts as a wrapper over the ActualRoute class.|
|GPSWrapper.cpp / GPSWrapper.h|
|Contains code for initializing the GPS device and getting information about the current location. Requires the GPS Intermediate Driver to be configured appropriately.|
|JourneyView.cpp / JourneyView.h|
|Acts as a wrapper class that takes care of invoking appropriate methods on selection of icons and menu options on the main screen.|
|RemoveFileDlg.cpp / RemoveFileDlg.h|
|Handles the UI behavior for the Remove File dialog and interacts with the Business Logic Layer for file removal.|
|AddFileDlg.cpp / AddFileDlg.h|
|Handles the UI behavior for the Add File dialog and interacts with the Business Logic Layer for addition of files.|
|AddMediaPointDlg.cpp / AddMediaPointDlg.h|
|Handles the UI Behavior for Add MediaPoint dialog and interacts with the Business Logic Layer for the addition of mediapoints.|
|UpdateMediaPointDlg.cpp / UpdateMediaPointDlg.h|
|Handles the UI behavior for Update MediaPoint dialog and interacts with the Business Logic Layer for managing mediapoints.|
|WayPointDlg.cpp / WayPointDlg.h|
|Handles the UI behavior for the WayPoint Details dialog and interacts with the Business Logic Layer for providing waypoint details.|
- The application can be extended to have facility for creating waypoints at any zoom level. Moreover the freezing of the map can be optional.
- Search functionality for waypoints/mediapoints in a plan can be extended.
- Pre-fetching and caching of map images from MapPoint and to facilitate smooth dragging and zooming of the map.
- Enhancements for points of interests for selected points can be made. The points of interests can include restaurants, lodging, drinking places, etc.; museums, art galleries, botanical and zoological gardens, airports, and so on can also be mapped.
- Application can be extended to provide directions from one point to another (searching a route). This information can be based on less time or less distance.
- Transparent Synchronization of Desktop and PDA components: This can be achieved by maintaining an independent application folder wherein we save our import-export files along with partial plans. In addition we can have serialized structures of finalized plans that will provide association between a plan, a mediapoint on the plan, and the links to corresponding media files. This way the user is only expected to choose to synchronize the two components and the application can take care of porting appropriate files to the PDA component. It will also make sure that files that will not be accepted by the PDA component—e.g., a Desktop partial plan—is not ported onto the PDA device. Similar changes will have to be made on the PDA component too.
- More details during travel: The desktop component can access more details such as nearby hotels, hospitals, etc. using the MapPoint Web service. These details may be ported onto the PDA device and made accessible to the user whenever required during the travel.
- Accessing media files on the PDA component: Currently the PDA component shows all the media files associates with a mediapoint. The user can choose to delete and add new media files. We can also provide the functionality for viewing media files by launching them using appropriate applications.
- Travel Diary: We can provide a "personal diary" feature to the user wherein he can maintain logs of his journey and associate them with waypoints and mediapoints, as well as actual route points.
- More control over tracking: Currently tracking is done every minute. We can allow the user to specify the time interval between calls to the tracking device. This will also help in performance improvement since ideally the user might not want to track his route every minute. Additionally, the Travel Log can provide another icon on the screen that enables the user to get details of the last time his position was tracked. This will be more user-friendly than having to use navigation keys to locate an actual route point which, in any case, won't be visible if the user is not within the limits of the map.