OpenLayers.Control

Controls affect the display or behavior of the map.  They allow everything from panning and zooming to displaying a scale indicator.  Controls by default are added to the map they are contained within however it is possible to add a control to an external div by passing the div in the options parameter.

Example

The following example shows how to add many of the common controls to a map.

var map = new OpenLayers.Map('map', { controls: [] });

map.addControl(new OpenLayers.Control.PanZoomBar());
map.addControl(new OpenLayers.Control.LayerSwitcher({'ascending':false}));
map.addControl(new OpenLayers.Control.Permalink());
map.addControl(new OpenLayers.Control.Permalink('permalink'));
map.addControl(new OpenLayers.Control.MousePosition());
map.addControl(new OpenLayers.Control.OverviewMap());
map.addControl(new OpenLayers.Control.KeyboardDefaults());

The next code fragment is a quick example of how to intercept shift-mouse click to display the extent of the bounding box dragged out by the user.  Usually controls are not created in exactly this manner.  See the source for a more complete example:

var control = new OpenLayers.Control();
OpenLayers.Util.extend(control, {
    draw: function () {
        // this Handler.Box will intercept the shift-mousedown
        // before Control.MouseDefault gets to see it
        this.box = new OpenLayers.Handler.Box( control,
            {"done": this.notice},
            {keyMask: OpenLayers.Handler.MOD_SHIFT});
        this.box.activate();
    },

    notice: function (bounds) {
        OpenLayers.Console.userError(bounds);
    }
});
map.addControl(control);
Summary
OpenLayers.ControlControls affect the display or behavior of the map.
Properties
div{DOMElement} The element that contains the control, if not present the control is placed inside the map.
type{Number} Controls can have a ‘type’.
title{string} This property is used for showing a tooltip over the Control.
autoActivate{Boolean} Activate the control when it is added to a map.
active{Boolean} The control is active (read-only).
eventListeners{Object} If set as an option at construction, the eventListeners object will be registered with OpenLayers.Events.on.
events{OpenLayers.Events} Events instance for listeners and triggering control specific events.
Constructor
OpenLayers.ControlCreate an OpenLayers Control.
Functions
activateExplicitly activates a control and its associated handler if one has been set.
deactivateDeactivates a control and its associated handler if any.
Constants
OpenLayers.Control.TYPE_BUTTON
OpenLayers.Control.TYPE_TOGGLE
OpenLayers.Control.TYPE_TOOL

Properties

div

{DOMElement} The element that contains the control, if not present the control is placed inside the map.

type

{Number} Controls can have a ‘type’.  The type determines the type of interactions which are possible with them when they are placed in an OpenLayers.Control.Panel.

title

{string} This property is used for showing a tooltip over the Control.

autoActivate

{Boolean} Activate the control when it is added to a map.  Default is false.

active

{Boolean} The control is active (read-only).  Use activate and deactivate to change control state.

eventListeners

{Object} If set as an option at construction, the eventListeners object will be registered with OpenLayers.Events.on.  Object structure must be a listeners object as shown in the example for the events.on method.

events

{OpenLayers.Events} Events instance for listeners and triggering control specific events.

Register a listener for a particular event with the following syntax

control.events.register(type, obj, listener);

Listeners will be called with a reference to an event object.  The properties of this event depends on exactly what happened.

All event objects have at least the following properties

object{Object} A reference to control.events.object (a reference to the control).
element{DOMElement} A reference to control.events.element (which will be null unless documented otherwise).

Supported map event types

activateTriggered when activated.
deactivateTriggered when deactivated.

Constructor

OpenLayers.Control

Create an OpenLayers Control.  The options passed as a parameter directly extend the control.  For example passing the following:

var control = new OpenLayers.Control({div: myDiv});

Overrides the default div attribute value of null.

Parameters

options{Object}

Functions

activate

activate: function ()

Explicitly activates a control and its associated handler if one has been set.  Controls can be deactivated by calling the deactivate() method.

Returns

{Boolean} True if the control was successfully activated or false if the control was already active.

deactivate

deactivate: function ()

Deactivates a control and its associated handler if any.  The exact effect of this depends on the control itself.

Returns

{Boolean} True if the control was effectively deactivated or false if the control was already inactive.

Constants

OpenLayers.Control.TYPE_BUTTON

OpenLayers.Control.TYPE_TOGGLE

OpenLayers.Control.TYPE_TOOL

on: function(object)
Convenience method for registering listeners with a common scope.
activate: function ()
Explicitly activates a control and its associated handler if one has been set.
deactivate: function ()
Deactivates a control and its associated handler if any.
The Panel control is a container for other controls.
Close