Paths & Current Directory

After MenuBox has been launched from its own executable file ("menubox.exe", which may be renamed, if so desired) it needs to access one or more additional files (e.g. configuration files, documents to be displayed and executable files to be launched). Documents opened by MenuBox may in turn also contain links to other files. The following sections explain how to make sure that all files and other links references directly or indirectly by MenuBox will work flawlessly in a variety of configurations.

Relative vs. Absolute Paths

Paths would not be necessary if all files were located in the same directory, and if that directory were the current directory. When directories (or different drives, or computers, locally or on a network) are used to group content, paths indicate how to find files located in different locations. MenuBox supports different types of path formats in its command line and configuration file options, including:

Relative paths

e.g. "Directory\File", "Directory\Directory2\File", etc.

Absolute paths

e.g. "DriveLetter:\Directory\File, "DriveLetter:\Directory\Directory2\File", etc.

Paths containing environment variables

e.g. "%temp%\Directory\File, "%temp%\Directory\Directory2\File", etc.

UNC paths

e.g. "\\Server\ShareOrDrive\Directory\File", "\\Server\ShareOrDrive\Directory\Directory2File", etc.

Internet absolute paths

e.g. "http://Server/Directory/File", "ftp://Server/Directory/Directory2/File", etc.

Internet relative paths

e.g. "Directory/File", "Directory/Directory2/File", etc.
Paths within HTML scripts

e.g. "javascript:menubox_execute('Directory\\setup.exe')"

Absolute paths always begin with an absolute reference to a drive, device or server. While absolute paths may be useful when pointing to documents on the internet, we recommend to only use relative paths when referencing files on removable media such as CDs and DVDs. As different computer configurations use different drive letters (e.g. "D:\", "E:\", etc. for CD/DVD drives), absolute paths which include drive letters are guaranteed to fail as soon as the medium containing the application is used on a computer where the letters are assigned differently than on the test machine.

Relative paths are relative to the current directory, and may begin with one or more optional ".." parts, each meaning "up one level". For example, if MenuBox is running from inside the "AutoRun\Software" directory on a CD, and you need to reference an HTML file named "index.html" located in "Docs\HTML", you would reference that file as "..\..\Docs\HTML\index.html".

Keep in mind that space characters are not allowed within paths referenced in "autorun.inf".

A few rare and usually older applications do not support relative paths in their command line arguments. If you need to use such a program, for example a specific document viewer, either place the viewer and the document in the same directory as the configuration file ("menubox.ini"), or use the /d and/or /a command line options or the corresponding Directory and AbsolutePath configuration file keys to set the appropriate current directory and/or let MenuBox convert the relative path to an absolute path.

When using MenuBox to open Microsoft Office documents (e.g. PowerPoint, Excel, Access, etc.) which in turn link to other files which are also distributed with the linking document, be sure to enable the "Use relative path for hyperlink" option in the Office software before saving the document. For maximum compatibility with various document viewers it is recommended that you group all such linked files in a single directory, and that you set that directory to be the current directory with the appropriate MenuBox option (see below). You don't need to worry about this if the document is self-contained and does not contain references to other files.

If in doubt, remember to test all links of your final project, and then test again from a different drive (i.e. one where your project will be mounted under a different drive letter), preferably on a different computer (to also make sure that the links are not referencing some file which only exists on the hard disk where the project was created, e.g. you don't want to test a CD-ROM master on drives "D:\" and "E:\", only to later find out that the links were working only because they contained absolute references to something on your own "C:\" hard disk partition).

Within an HTML scripting environment, remember to use the applicable escape sequences for any special characters which may be contained in the File argument (e.g. "\" should become "\\").

MenuBox automatically expands environment variables (e.g. "%name%") in paths to the full absolute path before further processing. This occurs at all levels (command line parameters, configuration file options, Windowless mode, and Extended DOM functionality). This allows a MenuBox application to locate and reference, for example, an installed application.

For maximum compatibility across different versions of Windows, and in consideration of the fact that paths stored in environment variables do not consistently end with or without a backslash character, multiple consecutive backslash characters that may be present in the final (expanded) path are automatically converted to a single backslash character.

Relative paths and files referenced directly (without path), are always relative to the current directory. The following cases may apply depending on the application.

• The default current directory for command line mode is inherited from the context in which the MenuBox executable file is launched. For AutoRun applications this is the root of the medium. The /d command line option can be used to explicitly set the current directory.
• As soon as a configuration file (e.g. "menubox.ini") has been opened, the directory containing that file becomes the current directory. All files referenced from a configuration file are relative to this directory (unless a different directory is explicitly set via the Directory key).
• Once an HTML file has been opened, all relative links inside the HTML document are relative to the location of the HTML file containing the link, regardless of the current directory (this behavior is implemented by web browsers, based on HTML specifications).
• Relative links contained in types of documents other than HTML (e.g. PowerPoint) are usually relative to the current directory, so care should be taken to set the appropriate directory to be the current directory (using the /d command line option or the Directory key of the configuration file) if necessary when opening such a document.
• If the MenuBox Execute() method is used from inside an HTML document (browser window mode), that always operates relative to the directory containing the first HTML file (i.e. the file referenced by the URL key of the [BrowserWindow] section). This is because the MenuBox document object model is initialized when this first file is opened, and it does not reflect the directory of subsequent HTML files which may be opened during the browser session.

The default location of the configuration file, if not explicitly set using the /m command line option, is the directory containing the MenuBox executable file. This means that in most cases, as far as configuration files are concerned, the current directory will be the directory containing the MenuBox executable file (e.g. "menubox.exe").

If you understand how the current directory works, and if you group files properly with respect to each other in your distribution, you normally won't need to explicitly set or change directories. If however your needs are slightly more demanding, remember that the Directory and AbsolutePath keys, as well as the equivalent command line options, were designed to help you cover even the most exotic path and compatibility issues.