Configuration File Options

Overview

The configuration file options of MenuBox include and extend the functionality provided by the command line options. A single INI file (named "menubox.ini" by default) is usually sufficient to cover most needs, including windowless mode, simple window mode, browser window mode, conditional code, application setup and fallback options. Multiple files are used to support language-localized configurations, and can also be employed for more complex conditional branches and/or to create multiple levels of text menus (just like multiple levels of HTML menus can be created using different HTML pages).

Localization (Internationalization)

Multiple INI files, each having a name ending with "-xx.ini" (where "xx" is a two-letter language code as per ISO 639-1), can be placed in the same directory as the default INI file ("menubox.ini", i.e. the same base name as the MenuBox executable file, unless a different name is specified using the /m command line option). When MenuBox starts, it first checks to see if a configuration file with a name matching the current system language exists (e.g. "menubox-en.ini" for English, "menubox-de.ini" for German, "menubox-es.ini" for Spanish, "menubox-fr.ini" for French, "menubox-it.ini" for Italian, etc.), and then, if no match is found, it opens the file with no "-xx" language code (e.g. "menubox.ini").

There should always be a fallback file with no language code (e.g. use "menubox.ini", and not "menubox-en.ini", for English, if you want MenuBox to use the English language configuration in case no other configuration file matches the user's language). There is no need to use language-coded files if only one language is supported (e.g. use "menubox.ini", and not "menubox-en.ini", for English, if English is the only language which is supported by your project).

If the MenuBox executable file is renamed, for example from "menubox.exe" to "autorun.exe", "setup.exe", etc., then the default base name of the .ini file (if not set explicitly with the /m command line option) automatically changes accordingly: "autorun-xx.ini"/"autorun.ini", "setup-xx.ini"/"setup.ini", etc.

INI File Structure
A MenuBox INI file is an 8-bit text file (ISO 8859-1 character set) divided into sections, each containing one or more keys. Each key contains one or more values. The file can be created and modified with a simple editor like Notepad or WordPad (Save as type: Text Document).

Example:

[SectionName]
keyname=value
;comment
keyname=value, value, value ;comment
Section names are enclosed in square brackets, and must begin at the beginning of a line. Section and key names are case-insensitive, and cannot contain spacing characters. The key name is followed by an equal sign ("=", decimal code 61), optionally surrounded by spacing characters, which are ignored.

Multiple values for a key are separated by a comma followed by at least one spacing character.

Numerical values may be entered in decimal, hexadecimal (digits prefixed by "0x") or octal format (digits prefixed by a "0" character). In Boolean keys "True" and "False", and "Yes" and "No" are equivalent to 1 and 0.

When the MenuBox parser encounters an unrecognized section name, the entire section (with all its keys) is skipped. Within a known section, only unrecognized keys are skipped.

Both Space (decimal code 32) and Horizontal Tab (HT, decimal code 9) are acceptable spacing characters.

Lines are terminated by a CR (decimal code 13) and/or LF (decimal code 10) character.

Comments are introduced by a semicolon character (";", decimal code 59). Comments must begin at the beginning of a line or after a spacing character. Comments terminate at the end of the line.

The Cloanto web site contains additional technical information about the INI file format as it is used in MenuBox.

Overview of Sections
In the following documentation of the MenuBox configuration file, section descriptions are grouped into four parts.

Shared settings (used with all three operation modes):

[Publisher] (one per file)
[ApplicationCheck] (multiple sections allowed)
Windowless mode:

[Windowless] (one per file)

Simple window mode:

[SimpleWindow] (one per file)
[LinkArea] (one per file)
[LinkFont] (one per file)
[DescriptionArea] (one per file)
[DescriptionFont] (one per file)
[Link] (multiple sections allowed)

Browser window mode:

[BrowserWindow] (one per file)
[Publisher]

This section contains the keys used to enter the software license information and to optionally assign a unique ID to each MenuBox project.

Keys:
License = String

This key is supported for legacy purposes only. Its functionality has been superseded by the Signature key.

Signature = String

If you are using a registered version of MenuBox you can sign your projects to enable full functionality and disable the "Free Version" message which is otherwise displayed when MenuBox starts and exits. Click here to register the software now.

The Signature key contains licensing information combined with a checksum of the INI file content itself. This key cannot be added or edited manually. It is inserted automatically by the MenuBox wizard, and can also be inserted or updated manually by using the Sign Project tool.

If the INI file is modified, but the signature is not updated, MenuBox will work as if it were not registered ("Free Version" message).

UniqueID = String

MenuBox normally opens a new window each time it is invoked, even if it is executed with reference to the same MenuBox executable and configuration file. This may result in multiple identical windows being opened at the same time, for example when the same a href="02-08_autorun.html">AutoRun-enabled medium is repeatedly inserted and ejected. which may or may not be desirable. If you use the UniqueID key to assign a unique identifier (e.g. a sequence number, a product-unique string, etc.) to a configuration file, then multiple instances of the same MenuBox executable which refer to a configuration file with the same UniqueID will cause the first MenuBox window to be brought to the front, instead of new windows being opened.

The Signature key and the UniqueID key are combined so that each publisher is guaranteed to have an independent range of unique identifiers. UniqueID is ignored if no Signature key is indicated (which is always the case for unregistered versions of the software).

For additional per-publisher nonvolatile storage options, see the GetNV and SetNV methods of the MenuBox Extended DOM.

For example:

[Publisher]
Signature = "12,34,56,78,9A,BC,DE,F0,12,34,56,78,9A"
UniqueID = "MyProduct - Version 1.0"
Please note that the Signature key shown above is for example purposes only. You can enter a UniqueID key, and let the Sign Project tool add the Signature key at a later stage, when you are finished editing.

[ApplicationCheck]
This section not only controls the conditional execution of code (e.g. to install a viewer or to display an error message), but also determines which of the windowless, simple window or browser window sections should be switched off (ignored) based on certain conditions. An optional confirmation or information message can be displayed to the user before the conditional launch of an executable, or before exiting MenuBox, in case no other fallback option (e.g. a text menu) is available.

The existence of an application can be verified searching by document extension (e.g. ".html") or looking for the globally unique identifier (GUID) or the programmatic identifier (ProgID) of a program or COM object. Once an application has been found based on these criteria, it can additionally be checked to be at least a given version and/or to match a known file name. The Architecture key can be used to invoke different code on x86 and x64 systems.

This section can execute code (e.g. launch the setup procedure of a document viewer) if a certain condition (e.g. the presence of a viewer for a certain document type) is not met. It can optionally check again to see if the condition is met after the conditional code has been executed. Based on these results, it is possible to disable one or more of the [Windowless], [SimpleWindow] and [BrowserWindow] sections in the same INI file. When two or more of these sections are active (because they have not been disabled by conditional code in [ApplicationCheck]), they are processed in the following order:

[Windowless] -> [SimpleWindow] -> [BrowserWindow]

Multiple [ApplicationCheck] sections may appear in the same configuration file. A [Windowless], [SimpleWindow] or [BrowserWindow] section only needs to be disabled by a single [ApplicationCheck] section in order to be permanently disabled (sections are disabled using an OR rule, not following an AND logic of [ApplicationCheck] success/failure results).

»