Элементы управления

Введение

Элементы управления — это компоненты пользовательского интерфейса, с помощью которых пользователь может менять настройки карты.

Предполагается, что вы уже ознакомились с разделами «Быстрый старт», «Карта» и «События».

Основы

Элементы управления

В настоящий момент доступны элементы управления:
DG.Controls.Zoom — позволяет менять разрешение карты;
DG.Controls.Abstract — класс, с помощью которого можно создавать свои собственные элементы управления.

Группы элементов управления

Каждый элемент управления должен принадлежать определенной группе. Это даёт возможность выполнять групповые операции.

Например, пусть у нас есть два типа элементов управления: одни для перемещения по городам, другие для фиксированной установки масштаба. Разместив первые в одну группу, а вторые — в другую, мы можем явно манипулировать каждым из наборов элементов управления.

Объект группы предоставляет наиболее полный арсенал методов для управления элементами управления.

Любые операции с элементами управления в группе сразу же отображаются на карте.

Менеджер элементов управления

Менеджер отвечает за управление группами. А группы, в свою очередь, управляют элементами управления.

При этом, для удобства, часть методов по работе с элементами управления есть также и в менеджере.

Менеджер элементов управления доступен как свойство controls объекта карты:

// Инициализируем объект карты:
var myMap = new DG.Map("myMapId");
// Менеджер элементов управления:
myMap.controls;

Класс DG.Controls.Zoom

Конструктор

Пример:

// Создаем элемент управления коэффициентом масштабирования:
myControlZoom = new DG.Controls.Zoom();

Класс DG.Controls.FullScreen

Кнопка разворачивания карты на весь экран браузера и восстановления предыдущего размера.

Класс является устаревшим. Рекомендуем использовать стандартную реализацию данного элемента управленния.

Конструктор

Пример:

// Создаем элемент управления:
myFullScreenControl = new DG.Controls.FullScreen();

Класс DG.ControlPosition

Для того чтобы разместить элемент управления в нужном месте карты, используем класс DG.ControlPosition.

Для наглядности допустим, что myPosition — экземпляр класса DG.ControlPostition.

Конструктор

Параметры:

Имя Тип Обязательный Описание
position String Да Задает точку отсчета для объекта DG.Point, тем самым позволяя определить область размещения элемента управление на карте.

Допустимые значения:
DG.ControlPosition.TOP_LEFT — Верхний левый угол границы карты. Константа.
DG.ControlPosition.TOP_RIGHT — Верхний правый угол границы карты. Константа.
DG.ControlPosition.BOTTOM_LEFT — Нижний левый угол границы карты. Константа.
DG.ControlPosition.BOTTOM_RIGHT — Нижний правый угол границы карты. Константа.
offsets DG.Point Да Объект DG.Point. Задает позицию элемента управления — отступы от новой точки отсчета, заданной в position. Значения в пикселях.

Пример:

var myPosition = new DG.ControlPosition(DG.ControlPosition.TOP_RIGHT, new DG.Point(20,10));

Получим элемент управления в правом верхнем углу карты с отступами 20 и 10 пикселей от границ карты, по горизонтали и вертикали соответственно.

Методы

Установить позицию элемента управления
myPosition.apply(controlDiv)

Параметры:

Имя Тип Обязательный Описание
controlDiv DOMElement Да Контейнерный DOM-элемент элемента управления.

Класс элемента управления DG.Controls.Abstract

Ниже мы подробно рассмотрим, как создавать свои собственные элементы управления.

Если вам достаточно уже готовых элементов управления, можете сразу переходить к следующему разделу «Класс менеджера элементов управления DG.Controls».

Особенность создания собственных классов элементов управления в том, что мы их создаем специальным методом. Но об этом ниже.

Методы

DG.Controls.Abstract.extend(obj)

Параметры:

Имя Тип Обязательный Описание
obj Object Да Объект, который должен содержать методы onAddToMap() и onRemoveFromMap().

Возвращает:

Тип Описание
Function Функция-конструктор, с помощью которой можно создать объект элемента управления. Важно понимать, что любой класс — это функция-конструктор.

Внесем ясность. Допустим, мы хотим создать класс MyControlClass. На первом шаге создаем объект obj, который содержит методы onAddToMap() и onRemoveFromMap():

var obj = {
onAddToMap: function(map) { // где map - экземпляр карты
// ...
},
onRemoveFromMap: function() {
// ...
},
// возвращает массив строк, которые представляют собой некие состояния элемента управления:
getStates: function(
// ...
)
}

На втором шаге создаем класс MyControlClass:

var MyControlClass = DG.Controls.Abstract.extend(obj);

Теперь, чтобы создать объект класса MyControlClass, все как обычно:

// Создаем объект элемента управления:
var myControl = new MyControlClass();
// Добавляем элемент управления на карту:
myMap.controls.add(myControl);

При этом метод obj.onAddToMap будет вызван при создании класса MyControlClass, а метод obj.onRemoveFromMap — при его удалении.

Важная особенность: MyControlClass содержит все члены объекта obj, а также все методы DG.Controls.Abstract, которые мы рассмотрим в дальнейшем.

Сейчас рассмотрим комплексный, но достаточно сложный пример.

Пример:

UserMoscowControl = DG.Controls.Abstract.extend({
observers: [],

// Инициализация элемента управления:
onAddToMap: function (map) {

// Получение главного контейнера элемента управления, он автоматически добавляется к карте:
var container = this.getContainer();

// Создание вложенных элементов:
var controlMove = document.createElement('DIV');
controlMove.id = container.id+'_controlMove';
controlMove.style.backgroundColor = 'white';
controlMove.style.cursor = 'pointer';
controlMove.innerHTML = 'Moscow';
container.appendChild(controlMove);

// Подписка на событие элемента управления:
this.observers.push(this.getDgMap().addEventListener(controlMove.id, 'DgClick', function(){ myMap.setCenter(new DG.GeoPoint(37.609,55.753)); }));
},

// Очистка всех зависимостей при удалении элемента управления с карты:
onRemoveFromMap: function () {
var oIndex;
for (oIndex in this.observers) {
this.observers[oIndex].cleanup();
this.observers[oIndex] = null;
}
},

// Указание допустимых состояний для обработчика событий:
getStates: function () {
return ['enable', 'disable'];
},

// Включение обработчика событий при установленном состоянии 'enable':
onEnable: function () {
this.getContainer().className = 'uTControlEnabled';

var oIndex;
for (oIndex in this.observers) {
this.observers[oIndex].enable();
}
},

// Выключение обработчика событий при установленном состоянии 'disable':
onDisable: function () {
this.getContainer().className = 'uTControlDisabled';

var oIndex;
for (oIndex in this.observers) {
this.observers[oIndex].disable();
}
}
});

DG.autoload( function () {

// Создание карты:
myMap = new DG.Map('map');
myMap.setCenter(new DG.GeoPoint(82.927810142519,55.028936234826));
myMap.setZoom(16);
myMap.controls.add(new DG.Controls.Zoom());

// Добавление элемента управления на карту:
myMap.controls.add(new UserMoscowControl('myControl'), null, new DG.ControlPosition(DG.ControlPosition.TOP_RIGHT, new DG.Point(20,10)));

// Установка состояния элемента управления. В данном случае включение.
myMap.controls.get('myControl').setState('enable');
});

В результате получим элемент управления, который находится в правом верхнем углу экрана и представляет собою прямоугольник с надписью Moscow, при клике по которой центр карты устанавливается в центр города Москва — координаты (37.609, 55.753).

Получить контейнерный DOMElement элемента управленияя
myControl.getContainer()

Возвращает:

Тип Описание
DOMElement Контейнерный DOMElement элемента управления
Получить объект карты
myControl.getDgMap()

Возвращает:

Тип Описание
DG.Map Объект карты, на которой размещен элемент управления
Получить идентификатор элемента управления
myControl.getId()

Возвращает:

Тип Описание
String Идентификатор элемента управления, который генерируется в момент его создания.
Получить все доступные состояния элемента управления
myControl.getStates()

Возвращает:

Тип Описание
Array Массив строк, которые представляют собой доступные состояния элемента управления.
Получить состояние элемента управления
myControl.getState()

Возвращает:

Тип Описание
String Текущее состояние элемента управления.
Проверка нахождения в определенном состоянии
myControl.isInState(state)

Параметры:

Имя Тип Обязательный Описание
state String Да Состояние элемента управления

Возвращает:

Тип Описание
Boolean true — если элемент управления находится в заданном состоянии, false — в других случаях.
Установка свойств элементу управления
myControl.setState(state)

Параметры:

Имя Тип Обязательный Описание
state String Да Состояние элемента управления
Скрыть элемент управления
myControl.hide()
Показать элемент управления
myControl.show()
Удалить элемент управления
myControl.destroy()

Класс менеджера элементов управления DG.Controls

Менеджер отвечает за управление группами. А группы, в свою очередь, управляют элементами управления.

При этом, для удобства, часть методов по работе с маркерами есть также и в менеджере.

Ниже мы подробно рассмотрим все методы класса менеджера. Для наглядности допустим, что myMap — объект карты.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем, представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Создать менеджер слоев явно через ключевое слово new нельзя. Он автоматически доступен как свойство controls объекта карты.

Методы управления группами элементов управления

Создать группу
myMap.controls.createGroup(groupName)

Параметры:

Имя Тип Обязательный Описание
groupName String Да Название группы. Должно быть уникальным.

Возвращает:

Тип Описание
DG.ControlGroup Экземпляр класса DG.ControlGroup
Удалить группу
myMap.controls.removeGroup(groupName)

Параметры:

Имя Тип Обязательный Описание
groupName String Да Название группы.
Получить список имен групп
myMap.controls.getAllGroupsNames()

Возвращает:

Тип Описание
Array Список имен групп. Массив строк.
Получить уже созданный объект группы по ее имени
myMap.controls.getGroup(groupName)

Параметры:

Имя Тип Обязательный Описание
groupName String Да Название группы.

Возвращает:

Тип Описание
DG.ControlGroup | null Экземпляр класс DG.ControlGroup, который уже был создан с помощью метода myMap.controls.createGroup. Если запросить у метода несуществующую группу, возвращает null.

Методы управления элементами управления

Далее рассмотрим часть методов по работе с элементами управления, которую можно выполнить в менеджере. Если требуются более сложные операции, их можно выполнить средствами объекта группы.

Добавить элемент управления
myMap.controls.add(сontrol, groupName, position)

Параметры:

Имя Тип Обязательный Описание
сontrol Object Да Элемент управления. Объект элемента управления.
groupName String Нет

Название группы. Если параметр не передан, элемент управления будет добавлен в группу по умолчанию.

Если название группы новое, автоматически будет создана новая группа с переданным именем.

Ограничение: нельзя добавлять один и тот же элемент управления дважды, во-первых, в одну группу, а во-вторых, в несколько групп сразу.

position DG.ControlPosition Нет Положение элемента управления
Удалить элемент управления
myMap.controls.remove(item)

Параметры:

Имя Тип Обязательный Описание
item Object | String Да Может быть либо объектом элемента управления, либо его идентификатором. Для получения идентификатора у элемента управления есть метод getId().
Получить список всех элементов управления
myMap.controls.getAll()

Возвращает:

Тип Описание
Array Массив объектов элементов управления.
Получить элемент управления по его идентификатору
myMap.controls.get(id)

Параметры:

Имя Тип Обязательный Описание

Возвращает:

Тип Описание
Object Объект элемента управления.
Удалить все элементы управления
myMap.controls.removeAll()

При этом, хоть все элементы управления и удаляются, группы остаются не тронутыми.

Класс группы элементов управления DG.ControlGroup

Объект группы предоставляет наиболее полный арсенал методов, для управления элементами управления.

Ниже мы подробно рассмотрим все методы класса группы элементов управления. Для наглядности допустим, что myGroup — объект группы.

Описание методов представляет собой действие (что делает метод, для чего он нужен?) и название метода. Вместе с тем, представлены дополнительно параметры, возвращаемое значение метода и особенности, если таковые имеются.

Создать группу элементов управления явно через ключевое слово new нельзя. Правильно это делать с помощью метода createGroup менеджера элементов управления.

Методы

Добавить элемент управления в группу
myGroup.add(item, index)

Параметры:

Имя Тип Обязательный Описание
item Object Да Объект элемента управления
index Number Нет

Порядковый номер добавляемого элемента управления в группе. При этом нумерация элементов управления начинается с нуля.

Если параметр не передан, элемент управления будет добавлен в конец группы.

Ограничение: значение должно быть целым неотрицательным числом не превышающим текущее кол-во элементов управления в группе. Таким образом обеспечивается непрерывная нумерация элементов в группе.

Удалить элемент управления из группы
myGroup.remove(item)

Параметры:

Имя Тип Обязательный Описание
item Object Да Объект элемента управления
Получить список всех элементов управления в группе
myGroup.getAll()

Возвращает:

Тип Описание
Array Массив состоящий из объектов элементов управления.
Получить элемент управления по его идентификатору в группе
myGroup.get(item)

Параметры:

Имя Тип Обязательный Описание
item Number Да Порядковый номер элемента управления в группе
Удалить все элементы управления из группы
myGroup.removeAll()

При этом, хоть все элементы управления и удаляются из группы, сам объект группы остается не тронутыми.

Скрыть группу
myGroup.get(item)

При этом все элементы управления становятся невидимыми. Более того, при добавлении новых элементов управления, они также остаются невидимыми.

Отобразить группу
myGroup.show()
Получить количество элементов управления в группе
myGroup.length()

Возвращает:

Тип Описание
Number Возвращает количество элементов управления в группе
Проверить наличие элемента управления в группе
myGroup.contains(item)

Параметры:

Имя Тип Обязательный Описание
item Object Да Объект элемента управления

Возвращает:

Тип Описание
Boollean Возвращает true, если элемент управления содержится в группе. В противном случае - false.
Получить порядковый номер элемента управления в группе
myGroup.indexOf(item)

Параметры:

Имя Тип Обязательный Описание
item Object Да Объект элемента управления

Возвращает:

Тип Описание
Number | null Возвращает порядковый номер элемента управления в группе. Нумерация начинается с нуля.Если элемента управления нет в группе, возвращает null.
Выполнить операцию для каждого элемента управления в группе
myGroup.forEach(callback, context)

Параметры:

Имя Тип Обязательный Описание
callback Function Да Сallback-функция, вызываемая для каждого элемента в группе. Функция вызывается со следующими параметрами callback(control, index, group), где:
control — текущий элемент управления,
index — порядковый номер текущего элемента управления (нумерация начинается с нуля),
group — объект группы myGroup.
context Object Нет Контекст выполнения callback-функции. Другими словами, что будет скрываться за ключевым словом this внутри callback-функции. Если параметр не передан, по умолчанию this равен глобальному объекту window.
Получить имя группы
myGroup.getName()

Возвращает:

Тип Описание
String Возвращает имя группы, которое задается в конструкторе группы при ее создании.