Visibility and opacity

This page covers switching layers on and off, how groups decide whether a layer is actually showing, and setting opacity.

The examples assume a manager with this layer structure, all added switched off. See Layers and groups for how to add them. The trees on this page show the state of each layer after each example.

LayerManager
├── coastline        disabled
└── ocean (group)    disabled
    └── sea-ice      disabled

Switching layers on and off

Switch a layer on with setEnabled:

manager.setEnabled('coastline', true);

The coastline sits at the top level with no groups above it, so switching it on makes it visible straight away:

LayerManager
├── coastline        enabled, visible
└── ocean (group)    disabled
    └── sea-ice      disabled

Switching it off again hides it, and the tree goes back to how it started:

manager.setEnabled('coastline', false);

Enabled and visible

The manager keeps track of two separate things for every layer and group:

• Enabled is whether the layer has been switched on. This is what you set with setEnabled.
• Visible is whether the layer is actually showing. A layer is visible when it is enabled and every group above it is visible too.

For a top-level layer the two are always the same. Inside a group they can differ, because the group above the layer has a say in whether it shows.

Cascading through groups

Switching on a layer that is switched off also switches on every group above it, so the layer becomes visible, however deeply it is nested:

manager.setEnabled('sea-ice', true);

LayerManager
├── coastline        disabled
└── ocean (group)    enabled, visible
    └── sea-ice      enabled, visible

Switching a group off hides everything inside it, but leaves those layers enabled:

manager.setEnabled('ocean', false);

LayerManager
├── coastline        disabled
└── ocean (group)    disabled
    └── sea-ice      enabled, hidden

When the group is switched back on, the sea ice shows again just as it was, and the tree is the same as after switching on the sea ice:

manager.setEnabled('ocean', true);

Showing a layer

setEnabled works like a checkbox. A layer that is already switched on has nothing to switch, so setEnabled(…, true) leaves it as it is, even while a group above it hides it. With the ocean group switched off, the second line here does nothing:

manager.setEnabled('ocean', false);
manager.setEnabled('sea-ice', true);

LayerManager
├── coastline        disabled
└── ocean (group)    disabled
    └── sea-ice      enabled, hidden

When your code needs a layer to show whatever its checkbox says, for example after a search or from a "zoom to layer" button, use showLayer. It switches on the layer and every group above it:

manager.showLayer('sea-ice');

LayerManager
├── coastline        disabled
└── ocean (group)    enabled, visible
    └── sea-ice      enabled, visible

showLayer works on groups too. There is no hideLayer: hiding a layer always means switching off the layer or a group above it, which is what setEnabled does.

Opacity

Every layer and group has its own opacity, from 0 (transparent) to 1 (opaque), set with setOpacity. A group's opacity also applies to the layers inside it, so the manager gives each layer a computed opacity, which is the value to use on the map.

manager.setOpacity('ocean', 0.5);

LayerManager
├── coastline        opacity 1
└── ocean (group)    opacity 0.5
    └── sea-ice      opacity 1, computed opacity 0.5

Listening for changes

Your layer list and the rest of your UI need to react when these values change. Pass onVisibilityChanged and onOpacityChanged callbacks when creating the manager. Each receives the layer's details, including its enabled, visible, opacity and computedOpacity, along with your own layerData.

const manager = new LayerManager<LayerData>({
  onVisibilityChanged(info, visible) {
    console.log(`${info.layerName}: ${visible ? 'showing' : 'hidden'}, enabled: ${info.enabled}`);
  },
  onOpacityChanged(info, computedOpacity) {
    console.log(`${info.layerName}: opacity ${info.opacity}, computed opacity ${computedOpacity}`);
  },
});

Running the cascading examples above prints:

Ocean: showing, enabled: true
Sea ice: showing, enabled: true
Ocean: hidden, enabled: false
Sea ice: hidden, enabled: true
Sea ice: showing, enabled: true
Ocean: showing, enabled: true

The callbacks fire for groups as well as layers, and only for those whose values actually changed. Switching on the sea ice, for example, also reports the ocean group.

Switching on and off

Visibility doesn't tell you about every checkbox change. While a group hides a layer, switching the layer off leaves it hidden, so onVisibilityChanged doesn't fire. Use onEnabledChanged to keep your checkboxes in step:

const manager = new LayerManager<LayerData>({
  onEnabledChanged(info, enabled) {
    console.log(`${info.layerName}: ${enabled ? 'switched on' : 'switched off'}`);
  },
});

With the ocean group switched off, switching off the sea ice prints:

Sea ice: switched off

TIP

In a layer list, tie each checkbox to info.enabled and update it from onEnabledChanged. Use info.visible to show whether the layer is actually on the map, for example by greying out a row that is switched on but hidden.