Event object

Represents user interface event. Events and correspndent event handlers are defined in Events.

Constants

Event Group codes (used with Element.subscribe() method)

MOUSE
mouse events group
KEY
key events group
FOCUS
focus events group
BEHAVIOR_EVENT
group of events generated (synthesized) by particular behaviors (like BUTTON_CLICK, EDIT_VALUE_CHANGING, etc.)
SCROLL
scroll events group
SIZE
size events group (that is just single event, onSize)

Mouse event codes

MOUSE_ENTER
type of event, mouse enters the element.
MOUSE_LEAVE
type of event, mouse leaves the element.
MOUSE_MOVE
type of event, mouse moves over the element.
MOUSE_DOWN
type of event, mouse button pressed in the element.
MOUSE_UP
type of event, mouse button released in the element.
MOUSE_DCLICK
type of event, mouse clicked twice in the element.
MOUSE_WHEEL
type of event, mouse wheel rotated.
MOUSE_TICK
type of event, mouse timer event. Runtime sends this event regularly when mouse button is pressed on the element.
MOUSE_IDLE
type of event, mouse timer event. Runtime sends this event when mouse is over the element, not pressed and not moving for some time. By default this event triggers popup of tooltip.
MOUSE_DRAG_REQUEST
mouse pressed and moved by distance larger than some threshold.  <input|text> and <textarea> start dragging selection while handling the event. To discard default handlers - consume the event by returning true.

Keyboard event codes

KEY_DOWN
type of event, key pressed when element or one of its children is in focus.
KEY_UP
type of event, key released when element or one of its children is in focus.
KEY_CHAR
type of event, character key pressed when element or one of its children is in focus.

Scroll event codes

SCROLL_HOME
SCROLL_END
SCROLL_STEP_PLUS
SCROLL_STEP_MINUS
SCROLL_PAGE_PLUS
SCROLL_PAGE_MINUS
SCROLL_POS

Gesture (touch screen) event codes

GESTURE_REQUEST
The engine sends this event to request list of gestures that the element supports. Set "ORed" flags in Event.flags field. List of supported flags/gesture types:
GESTURE_ZOOM
The zoom gesture. Event.deltaV  field contains float > 1.0 in case of zoom-out and float < 1.0 for zoom-in.
GESTURE_PAN
The pan/swipe gesture. Event.deltaX and Event.deltaY fields contain integers - number of pixels in X and Y directions.
GESTURE_ROTATE
The rotation gesture. Event.deltaV  field contains delta angle (in radians).
GESTURE_TAP1
The press and tap gesture.
GESTURE_TAP2
Tap by two fingers gesture.

Event.flags in all events (but not in GESTURE_REQUEST) is ORed combination of the following states:

Focus event codes

LOST_FOCUS
GOT_FOCUS

Logical event codes from builtin behaviors

BUTTON_CLICK
BUTTON_PRESS
BUTTON_STATE_CHANGED
Checkbox/radio state was changed. ( Not all BUTTON_CLICKs are changing state of those. )
EDIT_VALUE_CHANGING
EDIT_VALUE_CHANGED
SELECT_SELECTION_CHANGED
SELECT_STATE_CHANGED
HYPERLINK_CLICK
ACTIVATE_CHILD
POPUP_REQUEST
POPUP_READY
POPUP_DISMISSED
POPUP_DISMISSING
MENU_ITEM_ACTIVE
Mouse over the menu item, Event.target is a menu item, Event.owner - initiator of the menu  
MENU_ITEM_CLICK
Click on the menu item, Event.target is a menu item, Event.owner - initiator of the menu
CONTEXT_MENU_REQUEST
Is sent by the engine when context menu needs to be shown. evt.target is a top element that have got e.g. right mous click. evt.source [read/write] is a menu element that is about to popup. You can set your own menu element to the evt.source field while handling this event.
CONTEXT_MENU_SETUP
Is sent by the engine when context menu is found. evt.source is the menu element that you can modify at this point.
VISUAL_STATUS_CHANGED
Notification that the element changed its visibility either by changing display or visibility CSS attributes. The event is sent only to the element itself (so not a bubbling event).
DISABLED_STATUS_CHANGED
Notification that the element or one of its containers have changed its disabled status.
TOOLTIP_REQUEST
Request for tooltip, the event is sent in response of MOUSE_IDLE. Element on evt.source is a proposed tooltip element. You can assign your own DOM element to the evt.source field or text to evt.data field. To cancel tooltip generation set evt.source to null and return true (event handled) from the event handler.
DOCUMENT_COMPLETE
Notification that document finishes its loading - all requests for external resources are finished. evt.target is the root node ( <html> ) of the document that is complete. Note that the event is being generated even if some of resources were not available. DOM elements that contain non-available resources will get :incomplete state flag.
FORM_SUBMIT
behavior:form detected submission event from button type=reset. evt.data field contains data to be sent to the server as a map (object). You can modify the data or discard submission by returning true ("event consumed") from the event handler.
FORM_RESET
behavior:form detected reset event (from button type=reset). evt.data field contains data to be set to input fields.

Event flags

SINKING
Event dispatching direction. If this flag set then event is being dispatched in the direction from parent to child. Example:
switch(evt.type)
{
   case Event.MOUSE_DOWN | Event.SINKING:
        // handle thr event before any child
   case Event.MOUSE_DOWN:
        // it is here as no one child processed it.
}
HANDLED
Event was handled (event handler function returned true) by some child of the element or behavior. Example:
switch(evt.type)
{
   case Event.MOUSE_DOWN:
       // after all children and no one has handled it.
   case Event.MOUSE_DOWN | Event.HANDLED:
       // after all children, and some child has handled it.
}

Dragging modes

DRAGGING_MOVE
DRAGGING_COPY
Values of the draggingMode attribute below.

Virtual key codes - values of keyCode filed in KEY_DOWN and KEY_UP events

VK_CANCEL   VK_BACK     VK_TAB      VK_CLEAR    VK_RETURN   VK_SHIFT    VK_CONTROL
VK_MENU     VK_PAUSE    VK_CAPITAL  VK_KANA     VK_HANGUL   VK_JUNJA    VK_FINAL
VK_HANJA    VK_KANJI    VK_ESCAPE   VK_CONVERT  VK_SPACE    VK_PRIOR    VK_NEXT
VK_END      VK_HOME     VK_LEFT     VK_UP       VK_RIGHT    VK_DOWN     VK_SELECT
VK_PRINT    VK_EXECUTE  VK_SNAPSHOT VK_INSERT   VK_DELETE   VK_HELP     VK_SLEEP
VK_NUMPAD0  VK_NUMPAD1  VK_NUMPAD2  VK_NUMPAD3  VK_NUMPAD4  VK_NUMPAD5  VK_NUMPAD6
VK_NUMPAD7  VK_NUMPAD8  VK_NUMPAD9  VK_MULTIPLY VK_ADD      VK_SEPARATOR VK_SUBTRACT
VK_DECIMAL  VK_DIVIDE   VK_F1       VK_F2       VK_F3       VK_F4       VK_F5
VK_F6       VK_F7       VK_F8       VK_F9       VK_F10      VK_F11      VK_F12
VK_F13      VK_F14      VK_F15      VK_F16      VK_F17      VK_F18      VK_F19
VK_F20      VK_F21      VK_F22      VK_F23      VK_F24

Example:

switch(event.keyCode)
{
  case Event.VK_HOME: index = 0; break;
  case Event.VK_END: index = this.length - 1; break;
}

Properties

type
r - Integer, type of the event, value equal to one of the constant above.
altKey
r - true/false, true if ALT key is pressed. Valid for Mouse, Key events.
ctrlKey
r - true/false, true if CTRL key is pressed. Valid for Mouse, Key events.
shiftKey
r - true/false, true if SHIFT key is pressed. Valid for Mouse, Key events.
shortcutKey
r - true/false, true if either CTRL (on Windows) or COMMAND (on OSX) keys are pressed. Valid for Mouse and Key events. Use it if you want to handle keyboard shortcut commands in cross-platform manner. CTRL+C on Windows is an equivalent of COMMAND+C on OSX. Bastards, aren't they?
commandKey
r - true/false, true if either "Win" (on Windows keyboard) or COMMAND (on Mac keyboard) keys are pressed. Valid for Mouse and Key events.
extendedKey
r - true/false, indicates whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard.
mainButton
r - true/false, true if main mouse button pressed (usually left mouse button). Valid for Mouse events.
propButton
r - true/false, true if property mouse button pressed (usually right mouse button). Valid for Mouse events.
buttons
r - integer, bit flags representing pressed mouse buttons, 0x01 - main (usually left) mouse button, 0x02 - right mouse button, 0x04 - middle mouse button.
target
r - Element,  element this event tageted to.
reason
r/w - integer, reason field of control event code.
keyCode
r/w - integer, key scan code for KEY_DOWN/KEY_UP events and unicode codepoint of the character pressed for the KEY_CHAR event.
group
r - symbol, event group symbol, here it is a symbol of event handler function: #onMouse, #onKey, #onFocus, etc.
wheelDelta
r - integer, mouse wheel "tick" - valid in onMouse/MOUSE_WHEEL event. Either -1 or +1 depending on direction.
scrollPos
r - integer, scroll position in SCROLL_POS event.
scrollAxis
r - #vertical | #horizontal, scrollbar axis in scroll events.
x
r - integer, x coordinate of the mouse event relative to the element itself (origin of its content box)
y
r - integer, y coordinate of the mouse event relative to the element itself (origin of its content box)
xRoot
r - integer, x coordinate of the mouse event relative to the element's root element (<html>).
yRoot
r -integer, y coordinate of the mouse event relative to the element's root element (<html>).
xView
r - integer, x coordinate of the mouse event relative to the element's view (window).
yView
r - integer, y coordinate of the mouse event relative to the element's view (window).
xScreen
r - integer, x coordinate of the mouse event relative to the screen.
yScreen
r -integer, y coordinate of the mouse event relative to the screen.
owner
rw - Element, owner (initiator) of the menu in MENU_ITEM_CLICK, also this is value of last parameter in Element.sendEvent method.
isOnIcon
r - true | false, onMouse(evt) only. true if mouse is on icon area. Element icon is foreground, no-repeat image.
dragging
r/w - Element, onMouse(evt) and onExchange(evt) only. Reference of element being dragged when onMouse and data being dragged when onExchange().
draggingMode
r/w - integer, onMouse(evt) only. Dragging mode - either Event.DRAGGING_MOVE or Event.DRAGGING_COPY - current dragging mode.
draggingDataType
r - symbol,  onExchange(evt) only. One of the following values:
deltaV, deltaX, deltaY, flags
r/o - onGesture() event specific fields. See prose above about GESTURE_**** values.
cursor
w/o - string, onMouse(evt) only. Set current cursor.

Methods

match
(eventName:string [,selector:string]) : true | false

Returns true if the event has symbolic name of eventName and its target matches the selector. The eventName can accept following symbolic names:

exchangeData
() : array of symbols.

Retuns list of data items types associated with exchange oeration. The list is an array containing #text, #html, #url, #file, #picture or #json.

exchangeData
(dataType:symbol) : value

The method allows to get data of particular data type:

#text - returns string - dragged text;

#html - returns (url,html) pair - url of dragged HTML fragment and the HTML itself;

#url - returns (caption,url) pair - caption and the url itself;

#file - returns filenames array - list of dragged file paths;

#picture - returns Image object if dragged data contains an image;

#json - returns value - json value.

keyPressed
(vkKeyCode: integer) : true | false

Class (static) function, reports true if key is pressed. Can be used to check state of for example CAPSLOCK or NUMLOCK keys : 

if( Event.keyPressed(Event.VK_CAPITAL) ) 
  ... CAPSLOCK is pressed ... 

Symbolic event names

Symbolic event names are used by Element.subscribe("name", ...), Element.on("name", ...), Event.match("name", ...) and event name () {} script functions.

click
- button and hyperlink clicks;
dblclick
- mouse double clicks;
change
- value has been changed by the user;
changing
- value of <input> is about to change, the event gets sent before actual changes applied.
submit
- form submit event fired before data of the form is submited;
reset
- form reset event fired before data of the form gets reset;
expand
- event generated by various behaviors when event.target item gets expanded / shown (e.g. in tree view widget);
collapse
- event generated by various behaviors when event.target item gets collapsed / hidden (e.g. in tree view widget);
statechange
- UI state change, for example behavior:textarea and behavior:richtext send this event when caret or selection position changes;
visualstatechange
- visibility or display change causes element to become visible/invisible;
disabledstatechange
- state.disabled change on element;
readonlystatechange
- state.readonly change on element;
contextmenu
- context menu request (right button or property key click);
animationstart
- animation life cycle event - notifies about start of animation;
animationend
- animation life cycle event - notifies about end of any animation on the element;
mediachange
- Event.MEDIA_CHANGED, the mediachange event is received when runtime detects display settings/parameters change. Received only by root document inside the view.
contentchange
- Event.CONTENT_CHANGED,  received by the element when its content gets changed - DOM elements added or removed.  
inputlangchange
- Event.INPUT_LANGUAGE_CHANGED,  received by the focus element when the user changes input language.  event.data is a string - ISO lang-country code.

Mouse events

mousedown
- Event.MOUSE_DOWN event;
mouseup
- Event.MOUSE_UP event;
mousemove
- Event.MOUSE_MOVE event;
mouseenter
- Event.MOUSE_ENTER event, mouse entered the element.
mouseleave
- Event.MOUSE_LEAVE event, mouse left the element.
mousedragrequest
- Event.MOUSE_DRAG_REQUEST event, drag condition (mouse pressed and moved) is detected.

Focus events

focusin
- Event.FOCUS_IN, the focusin event is sent to an element when it, or any element inside of it, gains focus. If focus stays inside some container then the container will not receive the event.
focusout
- Event.FOCUS_OUT, the focusin event is sent to an element when it, or any element inside of it, loses focus. If focus stays inside some container then the container will not receive the event.
focus
- Event.GOT_FOCUS, the focus event is sent to an element when it gains focus. Event.target is the element that got focus.
blur
- Event.LOST_FOCUS, the focus event is sent to an element when it loses focus. Event.target is the element that lost focus.

Keyboard events

keydown
- Event.KEY_DOWN, the keydown event is fired when a key is pressed down. Event.keyCode is virtual key code - one of Event.VK_**** values.
keyup
- Event.KEY_UP, the keyup event is fired when a key is released. Event.keyCode is virtual key code - one of Event.VK_**** values.
keypress
- Event.KEY_CHAR, the keypress event is fired when the element receives character value. Event.keyCode is a UNICODE code point of the character.

Scroll event

scroll
- scroll event;

Popup and tooltip events

popuprequest
- Event.POPUP_REQUEST, the event is fired as a first phase of popup creation, when window for it is not created. event.source is the popup element. Use this event to popuplate content of the popup.
popupready
- Event.POPUP_READY, the event is fired as a last phase of popup creation, when window for it is created. event.source is the popup element.
popupdismissing
- Event.POPUP_DISMISSING, the event is sent before popup window gets removed from screen. The event is sent to the element itself while popup is still visible (but about to be closed).
popupdismissed
- Event.POPUP_DISMISSED, the event is posted to the popup owner and after popup window gets removed from screen.
tooltiprequest
- Event.TOOLTIP_REQUEST, the event is sent in response to Event.MOUSE_IDLE.

Element lifecycle events

detached
- not a bubbling event - is sent to the element itself only before it gets removed from the DOM.

Document lifecycle events

close
- Event.DOCUMENT_CLOSE, the event is fired as when document gets removed from its container (view or frame). Only document elements and its containers receive this event.
closerequest
- Event.DOCUMENT_CLOSE_REQUEST, the event is fired to request document removal from its container (view or frame). Only document elements and its containers receive this event. By handling this request application can discard window or document closing by setting event.cancel = true;  in event handler.
ready
- Event.DOCUMENT_READY, the event is fired as when document gets parsed in full and its DOM is established. Only document elements and its containers receive this event.
complete
- Event.DOCUMENT_COMPLETE, the event is fired as when document have downloaded all resources (images, styles, scripts) it requested . Only document elements and its containers receive this event.

Command execution events

query:{command}
- the event is fired to query readiness to execute the {command}. E.g. "query:edit:paste" event gets sent to check if the element is able to paste content from clipboard at the moment. The element can set event.result field to report availability of the command. Command can have additional command parameters in event.data field.
exec:{command}
- the event is fired to execute the {command}. E.g. "query:edit:paste" event is sent to the element to execute paste from clipboard.

System drag and drop events

dragaccept
- fired before any other drag*** events, a.k.a. Event.X_WILL_ACCEPT_DROP . "Will the element accept the event.dragging data?". The element shall return true from the handler in order to receive all other drag/drop events.
drag
- fired when a data is being dragged over the element. 
dragenter
- fired when data drag enters the element.
dragleave
- fired when data drag leaves the element.
drop
- fired when data is dropped onto the target element.

Any other string is considered as custom event, to post/send such events use Element.postEvent/sendEvent(name,...)  methods.