Skip to Content

TrayBrowser API - Base window API

Last modified by Alex/AT on 2026/03/29 10:50

API Information

GetAPIVersion

Parameters Return value On error Sample Result sample
None 
String TrayBrowser API version in strict form of major.minor
 Undefined traybrowser.GetApiVersion(); 3.0

Returns base TrayBrowser API version string in form of "major.minor", i.e. "3.0". Base API version is guaranteed not to change unless there are new API methods implemented or incompatible argument or behavioral changes done to some of API calls. Minor version change means new API methods, new arguments added or small incompatible API / behavioral changes. Major version change means extensive breaking changes are done or API changes significantly.

Please note API version may not follow TrayBrowser version, i.e. future TrayBrowser version 3.1/3.2/3.5 whatever may still carry API of version 3.0 inside. Major future TrayBrowser version changes (i.e. TrayBrowser 4.0) will update API major version alongside even if it stays fully compatible.

GetAPIModel

Parameters Return value On error Sample Result sample
None 
String TrayBrowser API operational model
 Undefined traybrowser.GetApiModel(); cef

Returns operational (behavioral) model of TrayBrowser API implementation. Allows to account for behavioral differences between different TrayBrowser engines, should there be more. Please note that returned value may differ from known values described here, so if using it, implement some sensible defaults for cases the returned API model is unknown to the application.

Known and planned return values

cef Default TrayBrowser 3.0 engine based on Chromium Embedded Framework (CEF) and CEF4Delphi project code
ie Embedded Windows Internet Explorer engine, similar to one TrayBrowser 1.0 had, this engine is not implemented yet but is planned to be reimplemented as small footprint alternative to CEF

Known historical and other return values (not encountered in TrayBrowser 3.0)

electron Default TrayBrowser 2.0 engine based on Electron framework
original Returned by traybrowser.api.js compatibility layer in case TrayBrowser 1.0 is detected (TrayBrowser 1.0 does not have GetAPIModel call)
browser Returned by traybrowser.api.js compatibility layer in case it runs under normal browser and TrayBrowser API is partially emulated

GetAPIOS

Parameters Return value On error Sample Result sample
None 
String Operating system TrayBrowser is running under
 Undefined traybrowser.GetAPIOS(); windows

Returns operating system TrayBrowser is running under. Allows to account for behavioral differences between different operating systems TrayBrowser can run under. Please note that returned value may differ from known values described here, so if using it, implement some sensible defaults for cases the returned OS is unknown to the application.

Known and planned return values

windows Windows flavors
linux Linux flavors
macos Mac OS flavors

Known historical and other return values (not encountered in TrayBrowser 3.0)

native Returned by traybrowser.api.js compatibility layer in case it runs under normal browser and TrayBrowser API is partially emulated

GetAPIBrowser

Parameters Return value On error Sample Result sample
None 
String Embedded browser used by TrayBrowser engine
 Undefined traybrowser.GetAPIBrowser(); chromium

Known and planned return values

chromium Embedded CEF Chromium browser
ie Embedded Windows Internet Explorer browser

Known historical and other return values (not encountered in TrayBrowser 3.0)

native Returned by traybrowser.api.js compatibility layer in case it runs under normal browser and TrayBrowser API is partially emulated

GetVersion

Parameters Return value On error Sample Result sample
None 
String Fully qualified TrayBrowser version
 Undefined traybrowser.GetVersion(); 3.0.0

Returns full TrayBrowser version in arbitrary format and of arbitrary length (can include build-specific information). Suitable for logging and printing only as it is not guaranteed to follow any predictable formatting and may freely change depending on version specifics.

GetCopyright

Parameters Return value On error Sample Result sample
None 
String (HTML) Printable TrayBrowser copyright information string in HTML
 Undefined GetCopyright(); by Alex/AT (<a href="javascript:;" onclick="traybrowser.OpenBrowser(''mailto:alex@alex-at.net'');">alex@alex-at.net</a>), 2025-2026

Returns TrayBrowser own copyright information suitable for displaying in footer / information windows / wherever it belongs. Normally would be exactly as the above sample.

Window commands and information

Show

Parameters Return value On error Sample
None None Undefined traybrowser.Show();

Shows the TrayBrowser window. The window will not automatically get focus on show operation, so user can continue working with other applications when the window is shown. To capture user focus, use Focus API call.

If window is already shown and ShowOnTaskbar option is enabled, but AlwaysOnTop option is disabled, under Windows platform this call will flash the taskbar bar, indicating window wants attention.

If window is minimized (both shown or hidden) and RestoreOnShow option is enabled, this call will automatically restore window state to normal (so un-minimizing the window).

The API is synchronous. This call will return only after window show process has been fully initiated in the operating system.

Hide

Parameters Return value On error Sample
None None Undefined traybrowser.Hide();

Hides the TrayBrowser window unconditionally. Also removes window from taskbar if ShowOnTaskbar option is enabled. If the window is already hidden, does nothing.

The API is synchronous. This call will return only after window hide process has been fully initiated in the operating system.

Focus

Parameters Return value On error Sample
None None Undefined traybrowser.Focus();

Shows TrayBrowser window, brings it to front and captures user focus, switching user interaction to the window.

If window is minimized (both shown or hidden) and RestoreOnShow option is enabled, this call will automatically restore window state to normal (so un-minimizing the window).

If window is a secondary window (so not the main application window) and TrayBrowser application is minimized to tray, this call will automatically show the whole application with all windows to be shown.

The API is synchronous. This call will return only after window(s) show and focus process has been fully initiated in the operating system.

Close

Parameters Return value On error Sample
None None Undefined traybrowser.Close();

Immediately and ungracefully closes / terminates TrayBrowser window, not calling and waiting for OnExit event handlers. Can be used in OnExit event notification handling to confirm the window may finally be closed.

If window is the main application window, effectively closes main window immediately and then terminates the whole application, secondary windows will be terminated gracefully in case OnExit event notification is used in them, immediately otherwise.

Take care that despite API being synchronous, window close / exit happens asynchronously. This call will return after the process has been initiated, but scripts will continue to run until the browser terminates.

Exit

Parameters Return value On error Sample
None None Undefined traybrowser.Exit();

Gracefully closes / terminates TrayBrowser window.

If OnExit event handler is not set for the window, this call is technically equivalent to the Close call. Can also be used in OnExit event notification handling to confirm the window may finally be closed, so make sure second call to Exit can only be done when it is finally possible to close.

If OnExit event handler is set, TrayBrowser sends OnExit notification to the window and then waits until Close / another OnExit call arrives indicating the window may finally be closed or until GracefulExitTime timer expires.

If window is the main application window, effectively terminates the whole application. All windows will be terminated, windows using OnExit notification will be terminated gracefully, waiting for Close / Exit API call or timer expiration.

Take care that despite API being synchronous, window close / exit happens asynchronously. This call will return after the process has been fully initiated, but scripts will continue to run until OnExit event is confirmed by Close / Exit and the browser terminates.

IsVisible

Parameters Return value On error Sample Result sample
None 
Boolean True if window is visible, false otherwise
 Undefined traybrowser.IsVisible(); true

Returns true if the window is visible, false otherwise.

IsInFocus

Parameters Return value On error Sample Result sample
None 
Boolean True if window is visible, false otherwise
 Undefined traybrowser.IsInFocus(); true

Returns true if the window is visible and has user interaction focus, false otherwise.

GetParameters

Parameters Return value On error Sample Result sample
None 
String Window Parameters setting value
 Undefined traybrowser.GetParameters(); some Parameters setting text

Returns text string set in the Parameters setting for the window. Main window gets this from application settings.

SetCaption(text)

Parameters Return value On error Sample
text String (250 characters max) Window caption / title to set
 None Undefined traybrowser.SetCaption('My window caption');

Sets window caption / title to be displayed in the window title bar if OS-based borders are used, taskbar if shown on taskbar and other places operating system displays it.

Window sizing and positioning

GetBrowserSize

Parameters Return value On error Sample Result sample
None 
Object 

Browser window width and height in browser dots

width Integer Width in browser dots
height Integer Height in browser dots
 Undefined traybrowser.GetBrowserSize(); { width: 1024, height: 768 }

Returns object containing width and height properties for browser window width and height in browser dots. Normally equivalent to the browser document width and height.

Take care this is window size as felt by browser and JS code, but may be not a real on-screen browser size as user may have scaling enabled for the monitor. Refer to the Scaling, browser dots and screen pixels topic for details on the matter.

Take care this size is exactly browser viewport size and does not include any window borders.

SetBrowserSize(browserWidth, browserHeight)

SetBrowserSize(sizeObject)

Parameters Return value On error Sample Result sample
browserWidth Integer New browser viewport width in browser dots
browserHeight Integer New browser viewport height in browser dots
 
 
sizeObject Object 

Alternative variant of setting width and height via passing them as one of following objects

width Integer New browser viewport width in browser dots
height Integer New browser viewport height in browser dots
w Integer New browser viewport width in browser dots
h Integer New browser viewport height in browser dots
 true on success false or undefined 

traybrowser.SetBrowserSize(1024,768);

traybrowser.SetBrowserSize({ width: 1024, height: 768 });

traybrowser.SetBrowserSize({ w: 1024, h: 768 });

 true

Sets new window size to accomodate browser viewport with provided browserWidth and browserHeight parameters for width and height correspondingly.

Returns false is supplied parameters are invalid, true otherwise.

Take care real window size may differ as user may have scaling enabled for the monitor, and as window may have borders.

Take care window will normally snap to active monitor size, and thus final window width and height may be different from what is provided.

Take care that even if i.e. window has no borders and monitor can accomodate actual window size, final window width and height may be slightly offset from what is provided to accomodate for integer browser scaling. Refer to Scaling, browser dots and screen pixels topic and ScalingMode / ScaleAlignmentMax parameters for details on the matter.

Thus, rely on OnSizeChange event and real document width/height reported by browser to resize application elements accordingly, on GetBrowserSize call and other API calls to determine final actual window sizing if necessary.

The API is synchronous. This call will return only after new window size has been set, aligned and confirmed by the operating system, so i.e. GetBrowserSize call is guaranteed to return the new size properly after this call returns. User-visible on-screen resizing and browser elements resizing process may happen asynchronously.

GetPixelSize

Parameters Return value On error Sample Result sample
None 
Object 

Browser window width and height in screen pixels

width Integer Width in real screen pixels
height Integer Height in real screen pixels
 Undefined traybrowser.GetPixelSize(); { width: 1024, height: 768 }

Functionally equivalent to GetBrowserSize, this call returns object containing width and height properties for browser working area width and height, but in real screen pixels, not subject to any screen scaling set by the user.

Take care this size does not have completely defined relation to the browser document size as screen scaling may be in effect. Refer to Scaling, browser dots and screen pixels topic and ScalingMode / ScaleAlignmentMax parameters for details on the matter.

Take care this size is exactly browser window working area size and so does not include any window borders.

SetPixelSize(pixelWidth, pixelHeight)

SetPixelSize(sizeObject)

Parameters Return value On error Sample Result sample
pixelWidth Integer New browser viewport width in real screen pixels
pixelHeight Integer New browser viewport height in real screen pixels
 
 
sizeObject Object 

Alternative variant of setting width and height via passing them as one of following objects

width Integer New browser viewport width in real screen pixels
height Integer New browser viewport height in real screen pixels
w Integer New browser viewport width in real screen pixels
h Integer New browser viewport height in real screen pixels
 true on success false or undefined 

traybrowser.SetPixelSize(1024,768);

traybrowser.SetPixelSize({ width: 1024, height: 768 });

traybrowser.SetPixelSize({ w: 1024, h: 768 });

 true

Sets new window size to accomodate browser viewport in real screen pixels with provided pixelWidth and pixelHeight parameters for width and height correspondingly.

Returns false is supplied parameters are invalid, true otherwise.

Take care real window size may differ as window may have borders.

Take care window will normally snap to active monitor size, and thus final window width and height may be different from what is provided.

Take care browser viewport size will be set according to the screen scaling set by user. While real window size will try its best to conform, browser document size will be affected by scaling. Refer to Scaling, browser dots and screen pixels topic and ScalingMode / ScaleAlignmentMax parameters for details on the matter.

Take care that even if i.e. window has no borders and monitor can accomodate actual window size, final window width and height may be slightly offset from what is provided to accomodate for integer scaling result. Refer to Scaling, browser dots and screen pixels topic and ScalingMode / ScaleAlignmentMax parameters for details on the matter.

Thus, rely on OnSizeChange event and real document width/height reported by browser to resize application elements accordingly, on GetBrowserSize call and other API calls to determine final actual window sizing if necessary.

The API is synchronous. This call will return only after new window size has been set, aligned and confirmed by the operating system, so i.e. GetBrowserSize call is guaranteed to return the new size properly after this call returns. User-visible on-screen resizing and browser elements resizing process may happen asynchronously.

GetPixelPosition

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetPixelPosition();  

SetPixelPosition(pixelLeft, pixelTop)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.SetPixelPosition(100, 100);  

GetScaledPosition

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetScaledPosition();  

SetScaledPosition(browserLeft, browserTop)

Parameters Return value On error Sample Result sample
browserLeft Integer Position of the window left side in browser dots on the current monitor
browserTop Integer Position of the window top side in browser dots on the current monitor
 None Undefined traybrowser.SetScaledPosition(100, 100);  

GetDesktopPosition

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetDesktopPosition();  

SetDesktopPosition(pixelLeft, pixelTop)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the whole desktop space available
pixelTop Integer Position of the window top side in screen pixels on the whole desktop space available
 None Undefined traybrowser.SetDesktopPosition(3940, 100);  

GetSavedPosition(id)

Parameters Return value On error Sample Result sample
 
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.GetSavedPosition('');  

SetSavedPosition(id, position)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.SetSavedPosition('', { left: 100, top: 100 });  

WasPositionRestored

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.WasPositionRestored();  

Window and screen information

GetMonitorBrowserSize

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetMonitorBrowserSize();  

GetMonitorPixelSize

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetMonitorPixelSize();  

GetDesktopSize

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetDesktopSize();  

GetWindowInfo

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetWindowInfo();  

GetScreenInfo

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetScreenInfo();  

GetColorScheme

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetColorScheme();  

Window state

Minimize

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.Minimize();  

Maximize

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.Maximize();  

Restore

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.Restore();  

GetWindowState

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.GetWindowState();  

Custom drag region

SetCustomDragRegion(browserLeft, browserTop, browserWidth, browserHeight)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.SetCustomDragRegion(16, 16, 608, 112)  

Browser commands

Start

Parameters Return value On error Sample Result sample
None None Undefined traybrowser.Start();  

Navigate(url)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.Navigate('https://mydomain.tld/page/');  

RestartBrowser(url)

Parameters Return value On error Sample Result sample
pixelLeft Integer Position of the window left side in screen pixels on the current monitor
pixelTop Integer Position of the window top side in screen pixels on the current monitor
 None Undefined traybrowser.RestartBrowser('https://mydomain.tld/page/');