elmWrapper – обертка для произвольного элемента HTML-кода

Для элемента HTML-кода можно получить упрощающую некоторые манипуляции с этим объектом. Для получения такой обертки рекомендуется использовать методы у winWrapper, такие как getElement, getForm, getFormElement, getImage, getCloneElement, getElmWrapper или getElementWrapper.

Как вариант можно использовать специальную функцию getElmWrapper(element, windowWrapper), где в качестве первого атрибута передается ссылка на оборачиваемый элемент. В качестве второго атрибута - передается ссылка на обертку окна содержащего объект (второй параметр может не указываться, если Вы работаете только с одним окном). Данная функция может использоваться для самых простых задач. Но, тем не менее, ее использование не рекомендуется - гораздо правильнее использовать методы перечисленные выше.

Не используйте для получения обертки конструкцию new elmWrapper(element, windowWrapper). Несмотря на то, что синтаксически эта конструкция абсолютно правильная - у вас может возникнуть ошибка, если вы случайно создадите для одного элемента несколько оберток. Во всех выше перечисленных методах делается проверка на существование обертки у элемента, перед ее созданием и если обертка уже создана - вы получите ссылку на ранее созданную обертку.

После создания обертки элемент получает новое свойство _wrapper, которое содержит ссылку на обертку этого элемента. Другими словами, обертка хранит ссылку на обернутый объект, а объект хранит ссылку на свою обертку. И эти значения сохраняются на протяжении всего времени существования объекта. Вы можете использовать данную специфику для хранения каких-либо своих дополнительных значений, связанных с этим объектом, в самой обертке элемента. Для этого у обертки элемента есть специальное свойство userData, которому можно задавать любые свойства.

Основные свойства
Свойство Описание
elm Ссылка на обернутый html-элемент.
winWr Ссылка на window wrapper.
Дополнительные свойства
Свойство Описание
css Стиль элемента (с учетом определений сделанных в таблице стилей).
style Стиль элемента (как атрибут тэга).
bv объект browserVersion.
Методы для манипуляций с обернутым объектом
Метод Описание
getAbsOffset array(x,y) – координаты объекта относительно документа.
getAbsLeft, getX координата X – относительно документа (с учетом смещения).
getAbsTop, getY координата Y – относительно документа (с учетом смещения).
getRelOffset array(x,y) – координаты объекта относительно родительского элемента.
getRelLeft координата X – относительно родительского элемента.
getRelTop координата Y – относительно родительского элемента.
getWidth ширина объекта.
getHeight высота объекта.
getZIndex получить Z-index.
getColor цвет: шрифта, фона, границ.
isVisible проверка видимости элемента по Visibility.
isDisplay проверка видимости элемента по Display.
isShow проверка видимости элемента по Display и Visibility.
setAbsLeft, moveX абсолютное перемещение по горизонтали (с учетом смещения).
setAbsTop, moveY абсолютное перемещение по вертикали (с учетом смещения).
moveAbs, move абсолютное перемещение.
moveRel перемещение элемента относительно его текущей позиции.
setZIndex, moveZ установить Z-index.
setVisibility установить Visibility.
setDisplay установить Display.
invVisibility инвертировать Visibility.
invDisplay инвертировать Display.
show установить Display = block (по условию).
hide установить Display = none (по условию).
write Вписать новый текст, как содержимое контейнера.
setBgColor Задать цвет фона.
setBgImage Задать фоновое изображение.
setClip, clip Обрезать блок.
setClass задать класс стилей для объекта.
addClass добавить новый класс стилей к имеющимся.
removeClass удалить класс стилей у объекта.
Подписка на событие, сброс подписки
Метод Описание
addListener Подписаться на любое событие window или document.
removeListener Убрать подписку с любого события window или document.

Свойство elm

Синтаксис: объект.elm;

Значением свойства elm является ссылка на элемент HTML-кода, для которого создана обертка.

Свойство winWr

Синтаксис: объект.winWr;

Значением свойства winWr является ссылка на объект "window wrapper".

Свойство css

Синтаксис: объект.css;

Значением свойства css является специальный объект, содержащий все стили объекта (не только те, что заданы при помощи атрибута "stile"). Данное свойство можно использовать только для чтения.

Свойство style

Синтаксис: объект.style;

Значением свойства style является специальный объект, содержащий стили объекта заданные при помощи атрибута "stile". Фактически выражения объект.style; и объект.elm.style; - абсолютно тождественны.

Свойство bv

Синтаксис: объект.bv

Значение свойства bv является объектом browserVersion.

Метод getAbsOffset

Синтаксис: объект.getAbsOffset(); Результат: объект типа массив

Метод getAbsOffset позволяет получить абсолютные координаты верхнего левого угла объекта (относительно документа) в виде массива. Нулевой элемент массива содержит координату X, а первый - Y, в виде целых чисел.

Методы getAbsLeft, getX

Синтаксис: объект.getAbsLeft(); или объект.getX(); Результат: числовое значение

Методы getAbsLeft, getX являются синонимами и возвращают значение координаты верхнего левого угла объекта по оси X (по горизонтали), относительно документа.

Методы getAbsTop, getY

Синтаксис: объект.getAbsTop(); или объект.getY(); Результат: числовое значение

Методы getAbsTop, getY являются синонимами и возвращают значение координаты верхнего левого угла объекта по оси Y (по вертикали), относительно документа.

Метод getRelOffset

Синтаксис: объект.getRelOffset(); Результат: объект типа массив

Метод getRelOffset позволяет получить относительные координаты верхнего левого угла объекта (относительно HTML-элемента содержащего данный HTML-элемент) в виде массива. Нулевой элемент массива содержит координату X, а первый - Y, в виде целых чисел.

Метод getRelLeft

Синтаксис: объект.getRelLeft(); Результат: числовое значение

Метод getRelLeft возвращает значение координаты верхнего левого угла объекта по оси X (по горизонтали), относительно HTML-элемента содержащего данный HTML-элемент.

Метод getRelTop

Синтаксис: объект.getRelTop(); Результат: числовое значение

Метод getRelTop возвращает значение координаты верхнего левого угла объекта по оси Y (по вертикали), относительно HTML-элемента содержащего данный HTML-элемент.

Метод getWidth

Синтаксис: объект.getWidth(); Результат: числовое значение

Метод getWidth возвращает ширину данного объекта в пикселах.

Метод getHeight

Синтаксис: объект.getHeight(); Результат: числовое значение

Метод getHeight возвращает высоту данного объекта в пикселах.

Метод getZIndex

Синтаксис: объект.getZIndex(); Результат: числовое значение

Метод getZIndex возвращает z-index данного объекта в пикселах.

Метод getColor

Синтаксис: объект.getColor([type]?); Аргументы: type — любое строковое выражение Результат: строковое выражение

Метод getColor возвращает цвет шрифта, фона или границ в виде шестнадцатеричного числа формата #XXXXXX. По умолчанию, если не указан аргумент метода, она возвращает цвет шрифта. Используя аргументы: color, backgroundColor, borderLeftColor, borderRightColor, borderTopColor, borderBottomColor - можно получить значения цвета остальных частей HTML-элемента.

Метод isVisible

Синтаксис: объект.isVisible(); Результат: булево значение

Метод isVisible возвращает true, если значение стиля visibility не равно "hidden". В противном случае метод возвращает false.

Метод isDisplay

Синтаксис: объект.isDisplay(); Результат: булево значение

Метод isDisplay возвращает true, если значение стиля display не равно "none". В противном случае метод возвращает false.

Метод isShow

Синтаксис: объект.isShow(); Результат: булево значение

Метод isShow возвращает true, если значение стиля visibility не равно "hidden" и значение стиля display не равно "none". В противном случае метод возвращает false.

Методы setAbsLeft, moveX

Синтаксис: объект.setAbsLeft(X-координата); или объект.moveX(X-координата); Аргументы: X-координата — любое числовое значение

Методы setAbsLeft, moveX являются синонимами и служат для перемещения объекта по горизонтали, путем указания значения координаты верхнего левого угла объекта по оси X, относительно документа.

Методы setAbsTop, moveY

Синтаксис: объект.setAbsTop(Y-координата); или объект.moveY(Y-координата); Аргументы: Y-координата — любое числовое значение

Методы setAbsTop, moveY являются синонимами и служат для перемещения объекта по вертикали, путем указания значения координаты верхнего левого угла объекта по оси Y, относительно документа.

Методы moveAbs, move

Синтаксис: объект.moveAbs(X-координата, Y-координата); или объект.move(X-координата, Y-координата); Аргументы: X-координата — любое числовое значение Y-координата — любое числовое значение

Методы moveAbs, move являются синонимами и служат для перемещения объекта по двум координатам, путем указания значения координаты верхнего левого угла объекта по осям X и Y, относительно документа.

Метод moveRel

Синтаксис: объект.moveRel(X-смещение, Y-смещение); Аргументы: X-смещение — любое числовое значение Y-смещение — любое числовое значение

Метод moveRel служит для перемещения объекта по двум координатам, путем указания смещения объекта по осям X и Y относительно его положения. Значения смещения могут быть как положительными, так и отрицательными. Положительные значения вызывают смещение объекта вправо и вниз, а отрицательные влево и вверх, соответственно. Метод не учитывает, что в результате указания отрицательного смещения, могут получиться отрицательные координаты объекта и в результате выполнения этого метода объект может переместиться за границы верхней или левой границы экрана. Если необходимо ограничить такое перемещение - Вы должны контролировать его самостоятельно.

Методы setZIndex, moveZ

Синтаксис: объект.setZIndex(z-index); или объект.moveZ(z-index); Аргументы: z-index — любое числовое значение

Методы setZIndex, moveZ являются синонимами и служат для указания значения z-index у объекта.

Метод setVisibility

Синтаксис: объект.setVisibility(value); Аргументы: value — булево значение

Метод setVisibility служит для задания значения свойства visibility у атрибута style текущего объекта. Если значение аргумента данного метода соответствует true, то значением свойства будет "visible", в противном случае - "hidden".

Метод setDisplay

Синтаксис: объект.setDisplay(value); Аргументы: value — булево значение либо строковое выражение

Метод setDisplay служит для задания значения свойства display у атрибута style текущего объекта. Если значение аргумента данного метода является булевым значением и содержит true, то значением свойства будет "block", в противном случае - "none". Если в качестве аргумента передано строковое значение, то именно оно будет использовано как значение свойства display.

Примечание: для Internet Explorer любое текстовое значение атрибута отличное от "inline" и "none" будет изменено на "block", т.к. Internet Explorer не принимает других значений, кроме "block", "inline" и "none".

Метод invVisibility

Синтаксис: объект.invVisibility();

Метод invVisibility служит для инвертирования значения свойства visibility у атрибута style текущего объекта. Если значение атрибута равно "visible", то оно изменяется на "hidden" и наоборот.

Метод invDisplay

Синтаксис: объект.invDisplay([value]?); Аргументы: value — любое строковое выражение

Метод invDisplay служит для инвертирования значения свойства display у атрибута style текущего объекта. Если значение атрибута не равно "none", то оно изменяется на "none". В противном случае, если передан аргумент метода, то значением свойства display будет переданное значение, либо "block", если аргумент не указан.

Примечание: для Internet Explorer любое текстовое значение атрибута отличное от "inline" и "none" будет изменено на "block", т.к. Internet Explorer не принимает других значений, кроме "block", "inline" и "none".

Метод show

Синтаксис: объект.show([value]?); Аргументы: value — булево значение либо строковое выражение

Метод show служит для включения отображения объекта. Если аргумент метода не указан, или его значение эквивалентно true, то для включения отображения будет использовано свойство display у атрибута style текущего объекта, со значениями, описанными ниже. В противном случае будет использовано свойство visibility со значением "visible". Если в качестве аргумента передано текстовое значение, то именно оно будет использовано как значение свойства display.

Примечание: для Internet Explorer любое текстовое значение атрибута отличное от "block будет изменено на "block", т.к. Internet Explorer не принимает других значений, кроме "block", "inline" и "none".

Метод hide

Синтаксис: объект.hide([value]?); Аргументы: value — булево значение

Метод hide служит для выключения отображения (скрытия) объекта. Если аргумент метода не указан, или его значение эквивалентно true, то для выключения отображения будет использовано свойство display со значением "none" у атрибута style текущего объекта. В противном случае будет использовано свойство visibility со значением "hidden".

Метод write

Синтаксис: объект.write(text[,position,noDOM]?); Аргументы: text — любое строковое выражение position — значения: -1, 0, 1 noDOM — логическое выражение

Метод write служит для вставки/замены текста внутрь любого текстового элемента. Текст передается как обязательный первый аргумент метода. Если необязательный аргумент position не указан или равен нулю, то старый текст заменяется новым. Если значение position меньше нуля, то новый текст добавляется перед старым, а при положительном значении новый текст добавляется после старого. По умолчанию значение position равно нулю.

Если Вы для вставки текста хотите воспользоваться свойством innerHTML данного объекта (не рекомендуется), а не стандартными методами DOM, то передайте в качестве третьего необязательного аргумента значение true.

Метод setBgColor

Синтаксис: объект.setBgColor(color); Аргументы: color — любое строковое выражение

Метод setBgColor для задания цвета фона элемента. Аргумент для задания цвета должен соответствовать либо шестнадцатеричному значению цвета формата #XXXXXX, либо текстовому названию цвета (из текстовых значений допустимых для задания цвета).

Метод setBgImage

Синтаксис: объект.setBgImage(url); Аргументы: url — любое строковое выражение

Метод setBgImage для фонового изображения элемента. В качестве аргумента необходимо передать URL к изображению.

Методы setClip, clip

Синтаксис: объект.setClip(top,right,bottom,left); или объект.clip(top,right,bottom,left); Аргументы: top — любое числовое выражение right — любое числовое выражение bottom — любое числовое выражение left — любое числовое выражение

Методы setClip, clip являются синонимами и служат для того, чтобы отображать не весь объект целиком, а только его фрагмент. Для указания фрагмента, необходимо передать размеры "отсекаемых" областей в пикселах (сверху, справа, снизу и слева). Если размер какой-либо области будет равен 0, то эта область "отсекаться" не будет.

Метод setClass

Синтаксис: объект.setClass(className); Аргументы: className — любое строковое выражение

Метод setClass позволяет определить значение css-класса/-ов для данного объекта. Если объект до этого использовал какие-либо css-классы - их значения сбрасываются. Если необходимо определить несколько новых классов для объекта - передавайте их названия в виде одной текстовой строки с разделением через пробел.

Метод setClass может быть использован для удаления всех классов объекта - для этого при вызове метода указывайте в качестве аргумента пустую строку.

Метод addClass

Синтаксис: объект.addClass(className); Аргументы: className — любое строковое выражение

Метод addClass позволяет добавить новые значение css-класса/-ов к уже существующим у данного объекта. Если необходимо добавить несколько новых классов для объекта - передавайте их названия в виде одной текстовой строки с разделением через пробел.

Метод removeClass

Синтаксис: объект.removeClass(className); Аргументы: className — любое строковое выражение

Метод removeClass позволяет удалить значение css-класса/-ов у данного объекта. Если объект использовал несколько css-классов - значения других классов сохраняются. Категорически не рекомендуется удалять несколько классов одновременно - вызывайте метод removeClass для удаления каждого класса в отдельности. Если необходимо удалить все используемые объектом классы - используйте метод setClass, указав в качестве аргумента - пустую строку.

Метод addListener

Синтаксис: объект.addListener(object,event[,method,useCapture]?); Аргументы: object — любой объект event — любое строковое выражение method — любое строковое выражение useCapture — булево значение Результат: объект

Метод addListener позволяет подписаться на любые события объекта, для которого создана обертка. Название события (event) может делаться либо полностью строчными буквами, либо в Венгерской нотации. Вы также можете опускать префикс "on" в названии события, если это будет определено в конфиге wrapper. Если третий аргумент не указан, то в момент возникновения события будет вызываться метод, название которого соответствует второму аргументу, в противном случае - будет вызываться указанный Вами метод. Аргумент: useCapture - в данной версии пока не используется, но в будущем с помощью него можно будет использовать либо "Capture", либо "Bubbling" в момент подписки. Также см. примечание.

Метод removeListener

Синтаксис: объект.removeListener(object,event[,method,useCapture]?); Аргументы: object — любой объект event — любое строковое выражение method — любое строковое выражение useCapture — булево значение

Метод removeListener позволяет убрать подписку на любые события объекта, для которого создана обертка. Список аргументов этого метода совпадает со списком аргументов метода Метод addListener и при удалении подписки Вы должны указать эти аргументы с точно такими же значениями, как и при подписке.

примечание ко всем методам, связанным с подпиской

Все методы связанные с подпиской возвращают Вам некий объект, не имеющий ни методов, ни свойств. Но вы можете задать этому объекту любые свойства. Затем в момент возникновения события этот объект будет передан методу, обрабатывающему событие в качестве второго аргумента (первым аргументом всегда идет объект event-wrapper). Таким образом, если у Вас один метод используется для обработки нескольких событий - вы можете таким способом передавать в него дополнительную информацию, которая будет иметь свои значения для каждой подписки.