class Window

Instances of the Window class represent desktop windows.

Window.this is a reference to current window object, that is the instance of the Window class where the HTML document is loaded.

NOTE: the window below is an instance of Sciter's Window class - e.g. Window.this but not that strange "window" thing of browsers.

constructor:

new Window({params:object})

where params is an object with properties:

type - optional, is one of:
- Window.POPUP_WINDOW
- Window.TOOL_WINDOW
- Window.CHILD_WINDOW
- Window.FRAME_WINDOW - default window type
- Window.DIALOG_WINDOW
parent : Window - optional, instance of parent (owner window). When owner is closed or minimized then this window will be closed/minimized too. parent defines z-order of this new window. Window with the defined parent will always float on top its parent.
caption : string - optional, window caption (or title).
x : integer - optional, screen pixels, horizontal position of the window on screen;
y : integer - optional, screen pixels, vertical position of the window from the top of the screen;
width : integer - screen pixels, window width;
height : integer - screen pixels, window height;
client : true | false - if true then x,y,w,h are coordinates of desired window client box on the screen;
alignment : integer - optional, [1 to 9] alignment of the window on monitor, if [-1 to -9] and parent is provided then it aligns the window against parent window. (1 bottom left corner, 2 bottom middle, 3 bottom right corner, 4 middle left, 5 center, 6 middle right, 7 top left corner, 8 top middle, 9 top right corner)
screen : integer - optional, number of monitor on multi-home systems.
state : - optional - window state, is one of:
- Window.WINDOW_SHOWN - default state
- Window.WINDOW_MINIMIZED
- Window.WINDOW_MAXIMIZED
- Window.WINDOW_HIDDEN
- Window.WINDOW_FULL_SCREEN
url : string - optional, window html source code file.
parameters : array | string | object, ... - optional, extra parameters to pass to the new window.

properties:

focus

read/write property, either null or an element in focus;

state

window.state - read/write, integer, one of:

1 Window.WINDOW_SHOWN - window is shown normally;
2 Window.WINDOW_MINIMIZED - window is collapsed to icon/tray, also known as "iconified" state;
3 Window.WINDOW_MAXIMIZED - window spans whole working area (excludes taskbar, etc) of the desktop;
4 Window.WINDOW_HIDDEN - window is hidden (not visible);
5 Window.WINDOW_FULL_SCREEN - window spans whole desktop area, so appears on top of all other windows including taskbar, etc;
0 Window.WINDOW_SHOWN_NA - write only value, use it to show window without activating it (setting focus on it);

frameType

window.frameType - read/write, string, frame type of the window, one of:

"standard" - default frame type;
"transparent" - transparent (a.k.a. layered) window;
"solid" - non-transparent, rectangular window without any decorations;
"solid-with-shadow" - non-transparent window without caption and buttons, may have rounded corners and shadow if OS supports that.
"extended" - standard window shape but without caption bar. Caption and window buttons(exception:MacOS) shall be defined in markup/css.

caption

read-write, string, window's caption (title).

icon

read/write, Graphics.Image, window icon.

screen

read-only, integer. Reports screen (monitor) index this window is on at the moment. Integer in the range [0 ... Window.screens).

graphicsBackend

read-only, string. Reports current graphics backend used: "direct2d", "Skia/OpenGL", etc.

minSize, maxSize

window.minSize = [w,h] - get/set minimal size of resizable window.
window.maxSize = [w,h] - get/set maximum size of resizable window.

blurBehind

window.blurBehind = "..." - read/write, string, blur-behind effect configuration string, either:

"none" - no blur behind effect;
"dark|light|auto [ultra] [source-auto|source-windows|source-desktop]" - flags composition string, where:
- "source-windows" - blur of all windows behind this one;
- "source-desktop" - blur of desktop background image - so called Mica effect;
- "source-auto" - default, blur source is chosen according to window type;

Example: W11 Mica light effect window: window.blurBehind = "light source-desktop";

isActive

read-only, boolean, reports if window has input focus.

isAlive

read-only, boolean, it is true if the window is alive - has valid HWINDOW. The property is false when the window was closed and destroyed.

isOnActiveSpace

read-only, true if window is on active space now. The property is undefined if host system does not support spaces (virtual desktops).

isResizable

read/write, boolean, true if window can be resized by the user.

isMaximizable

read/write, boolean, true if window can be maximized by the user.

isMinimizable

read/write, boolean, true if window can be minimized by the user.

isTopmost

read/write, boolean, true if window is topmost at z-order.

isEnabled

read/write, boolean, true if the window is allowed to accept user's input.

aspectRatio

read/write, float, width to height ratio to keep on window resizes.

eventRoot

 Window.this.eventRoot = element | null

if set by element, short circuits all UI events to that element and its children as if the window contains only that element. Used in lightbox dialog scenarios (see: samples.sciter/lightbox-dialog).

focus

read/write, DOM element in focus.

parent

read-only, Window | null - parent window of this one.

document

read-only, Document - root document of the window.

parameters

read-only, any - parameters provided by constructor, available inside the window as they are.

methods:

box()

window.box(boxPart,boxOf[,relTo[, asPPX : bool ]]):[...]

Reports geometry of the window.

parameters:

boxPart defines what part of the box to return, is one of:
- "xywh" or "rectw" - [x,y,w,h], array, position and dimension of the rectangle.
- "rect" - [x1,y1,x2,y2], array, positions of origin and corner of the rectangle.
- "position" - [x,y], array, position of the rectangle.
- "dimension" - [w,h], array, dimension of the rectangle.
- "left","top","right","bottom","width","height" - individual integers.
boxOf is one of:
- "border" - border area of the window that includes window caption and borders around client area;
- "client" - client (content) area of the window;
- "cursor" - mouse cursor position, like let [cx,cy] = Window.this.box("position","cursor","desktop");
- "caret" - caret position, relative to client area of the window;
relTo is one of:
- "desktop" - coordinates are relative to desktop (outline of all monitors in the system);
- "monitor" - coordinates are relative to the monitor this window is replaced on;
- "self" - coordinates are relative to the origin of window's client area;
asPPX optional, is a boolean:
- true - coordinates are in physical device pixels;
- false - coordinates are in CSS pixels - 1/96 of inch;

screenBox()

window.screenBox(what [, boxPart [,asPPX]])

Reports geometry of monitor this window is on.

parameters:

what defines what information to return, is one of:
- "frame" - physical position and size of the monitor in screen pixels projected on desktop.
- "workarea" - physical position and size of work area on the monitor ( frame minus taskbar )
- "device" - string, name of the monitor.
- "isPrimary" - boolean, true is that is primary monitor.
- "snapshot" - Graphics.Image, returns snapshot (screenshot) of the monitor.
boxPart defines what part of the box to return, is one of:
- "xywh" or "rectw" - [x,y,w,h], array, position and dimension of the rectangle.
- "rect" - [x1,y1,x2,y2], array, positions of origin and corner of the rectangle.
- "position" - [x,y], array, position of the rectangle.
- "dimension" - [w,h], array, dimension of the rectangle.
- "left","top","right","bottom","width","height" - individual integers.
asPPX is a boolean:
- true - coordinates are in physical device pixels;
- false - coordinates are in CSS pixels - 1/96 of inch;

cursorPos()

const [x,y] = window.cursorPos();

Reports current position of cursor relative to client area of the window.

move()

window.move(x, y [,width, height [, "client" ]])

move/size window.

parameters: x, y, width, height are in PPX (physical screen pixels).

If "client" is provided then x, y, width, height are treated as window client area coordinates.

moveTo()

window.moveTo(monitor, x, y [,width, height [, "client" ]])

move/size window to particular monitor;

x, y, width, height are in DIPs - device independent pixels (a.k.a. CSS pixels).

shape()

window.shape( Graphics.Path | Element )

Defines shape of the window. Points out of the path are visually transparent and click-through.

If element is provided as a parameter then the path is constructed from non-transparent areas of the element and/or sub-elements.

selectFile()

window.selectFile({params:object})

file open/save dialog, params is an object with the fields:

mode : "save"|"open"|"open-multiple"
filter : "title|ext1;ext2", "HTML File (*.htm,*.html)|*.html;*.htm|All Files (*.*)|*.*"
extension : default file extension, "html"
caption : title of dialog, "Save As"
path : initial directory

returns:

string, file URL of selected file in "open" and "save" modes;
array(string), list of selected files;
null if selection was cancelled by the user.

selectFolder()

window.selectFolder({params:object})

folder open dialog, params is an object with the fields:

caption : title of dialog
path : initial directory

returns string - folder URL;

mediaVar()

window.mediaVar(varname[,value])

gets/sets media variable that can be used in CSS as @media varname {...}

mediaVars()

window.mediaVars([values:object])

gets/sets multiple media variables at once.

addEventHandler()

on()

window.on("eventname", handler)

subscribe to window related events.

tip

eventname may contain namespace suffix: "move.mycomponent"

off()

window.off("eventname" | handler)

unsubscribe event handler either by name, namespace or handler reference

dispatchEvent()

window.dispatchEvent(event):boolean

Send the event to the window synchronously. Returns true if any of event handlers consumes the event.

postEvent()

window.postEvent(event)

Post the event to the window asynchronously. The function returns immediately - does not wait for the event consumption.

load()

Window.this.load(url:string)

Loads new document into the window.

tip

Almost always it is better to do not use this method but to use <frame> inside the window and load needed document there:

document.$("frame.content").src = url;

xcall()

window.xcall(name:string [, arg0, ..., argN]): any

Interaction with native behaviors attached to the window. window.xcall("foo") will end up in handle_scripting_call() of native behavior attached to the window using SciterWindowAttachEventHandler API.

doEvent()

window.doEvent(mode) : any

Performs system event(s) in application message queue, mode is one of:

"wait" - waits for the next event and executes it;
"noWait" - if next event is available executes it otherwise returns immediately;
"untilMouseUp" - executes events until mouseup event arrives, used for various drag cases;
"untilQuit" - performs run loop - executes all events until application quit message arrives;
"I/O" - performs events associated with I/O;

window.modal(JSX) : any

shows predefined message boxes:

<info>..</info>,
<alert>..</alert>,
<error>..</error>,
<question>..</question>.

window.modal({params}) : any

shows new window as dialog, for params see new Window({params}). The function returns window close value of window.close(valToReturn) call inside the window.

window.modal(new Window(...)) : any

shows already constructed window modally.

performDrag()

window.performDrag(data:object, mode, dragIcon[, dragIconXoff, dragIconYoff] ): null | string

Performs drag-and-drop using system D&D mechanism.

parameters:

data - object, may contain one or several fields:
- text: string - plain text data;
- html: string - HTML data;
- file : [path1,path2,...] | path0 - single or multiple file names;
- json: any - any data that can be JSON.stringify'ed;
mode, string, either "copy" or "move";
dragIcon, either Image or Element;
dragIconXoff, dragIconXoff - integer, icon anchor point offset.

returns:

null - user has canncelled D&D operation by pressing Escape.
"copy" - user completes copy operation (D&D + CTRL);
"move" - user completes move operation;

focusable()

The function allows to enumerate elements in TAB order.

window.focusable(dir [,reference:element]): element

parameters:

dir, string, one of:
- "next" - next focusable element after the reference;
- "prior" - previous focusable element after the reference;
- "first" - first focusable DOM element on the window;
- "last" - last focusable DOM element on the window;
reference - optional, must be a focusable element with either:
- tabindex >= 0 or
- element.state.focusable = true or
- STATE_FOCUSABLE in native code.

tip

You can assign the found element to window.focus = element set the focus on it.

close()

window.close([value]): bool

request to close the window, the value is a return value used in modal dialogs;

update()

window.update()

request calculation of layout of elements inside the window. Positions of elements should be known after the call.

activate()

window.activate(bringToFront: bool)

set input focus on the window.

trayIcon()

window.trayIcon({image: Graphics.Image, text: string})

Show tray icon with the image and tooltip text.

Tray icon will generate "trayiconclick" event on user clicks.

window.trayIcon("remove")

removes tray icon.

const [x,y,w,h] = window.trayIcon("place");

reports location of the icon on desktop, coordinates are in screen pixels.

requestAttention()

window.requestAttention("info" | "alert" | "stop")

requests user attention by flashing or bouncing window icon in task/dock bar.

addHotKeyHandler()

window.addHotKeyHandler(keyCombination:string, callback:function):id

Registers global system hotkey hook. hotkey handlers allows to handle key combinations when the window is not in focus or even hidden.

The function throws an error if the system rejects the hotkey, for example if that hotkey is already assigned to other application.

keyCombination is a + combination of optional modifiers and key name (event.code names) like: "F5" and "Control+KeyN". Supported modifiers:

Control or Ctrl;
Command or Cmd - CMD key on MacOS and Win key on Windows;
Alt;
AltGr;
Shortcut - is CMD key on MacOS and Ctrl on other OSes;
Shift;

The function returns an id that can be used to unregister hot key.

danger

this function is supported only on Windows for a while as only this OS has official hotkey API.

removeHotKeyHandler()

removeHotKeyHandler(id)

Removes hotkey handler set by addHotKeyHandler.

isOnActiveSpace

true is the window is on active virtual desktop now.

class methods and properties:

this

Window.this

property, instance of Window class - reference of the window where this code is running;

all

Window.all: Array<Window>

List of all Sciter windows in current process (including Window.this). Used for enumeration of windows:

for(let wnd of Window.all)
   ...

Window.share: Object

property, is an object shared between all documents and windows in the application.

danger

Use it responsibly. If temporary window or document populates shared object then it should clean the stuff there in beforeunload.

screens

Window.screens: integer

returns number of screens (monitors) in the system;

screenBox()

Window.screenBox(screen:integer, what[, boxPart])

reports geometry and information of the given screen (monitor). For what and boxPart parameters see window.screenBox() method above.

Additionally what supports "devicePixelRatio" value, in this case the function returns the ratio of the resolution in physical pixels to the resolution in CSS pixels for the given monitor.

elementAt()

Window.elementAt(screenX,screenY):Element

returns DOM element under screenX/screenY position.

note

This method may return DOM element belonging to any Sciter window in current process.

ticks()

Window.ticks():milliseconds

returns value of internal timer in milliseconds.

post()

Window.post( ge: Event )

posts global event ge to all windows in current process.

send()

Window.send( ge: Event ) : boolean

Synchronously sends global event ge to all windows in current process.

Sending stops on first window that will consume the event by returning true from event handler of this event.

Returns true if some event handler consumes the event.

events

Use window.on("eventname", handler) to subscribe to these events.

"statechange"

window.state flag has changed.

"closerequest"

Window closure requested.

JS code can prevent window closure by the user by calling event.preventDefault():

const CLOSE_BY_CHROME = 0; // user clicked `🗙` on window chrome
const CLOSE_BY_CODE = 1;   // window.close() issued
const CLOSE_BY_LOAD = 2;   // document unload-old/load-new

Window.this.on("closerequest", event => {
  if(event.reason == CLOSE_BY_CHROME) {
    // instead of closing we just minimize it:
    Window.this.state = Window.WINDOW_MINIMIZED;
    event.preventDefault(); // prevent closing the window
  }
});

"resolutionchange"

after window moved to another monitor with different resolution, or user have changed screen resolution.

"mediachange"

one or several CSS media variables have changed.

"activate"

the window was deactivated (evt.reason == 0) or got focus (evt.reason > 0).

"replacementstart"

"replacementend"

the user has started/ended moving or resizing window frame.

"move"

user have moved the window.

"size"

user have changed size of the window.

"trayiconclick"

the user has clicked on tray icon.

"spacechange"

Space (a.k.a. virtual desktop) has changed. Use Window.this.isOnActiveSpace property to determine if window is on active space now.

"system-suspend"

The system is about to enter a suspended state (e.g., sleep mode).

"system-resume"

The system has resumed operation after being suspended.

"system-lock"

The desktop session has been locked.

"system-unlock"

The desktop session has been unlocked.

"system-logon"

A user logs on to a desktop session.

"system-logout"

A user has logged off the session.

"system-shutdown"

A user chooses to end the session.

class Window

constructor:​

properties:​

focus​

state​

frameType​

caption​

icon​

screen​

graphicsBackend​

minSize, maxSize​

blurBehind​

isActive​

isAlive​

isOnActiveSpace​

isResizable​

isMaximizable​

isMinimizable​

isTopmost​

isEnabled​

aspectRatio​

eventRoot​

focus​

parent​

document​

parameters​

methods:​

box()​

screenBox()​

cursorPos()​

move()​

moveTo()​

shape()​

selectFile()​

selectFolder()​

mediaVar()​

mediaVars()​

addEventHandler()​

on()​

off()​

dispatchEvent()​

postEvent()​

load()​

xcall()​

doEvent()​

modal()​

performDrag()​

focusable()​

close()​

update()​

activate()​

trayIcon()​

requestAttention()​

addHotKeyHandler()​

removeHotKeyHandler()​

isOnActiveSpace​

class methods and properties:​

this​

all​

share​

screens​

screenBox()​

elementAt()​

ticks()​

post()​

send()​

events​

"statechange"​

"closerequest"​

"resolutionchange"​

"mediachange"​

"activate"​

"replacementstart"​

"replacementend"​

"move"​

"size"​

"trayiconclick"​

"spacechange"​

"system-suspend"​

"system-resume"​

constructor:

properties:

focus

state

frameType

caption

icon

screen

graphicsBackend

minSize, maxSize

blurBehind

isActive

isAlive

isOnActiveSpace

isResizable

isMaximizable

isMinimizable

isTopmost

isEnabled

aspectRatio

eventRoot

focus

parent

document

parameters

methods:

box()

screenBox()

cursorPos()

move()

moveTo()

shape()

selectFile()

selectFolder()

mediaVar()

mediaVars()

addEventHandler()

on()

off()

dispatchEvent()

postEvent()

load()

xcall()

doEvent()

modal()

performDrag()

focusable()

close()

update()

activate()

trayIcon()

requestAttention()

addHotKeyHandler()

removeHotKeyHandler()

isOnActiveSpace

class methods and properties:

this

all

share

screens

screenBox()

elementAt()

ticks()

post()

send()

events

"statechange"

"closerequest"

"resolutionchange"

"mediachange"

"activate"

"replacementstart"

"replacementend"

"move"

"size"

"trayiconclick"

"spacechange"

"system-suspend"

"system-resume"

"system-lock"