HomeTrayBrowser - Settings
- General reference
- From where initial settings are read?
- What is the configuration file format?
- Are initial settings propagated to the additional windows in multi-windowed application?
- How to prevent reading settings from user-accessible directories / limit what user can override?
- How to set initial settings right in the application executable without relying on any configuration files?
- Which parameters are mandatory?
- Important topics
- Application ID and data storage directory
- Limiting settings user can change
- Limiting process execution capabilities
- Automated window positioning
- Fullscreen modes
- Scaling and multiple monitors
- Handling browser errors
- Certificate verification
- Clearing browser storage
- Browser resource usage
- Games and graphical applications
General reference
TrayBrowser provides numerous settings to control how application and its windows behave.
By default a sensible settings set for running your Web application linked to the system tray icon is provided. If that's all you need, they may be left as is, customizing only what is really necessary.
You should start with these defaults to understand what TrayBrowser does by default. Here is the page describing defaults for all the TrayBrowser settings:
For advanced use, like opening additional windows, some settings are altered for additional windows to provide sensible defaults for multi-windowed applications.
For even more advanced use, these settings can be altered per window opened or even altered for opened window in runtime, with some limitations.
The full list of settings is provided on the following page:
There may be some undocumented settings present in the TrayBrowser code, but it's strongly advised against altering these as they can be removed or non-functioning or their behavior may be changed anytime without any notice.
From where initial settings are read?
TrayBrowser reads its initial settings from numerous places. The order of reading settings is as follows:
- Application internal TRAYBROWSER_INI resource embedded in application executable [can be easily altered for Windows platform]
- Application executable directory executable name.ini file (so traybrowser.ini for traybrowser.exe)
- Application executable directory executable name.conf file (so traybrowser.conf for traybrowser.exe)
- Application symlink directory executable name.ini file (so traybrowser.ini for traybrowser.exe)
- Application symlink directory executable name.conf file (so traybrowser.ini for traybrowser.exe)
Next, command line based settings are read if they are allowed to be overridden (NoOverride setting is not * and does not contain commandline):
- If configuration file is specified as the first parameter, it is read.
- If URL starting with http:// or https:// is specified as the first parameter, it is applied as URL setting.
- All extra settings in key=value format specified further on the command line (see Command line parameters for reference) are applied until first parameter not matching key=value format is encountered.
At this point, the ApplicationID and ApplicationUseNativeDataDirectory parameters must be set as further configuration file paths rely on them, so these cannot be overridden anymore
The rest of command line parameters is processed as follows:
- If the first parameter or the one after last of the parameters described above is -- (two dashes), it is skipped.
- If TrayBrowser instance for the ApplicationID / ApplicationUseNativeDataDirectory is not yet running, the rest of command line parameters (up to 100) are made available to the main window via GetCommandLine API call.
- If TrayBrowser instance for the ApplicationID / ApplicationUseNativeDataDirectory is already running, the rest of command line parameters (up to 100) are passed to the running TrayBrowser main window via onCLICommand event.
Then, on Windows platform, the following files are read:
- If ApplicationUseNativeDataDirectory is true:
- User roaming profile Application ID/Application ID.ini file
- User roaming profile Application ID/Application ID.conf file
- User local profile Application Application ID/Application ID.ini file
- User local profile Application Application ID/Application ID.conf file
- If ApplicationUseNativeDataDirectory is false:
- User roaming profile TrayBrowser/Application ID.ini file
- User roaming profile TrayBrowser/Application ID.conf file
- User local profile TrayBrowser/Application ID.ini file
- User local profile TrayBrowser/Application ID.conf file
- /etc/application ID.ini file
- /etc/application ID.conf file
- If ApplicationUseNativeDataDirectory is true:
- User home directory Application ID/Application ID.ini file
- User home directory Application ID/Application ID.conf file
- If ApplicationUseNativeDataDirectory is false:
- User home directory TrayBrowser/Application ID.ini file
- User home directory TrayBrowser/Application ID.conf file
What is the configuration file format?
It is your typical .ini-style format without sections, so plain and simple Name=Value format, with single parameter taking single line.
All comments starting from # or ; characters, section definitions with [ and ] and all unknown parameters are ignored.
Parameter names (so everything before the first = character) are trimmed from leading and trailing spaces and are case-insensitive.
All parameter values (everything after the first = character) are trimmed from leading and trailing spaces. String parameters can be empty strings if allowed.
Boolean parameter values can take multiple different variants of saying true or false (see the full settings description), these are also case-insensitive. Choice parameter values are case-insensitive.
If multiple parameters with the same name appear in the same file, the last one prevails.
Are initial settings propagated to the additional windows in multi-windowed application?
No. While application settings are global, additional windows settings do not inherit main window settings altered. Any additional window settings that need to be altered from defaults must be explicitly set for the CreateWindow API call.
How to prevent reading settings from user-accessible directories / limit what user can override?
There is a mechanism in TrayBrowser to prevent overriding settings on each step of reading settings. It is NoOverride parameter that declares a list of parameters which are fixed for all the next stages. NoOverride parameter is additive, so any further NoOverride setting does not override but instead adds to the parameters to not to override already set in the list.
How to set initial settings right in the application executable without relying on any configuration files?
Read the Branding section to see what you can do for Windows executable and other platforms. Additionally, as described above, you can immediately set NoOverride to value of * to prevent TrayBrowser from reading any configuration files. Configuration files are not even accessed further if NoOverride parameter is set to *.
Which parameters are mandatory?
In general, only URL parameter with your site/application URL needs to be set for TrayBrowser to start displaying your page/application. TrayBrowser will run even without one though, displaying a welcome page.
ApplicationID is quite desirable to be set explicitly as it defines where the browser data is stored (and you cannot run two TrayBrowser instances with the same ApplicationID).
In general, Width and Height are also desirable to be set explicitly even for the very minimalistic use case as the defaults give very small browser window (450x300) to fit even 640x480 or lesser screens.