View object

Represents window where this script is running.

view - current view object (of the running script) is accessible through global 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 top-level windows. Accepts values: View.WINDOW_MINIMIZED, View.WINDOW_MAXIMIZED, View.WINDOW_HIDDEN, View.WINDOW_SHOWN or View.WINDOW_FULL_SCREEN.

focus

r/w - Element, current element that has input focus. To set new element in focus use view.focus = el;

eventsRoot

r/w - Element, "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 work area (dimension modulo task/menu bars). In device pixels.
  • #snapshot - returns Image - screenshot of this particular screen;
  • #isPrimary - returns true if this monitor is primary;
  • #device - returns string - name of monitor;
• part, one of view:
• #rect - (x1,y1,x2,y2) metrics, default;
• #rectw - metrics as (x,y,width,height);
• #position - (x,y) position of the screen on cumulative surface that includes all monitors; 
• #dimension - (width,height) of the screen;
• 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 interpreted as a desired position/size of the client area on the screen.

mediaVar

(name:string [, valueToSet: any]) : value | undefined

Returns or sets value of particular media variable.

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.

The method can be called as for particular view (window) as view.mediaVars(newVars) or as a class method View.mediaVars(newVars). In later case it will set default media variables for all windows created after the call.

selectFile

( #save | #open | #open-multiple, filter:string , ext: string [,initialPath:string[, dialogCaption:string]] ) : string | array(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 separated 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 ';' separated 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, [defaultFolder: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.
• defaultFolder - string, if provided shows dialog with that folder.

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 omitted 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 omitted 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 messages in the message queue. Returns immediately if there no any messages;
• #untilMouseUp - "short circuiting", 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 by 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. When data is an object then it is expected that it has the following structure where all properties are optional except any one:

{
   text: "some text",
   html: "<b>some html</b>",
   link: { caption: "some text", url: "file://some ..." },
   file: [ "path1",  "path2", ...],
   json: someData
}  

Please note that json clipboard format is Sciter specific. You can use it to pass data between Sciter applications.

You can set multiple data items at once (e.g. text and html together). Destination application will pick up format it understands in particular context. 

focusable

(#next | #prior | #first | #last, [from:Element]) : Element

The method returns next/previous/first/last focusable element in TAB order, either from element or from current element in focus.

performDrag

((element:Element | img: Image, xOffset: integer, yOffset: integer), 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, alternatively you can provide image and x/y icon offset 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 | { caption: "some text", url: "file://some ..." }} - single url as a string or caption/url pair;
• {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:

• type - symbol, HTTP verb, one of : #get, #post, #put or #delete, default: #get ;
• url - string, url;
• protocol - symbol,  one of #basic, #multipart and #json  ;
• params - object, HTTP request parameters;
• headers - object, additional HTTP request headers;
• success - function(data,status), callback function to be called on successful completion.
• error - function(err,status), callback function to be called on request failure.
• complete - function(data or err,status), callback function to be called on request completion (either success or error).
• progress - function(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, proxyPort - string, 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.
• noCache - true | false, if true then request will not use reading from cache nor writing the request response to cache. 

Sample: sdk/samples/communication/file-download.htm and sdk/samples/communication/http.tis

trayIcon

( param : symbol | object ) : many

Defines parameters of tray icon for the window. Accepts following parameters:

• view.trayIcon { image: Image, text: string } : boolean creates tray icon for the window, parameters:
  • image is an instance of Image class, mandatory - bitmap of system specific size (e.g. for MacOS 20x20px png);
  • text is string - tooltip text that will appear on mouse over the icon.
• view.trayIcon( #place ) : (x,y,w,h) - returns location of the tray icon in screen coordinates.
• view.trayIcon( #remove ) : boolean -  removes tray icon from system status bar.

When tray icon is created the view will start receiving trayicon-click events.

Sample: sdk/samples/trayicon

audio

( url: string ) : Audio

Creates Audio object that allows to play .mp3, .flac and .wav sounds

Notifications

onRequest(rq: Request)

When defined on the view the method will be called before execution of the request. The handler can call rq.fulfill() to provide data for the request;

onRequestResponse(rq: Request)

The method will be called after completion (with success or failure) of the request.

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 resizable 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 } - proposed 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 } - proposed 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.

"closing"

The event is generated as a part of view(window) closing sequence, delivered before view's document gets destroyed.

"close"

Very last event from view (window), delivered immediately before view (window) is destroyed.

"trayicon-click"

Click on tray icon (if any). Event parameter is an object { x: integer,  y: integer, button: integer }  where x/y are mouse screen coordinates, and button is 1 - left mouse button or 2 - right mouse button or 0 if system does not support right clicks (MacOS) on tray buttons.