# 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.Control | Controls 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).
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.Control | Create an OpenLayers Control.
Functions |
destroy | The destroy method is used to perform any clean up before the control is dereferenced.
setMap | Set the map property for the control.
draw | The draw method is called when the control is ready to be displayed on the page.
moveTo | Sets the left and top style attributes to the passed in pixel coordinates.
activate | Explicitly activates a control and it’s associated handler if one has been set.
deactivate | Deactivates a control and it’s 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.

### handler

{OpenLayers.Handler} null

### 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

activate | Triggered when activated.
deactivate | Triggered 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 it’s 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 it’s 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 it’s associated handler if one has been set.

> deactivate: function ()

Deactivates a control and it’s 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