SafeDispatch/Safedispatch_4_0/docs/map_handler.txt

/***************************************/
/**** SafeDispatch Map Handler v1.0 ****/
/***************************************/

This version of Map Handler is designed to prevent the map from freezing and to try and maximize the number of units displayed.
It was developed as a stand alone module to which you pass the list of vehicles which you need to add or remove and it will handle
everything else. Also the module has the role to receive and acumulate GPS positions in order to update the markers at an interval
that is autobalanced based on the traffic.

Map Handler is a User Control that instantiate a CefSharpChromiumWebBrowser instance that will provide functionality of loading 
the map html file, and will provide useful events to the user when different events occurs. 

In order for the Map Handler Module to be used, it will require an absolute path to the place where the Google/OSM Map html file
is stored on the hard drive.
Also the map can take other parameters between curly brackets using syntactics sugar or event after the constructor

	String mapUrl = "file:///" + safemobileDirPath + "/resource/" + MainForm2.MapHtmlName;
	MapHandler mapHandler = new MapHandler(mapUrl)
        {
            MapHashName = tabName,
            HasLabels = rcbMarkersLables.Checked,
            IsMetric = !MainForm2.isInMile,
            IsConsoleVisible = MainForm2.MapDebugConsole,
            IconType = MainForm2.iconThemeType,
            CenterPosition = centerPosition,
            HideTimeInactiveUnits = MainForm2.Livelastck,
            InactiveTimeoutMinutes = MainForm2.Livelastmin,
            IsNeverReportedWarning = true,
            MaxDisplayedNrOfUnits = 2000
        };
 
In the above example a list of configurable parameters is displayed, list which includes as follows: 
	- MapHashName			: is the Live Tab instance name (each instance has an unique name) in order to find the state of an unit on that tab
	- HasLabels				: provide indicator if the markers will have labels or they will be hidden
	- IsMetric				: speed unit will be set to metric if true, otherwise it will be in miles
	- IsConsoleVisible		: provides indicator if the console needs to be displayed for debug reasons
	- IconType				: pass the style of units that is used in order to change the labels position and color accordingly
	- Center Position		: default position to which the map needs to be center at initialization (usualy is the last visible position)
	- HideTimeInactiveUnits	: indicator if the units needs to be removed from the map if the GPS is older than a predefined amount of minutes
	- InactiveTimeutMinutes : number of minutes after which a unit can be considere inactive
	- IsNeverReportedWaning	: raise events which time you try to display a unit that had never reported any gps
	- MaxDisplayedNrOfUnits	: set dataset limit after which the units will be skipped by the map js library
	  

Regarding the available methods that the MapHandler exposes to other classes, here is a list o available methods is presented below:
	- AddVehicles(List<Vehicle> vehicles, bool scaleViewBounds)
	- RemoveVehicles(List<Vehicle> vehicle)
	- AddGroup(String groupName, List<Vehicle> vehicles, bool scaleViewBounds)
    - RemoveGroup(String groupName)
	- RemoveDataset(String dataSetName)
	- SetDataSetLimit(Int32 limit)
	- GPSUpdate(Vehicle vehicle)
	- ChangeConsoleState(bool isConsoleVisible)
    - ChangeMarkersType(IconType type)
    - CenterMapToPosition(LatLngZoom latLngZoom)
    - CenterMapToPosition(double lat, double lng)
    - CenterMapToPosition(double lat, double lng, Int32 zoomLevel)
    
    
Startring from ChangeConsoleState() to the end, the methods are self explanatory. All others will be explained below:
	- AddVehicles(List<Vehicle> vehicles, bool scaleViewBounds) : add the list of vehicles to the map paying atention to the group in which
						the vehicles are so each group is stored inside a dataset. Also the command to the JS library is sent in chunks of 
						100 vehicles with a customizable timeout which is 500ms in first version. The commands that are sent to the map are 
						highlighted to the end user by triggering the OnMapProgressChanged event which provides information about the group
						that is displayed and the number of step necessary to do this job. The ending of the update is flagged with the same
						event but the done flag. [all displayed units are stored inside a dictionary and migrated to the inactive dictionary
						when needed and if enabled this functionality]
	- RemoveVehicles(List<Vehicle> vehicle) : remove the list of vehicles from the map and dictionaries. Also, if all the units from a dataset
						are removed, then the dataset needs to be removed to prevent the center in the Atlatinc Ocean (when scaleViewBounds 
						was set to true for that dataset)
	- AddGroup(String groupName, List<Vehicle> vehicles, bool scaleViewBounds) : provides the same functionality aas the AddVehicles method
						with the difference that here the vehicles are all inside a group
	- RemoveGroup(String groupName) : Remove all the units that are displayed for a particular group and also it will remove the dataset 
						directly
	- RemoveDataset(String dataSetName) : Flag to the JS library that a dataset is not needed anymore and all it's properties can be deleted
	- SetDataSetLimit(Int32 limit) : will tell the JS map library what is the maximum number of units for which it needs to keep a track
						of updates
	- GPSUpdate(Vehicle vehicle) : received a new GPS position for that vehicles and it will be stored in GPS queue only if that vehicles 
						is displayed on the map or if it is in the inactive queue



!!! IMPORTANT !!! All functions are locking the map object in order to prevent multiple command to the map in the same time and GPS updates.
	The priority is set to be of type FIFO for user related command, and the GPS update will have to wait until all user interactions are 
	completed

!!! IMPORTANT !!! units are stored in datasets according to the group name and not inside a generic dataset as the previous version. This
	change affects the way the map changes the viewbounds in order to display the units, meaning that now the viewbounds are scaled for each 
	dataset and the last updated dataset will be in focus (if other unit is displayed for other dataset, then that dataset will be all displayed
	between the new viewbounds)



Once the MapHandler is loaded it will create a Worker which it's main objective is to check for the GPS queue and compare it with the displayed 
units before passing the command to the map. 
It should be noted that the GPS worker is autobalancing itself acording to the number of Displayed units on the map and the number of GPS 
positions received since the last iteration. The next iteration will be run according to the following rule:
	- next iteration in 3 seconds if the number of GPS position received since last iteration is lower that 100
	- next iteration in 10 seconds if the number of GPS position received since last iteration is lower that 300
	- next iteration in 20 seconds if the number of GPS position received since last iteration is lower that 500
	- next iteration in 30 seconds if the number of GPS position received since last iteration is grater that 500

Also, the GPS worker will handle the inactive units display and hide by storing them inside a sperate dictionary and migrate them back to the 
displayed dictionary when a unit becomes active again. Once some units are becoming inactive, an event will be raised in order to display a 
notification to the user with the reason why the units were removed from the map.