.. _nhmc.ctrl: ######### 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 :ref:`modules `. .. _nhmc.ctrl-scaling: ******* Scaling ******* .. _nhmc.ctrl.scaleStateMap: 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 :ref:`nationwide state map ` and ``us_counties`` for the :ref:`nationwide county map `. .. _nhmc.ctrl.scaleSurface: nhmc.ctrl.scaleSurface ====================== *Function* ``nhmc.ctrl.scaleSurface(factor)`` This function sets the height and width of the :ref:`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: nhmc.ctrl.scaleCurrentMap ========================= *Function* ``nhmc.ctrl.scaleCurrentMap(factor)`` This function first :ref:`scales the map surface ` and then :ref:`scales the current map view `, both by ``factor``. ****** Colors ****** .. _nhmc.ctrl.setStateColors: nhmc.ctrl.setStateColors ======================== *Function* ``nhmc.ctrl.setStateColors(states, color)`` This function only has an effect on the :ref:`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 :ref:`nhmc.config.stateToUSPS `. * ``color`` is a string consisting of either a hexadecimal color code or a color name found in :ref:`nhmc.config.styleColors`. .. _nhmc.ctrl.setCountyColors: nhmc.ctrl.setCountyColors ========================= *Function* ``nhmc.ctrl.setCountyColors(state, counties, color)`` This function affects both :ref:`nationwide ` and :ref:`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 :ref:`nhmc.config.countyToFIPS `. * ``color`` is a string consisting of either a hexadecimal color code or a color name found in :ref:`nhmc.config.styleColors`. .. _nhmc.ctrl-map_rendering: ************* Map rendering ************* .. _nhmc.ctrl.addCity: nhmc.ctrl.addCity ================= *Function* ``nhmc.ctrl.addCity(cityName, cityData, existingCities)`` This function adds a :ref:`city label ` to a map view (currently limited to :ref:`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 :ref:`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: nhmc.ctrl.zoomToState ===================== *Function* ``nhmc.ctrl.zoomToState(state)`` This function clears the current map view (by calling :ref:`nhmc.cleanup.clearMap`) and renders the one named by the ``state`` argument. If :ref:`tooltips ` are already bound on the page before this function is called, they are :ref:`reinitialized ` when the map view has finished rendering. .. seealso:: For more information on the map views themselves and the objects they comprise, see :ref:`nhmc.geo`. .. _nhmc.ctrl-miscellaneous: ************* Miscellaneous ************* .. _nhmc.ctrl.hashParams: nhmc.ctrl.hashParams ==================== *Function* ``nhmc.ctrl.hashParams([newParams[, destroyCurrent]])`` Some :ref:`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``. .. _URL: http://en.wikipedia.org/wiki/Uniform_resource_locator .. _fragment identifier: http://en.wikipedia.org/wiki/Fragment_identifier Assuming the default values for the properties of :ref:`nhmc.config.hashParams` and the fragment identifier ``foo=bar|spam=false|magic|xyzzy=42``, calling ``nhmc.ctrl.hashParams()`` would return the following object: .. code-block:: javascript { "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. .. _jQuery.extend: http://api.jquery.com/jQuery.extend/ .. _nhmc.ctrl-manipulation: ************ Manipulation ************ These functions are used for programmatically manipulating states and counties, which consists of clicking them or triggering :ref:`tooltips ` related to them. Lower-level functions ===================== .. _nhmc.ctrl.highlightArea: nhmc.ctrl.highlightArea ----------------------- *Function* ``nhmc.ctrl.highlightArea(area, pageX, pageY)`` This function highlights the ``area`` object, which is a state or county object from :ref:`nhmc.geo`, renders its :ref:`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: 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 :ref:`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. .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. _VML: http://en.wikipedia.org/wiki/Vector_Markup_Language Higher-level functions ====================== .. _nhmc.ctrl.dehighlightAreas: nhmc.ctrl.dehighlightAreas -------------------------- *Function* ``nhmc.ctrl.dehighlightAreas()`` This function removes any highlights and tooltips created by :ref:`nhmc.ctrl.highlightArea`. .. _nhmc.ctrl.highlightCounty: 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 :ref:`nhmc.ctrl.highlightArea`. .. _nhmc.ctrl.clickCounty: 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 :ref:`nationwide county map ` or the :ref:`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. .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. _VML: http://en.wikipedia.org/wiki/Vector_Markup_Language .. _nhmc.ctrl.highlightState: 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 :ref:`nhmc.ctrl.highlightArea`. .. _nhmc.ctrl.clickState: 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 :ref:`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. .. _SVG: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics .. _VML: http://en.wikipedia.org/wiki/Vector_Markup_Language .. _nhmc.ctrl-orphans: ******* Orphans ******* .. _nhmc.ctrl.renderLegend: 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 :ref:`modules ` often render the legend in different ways. .. todo:: Remove this.