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
id{String}
map{OpenLayers.Map} this gets set in the addControl() function in OpenLayers.Map
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’.
allowSelection{Boolean} By default, controls do not allow selection, because it may interfere with map dragging.
displayClass{string} This property is used for CSS related to the drawing of the Control.
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).
handlerOptions{Object} Used to set non-default properties on the control’s handler
handler{OpenLayers.Handler} null
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
destroyThe destroy method is used to perform any clean up before the control is dereferenced.
setMapSet the map property for the control.
drawThe draw method is called when the control is ready to be displayed on the page.
moveToSets the left and top style attributes to the passed in pixel coordinates.
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

id

{String}

map

{OpenLayers.Map} this gets set in the addControl() function in OpenLayers.Map

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.

allowSelection

{Boolean} By default, controls do not allow selection, because it may interfere with map dragging.  If this is true, OpenLayers will not prevent selection of the control.  Default is false.

displayClass

{string} This property is used for CSS related to the drawing of the Control.

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.

handlerOptions

{Object} Used to set non-default properties on the control’s handler

handler

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

destroy

destroy: function ()

The destroy method is used to perform any clean up before the control is dereferenced.  Typically this is where event listeners are removed to prevent memory leaks.

setMap

setMap: function(map)

Set the map property for the control.  This is done through an accessor so that subclasses can override this and take special action once they have their map variable set.

Parameters

map{OpenLayers.Map}

draw

draw: function (px)

The draw method is called when the control is ready to be displayed on the page.  If a div has not been created one is created.  Controls with a visual component will almost always want to override this method to customize the look of control.

Parameters

px{OpenLayers.Pixel} The top-left pixel position of the control or null.

Returns

{DOMElement} A reference to the DIV DOMElement containing the control

moveTo

moveTo: function (px)

Sets the left and top style attributes to the passed in pixel coordinates.

Parameters

px{OpenLayers.Pixel}

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

Instances of OpenLayers.Map are interactive maps embedded in a web page.
Base class to construct a higher-level handler for event sequences.
on: function(object)
Convenience method for registering listeners with a common scope.
destroy: function ()
The destroy method is used to perform any clean up before the control is dereferenced.
setMap: function(map)
Set the map property for the control.
draw: function (px)
The draw method is called when the control is ready to be displayed on the page.
moveTo: function (px)
Sets the left and top style attributes to the passed in pixel coordinates.
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.
This class represents a screen coordinate, in x and y coordinates
Close