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

• Введение
• Основы
  • Элементы управления
  • Группы элементов управления
  • Менеджер элементов управления
• Класс DG.Controls.Zoom
  • Конструктор
• Класс DG.Controls.FullScreen
  • Конструктор
• Класс DG.ControlPosition
  • Конструктор
  • Методы
    • Установить позицию элемента управления
• Класс элемента управления DG.Controls.Abstract
  • Методы
    • Получить контейнерный DOMElement элемента управленияя
    • Получить объект карты
    • Получить идентификатор элемента управления
    • Получить все доступные состояния элемента управления
    • Получить состояние элемента управления
    • Проверка нахождения в определенном состоянии
    • Установка свойств элементу управления
    • Скрыть элемент управления
    • Показать элемент управления
    • Удалить элемент управления
• Класс менеджера элементов управления DG.Controls
  • Методы управления группами элементов управления
    • Создать группу
    • Удалить группу
    • Получить список имен групп
    • Получить уже созданный объект группы по ее имени
  • Методы управления элементами управления
    • Добавить элемент управления
    • Удалить элемент управления
    • Получить список всех элементов управления
    • Получить элемент управления по его идентификатору
    • Удалить все элементы управления
• Класс группы элементов управления DG.ControlGroup
  • Методы
    • Добавить элемент управления в группу
    • Удалить элемент управления из группы
    • Получить список всех элементов управления в группе
    • Получить элемент управления по его идентификатору в группе
    • Удалить все элементы управления из группы
    • Скрыть группу
    • Отобразить группу
    • Получить количество элементов управления в группе
    • Проверить наличие элемента управления в группе
    • Получить порядковый номер элемента управления в группе
    • Выполнить операцию для каждого элемента управления в группе
    • Получить имя группы

Введение

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

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

Основы

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

В настоящий момент доступны элементы управления:
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	Возвращает имя группы, которое задается в конструкторе группы при ее создании.