Constants

Properties

• element.x.length - reports number of native behaviors attached to the element;
• element.x[n] - reports name of n-th native behavior attached to the element.
• element.x.funcname(....) - call of methods implemented by native behaviors.

Main purpose of this interface is to provide function call mechanism that is using separate namespace.

Note: property value(v) can be overriden in a behavior class in script. To access native value in such case use Element.state.value property.

Obsolete properties, replaced by the Style sub object:

Enumeration

Executes body of the loop for all child nodes of the element. Value of node variable is either text or element object.

Example, for p element in html:
<p>Hello <em>wonderfull</em> world</p>
loop will be executed three times and node variable will be equal to: "Hello ", Element("em") and " world" on correspondent iteration.

Methods

Constructs new Element object with tag equal to tagname (string or symbol). Use it as:

var el = new Element("option"); // or
var el = new Element(#option);

Element will be created in disconnected state. To connect it to the DOM use insert method of the parent element.

Static constructor of DOM elements. object here is an object literal with microformat defined below.

Example, following fragment is an equivalent of creating element with the markup <p>before <button>Hi!</button> after</p>:

var para = Element.create { p, "paragraph text" }; // or if text is a variable:
var para = Element.create { p, [paragraphText] };

Clears a content of the element, removing all its children.

Returns string - html representation of the element. Text returned is outer html - includes head and tail tags and content s equal to text returned by  html attribute.

Returns new copy of the element. Method performs a deep copy of the element. New element is disconnected from the DOM state. Use insert() method to include it in the DOM.

Returns first element satisfying CSS selector (CSSselector, string). CSSSelector may contain format specifiers like %d, %s which will be substituted by values of argument1 ... argumentN in final CSS selector string. Function uses the same rules as does Stream.printf function.

Example, if document contains <input type="text"/> element then following statement

var inp = self.select("input[type='text']");

will set inp by reference to such element.

Returns first element satisfying CSS selector.

Note: this is a "stringizer" method so CSS selector can  be written without "" quotes.

Example, if document contains <input type="text"/> elements then following statement

var inp = self.$( input[type='text'] );

will set inp by reference to such element.

And the following fragment:

var n = 3;
var li3 = self.$( ul > li:nth-child({n}) );

will find third list item in ul list element.

Calls func (function reference) for each element satisfying (matching) CSSselector. Function func shall accept one parameter where select will provide reference to matched element. Function may return true to stop enumeration.

Example, following fragment will print out names of all input elements in the document:
function printel(el) {  stdout.println( el.attributes["name"] );  }
document.select(printel, "input");

Returns array of elements satisfying CSS selector (CSSselector, string). CSSSelector may contain format specifiers like %d, %s which will be substituted by values of argument1 ... argumentN in final CSS selector string. Function uses the same rules as does Stream.printf function.

Returns array of elements satisfying CSS selector (CSSselector, string).

Note: this is a stringizer method - the CSSselector provided literally.

Returns first element in child/parent chain satisfying CSS selector (CSSselector, string). CSSSelector may contain format specifiers like %d, %s which will be substituted by values of argument1 ... argumentN in final CSS selector string. Function uses the same rules as does Stream.printf function.

ATTN: Function also inspects this element.

Returns first element in child/parent chain satisfying CSS selector.

Note 1: this is a stringizer method - the CSSselector provided literally.

Note 2: Function also inspects this element.

Calls func (function reference) for each element satisfying (matching) CSSselector. Function func shall accept one parameter where select will provide reference to matched element. Function may return true to stop enumeration.

Example, following fragment will print out ids of all parent divs of some element:

function printel(el) {  stdout.println( el.attributes["id"] );  }
some.selectParent(printel, "div");

Note: Function also inspects this element.

Returns array of references of elements in child/parent chain satisfying CSS selector.

Note 1: this is a stringizer method - the CSSselector provided literally.

Note 2: Function also inspects this element.

Checks if this DOM element satisfies given CSSselector.

Checks if this DOM element satisfies given CSSselector.

Note: this is a stringizer method - the CSSselector provided literally.

Returns reference to child element of the given element at x,y coordinates relative to the origin of the element. If there is no such element method returns element itself.

Remeasures given element (if deep == true) and invalidates its visual area after modifications. Use deep=true value if element will get new dimensions due to some operations on it. Omit deep parameter (or set it to false) if only decoration attributes (not changing dimensions, like color) were changed.

Invalidates area of occupied by the element on the screen. If x , y, width, height (coordinates of area inside element) are provided then it invalidates only that portion. This method is useful if you are using Graphics for rendering on element surface area.

Starts animation on the element. nextStep is a function that executes animation step (changes dimension, opacity, etc.). This function is called with this set to the element itself and should return integer - number of milliseconds for the next step. If it returns zero or not an integer then animation stops.

Returns coordinates of the edges of the element. Parameters:

• part - one of symbolic constants #left, #top, #right, #bottom, #width or #height. Defines part of box (rectangle) to return.
• If part is #rect then the function returns four values - left, top, right, bottom. Use it for example as
var (x1,y1,x2,y2) = this.box(#rect, #inner, #view);
• If part is #rectw then the function returns four values - left, top, width and height. Use it for example as
var (x,y,w,h) = this.box(#rectw, #inner, #view);
• If part is #dimension the function returns two values - width and height. Use it as:
var (w,h) = this.box(#dimension, #inner);
• If part is #position the function returns two values - left and top. Use it as:
var (x,y) = this.box(#position, #inner, #view);
• edge, one of edges of element:
• #margin - margin box edge,
• #border - border box edge,
• #padding - padding box edge,
• #inner, default value - inner box edge,
• #content - content box edge. Content box here is outline of the content of the element and this is not  an inner box of the element. E.g. content box can be bigger than inner box if the element has overflow attribute set.
• #client - client area, that is #inner box minus areas taken by [optional] scrollbars.
• #icon -area covered by element's icon. Icon here is element's foreground image with foreground-repeat: no-repeat. If element has no such image the function returns #width and #height equals to zero.
• relativeTo, one of:
• #screen - returns coordinate relative to the origin of the screen,
• #root - returns coordinate relative to the origin of root element (view),
• #parent - returns coordinate of the element in its layout container.
• #self, default value - all coordinates are relative to the origin of inner box of the element.
• #view - returns coordinate relative to the origin of the sciter window (view object).
• or if relativeTo equals one of the following values:
• #margin - margin box edge,
• #border - border box edge,
• #padding - padding box edge,
• #inner - inner box edge

For such relativeTo values the function will return cumulative widths of correspondent parts, examples:

var (mx1,my1,mx2,my2) = this.box(#rect, #margin, #inner);
Each mx* value here will get sum of margin, border and padding in the left, top, right and bottom directions. In other words this call will return distances of margin box from inner(content) box of the element. And this call var (mx1,my1,mx2,my2) = this.box(#rect, #margin, #border); will just return computed values of margin-left, margin-top, margin-right and margin-bottom CSS attributes.

For more information see the CSS box model specification: http://www.w3.org/TR/CSS2/box.html

returns min-intrinsic width of the element. min-intrinsic width is minimal width needed to show element without horizontal scrollbar.

returns max-intrinsic width of the element. max-intrinsic width is minimal width needed to show element without wrapping, e.g. for the <p> element this will be width of its text replaced in single line.

returns min-intrinsic height of the element for the given forWidth. min-intrinsic heigh is minimal height needed to show element without vertical scrollbar.

returns the length value converted to the number of device pixels. Conversion is made in context of current element style so el.toPixels( em(1.4) ) will number of pixel correspond to 1.4em that us dependent on current font size of the element.

length is a string or symbol then this string is treated as a CSS length literal so it is possible to get values like: el.toPixels(#xx-small)  or el.toPixels(#system-scrollbar-width),

Second symbol parameter is used with the conversion from perecentage lengths:
var h50p = el.toPixels( pr(50.0), #height ); - will calculate the same value as the following CSS declaration: height:50%.

Returns various scrolling related positions of the element. Parameters:

part - one of symbolic constants:

• #left - left position of the view relative to content origin,
• #top - top position,
• #right - offset of right edge of the view from right edge of  the content box,
• #bottom - offset of bottom edge of the view from bottom edge of the content box,
• #width - width of scrollable area,
• #height - height of scrollable area.

Sets scroll position of the element to x,y position. The element should have overflow: hidden-scroll, scroll or auto to be able to scroll its content.

Scrolls the element to the view - ensures that element is visible.  If toTop is true then forces element to be on top of its scrollable container. This method does deep scroll - it tries to make the element visible through all its scrollable containers. If smooth is false then no attempt to animate the scrolling will be made.

element is a child DOM element (instance of this Element class) to be inserted at the index position. If index is greater than current number of children in this element then new element will be appended as a last element. Index is optional parameter, if ommited then element will be appended to collection. If element is already a child of some other parent then it will be disconnected from it automaticly.

If first parameter is string (html text) then attempt will be made to insert it at given position.

If first parameter is an object then it is considered as a template for creation of new DOM element. Microformat of that object is defined below.

Equivalent of insert ( ... , Integer.MAX );

Equivalent of insert ( ... , 0 );

Replaces content of the element by elements, that is short form of el.clear(); el.append(element1); el.append(element2); ...

This method can be used for setting cells in <tr>s. It handles properly cells with col/rowspans.

For all other elements elementN can be either DOM element, string or object - template of the element that uses microformat.

Stringizer method, replaces content of the element by the inline html. As this is a stringizer method then html can be provided as it is, example:

var el = ... , num = ...;
el.$content(This is item number { num });

Method returns the element itself.

Stringizer method, adds content defined by the inline html to the end of the list of children of the element.

Method returns first added element.

Stringizer method, insert content defined by the inline html at the start of children list of the element.

Method returns first added element.

Stringizer method, adds content defined by the inline html to the parent of the element immediately after this one.

Method returns first added element.

Stringizer method, insert content defined by the inline html to the parent of the element immediately before this one.

Method returns last added element (that will be new this.prior element).

Stringizer method, removes this element from the DOM and content defined by the html in its place.

Method returns first added element.

Removes this element from its parent's children collection so after call of this method this.parent become null. If update is true then calls update() for the parent element. Returns element that was just detached (this). This method does not destroy state and behaviors attached to the element until GC will not collect the element (if there are no references to it)

Removes this element from its parent's children collection so after call of this method this.parent become null. If update is true then calls update() for the parent element. Returns element that was just detached (this). All runtime states and behaviors are destroyed by the method. Native behaviors will receive BEHAVIOR_DETACHED event.

Loads content of the document referred by url as a content of this element. For elements having behavior:frame assigned it loads html, styles and executes scripts refered by the url or contained in the stream. For any other elements it loads only content of body portion of the document, no style loading or script execution happens in this case.

Loads content of the document from in-memory stream as a content of this element. For elements having behavior:frame assigned it loads html, styles and executes scripts refered by the url or contained in the stream. For any other elements it loads only content of body portion of the document, no style loading or script execution happens in this case.

Loads image from the url. If callback is ommited then the engine will try to load image sycnhronously otherwise (if callback is a function) engine will issue asynchronous request and will call this function upon arrival.

Signature of the callback function is function callback(image) where image is an object of class Image or null in case of error.

Sends synchronous or asynchronous http data GET/POST request to the server/page (url), a.k.a. JSON-RPC calls.

• #get, #post, #post-data #json are literal symbols - type of http request to be sent:
• #get - sends plain HTTP GET request, url-encoded params (if any) are appended to the url to form the request;
• #post - sends HTTP POST request with params serialized as Content-Type: application/x-www-form-urlencoded;charset=utf-8;
• #post-data - sends HTTP POST request with params serialized as Content-Type: multipart/form-data; boundary= ...;
• #put-data - sends HTTP PUT request with params serialized as Content-Type: multipart/form-data; boundary= ...;
• #post-json - sends HTTP POST request with params serialized as JSON,  Content-Type: application/json;charset=utf-8;
• #put-json - sends HTTP PUT request with params serialized as JSON, Content-Type: application/json;charset=utf-8;
• #delete - - sends HTTP DELETE request.
• url is a string - url of the page (location) on the server handling HTTP requests.
• params is an object, its properties are serving role of parameters of HTTP request.
• returns: true|false for asynchronous requests or pair of (data:any,status:integer) - result of the request (see data below) and HTTP status code (e.g. 200 - OK, 404 - resource was not found on the server).

function dataArrivedCallback( data: any, status: integer );

where data is either one of:

• instanceof Error object, in case of data response parsing problems;
• stream, if data returned by the server is of textual type (text/plain, text/html, text/xml, etc.)
• instanceof Object, Array, etc. if response has content type text/javascript, text/ecmascript, text/tiscript or application/json and was successfully parsed into data object.
• Bytes, if data returned by the server is of binary type (image/*, etc.). Bytes.type in this case will contain a string - mime-type of the data reported by the server.

and status code is an integer - HTTP status code (e.g. 200 - OK, 404 - resource was not found on the server) or if code is greater than 12000 it is a WinInet error code, see: http://support.microsoft.com/kb/193625.

Example of server data response (type: text/javascript) :

  ({ id : 1234, message : "Hello from XYS server!" })

- in this case server returns object having two properties: id and message. Rationale behind of ({ and }) was explained here.

Returns state of the element. stateFlags here is a set of bits - "ORed" constants STATE_***. stateFlags is provided then function returns int - flags of the element ANDed with the provided stateFlags variable. If no stateFlags is given then the function returns full set of flags element has at hte moment.

Function will set flags to the element update document on the screen accordingly (resolve styles and refresh).

Function will clear flags of the element and update document on the screen.

element.capture(true) - sets the mouse capture to the element and element.capture(false) - removes the mouse capture from the element.

Function will show element el as a popup window placed relatively to this element. Placement accepts following values:

• 2 - popup element below this element (anchor);
• 8 - popup element above this element;
• 4 - popup element on the left side of this element;
• 6 - popup element on right side of this element;

Function will show element el as a popup window placed at x, y (view relative coordinates). Placement is '7'.

Function will close popup if element el or any of its parent is a popup window.

If milliseconds is greater than zero the method will create timer for the DOM element with milliseconds delay.

After milliseconds delay engine will call callback function with this variable set to the dom element. Return true from the callback() function if you need to continue timer ticks and false otherwise.

Call of timer() with milliseconds = 0 parameter will stop the timer.

Returns Graphics object of the element. Graphics is a bitmap that has dimensions of the element therefore, once drawn, image will stay on the screen. Each invocation of the graphics method with color value will return that bitmap with all bits initialized with the color if forceInitialization is true or if graphics does not exist (first call of graphics()). Call of graphics() without parameters first time creates Graphics and initializes it with transparent color 0xFFFFFF, further calls returns created Graphics object and do nothing.

To remove graphics from the element use el.graphics(#destroy) call.

Removes graphics from the element.

Swaps DOM positions of two elements - owner of the method and the other. Returns element whose method is called.

traverse (send) bubbling event to the parent/child chain of this element. Events generated by this method can be handled by onControlEvent() methods of elements in the chain.

• eventCode is either one of constants from Logical event codes from builtin behaviors ( see: Event ) or any integer value above 0x1000 (custom control events range).
• reason here is an arbitrary integer value that sender and receiver knows about.
• owner is an optional reference to some DOM element. E.g. in MENU_ITEM_CLICK this is a reference to element - owner of popup menu or null.
• data is any json value that will passed to BEHAVIOR_EVENT_PARAMS.data field (see: sdk/api/sciter-x-behavior.h file)

The postEvent places event into the internal queue of posted events for future traversal by sendEvent and returns immediately.

The sendKeyEvent simulates the key event. eventDef may have following fields:

{
  type: Event.KEY_DOWN or Event.KEY_UP or Event.KEY_CHAR; // type if key event
  keyCode: int; // Key or char code, e.g. 'O'
  altKey: true or false; // optional, 'ALT' key pressed flag
  shiftKey: true or false; // optional, 'SHIFT' key pressed flag
  ctrlKey: true or false; // optional, 'CTRL' key pressed flag
}

Function returns true if the event was consumed during sinking/bubbling dispatching of the event using this element as a target.

The sendMouseEvent simulates the mouse event. eventDef may have following fields:

{
  type: Event.KEY_DOWN or Event.KEY_UP or Event.KEY_CHAR, // type if key event
  altKey: true or false, // optional, 'ALT' key pressed flag
  shiftKey: true or false, // optional, 'SHIFT' key pressed flag
  ctrlKey: true or false, // optional, 'CTRL' key pressed flag
  mainButton: true or false, // optional, left mouse button pressed flag
  propButton: true or false, // optional, right mouse button pressed flag
  x: int, // x mouse coordinate, view relative
  y: int, // y mouse coordinate, view relative
}

Function returns true if the event was consumed during sinking/bubbling dispatching of the event using this element as a target.

This method allows to delay execution of callback function. While calling the callback function engine will set this environment variable to the element this post call was invoked with.

Optional parameter only_if_not_there if defined and is true allows to post delayed event only once. Multiple post with the same callback function will yield to a single entry in posted events queue.

Method builds absolute url from the relativeUrl by using document url as a base.  If there is no relativeUrl then the method just returns url of the document this DOM element belongs to.

Sorts children of the element by using comparator function. comparator function has to have following signature:

function cmp(el1: Element, el2: Element) : int

that returns negative int value if el1 is less than el2, 0 if they are equal and positive value if el1 is greater than el2.

fromIndex and numOfElements are used for defining range of elements to sort.

This methods transforms the element into the "sprite" - element that moves independently from the rest of the DOM:

Declares element as having position:popup and moves it to the position (x,y). If the element happens to be outside of the view then engine creates special popup window for it. Third parameter describes role of x and y values. w and h parameters, if provided, change dimensions of the element.

Samples are in sdk/samples/ideas/moveable-windows/ and sdk/samples/ideas/rect-tracker/ folders.

See also: Element.style.dimension() method.

Calculates width of the text with respect of current font defined for the element. If text contains multiple lines separated by "\n" character then it returns width of widest string.

Calculates height of the text with respect of current font and line-height defined for the element. If text contains multiple lines separated by "\n" character then it returns sum of heights of all strings.

Assigns the handler function to the particular event that may occur on this particular DOM object.

handler function should have following signature function(evt) {...}, where evt is an Event object that describes the event in details.

eventGroup here is one of the following constants:

• Event.MOUSE - group of mouse events (like Event.MOUSE_DOWN, Event.MOUSE_UP, etc. );
• Event.KEY - group of keyboard events (like Event.KEY_DOWN, Event.KEY_UP, etc. );
• Event.BEHAVIOR_EVENT - group of generated, synthetic events (a.k.a. control events like Event.BUTTON_CLICK, Event.HYPERLINK_CLICK, Event.BUTTON_STATE_CHANGED, etc. );
• Event.FOCUS - group of scroll events;
• Event.SCROLL - group of scroll events;
• Event.SIZE - size changed event;

eventType here is one of constants defined below for particular group of event. eventType parameter is optional - if it is not provided then the handler function will receive all events of the eventGroup.

subscribe() method allows to attach multiple and independent event handling functions to single element.

Note that subscribe() is not a substitution of onMouse(evt), onKey(evt), etc. event handlers defined below. These two ways of handling events work side-by-side. onXXXX() methods are used for defining event handlers in classes (Behaviors) so to handle events for classes of elements. And subscribe()/unsubscribe() are used for attaching event handlers to particular elements.

Method returns the element it was called for. This allows to chain subscribe() calls.

unsubscribe() method detaches event handler[s] from the element.

The function returns list (array) of elements that were replaced in given row.

The function returns list (array) of elements that were replaced in given column.

The function returns position and height of the row.

The function returns position and width of the column.

The function removes row(s). Applicable to the <table> element only. It properly handles cells with rowspans.

The function removes column(s). Applicable to the <table> element only. It properly handles cells with colspans.

Sinking/Bubbling events:

Non-bubbling events