API Docs for: 7.2
Show:

MQA.Display Class

Module: MQA

Controls the screen slide coordinate system.

Methods

addLayer

(
  • key
  • layer
)

Adds a layer to the Display. The layer is expected to handle getting itself attached to the correct zindex container div if it contains DOM element. The two required methods for a layer are resetTransform and setViewport, which take the same args as the methods on Display.

Parameters:

  • key String

    the unique key for the layer

  • layer Object

    the layer to be added

ancestorEventCoords

(
  • domEvent
)

This method will safely determine display and screen coordinates from an event caught by an element that is an ancestor of the display. It returns an object of the form: { screen: { x, y }, // Screen coordinate (offset from the window topleft) display: { x, y}, // Display coordinates latLng: { lat, lng}, // Global coordinates } Note that this method is specifically designed to circumvent the dreaded IE "Error: Failed" exception that plagues events targeted at VML elements.

Parameters:

  • domEvent Object

    a DOM Event with the x/y coords set

beginAnimate

(
  • finalZoom
  • finalResolution
  • finalLat
  • finalLng
  • width
  • height
)

Takes the same parameters as initTransform but signals to all layers that provide explicit animation support that an animation is beginning and will end at the given state. If a layer supports a beginAnimate method, it will be invoked.

Parameters:

cancelDrag

()

Convenience method for making sure no drag operation is in progress.

eachLayer

(
  • cb
)

Iterate over each registered layer invoking the callback and passing the layer followed by the layer key

Parameters:

endAnimate

()

Signals each animating layer to stop their animation.

findParent

(
  • ancestorElt
)
Element

Given an element that is an ancestor of a zlevel, find the zlevel element which is the ultimate parent. This is most commonly used in event handlers in order to find the parent element which "owns" the positioning context.

NOTE: This method can fail on IE when it receives events from VML elements. Callers should wrap in a try-catch handler and deal with this situation.

Parameters:

  • ancestorElt Element

    the DOM elt to start at

Returns <Element>

the zlevel parent elt of the given ancestor, or null if the elt doesn't exist in a zlevel.

getInitialSize

()

Sets the initial DOM width and height on map DOM elt container, based off the provided container elt given in the CoreMap constructor.

initTransform

(
  • zoom
  • resolution
  • refLat
  • refLng
  • width
  • height
)

Should be triggered by a zoom level being set. Sets the Display's display projection and local projection (Transform) to the correct resolution and reference x/y coordinate in display space.

Parameters:

invalidateLayer

(
  • layer
)

Resets the given layer's state by calling layer.setViewport with the current Display values.

Parameters:

  • layer String | Object

    the layer id, or the layer instance itself

removeLayer

(
  • key
)

Removes the layer from the Display that matches the passed layer key. If the layer implements a dispose method it will be called before removing the layer.

Parameters:

  • key String

    the unique key for the layer

startDrag

(
  • startDomEvt
  • delegate
)

Start a drag operation from a DOM event (typically mousedown) captured by an element which is a descendant of the display. The passed in delegate is a single-use object used for the duration of the drag gesture and defines a protocol between the display and the initiator of the drag gesture (usually the TileMap).

Only one drag operation can be active on a display at a given time. A drag operation terminates either when the mouse button is released (mouseup) anywhere in the window, when another drag operation is initiated or when the initiator cancels the drag. In addition, drag operations will be cancelled on certain display state changes, such as a change of transform.

The delegate may define the following methods in order to receive notification of drag progress:

  • dragStart() - This method was called
  • dragMove() - The mouse has been moved
  • dragCancelled() - The drag operation has been cancelled (either because a call was made to cancelDrag() or another drag operation was initiated
  • dragEnd() - The drag operation ended normally because the mouse was released.

Calling this method will result in the creation of the following fields/methods:

  • cancelDrag() - If called, then the drag operation will be cancelled. A call to dragCancelled() will be made.
  • dragXY - The XY coordinates object of the current location of the drag gesture
  • dragLatLng - The global coordinates of the current location of the drag gesture
  • startedToDrag - Flag that is false until the first move of the drag gesture is detected
  • startXY - The starting XY coordinates where the gesture began
  • startLatLng - The starting global coordinates where the gesture began
  • display - The owning display

Parameters:

  • startDomEvt Event
  • delegate Object

zlevel

(
  • level
  • fixed
)
HTMLElement

The W3C defined a very lovely model for determining z-indexing. Unfortunately, the Microsoft developers don't seem to be possessed of the capability to read specs.

Up until IE8, IE introduces a new Z context for every positioned element. What this means is that we can only ever change the zindex on peer positioned elements as opposed to any that share the same z context. As a result, we introduce z-levels as direct children of the display. Overall z management is handled at the z-level while fine, intra-level z-indexing is managed normally with z-index properties.

What this means is that when you need to put something on a map, you call this method to get your parent element based on the overall z-level the thing needs to be a part of. Optionally, specify the fixed parameter as true to disable the display coordinate fixup (ie. coordinates of the resultant element will be screen coordinates, not map coordinates).

Here are the standard z level numbers:

  • 0: Things which need to display "behind" the map tiles (ie. loading tiles)
  • 100: Map tiles
  • 200: Logos/copyrights, etc (fixed)
  • 300: POIs, shape overlays, etc
  • 400: Map controls (fixed)
  • 500: Attached dialogs

See mqa.zindex.js for the full list.

Parameters:

  • level String

    the string constant that represents the zlevel

  • fixed Boolean

    true if the z-index should exist outside the level

Returns <HTMLElement>

the containing div elt for the z-index level