MGLStyle key-value coding compliance

[1ec5]

This PR makes the runtime styling API’s entry points key-value coding compliant.

The -[MGLMapView style] factory method has been replaced with a KVC-compliant style property whose value changes only when reloading the style or changing the style URL. This makes the API more convenient in Swift and more predictable overall.

New layers and sources properties have been added to MGLStyle that make it easy to enumerate style layers or sources without having to hard-code style-specific identifiers in application code. See #5999, #7030, and #7031 for examples of how these properties would be used.

The layers array is ordered from front to back, for consistency with Cocoa, as opposed to mbgl’s back-to-front ordering. There are complementary -insertLayer:aboveLayer: and -insertLayer:belowLayer: methods, for consistency with MapKit’s -[MKMapView insertOverlay:aboveOverlay:] and -[MKMapView insertOverlay:belowOverlay:]. Please double-check my index arithmetic to make sure I didn’t make any off-by-one errors. The sources property is a unordered set. A dictionary mapping identifiers to source objects would better conform to the style specification but would encourage some antipatterns we want to avoid; see #7011 (comment) for details.

The mutable layers and sources collections comply with KVC conventions for to-many relationships, which entails additional methods that mbgl::Map and mbgl::style::Style wouldn’t ordinarily provide. These KVC methods could be optimized further with corresponding methods in mbgl; however, memory management would become a lot less clear. For example, who owns an mbgl::style::Layer if it’s already part of a style but is included in an array passed into -[MGLStyle setLayers:]? Rather than muddle the pointer ownership model or implement complex array diffing, this PR sticks to the safest, most straightforward implementation despite a possible performance tradeoff.

As a real-world stress test of KVC compliance, a sidebar has been added to macosapp that displays the layers in the current style and updates the list automatically using Cocoa bindings. The sidebar can be opened and closed via View ‣ Show/Hide Layers or ⇧⌘L. Layers are shown with their identifiers and icons representing their types. Hidden layers are shown in italics. To toggle one or more layers’ visibility, select them and double-click on them. Or use the context menu, which also has an option to delete the selected layers.

Finally, to illustrate one common use of the new APIs, macosapp now has an option to localize all labels in the user’s preferred language, and the Style toolbar button displays the name of the current style when a custom style is shown.

Hiding layers using the new Layers sidebar in macosapp.

• Make MGLMapView’s style property KVC-compliant
• Make layers API KVC-compliant
• Reverse layers to go from front to back
• Implement -[MGLStyle insertLayer:aboveLayer:] (reprising [macos, ios] Insert layer above #6730)
• Make sources API KVC-compliant
• Fix race condition involving change notifications when switching styles
• Issue change notifications for layers when adding shape annotations
• Add layers sidebar to macosapp
• Allow showing/hiding layers sidebar

Fixes #6003, fixes #6096, fixes #6931.

/cc @frederoni @jfirebaugh

[jfirebaugh]

Map/Style must have ownership of the layers, so this signature needs to be void setLayers(std::vector<std::unique_ptr<style::Layer>>).

[1ec5]

Fixed in e43fbf4.

[jfirebaugh]

Needs an if (!impl->style) guard and impl->styleMutated = true; like the other mutators.

[jfirebaugh]

Constructing a std::unique_ptr from anything other than the result of new is usually incorrect (and even then, you should be using std::make_unique). What's the ownership model of layer.layer?

[1ec5]

It’s complicated: #6254. 😕 Maybe we need to tackle that issue first.

[1ec5]

To respect ownership of the layers passed into -setLayers: – some of which may exist in the style and some of which may be new – we need to ability to remove a layer from the style and regain ownership of it in order to re-add it. So we’re blocked on mbgl::Map::removeLayer() returning ownership of the layer: #6959.

[frederoni]

Great work here @1ec5
This PR will help a lot with debugging and taking runtime styling even further.

[jfirebaugh]

This goes in the opposite branch -- we're only mutating the style if we have one.

[1ec5]

👍 I ended up not using this method in the SDK due to the memory management conundrum in the PR description. Should I keep this method around to complement getLayers() or remove it?

[1ec5]

Fixed.

[jfirebaugh]

Yes, please remove it if it's not used.

[1ec5]

Removed.

[jfirebaugh]

Not part of this PR, but this cast is undefined behavior. You need to write something like:

template <class T, class U>
std::unique_ptr<T> dynamic_ptr_cast(std::unique_ptr<U> p) {
    T* t = dynamic_cast<T*>(p.get());
    if (!t) return nullptr;
    p.release();
    return t;
}

And be aware that this will return a null unique_ptr (and deallocate the input) if the dynamic_cast fails, i.e. if the input is not the anticipated derived type. In this particular code, it looks like this could happen if the user was aliasing *StyleLayer objects while at the same time removing a layer and adding another layer with the same identifier but a different layer type.

[1ec5]

→ #7211