View object

View object

Represents window where this script is runnung.

view – current view object (of the running script) is accessible through gloabal view variable.

WINDOW_MINIMIZED
WINDOW_MAXIMIZED
WINDOW_HIDDEN
WINDOW_SHOWN
WINDOW_FULL_SCREEN
Values of view.state property.

Properties

root
r – Element, root element of a document loaded into the view.
windowState
r/w – state of the window. Applicable only for toplevel windows. Accepts values: View.WINDOW_MINIMIZED, View.WINDOW_MAXIMIZED, View.WINDOW_HIDDEN, View.WINDOW_SHOWN or View.WINDOW_FULL_SCREEN.
focus
r/wElement, current element that has input focus. To set new element in focus use view.focus = el;
eventsRoot
r/wElement, "events root" element. Used for implementation of "modal document loops". If set then all UI events that are targeted to elements that are not descendants of the element will be rerouted to the element. Setting this element may cause current focus element to be changed. Here is typical modal document loop:
view.eventsRoot = dlg;
while (dlg.isVisible) view.doEvent();
dlg.style#display = "none";
view.eventsRoot = null;
screen
r – integer, screen number where this window is located
screens
r – integer, number of screens (monitors) in the system.
windowCaption
r/w – string, window caption.
windowAspectRatio
r/w – float | null, aspect area of client area of this window;
windowResizable
r/w – boolean, true if window can be resized by the user;
windowMinimizable
r/w – boolean, true if window has minimize button – can be minimized by the user;
windowMaximizable
r/w – boolean, true if window has maximize button – can be maximized by the user;
windowTopmost
r/w – boolean, true if the window is at the topmost level;
windowMinSize
r/w – (x:integer,y:integer), min window dimension constraints. User cannot make window smaller than these;
Example: view.minSize = (160,100);
windowMaxSize
r/w – (x:integer,y:integer), max window dimension constraints. User cannot make window larger than these;
Example: view.maxSize = (1600,1000);
windowIcon
r/w – window icon, the property accepts: null – set default icon, "url" – string, url of window icon or instance of Image.
windowBlurbehind
r/w – window blur-behind effect, the property accepts: #auto | #ultra-dark | #dark | #light | #ultra-light | #none values. If this flag is set then the window window is semitransparent. Root document shall use html { background:transparent; } in order to see desktop behind the window.

Methods

this
(non-constructable)
load
(url:string[, now: bool]) : true/false

Method loads new document (replaces current one) in the current view from the given url. If now is equal to true this method loads document synchronously – method will return after document will be downloaded and loaded in the view.

load
(stream:Stream) : true/false

Method loads new document (replaces current one) in the current view from the given in-memory stream.

box
( part [, edge [, relativeTo ]] ) returns: integer, device pixels

Returns coordinates of the edges of the view. Parameters:

  • part – one of symbolic constants #left, #top, #right, #bottom, #width or #height. Defines part of box (rectangle) to return. Additionally #part may accept the following constants:
    • #rect – (x1,y1,x2,y2) metrics;
    • #rectw – metrics as (x,y,width,height), default;
    • #position – (x,y),
    • #dimension – (width,height),
  • edge, one of view:
    • #border – border box edge – OS window border bounds,
    • #client – client area edge,
  • relativeTo, one of:
    • #screen – returns coordinate relative to the origin of the screen,
    • #self, default value – all coordinates are relative to the origin of the client area of the view.
screenBox
( [screenNo: integer,] area [, part ] ) returns: integer, device pixels

Returns screen(monitor) projection on cumulative desktop space. Parameters:

  • area – one of symbolic constants #frame – monitor screen dimension, #workarea – monitor workarea (dimension modulo task/menu bars). In device pixels.
  • part, one of view:
    • #rect – (x1,y1,x2,y2) metrics, default;
    • #rectw – metrics as (x,y,width,height);
    • #position – (x,y),
    • #dimension – (width,height),
  • screenNo – integer, optional. If provided returns metrics of particular screen. If omitted returns metrics of this window screen.
move
( x:int, y:int [, clientCoordinates: true | false] ) :void

Replaces window of the view (dialog or frame) on the screen. This method is applicable only for standalone Sciter.

If clientCoordinates is true x and y are interpretted as a desired position of the client area on the screen.

move
( x:int, y:int, width:int, height:int [, clientCoordinates: true | false] ) :void

Replaces window and changes dimension of the view (dialog or frame) on the screen. This method is applicable only for standalone Sciter.

If clientCoordinates is true x,y, width and height are interpretted as a desired position/size of the client area on the screen.

mediaVars
([ newVars:object]) : Object | undefined

If no newVars parameter provided then the method returns current set of media variables used by the view.

If newVars is an object then the method will update view’s media variables from properties of the object. Returns undefined in this case.

selectFile
( #save | #open, filter:string , ext: string [,initialPath:string[, dialogCaption:string]] ) : string | null

Methods shows system file selector modal dialog and returns full path name of the selected file or null if user cancels this dialog.

  • First parameter is either #save or #open symbol. If #save is provided then dialog will have a caption Save As… otherwise (#open) it will have caption Open…
  • filter is a string – filter which defines list of allowed file extensions seprated by character ‘|’ in the form: "label1|file.ext1|label2|file.ext1|.." where label is a label of item (appears in the selector on the dialog) and file.ext is a ‘;’ seprated list of filename templates.
  • ext is a string – default file extension used if user will type filename without extension.
  • initialPath – string, if provided will open dialog with folder.
  • dialogCaption – string, caption of the file open dialog.
Following sample will popup dialog to select html files and will load file in current view:
var fn = view.selectFile(#open,
       "HTML Files (*.htm,*.html)|*.HTM;*.HTML|All Files (*.*)|*.*" , "html" );
if( fn ) view.load(fn);
selectFolder
( [ dialogCaption:string]] ) : string | null

Methods shows system folder selector modal dialog and returns full path name of the selected folder or null if user cancels this dialog.

  • dialogCaption – string, caption of the file open dialog.
Note that different platforms may have different UI for the selectFolder from the one used by view.selectFolder.
selectPrinter
TBD
dialog
( url: string | stream: Stream [, parameters: any [, alignment: int = 5] ] ) : undefined | value passed to close method of the dialog.

Shows modal dialog defined by document at url or contained in in-memory stream. В object parameters if given will be copied to view.parameters variable available for scripts inside dialog HTML.

alignment – integer, 1..9 – alignment of the window relative to the screen, -1 .. -9 – relative to its parent window, For meaning of the values see NUMPAD on the keyboard, e.g. alignment 5 means center/middle of the dialog will be placed in the center/middle of the screen.

dialog
( creationParams:object ) :undefined | value passed to close method of the dialog.

Another form of calling modal dialog using single parameter object.

The creationParams is an object that may have following fields:
  • url – string, url of the document to load into the window;
  • html – string, content to load into the window. Either url or html must be provided;
  • x,y, width, height – integers, dimension of the window. If ommited dimensions will be calculated by intrinsic sizes of given document;
  • client – true | false, if true then x,y, width, height above are treated as coordinates of client area rather than window box;
  • parameters – object, parameters passed as they are to the view.parameters object of newly created window;
  • caption – string, window caption;
  • alignment – integer, 1..9 – alignment of the window relative to the screen, -1 .. -9 – relative to the parent.
  • screen – integer, 0 .. View.screens – 1, if alignment is 1..9 then it determines screen/monitor where the window will appear, optional.

If x,y and alignment provided then x,y defines reference point and the alignment defines relative position of the window against that point.

msgbox
( type:symbol, text: string, [ title: string, [ buttons В [, onLoad: function [, onClose: function ]]]] ) : undefined | symbol of the button pressed to close dialog.
  • type – symbol, one of the following values: #alert, #information, #question or #warning ;
  • text – string, either plain text or html ;
  • title – string, caption of the dialog window;
  • buttons – button definition(s), either:
    • one of the symbols: #ok, #cancel, #abort, #ignore, #yes, #no or #close, or
    • object with the structure { id:#somesymbol, text:"Some Text" } or
    • array of symbols or objects above;
  • onClose – function with the signature function(root, id) returning true|false. This function will be called on attempt to close dialog with parameters id – id of the button pressed and root – root node of the HTML document of the dialog. Function shall return true if dialog can be closed at the moment.
  • onLoad – function with the signature function(root). This function will be called after creating dialog window. Use it if you need to do some initialization, e.g. fill data of input fields if text is an html containing <input>s.
Samples:
  1. view.msgbox(#information, "I am fine!"); – will show simple message;
  2. view.msgbox(#question, "Be or not to be?", "Huh?",
    [ {id:#yes, text:"To be"}, {id:#no, text:"Not to be"} ] );
window
( params:object ) :View – view object of created window.

Creates separate window.  

The params is an object that may have following fields:
  • type – int, window type, one of the following values: View.FRAME_WINDOW, View.TOOL_WINDOW and View.POPUP_WINDOW ;
  • url – string, url of the document to load into the window;
  • html – string, content to load into the window. Either url or html must be provided;
  • x,y, width, height – integers, dimension of the window. If ommited dimensions will be calculated by intrinsic sizes of given document;
  • client – true | false, if true then x,y, width, height above are treated as coordinates of client area rather than window box;
  • state – integer. initial state of the window, either View.WINDOW_SHOWN, View.WINDOW_HIDDEN, View.WINDOW_MINIMIZED, View.WINDOW_MAXIMIZED or View.WINDOW_FULL_SCREEN;
  • parameters – object, parameters passed as they are to the view.parameters object of newly created window;
  • caption – string, window caption;
  • alignment – integer, alignment of the window relative to the screen, -1 .. -9 – relative to the parent.
  • screen – integer, 0 .. View.screens – 1, if alignment is 1..9 then it determines screen/monitor where the window will appear, optional.

If x,y and alignment provided then x,y defines reference point and the alignment defines relative position of the window against that point.

To open window in detached mode ( it will stay on screen even when its owner window is collapsed ) call the method as static one – using View class rather than view instance: View.window(...).

close
( [retval: any] ) : undefined

closes current view (or dialog if it is view of dialog window). retval is any scripting object – return value of the dialog() function.

doEvent
( [#wait | #nowait | #all] | #untilMouseUp ) : undefined

Passes control to the operating system. Control is returned after the operating system has finished processing next event in its event queue. This method is used for implementing modal document loops.

In case of:

  • #wait – waits for the next event in the UI message queue, default behavior.
  • #nowait – if there is any event in message queue handles it and returns immediately if there no any messages;
  • #all – executes all pending messeages in the message queue. Returns immediately if there no any messages;
  • #untilMouseUp – "short circuting", executes and dispatches messages until MOUSE_UP is received, used in drag scenarios;
update
() : undefined

Executes all pending changes in the view and renders what was changed on the screen. After this call box coordinates of all DOM elements are valid.

Use this method when you need to commit all updates made on the DOM to the moment. For example:

function retrieveDataFromDB(recordSet)
{
  while(!recordSet.EOF())
  {
    grid.appendRow(recordSet.row);
    if(++numRowsAdded > 10)
    {
      numRowsAdded = 0;
      view.update();
    }
  }
}
clipboard
(callback: function) : undefined

Calls the callback function for each format of data presented in system clipboard at the moment. The callback function has following signature: function ( dataType: symbol ) {...}, where dataType is a symbol designating one of supported formats:

#text
– text/plain, represented bys string
#html
– text/html, represented by string;
#picture
– bitmap image, represented by object of type Image;
#url
– url or link, represented by object of the following structure: В { url: string , caption: string };
#json
– JSON data, represented as an object. returns integer – clipboard sequence number. Each change of clipboard buffer changes this number.
clipboard
(#get, dataType: symbol) : string | object | Image;

Fetches data from the clipboard in format defined by the dataType parameter. For list of allowed values see previous method definition.

Note: for the #html format this function returns two values: source url (if any) and html data per se.
To get both of them use this : var (url, html) = view.clipboard(#get, #html);

clipboard
(#put, data: string | object | Image ) : undefined;

Stores data to the clipboard.

performDrag
(element:Element, data:Object, ddMode: #any | #copy | #move) : null | #copy | #move

Performs system drag and drop operation.

element is a DOM element that is used as a drag image.

data is an object that contain following properties:

  • {text: String} – plain text string;
  • {html: String | Element} – html, either as a string or outer HTML of given element;
  • {file: String | [String, String, ...]} – single file name or list of file names to drop;
  • {link: String} – single url as a string;
  • {json: value} – any value that will be serialized into JSON string. JSON can be used to pass additional data between Sciter windows.

The data object may contain multiple properties, destination will choose most appropriate.

ddMode defines types of drag-n-drop operations allowed:

  • #copy – copy from source to destination;
  • #move – move from source to destination;
  • #any – either move or copy.

performDrag() is a blocking operation – the function returns when drag-n-drop is complete or rejected.

cursorLocation
( ) : (x:int, y: int)

Returns cursor location relative to client area of the view:
var (x,y) = view.cursorLocation();

on
( nameandns: string, handler: function ) : view

Attaches the handler to one of view (window) related events.

nameandns – string that contains one of the event names at the bottom and optionally arbitrary namespace name in the form "name.namespace".

off
( eventname: string | handler: function ) : view

Detaches event handler either by name or by function itself.

eventname here is either "name", full "name.namepsace" or just ".namepsace". Example:

view.off(".mymodule");

will unsubscribe both event handlers set by the code:

view.on("move.mymodule",foo)
    .on("size.mymodule",foo);
request
( params: object) : undefined.

Sends HTTP request with params object having following fields:

  • typesymbol, HTTP verb, one of : #get, #post, #put or #delete, default: #get ;
  • url – string, url;
  • protocolsymbol,  one of #basic, #multipart and #json  ;
  • paramsobject, HTTP request parameters;
  • headersobject, additional HTTP request headers;
  • successfunction(data,status), callback function to be called on successful completion.
  • errorfunction(err,status), callback function to be called on request failure.
  • completefunction(data or err,status), callback function to be called on request competion (either success or error).
  • progressfunction(bytesReceived, totalBytes), callback function to be called on each chunk of data received. bytesReceived is an integer – number of bytes received so far and totalBytes is an integer – total bytes as reported by server in HTTP’s "content-length" field. totalBytes can be undefined if server does not report it.
  • toFile – string, if provided shall contain path of the file where to store the response. Used in file download scenarios.
  • proxyHost, proxyPortstring, integer. If these two are provided then the request will go through that proxy host.
  • output – symbol, one of #string | #stream | #bytes | #json. If provided forces data to be reported as instance of String, Stream, Bytes or a value – result of JSON parsing.
Sample: sdk/samples/communication/file-download.htm and sdk/samples/communication/http.tis

View events

To subscribe to view events use view.on(eventname, handler) method of the view object providing:

  • eventname – string that contains one of names below and optionally arbitrary namespace name in the form "name.namespace";
  • handler – function that will be called on the event.

Event names

"size"
Event is generated after dimensions of the view (window) was changed. Use view.box() method to get dimensions.
"sizing"
Event is generated while user is changing dimensions of resizeable window. Function-handler shall have signature: function(sizingParams) where sizingParams is an object of this structure: { x:integer, y:integer, width:integer, height: integer, side: 1...9 } – propsed dimensions of the window and side is a window side/corner dragged to change window dimension.
"move"
Event is generated after position of the view (window) was changed. Use view.box() method to get dimensions and positions.
"moving"
Event is generated while user is moving the window by dragging it by caption. Function-handler shall have signature: function(movingParams) where movingParams is an object of this structure: { x:integer, y:integer, width:integer, height: integer } – propsed dimensions of the window. Function-handler can change properties of the object discriminating window movements.
"statechange"
Event is generated when state of the view (maximized, minimized, hidden, shown ) was changed. See View.state property.
"resolutionchange"
Event is generated when window PPI (pixels per inch scale factor) changes. To get actual pixels-per-inch value use:
var ppi = (1in).toFloat(#px); and to get pixels-per-dip:  
var ppdip = (1dip).toFloat(#px);
"mediachange"
Event is generated when one of media variables changes (including resolution change), for example when number of monitors or color depth changes.
"replacement-start"
Event is generated when user starts replacing (moving and/or sizing) of the window by UI means (e.g. dragging it by caption).
"replacement-end"
Event is generated after user completes the window replacement by UI means (e.g. dragging it by caption).
"activate"
The event is generated when Sciter window gets activated or deactivated. Event handling function may have parameter mode defined that will take one of the following values:
  • false – window is deactivated;
  • true – window is activated somehow but not by mouse;
  • #by-mouse – window is activated by mouse click on it.