Screen labels are 2D labels that follow a location on the globe or map. As the user moves, they move, but don’t get any bigger or smaller. You have a lot of control over how they look and interact, but they’re simple to use.
We’re going to make use of country outlines from the Vector Data tutorial if you have not yet. If you don’t have a project, build one with the Hello Earth tutorial and you can use this ViewController (for Objective-C or Swift). You’ll also need the source data from that tutorial.
Let’s take a quick look at our project from before. There’s a method in there called addCountries that we’ll be expanding.
As a reminder, that routine is doing the following.
Kicking off another thread.
Loading each and every GeoJSON file it finds.
Adding them as vectors.
We’re going to make a really minor tweak to add a MaplyScreenLabel per country.
We’ll be adding code right after the line where it says the following.
For Swift, we’ll do it after the line where we assign vecName to userObject attribute.
Here’s the plan. We’ll create a MaplyScreenLabel, give it a location and some text and then add it. Adding it involves a little styling, but we’ll keep it simple.
So labels! Great! And they move around but stay the same size! Let’s look a little closer.
Let’s look at what we did there. First, we created a MaplyScreenLabel. We gave it some text, which was the country name and we gave it a location, the middle point of the country. For this, it’s recommended to use the centroid of the polygon, instead of just the center. This gives you more accurate results for countries with outlier regions. And you don’t want your label to be placed outside the country, do you?
Then it gets interesting. You may notice we’re calling addScreenLabels to, ya know, add the labels. This method takes an array, so we make a small one and it takes a description dictionary.
Description dictionaries are a little wacky. Rather than specify everything in the MaplyScreenLabel, we stuff much of it in an NSDictionary and pass that in. This lets us leave lots of stuff out and gives it a styling sort of feel.
The description dictionary contains entries for the font, outline details, and the text color. Consult the addScreenLabels method documentation for a full list of options.
But there’s one problem. Those labels are all on top of each other. Can we do anything about that?
WhirlyGlobe-Maply has an interactive label and marker layout engine. All you have to do is use it. Right when you create the MaplyScreenLabel do this.
Now it looks like this.
To ignore the layout engine, layoutImportance to MAXFLOAT. Otherwise, it’s just a number we use for sorting. Assign it however you like.