en-ca 1999-12-31 $id:$ Doc_Builder DM Solutions Group Inc. chameleon@lists.maptools.org Christopher R. Thorne DM Solutions Group Inc. chameleon@lists.maptools.org Paul Spencer DM Solutions Group Inc. chameleon@lists.maptools.org KeyMap TBD Map Widgets 2.0 2005-01-10 TECHRELEASE Paul Spencer DM Solutions Group Inc. chameleon@lists.maptools.org The KeyMap widget is used to display a key map (or reference map) that displays the user's current extents within a larger reference frame, typically the "full" or default extents of the application. The KeyMap widget's attributes are based on the settings that can be used inside a MapServer MAP file REFERENCE object. The KeyMap widget uses the current MAP file's attributes as default values and overrides them with the attributes defined in the template. It is a design choice whether the attributes should be defined in the MAP file or in the widget tag. If the intention is to build a single template that can be reused for several applications with different map files and different spatial areas of interest, then it is preferable to let all the attributes be defined in the MAP file. However, if a template is used for applications for a specific region of interest, and a standard look and feel is necessary, then it is better to define all of the attributes in the widget tag so that the KeyMap will appear the same regardless of the values in the MAP file. Also, if when working with OGC Contexts, the attributes must be defined in the template as there is currently no support for reference maps in Context files. Finally, if building an application that allows the user to change the projection of the map view on the fly, a projection must be defined in the KeyMap attributes in order for it to work correctly, as the MAP file does not have support for projections at this time. The KeyMap's image attribute deserves some description. Even though MapServer cannot handle remote images directly in its REFERENCE object, you can specify a URL to a KeyMap image in the widget. Chameleon will download the image into a local temporary directory and then use that copy of the image with MapServer. Valid ways to specify an image are by URL, by absolute file system path, or by relative file system path. When using a relative file system path, the skinning rules are applied (see Application Developer's Guide to review relative image path searching rules). The MapServer file (*.map) and/or OGC Context file (*.cml) must have a defined projection. To obtain a valid projection, use EPSG projection codes. It is important to define the projection so that the extent values of both the KeyMap and main map have valid units (e.g., decimal degrees, meters, etc.), so that the map becomes geospatially significant within the application map view. The extents values defined in the MapServer file (*.map) and/or OGC Context file (*.xml) must equal the extents defined in the KeyMap widget tag. If they are not equal, then the key map extents rectangle and main map view will not match. The KeyMap widget displays a smaller image of an application's default view of the world and a red rectangle that shows the location of the main map's current view. Clicking on the key map recentres the map view at the point of the click while maintaining the current scale. The key map is a static image defined by the designer of the application. For applications that allow uploading of arbitrary contexts, it is possible that the uploaded context could define a geographically different area than is represented by the key map. In these cases, it is generally recommended that the key map represent the entire world. The key map is a very important tool to help users visually navigate within the map. It enriches users' knowledge of what they are seeing in the main map and also defines the map relationships between map layers. This is accomplished through a combination of the key map image and the rectangle that is dynamically calculated to represent the current extents of the main map. The key map has one more helpful feature - it can be used for map navigation. Unlike other navigation tools that operate only on the main map interface and are restricted to moving based on the current extents, selecting a point on the key map allows the user to rapidly move to a completely different area. <CWC2 TYPE="KeyMap" ENABLED="[TRUE|FALSE]" FORMINDEX="[0 < integer]" VISIBLE="[TRUE|FALSE]" <!-- KeyMap Attributes--> IMAGE="[path]" WIDTH ="[integer]" HEIGHT ="[integer]" COLOR ="[rgbcolor]" OUTLINECOLOR ="[rgbcolor]" MINX ="[float]" MINY ="[float]" MAXX ="[float]" MAXY ="[float]" SRS ="[string]" <!-- Navigation Attribute Group --> CURSORTYPE="[string]" DEFAULT="[TRUE|FALSE]" MAPID="[string]" WIDGETSTYLE="[string]" /> The following example assumes that the application is using a MapServer map file (*.map), as opposed to an OGC Context map file (*.cml), and that this map file contains the Reference Object which holds important key map reference information like: the path to the key map image, the size of the image (width and height, in pixels), the projection, and the extents of what the key map image represents. <cwc2 type="KeyMap"/> The following example assumes that no key map information is defined in the map file (*.map or *.cml) and that there are no default values for the color or outlinecolor attributes. <cwc2 type="KeyMap" image="../htdocs/images/KeyMap.png" width="100" height="75" color="-1 -1 -1" outlinecolor="255 0 0" minx="-2594561" miny=" -712631" maxx="3467361" maxy="3840000" srs="epsg:42304"/> Hawaii Demo www.mapsherpa.com/hawaii2/ The Hawaii Demo uses the latest 1.99 Chameleon version. Base NavTool IMAGE path Widget Only NULL The path to the key map image (URL or directory path). COLOR RGB color Widget Only -1 -1 -1 transparent The fill color for the box drawn to represent the current extents. The default is transparent. HEIGHT integer Widget Only 0 NULL 0 2147483647 The height (in pixels) of the key map image. MAXX float Widget Only NULL -1.#INF 1.#INF The maximum X value (in geographic coordinates) that this image represents. If not set, uses the map extent defined in the map file. MAXY float Widget Only NULL -1.#INF 1.#INF The maximum Y value (in geographic coordinates) that this image represents. If not set, uses the map extent defined in the map file. MINX float Widget Only NULL -1.#INF 1.#INF The minimum X value (in geographic coordinates) that this image represents. If not set, uses the map extent defined in the map file. MINY float Widget Only NULL -1.#INF 1.#INF The minimum Y value (in geographic coordinates) that this image represents. If not set, uses the map extent defined in the map file. OUTLINECOLOR RGB color Widget Only 255 0 0 red The outline color for the box drawn to represent the current extents. SRS string Widget Only NULL The projection in which the extents for this widget are defined. If not set, uses the map projection defined in the map file. This is only required if the key map is in a different projection from the map or the application allows the user to change projections on the fly. WIDTH integer Widget Only 0 NULL 0 2147483647 The width (in pixels) of the key map image. NAV_CMD String The last command that was used to interact with the map. This is set to NAV_KEYMAP if the user clicks on the key map image to recentre the map. NAV_ALLOW_RECTANGLE Boolean Tracks whether the current navigation tool uses a rubber-banding box or not. This is false if key map navigation is used. NAV_INPUT_TYPE String The type of the last navigation command, either POINT or RECTANGLE. NAV_INPUT_COORDINATES String The coordinates that the last command generated. May be a single point or two points representing a rectangle. The coordinates are contained in a single string and are separated by commas. For the key map, this is always a single point, measured in pixels from the top left corner of the image. KeyMapWidget boolean Private [true|false] Ensure that mouse movement events are captured under Microsoft Internet Explorer. gnMouseX float Private -1 The current X position of the mouse over the key map. gnMouseY float Private -1 The current Y position of the mouse over the key map. KeyMapTrackMouseXY Private Called when the user moves the mouse. e unknown true KeyMapCaptureMouse Private This function captures the mouse position. KeyMapReleaseMouse Private This function ends the tracking of the mouse position. KeyMapClicked Private This function submits when the mouse is clicked.