Cartographer API Documentation

From WowAce Wiki

For Cartographer-Notes API, see Notes.

Contents 1 Cartographer:AddToMagnifyingGlass("text") 1.1 Args 1.2 Example 2 Cartographer:RemoveFromMagnifyingGlass("text") 2.1 Args 2.2 Example 3 Cartographer:SetCurrentInstance("zone") 3.1 Args 3.2 Remarks 3.3 Example 4 Cartographer:GetCurrentInstance() 4.1 Returns 4.2 Remarks 4.3 Example 5 Cartographer:RegisterInstanceWorldMapButton(frame) 5.1 Args 5.2 Remarks 5.3 Example 6 Cartographer:GetInstanceWorldMapButton() 6.1 Returns 6.2 Example 7 Cartographer:GetCurrentLocalizedZoneName() 7.1 Returns 7.2 Example 8 Cartographer:GetCurrentEnglishZoneName() 8.1 Returns 8.2 Example 9 Cartographer:AcquireSideTablet("side", handler) 9.1 Args 9.2 Remarks 9.3 Example 10 Cartographer:ReleaseSideTablet("side", handler) 10.1 Args 10.2 Remarks 10.3 Example 11 Cartographer:RefreshSideTablet(["side"] [, handler]) 11.1 Args 11.2 Remarks 11.3 Example 12 Cartographer:GetCurrentSideTabletHandler("side") 12.1 Args 12.2 Returns 12.3 Example 13 Cartographer:PointToYards(x, y) 13.1 Args 13.2 Returns 13.3 Example 14 Cartographer:GetDistanceToPoint(x, y [, "zone" [, x_p, y_p [, "zone_p"]]]) 14.1 Args 14.2 Returns 14.3 Example 15 Cartographer:GetCurrentPlayerPosition() 15.1 Returns 15.2 Remarks 15.3 Example 16 Event: "Cartographer_MapClosed" 17 Event: "Cartographer_MapOpened" 18 Event: "Cartographer_ChangeZone" - ["englishZone", "localizedZone"] 18.1 Provided args 19 Event: "Cartographer_SetCurrentInstance" - ["zone"] 19.1 Provided args 19.2 Remarks 20 Event: "Cartographer_RegisterInstanceWorldMapButton" - frame

Cartographer:AddToMagnifyingGlass("text")

Adds text to the magnifying glass in the top=left of the world map frame.

Args

"text" 

string - text to add

Example

Cartographer:AddToMagnifyingGlass("Left-click to make the monkey dance")

Cartographer:RemoveFromMagnifyingGlass("text")

Removes text from the magnifying glass in the top=left of the world map frame.

Args

"text" 

string - text to remove

Example

Cartographer:RemoveFromMagnifyingGlass("Left-click to make the monkey dance")

Cartographer:SetCurrentInstance("zone")

Sets the current instance the world map is handling.

Args

"zone" 

string - instance to change to

Remarks

This should only be set by a module that shows the instance.

"zone" must be in English.

Example

Cartographer:SetCurrentInstance("Scarlet Monastery")

Cartographer:GetCurrentInstance()

Returns the current instance the world map is handling.

Returns

string - the current instance the world map is handling. Note: may be nil.

Remarks

You'd probably want to get Cartographer:GetCurrentEnglishZoneName() instead.

Example

local instance = Cartographer:GetCurrentInstance(")

Cartographer:RegisterInstanceWorldMapButton(frame)

Sets the instance WorldMapButton, that allows the user to click on.

Args

frame 

frame - the button to register.

Remarks

This should only be set by the module that shows the instance map.

Example

Cartographer:RegisterInstanceWorldMapButton(myFrame)

Cartographer:GetInstanceWorldMapButton()

Returns the instance WorldMapButton.

Returns

frame - the instance WorldMapButton. Note: may be nil.

Example

local frame = Cartographer:GetInstanceWorldMapButton()

Cartographer:GetCurrentLocalizedZoneName()

Returns the localized name of the map the user is currently viewing.

Returns

string - the localized name of the map the user is currently viewing. Note: may be nil if viewing a continent.

Example

local zone = Cartographer:GetCurrentLocalizedZoneName()

Cartographer:GetCurrentEnglishZoneName()

Returns the English name of the map the user is currently viewing.

Returns

string - the English name of the map the user is currently viewing. Note: may be nil if viewing a continent.

Example

local zone = Cartographer:GetCurrentEnglishZoneName()

Cartographer:AcquireSideTablet("side", handler)

Acquires a side tablet for the handler to use.

Args

"side" 

string - "LEFT" or "RIGHT"

handler 

table - handler that includes :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest()

Remarks

The handler provided must include either :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest(), depending on the "side" provided

This will steal the lock from another handler if need be.

Example

Cartographer:AcquireSideTablet("LEFT", MyAddon)

Cartographer:ReleaseSideTablet("side", handler)

Release a side tablet back to Cartographer

Args

"side" 

string - "LEFT" or "RIGHT"

handler 

table - handler that includes :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest()

Remarks

The handler provided must include either :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest(), depending on the "side" provided

This can be called and have no effect if the handler does not have a lock on the given side.

Example

Cartographer:ReleaseSideTablet("LEFT", MyAddon)

Cartographer:RefreshSideTablet(["side"] [, handler])

Release a side tablet back to Cartographer

Args

["side"] 

string - "LEFT" or "RIGHT"

nil - both sides

handler 

table - handler that includes :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest()

nil - refresh no matter the handler

Remarks

The handler provided must include either :OnCartographerLeftTabletRequest() or :OnCartographerRightTabletRequest(), depending on the "side" provided

This will refresh the contents of the tablet. If the given handler/side combo is not in use, then this will have no effect.

Example

Cartographer:RefreshSideTablet("LEFT", MyAddon)

Cartographer:GetCurrentSideTabletHandler("side")

Return the handler of the given side

Args

"side" 

string - "LEFT" or "RIGHT"

Returns

table - handler
nil - no handler currently

Example

if Cartographer:GetCurrentSideTabletHandler("LEFT") == MyAddon then
    -- do something
end

Cartographer:PointToYards(x, y)

Turn an x/y coordinate pair into yards.

Args

x 

number - horizontal coordinate [0, 1]

y 

number - vertical coordinate [0, 1]

Returns

x_yards, y_yards

x_yards 

number - horizontal coordinate in yards

y_yards 

number - vertical coordinate in yards

Example

x, y = Cartographer:PointToYards(x, y)

Cartographer:GetDistanceToPoint(x, y [, "zone" [, x_p, y_p [, "zone_p"]]])

Return the distance between two points

Args

x 

number - first horizontal coordinate [0, 1]

y 

number - first vertical coordinate [0, 1]

["zone"] 

text - real zone text for the coordinates (default: plyer's current zone)

[x_p] 

number - second horizontal coordinate [0, 1] (default: player x position)

[y_p] 

number - second vertical coordinate [0, 1] (default: player y position)

["zone_p"] 

text - real zone text for the player's location (default: player's current zone)

Returns

distance

distance 

number - number of yards between the two points given

Example

local distance = Cartographer:GetDistanceToPoint(x, y)

Cartographer:GetCurrentPlayerPosition()

Return the position of the player as if looking at the zoomed-in map, even if the map is actually zoomed out or the player not visible.

Returns

x, y, "zone"

x 

number - horizontal position [0, 1]

y 

number - vertical position [0, 1]

"zone" 

string - english name of the zone or continent.

Remarks

The "zone" return may return a continent if in an instance but not actually inside the instance, e.g. Wailing Caverns.

Example

local x, y, zone = Cartographer:GetCurrentPlayerPosition()

Event: "Cartographer_MapClosed"

Fired when the map is closed.

Event: "Cartographer_MapOpened"

Fired when the map is opened.

Event: "Cartographer_ChangeZone" - ["englishZone", "localizedZone"]

Fired when the map changes to a different zone.

Provided args

["englishZone"] 

string - English name of the zone.

nil - not looking at a zone, could be looking at a continent.

["localizedZone"] 

string - Localized name of the zone.

nil - not looking at a zone, could be looking at a continent.

Event: "Cartographer_SetCurrentInstance" - ["zone"]

Fired when the map changes to an instance or from an instance.

Provided args

["zone"] 

string - English name of the instance

nil - switched away from an instance.

Remarks

You probably should check Cartographer_ChangeZone instead.

Event: "Cartographer_RegisterInstanceWorldMapButton" - frame

Fired when Cartographer:RegisterInstanceWorldMapButton(frame) is called.