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:

• Event.GESTURE_FLAG_ZOOM - two fingers zoom;
• Event.GESTURE_FLAG_ROTATE - two fingers rotate;
• Event.GESTURE_FLAG_PAN_VERTICAL - vertical swipe or panning;
• Event.GESTURE_FLAG_PAN_HORIZONTAL- horizontal swipe or panning;
• Event.GESTURE_FLAG_TAP1 - press-and-tap gesture;
• Event.GESTURE_FLAG_TAP2 - tap by two fingers;
• Event.GESTURE_FLAG_PAN_WITH_GUTTER - PAN_VERTICAL and PAN_HORIZONTAL modifier - gutter.
• Event.GESTURE_FLAG_PAN_WITH_INERTIA - PAN_VERTICAL and PAN_HORIZONTAL modifier - generate inertia events.
• Event.GESTURE_FLAGS_ALL - all flags/events

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:

• Event.GESTURE_STATE_BEGIN - is "on" for first event in the gesture sequence.
• Event.GESTURE_STATE_INERTIA - is "on" for events synthesized by the inertia processor.
• Event.GESTURE_STATE_END - is "on" for last event in the gesture sequence.

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:

• #text - plain text;
• #html - html;
• #url - hyperlink;
• #file - file list;
• #json - JSON data (sciter specific);

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.