nhmc.ctrl

This package contains functions mostly for manipulating, rendering and switching among various map views, though it also contains other utility functions that can be useful to various modules.

Scaling

nhmc.ctrl.scaleStateMap

Function

nhmc.ctrl.scaleStateMap(state, factor)

This function scales the map view specified by state by the scale factor specified by factor. Scaling the map view consists of resizing each state or county path in the map view and then resizing each city label in the map view.

Note

Despite the name state in the argument and the function name, that term in this context is used in a general sense to refer to the name of any map view, including us_all for the nationwide state map and us_counties for the nationwide county map.

nhmc.ctrl.scaleSurface

Function

nhmc.ctrl.scaleSurface(factor)

This function sets the height and width of the map surface to the default image size scaled in both dimensions by factor; for example, a 768x486px image scaled by 0.5 would be 384x243px.

nhmc.ctrl.scaleCurrentMap

Function

nhmc.ctrl.scaleCurrentMap(factor)

This function first scales the map surface and then scales the current map view, both by factor.

Colors

nhmc.ctrl.setStateColors

Function

nhmc.ctrl.setStateColors(states, color)

This function only has an effect on the nationwide state map and sets the fill color of each specified state. It accepts two arguments:

• states is an array of full state names as found in nhmc.config.stateToUSPS.
• color is a string consisting of either a hexadecimal color code or a color name found in nhmc.config.styleColors.

nhmc.ctrl.setCountyColors

Function

nhmc.ctrl.setCountyColors(state, counties, color)

This function affects both nationwide and statewide county maps. It accepts three arguments:

• state is a full state name specifying the state containing the named counties.
• counties is an array of full county names within the state as found in nhmc.config.countyToFIPS.
• color is a string consisting of either a hexadecimal color code or a color name found in nhmc.config.styleColors.

Map rendering

nhmc.ctrl.addCity

Function

nhmc.ctrl.addCity(cityName, cityData, existingCities)

This function adds a city label to a map view (currently limited to statewide county maps). It takes three arguments:

• cityName is a string with the name of the city.
• cityData is an array with two elements:
  • The first element is an x-y coordinate pair expressed as a two-element array.
  • The second element is a city rank that can be used to distinguish cities by size or importance. This element is a number, and lower values represent more important/larger cities. (By convention, zero is used for a state capital.) This value currently is not used to vary a city’s visual representation, but it is used in nhmc.ctrl.zoomToState to ensure that more important cities are drawn first before proceeding to other cities.
• existingCities is an array of city labels that have already been drawn on the current map view. This is used to ensure city labels don’t inadvertently overlap.

nhmc.ctrl.zoomToState

Function

nhmc.ctrl.zoomToState(state)

This function clears the current map view (by calling nhmc.cleanup.clearMap) and renders the one named by the state argument.

If tooltips are already bound on the page before this function is called, they are reinitialized when the map view has finished rendering.

See also

For more information on the map views themselves and the objects they comprise, see nhmc.geo.

Miscellaneous

nhmc.ctrl.hashParams

Function

nhmc.ctrl.hashParams([newParams[, destroyCurrent]])

Some modules make use of the URL fragment identifier to direct users to a particular starting map view or other initial state. To streamline this process, the nhmc.ctrl.hashParams function returns an object that contains all values stored in the fragment identifier. Where possible, items are coerced to Number objects; Boolean values are also accepted in the form of the values “true” or “false”, and keys without values are treated as true.

Assuming the default values for the properties of nhmc.config.hashParams and the fragment identifier foo=bar|spam=false|magic|xyzzy=42, calling nhmc.ctrl.hashParams() would return the following object:

{
    "foo": "bar",
    "spam": false,
    "baz": true,
    "xyzzy": 42
}

This function also may be used to set any or all values in the fragment identifier, and it accepts up to two arguments to that effect:

• newParams is an object containing keys and values in the same fashion as the object this function returns. This adds key-value pairs to the fragment identifier, overwriting any keys that already exist (using jQuery.extend).
• destroyCurrent is a Boolean (defaulting to false) that, if true, replaces all key-value pairs in the fragment identifier with those specified in newParams instead of simply adding/overwriting them as described above.

Manipulation

These functions are used for programmatically manipulating states and counties, which consists of clicking them or triggering tooltips related to them.

Lower-level functions

nhmc.ctrl.highlightArea

Function

nhmc.ctrl.highlightArea(area, pageX, pageY)

This function highlights the area object, which is a state or county object from nhmc.geo, renders its tooltip if any exists and positions the tooltip at the coordinates (pageX, pageY) if those coordinates are specified. If those coordinates are not specified, the tooltip is positioned at the left edge of the map with its top edge one-third of the way down the map.

nhmc.ctrl.clickArea

Function

nhmc.ctrl.clickArea(area)

This function triggers a click event on the area object, which is a state or county object from nhmc.geo.

Warning

Because this uses the actual DOM node for area, this is not supported for browsers that do not support either SVG or VML rendering, such as Android 2.x.

Higher-level functions

nhmc.ctrl.dehighlightAreas

Function

nhmc.ctrl.dehighlightAreas()

This function removes any highlights and tooltips created by nhmc.ctrl.highlightArea.

nhmc.ctrl.highlightCounty

Function

nhmc.ctrl.highlightCounty(stateName, countyName, pageX, pageY)

This function highlights the county with the name countyName in the state with the name stateName and positions the tooltip (if applicable) at (pageX, pageY) if specified. For more details, see nhmc.ctrl.highlightArea.

nhmc.ctrl.clickCounty

Function

nhmc.ctrl.clickCounty(stateName, countyName)

This function triggers a click event on the county with the name countyName in the state with the name stateName. This only makes sense for maps that show counties, such as the nationwide county map or the statewide county maps.

Warning

Because this uses the actual DOM node for the county, this is not supported for browsers that do not support either SVG or VML rendering, such as Android 2.x.

nhmc.ctrl.highlightState

Function

nhmc.ctrl.highlightState(stateName, pageX, pageY)

This function highlights the state with the name stateName and positions the tooltip (if applicable) at (pageX, pageY) if specified. For more details, see nhmc.ctrl.highlightArea.

nhmc.ctrl.clickState

Function

nhmc.ctrl.clickState(stateName)

This function triggers a click event on the state with the name stateName. This only makes sense for map views with state boundaries, which currently only includes the nationwide state map.

Warning

Because this uses the actual DOM node for the state, this is not supported for browsers that do not support either SVG or VML rendering, such as Android 2.x.

Orphans

nhmc.ctrl.renderLegend

Function

nhmc.ctrl.renderLegend(title, items)

This function was intended to simplify rendering of map legends by accepting two parameters:

• title: A string to be used as the title of the legend.
• items: An array of items to be used as the entries of the legend. Each item should be an array containing two elements:
  • The text of the entry.
  • A background color for that entry.

This function hasn’t actually been used, though, since individual modules often render the legend in different ways.

Todo

Remove this.