Component is an abstract class that serves as basis for defining
replaceable software modules that extend the basic map with additional
functionality. Components allow API users to:
- include new functionality
- replace existing functionality with a different implementation
- deactivate existing functionality.
A component may fire custom events.
Component class is implemented in several packages outside
the map package, for example in routing and search.
The fact that components are replaceable and that they can add or remove other components, creating and potentially disrupting inter-component dependencies, makes a reference counting mechanism necessary. The basic principle is that whenever a component is created its reference count is incremented to indicate that the creator requires it (and holds a reference to it). The count is also incremented when a component already exists, but a new attempt to create it is made - thus, the count goes up, but duplicate components with the same id are not created. An attempt to deleted/remove a component, causes its reference count to be decremented.
This mechanism prevents not only component duplication, but also the removal
of components while other components dependent on them for as long as the
dependencies exist. Caution when physically removing components is necessary,
because on removal, a component's
detach callback is called to
delete its reference to the map
Display. As a result, the
component becomes unusable in an invalid state.
However, this mechanism remains transparent and you, as the API user simply need
to call the methods
of the map
Display class to add and remove components, respectively.
Here is an example:
// If a Kinetic component already exists, addComponent() // returns it instead of creating a duplicate. var component = display.addComponent(new nokia.maps.map.component.panning.Kinetic()); // If any other component or application part holds a reference // to the component, this call does not remove the component, but // decrements the reference counter by one, otherwise it removes // the component (if the reference counter reached zero). display.removeComponent(component); // Another possibility to remove a component is: display.removeComponent( display.getComponentById("panning.Kinetic") );
Note that a component must not be bound to two instances of
at the same time!
A reference to the
A reference to the
map.Displayinstance to which the given component belongs.