---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md
  - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/behavior.Ruler.md
---
# behavior.Ruler

Extends [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md).

The "Ruler" behavior. For marking points on the map and displaying the distance between them.

[Constructor](#constructor-summary) | [Fields](#properties-summary) | [Events](#events-summary) | [Methods](#methods-summary)

## Constructor {#constructor-summary}

```javascript
behavior.Ruler([options])
```

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`options`](#param-options) | — | Type: Object

Options. ||
|| [`options.balloonAutoPan`](#param-options.balloonAutoPan) | true | Type: Boolean

Whether to auto-position the map when opening the ruler balloon. ||
|| [`options.balloonAutoPanUseMapMargin`](#param-options.balloonAutoPanUseMapMargin) | true | Type: Boolean

Whether to account for map margins [map.margin.Manager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.margin.Manager.md) when executing autoPan for the ruler balloon. ||
|#


## Fields {#properties-summary}

#|
|| **Name** | **Type** | **Description** ||
|| [events](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events) | [IEventManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventManager.md)| Event manager.

Inherited from [IEventEmitter](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IEventEmitter.md#events). ||
|| [geometry](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md#geometry) | [geometry.LineString](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/geometry.LineString.md)| "Line" behavior geometry. ||
|| [options](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options) | [IOptionManager](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IOptionManager.md)| Options manager.

Inherited from [ICustomizable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#options). ||
|#

## Events {#events-summary}

#|
|| **Name** | **Description** ||
|| [disable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#event-disable)| Disabling behaviors.

Inherited from [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#event-disable). ||
|| [enable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#event-enable)| Enabling behaviors.

Inherited from [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#event-enable). ||
|| [optionschange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange)| Change to the object options.

Inherited from [ICustomizable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ICustomizable.md#event-optionschange). ||
|| [parentchange](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange)| The parent object reference changed.

Data fields:

- oldParent - Old parent.
- newParent - New parent.

Inherited from [IChild](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChild.md#event-parentchange). ||
|#

## Methods {#methods-summary}

#|
|| **Name** | **Returns** | **Description** ||
|| [close](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md#close)() | Boolean
| Deletes all the points on the ruler. If the current number of points is more than two, confirmation of this action will be requested. ||
|| [disable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#disable)() | | Disables the behavior.

Inherited from [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#disable). ||
|| [enable](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#enable)() | | Enables the behavior.

Inherited from [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#enable). ||
|| [getParent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent)() | [IParentOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IParentOnMap.md)\|null
| Returns link to the parent object, or null if the parent element was not set.

Inherited from [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#getParent). ||
|| [getState](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md#getState)() | String
| The ruler state is described by a string consisting of sequences separated by the "~" symbol. Each sequence is a substring in the format "longitude,latitude" that describes the increment in coordinates relative to the previous ruler point. ||
|| [isEnabled](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#isEnabled)() | Boolean
| Checks whether the behavior is enabled.

Inherited from [IBehavior](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IBehavior.md#isEnabled). ||
|| [setParent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent)([parent](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent-param-parent)) | [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md)
| Sets the parent object. If the null value is passed, the manager element will only be deleted from the current parent object.

Inherited from [IChildOnMap](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/IChildOnMap.md#setParent). ||
|| [setState](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md#setState)([state](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/behavior.Ruler.md#setState-param-state)) | | Retrieves the ruler state from the encoded string. See behavior.Ruler.getState. ||
|#

## Fields details {#field_detail}

### geometry

```javascript
{geometry.LineString} geometry
```

"Line" behavior geometry.

**Example:**

```javascript
// Setting coordinates of the first point on the ruler.
myMap.behaviors.get('ruler').geometry.set(0, [0, 0]);
```

## Methods details {#method_detail}

### close {#close}

```javascript
{Boolean} close()
```

Deletes all the points on the ruler. If the current number of points is more than two, confirmation of this action will be requested.

**Returns** true, if the action was completed successfully.

### getState {#getState}

```javascript
{String} getState()
```

The ruler state is described by a string consisting of sequences separated by the "~" symbol. Each sequence is a substring in the format "longitude,latitude" that describes the increment in coordinates relative to the previous ruler point.

**Returns** the current state of the ruler, in encoded format.

### setState {#setState}

```javascript
{} setState(state)
```

Retrieves the ruler state from the encoded string. See behavior.Ruler.getState.

**Parameters:**

#|
|| **Parameter** | **Default value** | **Description**  ||
|| [`state`](#setState-param-state)[*](*star) | — | Type: String

Encoded state of the ruler. ||
|#

\* Mandatory parameter/option.

[*star]: Mandatory parameter/option.