HomeTrayBrowser - API
- TrayBrowser API
- Methods
- Callbacks
- Events
- Important topics
- Scaling, browser dots and screen pixels
- Main window concept and handling multiple windows
- Window movement and sizing
- Window visibility and termination
- Application visibility, focus, positioning and termination
- Changing window settings and window restarts
- Kiosk modes
- Key-value storage
- Controlling running application from CLI
- Debugging applications
- Debugging TrayBrowser
TrayBrowser API
TrayBrowser provides a small and mostly synchronous API to control browser window(s) created by the application and the application itself.
The API is completely available under global JS traybrowser object when enabled, no other global objects and/or variables are defined nor may be used.
Take note the TrayBrowser API is not available under <iframe> and other embedded HTML objects for safety reasons.
The API includes ways to size and position active window, change window and application settings, get some system parameters, supplementary functions like browser-independent and temporary key-value storage, optional API to execute external processes, etc.
All TrayBrowser API functions are documented on their respective documentation pages. Take a look at API reference page for the full list and links to the corresponding documentation. API usage has additional topics to be discussed, you can find these topics further on this page, under the important topics section.
Detecting TrayBrowser API
Ideally, your TrayBrowser-enabled web-based application will probably be able to work both under both TrayBrowser and normal browser for users who opt to use it in browser instead.
To detect TrayBrowser API presence, first check for presence of global traybrowser object in your JS code. This object becomes available before actual page is loaded and displayed so you can use it in early <head> and other initialization places.
To detect TrayBrowser API validity and version, check presence of and then use traybrowser.GetAPIVersion() method. It will return TrayBrowser version in form of <major>.<minor> so you can immediately adjust to the actual version the API, should this be necessary (see API versioning section below).
If TrayBrowser API is present and version is correctly read and identified, you can assume the application is running under TrayBrowser and use all version-compatible TrayBrowser API calls. Further functional distinction may be done using traybrowser.GetAPIModel(), traybrowser.GetAPIOS() and traybrowser.GetApplicationSettings() methods.
The simplest detection sample you can use (probably with some error/exception handling in case GetAPIVersion() fails:
if ((typeof traybrowser.GetAPIVersion) !== 'undefined') {
trayBrowserAPIVersion = traybrowser.GetAPIVersion();
appInTrayBrowser = true; // we set this late because if GetAPIVersion() fails, this is not TrayBrowser
...
}
}
Using TrayBrowser API
TrayBrowser API is comprised of set of methods available under global traybrowser object. To use the API, just call provided and documented methods inside the object with proper parameters. There are also few constants inside the object defined for some methods, they are documented alongside API methods using them.
Most of TrayBrowser API is synchronous. This means every API method executed will do its job and return only when this job is complete, possibly providing some kind of result in return. This also means your JavaScript code will wait for execution of API method until its complete. For its very simplicity, TrayBrowser API uses no promises or other cumbersome and non-trivial programming elements.
When TrayBrowser API needs to be asynchronous and is related to some user interaction or late response, corresponding API methods provide callback parameter to supply your callback function that will be executed later on by the API into. All callback function signatures (parameter sets) are documented alongside API methods requiring them. See callbacks section below for information on how to pass callback parameters in general.
Of course, some significant application events are bound to happen even without using any API calls. TrayBrowser API provides a way to register asynchronous event handlers for such events that will be called correspondingly. Event handling is asynchronous, so JS code processing these events will not stall the application in general. See events section below for more general information on TrayBrowser event handling.
The simplest example that will first set browser window size and only then show the window:
traybrowser.Show();
API versioning
TrayBrowser API GetAPIVersion() method provides TrayBrowser API version number in form of <major>.<minor> where major and minor are arbitrary positive numbers. I.e. 3.0 for the TrayBrowser 3.0 and further releases until it becomes 3.<something> instead.
There are some assumptions that can be made of this version number:
- API version indicates exactly the API version and so does not follow TrayBrowser application version. I.e. TrayBrowser 3.1 may still report API version of 3.0 because API has not been changed.
- API minor number increases with backwards-compatible API changes, i.e. when there are some new methods or optional method parameters added.
- API versions with same major number are almost guaranteed to retain compatibility with older versions of the same major number, i.e. version 3.1 will be backwards compatible with version 3.0, version 3.3 will be backwards compatible with version 3.0, 3.1, 3.2 and so on.
- API major number change may indicate backwards-incompatible changes. Deprecated API methods and events may be removed, method signatures may change, there may be significant behavioral changes, etc. So version 4.0 and version 3.0 may only be partially compatible in terms of API.
- Minor behavioral changes will just be documented and will usually result in no API version change even if they are bound to affect existing implementations slightly. Major and breaking behavioral changes affecting important application behavior significantly will always result in at least minor version increase.
TrayBrowser 3.0 and further releases retain most of the API compatibility with legacy TrayBrowser 1.0, 1.1 and 2.0 versions, including (mostly) behavioral compatibility. Legacy API is documented on its respective documentation page. Take care legacy API may be dropped anytime though.
Methods
Callbacks
Events
Important topics
Scaling, browser dots and screen pixels
Window positioning and sizing requires specific coordinates to be specified. It would be all easy and pixel precise, if not for the operating system scaling. In modern OS, the screen sizes are scaled by default for smaller and high DPI screens, and also users can set specific scaling in the OS to make everything on screen larger for their needs.
The window screen positioning always operates in pixels. This means windows can be positioned arbitrarily at specific pixel of the screen, disregarding any scaling. When you operate with screen coordinates in desktop application, you always get them in pixels, whatever OS screen scaling is set at.
The browser element sizing operates in dots. Each browser dot is a virtual pixel that normally (when there is no scaling, "100% scaling") corresponds to normal screen pixel. But when scaling is set, browser dots correspond to custom number of screen pixels, not necessary integer. When you operate in browser, getting elements positions, widths and heights, you always get them in dots, not pixels. Browser then takes care of scaling everything that is rendered at dots sizes and positions to the real pixel size according to whatever scaling is set in the OS. A sample: you have page that renders at fixed 800px width in CSS. At 100% scaling, the browser window size needs to be 800 screen pixels (excluding borders) to accomodate that. But at 125% scaling, if set by user in OS, the same page would need 800 * 1.25 = 1000 screen pixels to be fully visible. At 150% scaling this would be 1200 pixels, and at 200% scaling this would be whooping 1600.
Basically, browser dots are "virtual pixels" browser operates in and is what seen by the application inside browser. They are not equal to screen pixels. Screen pixel size would be browser dot size multiplied by the screen scaling coefficient.
This poses certain problems for making desktop application out of browser page. First things first, setting size is done in dots, but window would be sized in pixels. This means actual window size will differ from what was passed to the method setting browser size. This also means reported screen size in pixels will not be equal to the maximum browser window size in dots that can be set. This also means, that when positioning window on screen, you need to take care of real pixel size of the window to not position window offscreen. To make things worse, i.e. Windows allows to set scaling independently for each monitor present in the system. This means that when moving windows between screens, scaling factor will change, and desktop window needs to be resized accordingly to make sure browser document size stays the same.
There is also a certain and serious caveat in Chromium that needs to be accounted for. Chromium aligns its viewport rendering size to integer number of screen pixels. If the resulting pixel size is not integer, the last line of the viewport (rightmost or bottommost) will not be visible. This means that if you set i.e. 1px border around the viewport, and the resulting window size is not integer in pixels, the rightmost and/or bottommost border lines will disappear. I.e. this will happen with 801px to 803px viewport width in case of 125% scaling.
TrayBrowser really takes care of most of that for you automatically, and provides you with numerous methods to handle this difference in dots and pixels easily. Let's elaborate how (the list is not exhaustive, there are some very specific quirks also handled that do not need specific elaboration):
- For sizing windows, SetBrowserSize (and corresponding GetBrowserSize) methods are provided. These operate in browser dots, and you may be sure browser document size will be equal to what you set there. Almost. To take care of the non-integer scaling caveat described above when it happens, TrayBrowser by default will slightly increase viewport size to make every line visible. This behavior can be changed with ScalingMode setting if you i.e. need downsizing instead or really fixed browser document size disregarding the condition of few lines being not visible. onSizeChange event provides final size in both browser dots and pixels so you can accomodate for scaling-induced sizing offset. GetMonitorBrowserSize method giving current monitor size in browser dots is provided to assist with sizing (basically the maximal browser size that can be set).
- For positioning windows, SetPixelPosition and GetPixelPosition are provided operating in real screen pixels. Also GetPixelSize can be used to retrieve browser real pixel size for precise positioning. SetPixelSize is also present for convenience of setting browser size in screen pixels instead of browser dots. GetMonitorPixelSize/GetDesktopSize are provided to get current monitor or the whole desktop size in pixels.
- When window changes monitors, TrayBrowser looks at the set browser size (which is in browser dots) and resizes window accordingly. This may cause some minor viewport size changes (because of the non-integer scaling caveat) and then onSizeChange event will be fired to let the application know.
- By default, TrayBrowser does not allow to position windows between monitors to work around issue of possibly different scaling for the monitors in question. If this is disabled with ClampToMonitor setting, TrayBrowser uses monitor window center resides on to size window and then relies on OS and browser behavior to adjust rendered content scaling - until window goes off to some specific single monitor.
- GetWindowInfo and GetScreenInfo methods provide a multitude of information (including scaling parameters) to assist with complex sizing and positioning, should you need it.
- ScalingMode option has 'noscale' value to completely disable browser scaling. In this case, screen scaling is ignored and browser content is rendered at 100% scale, with browser dots being equal to screen pixels, disregarding any scaling user may have set. This is useful when you can scale rendered content yourself accordingly, for i.e. web-based games and/or fullscreen applications. Some care is required for high-DPI screens in this case, but this is advanced option for those who want to get rid of browser and TrayBrowser internal support for scaling completely and render the content scaled by the application itself as necessary.
The very basics for easy handling of scaling-enabled sizing and positioning without taking excessive care are:
- Use SetBrowserSize to set the browser document size in browser own dots however you need, rely GetMonitorBrowserSize to determine maximum size in browser dots that can be set for the window
- Optionally look for onSizeChanged events and adjust your final document size accordingly as real size set may have small offset from what was passed to SetBrowserSize due to non-integer scaling
- For positioning inside current monitor, use SetPixelPosition. Rely on GetMonitorPixel size to get current monitor desktop size and on GetPixelSize to get the browser size in pixels.
More ways of handling scaling, sizing and positioning can be found in settings and API documentation.