Overview
This tutorial will guide you through the configuration of the MenuBox settings, including special tips to take advantage of MenuBox features from within your HTML code.
This tutorial is similar to the "Example 1" set of files which is distributed with MenuBox.
MenuBox Wizard
You can use the MenuBox Wizard application to create HTML (browser container) projects without ever having to edit the resulting HTML or INI files. In this case, you don't need to read this document.
However, you can also use the MenuBox Wizard to create a project skeleton, and then manually edit the resulting output. In this case, the following text will show you what files you need to edit, and some types of changes you can make. At the end of your modifications, if you are using the registered version of MenuBox, remember to use the Sign Project tool to insert the updated Signature key (which marks the project as registered, and protects it from changes).
Distribution Files
If you installed MenuBox in the default location on an English version of Windows, you should have a set of redistributable files in "C:/Program Files/Cloanto/MenuBox/Redistributable".
You will need two files: MenuBox.exe and menubox.js.
In this tutorial we will assume that the first page of your HTML project is named "MyProject.html", and that you have a Windows icon file named MyProject.ico. The use of this icon file is entirely optional. If you don't have an icon file, simply do not use the lines referencing it.
We will also assume that you are creating a CD AutoRun project, and that you created a MyProject directory at the root of the CD, where you will place your files.
MenuBox.exe
MenuBox.exe is the application which your users, or your AutoRun code, will open. You can place this file anywhere you wish, and even rename it, if so desired. For this tutorial, we shall copy the MenuBox.exe file to the MyProject directory.
Autorun.inf
Since we are creating an AutoRun CD, we need to reference the MenuBox.exe file, so that Windows will know where to open it from. This is done by placing a file named autorun.inf at the root of the CD. The data we will place in this file is read by Windows, and is ignored by other operating systems.
If you are not creating an AutoRun CD you can skip this section.
Open the autorun.inf file with Notepad, and enter the following lines:
[AutoRun]
Open=MyProject\MenuBox.exe
Icon=MyProject\MyProject.ico
Make sure that the lines don't contain any space characters.
If you don't have an icon you can omit the line referencing it. You can also use two different icon files, one for the CD icon, and one for the MenuBox window title bar.
Configuring MenuBox.ini
When MenuBox.exe starts, it tries to open a configuration file named MenuBox.ini (if you rename MenuBox.exe to MyLauncher.exe it will automatically open MyLauncher.ini instead). The documentation explains additional options, such as the use of different files for different user locales (languages).
Create a new file named MenuBox.ini, and place it in the MyProject directory. You can edit the file with Notepad.
We need to configure MenuBox.ini with a minimum of information, so that MenuBox.exe will know what HTML file it has to open, what the container window has to look like, etc.
Here is the information we will need:
- The desired size of the MenuBox browser container window. When MenuBox opens, your HTML content will be rendered in a region having this size. We will assume that the desired size is 540 by 400 pixels.
- A name and optional icon to be displayed in the window title bar.
- The name of the file we want to open.
We will also add an [ApplicationCheck] section to the file, to make sure that the system we are running on supports the MenuBox HTML window browser container and that JavaScript is enabled, before opening the HTML page. In practice, all systems except for the very first versions of Windows 95 and Windows NT 4.0 support the MenuBox browser. Even these systems will support MenuBox as long as they have at least Internet Explorer 3 installed. Scripting in local (non-internet) HTML files is used by Windows itself (for HTML Help, etc.), and can only be disabled by editing the Windows registry.
The resulting MenuBox.ini file will look like this:
[Project]
Signature = "12,34,56,78,9A,BC,DE,F0,12,34,56,78,9A"
[ApplicationCheck]
MenuBoxBrowser = Basic, Scripting
MessageFail = "Your system does not appear to support HTML browser containers, or scripting has been disabled for the \"My Computer\" security zone. If you are running Windows 95 or Windows NT 4.0 please install Internet Explorer 3 or higher before retrying."
ProceedFailure = NoHTMLWindow
[HTMLWindow]
Title = "My Project"
Icon = "MyProject.ico"
Width = 540
Height = 400
DisableNavigationSound = True
URL = "MyProject.html"
The Signature key is inserted or updated automatically by the Sign Project tool, if you are using a registered version of the software.
The MenuBox documentation includes information about several addition options, which give you control over details such as scroll bars, full screen mode, borderless mode, always on top mode, kiosk mode, etc.
Using the MenuBox Browser Extended Document Object Model
At this point, we are inside the MyProject.html file. If you are happy with standard HTML functionality, as is provided by Internet Explorer, we can terminate the tutorial here.
If you need to do things like opening a document (not inside the MenuBox window, but with a Windows application), run a Windows executable or close the MenuBox window, you may take advantage of some extra features provided by the MenuBox extended document object model.
We will briefly cover the use of two MenuBox methods: Execute() and Close(), which are used to respectively open documents and executables, and to close the MenuBox window. The MenuBox documentation covers additional methods and properties.
The functionality provided by the MenuBox browser extended document object model requires Windows 98 or higher, or any version of Windows with Internet Explorer 4.0 (released in September 1997) or higher to be installed, which does not need to be the default browser. Because we want our HTML pages to be usable even on older systems, we will invoke the MenuBox methods via corresponding JavaScript functions, rather than directly. The JavaScript code checks if the extensions are available, and, if not, provides fallback functionality. An added advantage of using the JavaScript code is that the pages can be viewed and tested even in Internet Explorer and in other browsers.
The MenuBox JavaScript code is included in the menubox.js file. You can copy this file to the MyProject directory, and reference it by means of a SCRIPT element inside the HEAD element of MyProject.html. For example:
<head>
<title>My Project - Title>
<script language="JavaScript" type="text/javascript" src="menubox.js"></script>
</head>
If you wish to also be compatible with old Windows 95 and Windows NT 4.0 systems with only the functionality level of Internet Explorer before version 3.02, you should copy the JavaScript code inside the HEAD element of MyProject.html, rather than reference the external file (early versions of IE3 did not properly support external JavaScript files).
<head>
<title>My Project</title>
<script language="JavaScript" type="text/javascript">
<!--
/* paste content of menubox.js instead of this line */
// -->
</script>
</head>
At this point, you can start using the new functionality.
If you would like to close MenuBox when when the user clicks on an "Exit" link:
<a href="javascript:menubox_close()">Exit</a>
If instead you need to run a Project.exe program (also stored in the same directory):
<a href="javascript:menubox_execute('Project.exe')">Run Project</a>
The same menubox_execute() method can also be used to open documents with their default application, rather than in the MenuBox window. Please refer to the MenuBox documentation for full details, including additional function arguments.
When MyProject.html is opened in Internet Explorer (or Opera, or Mozilla, etc.), instead of MenuBox, the JavaScript code will map the Close() and Execute() requests to standard HTML functionality, resulting in traditional browser dialog windows being displayed before the functionality is provided.
Similarly, if you would like to play an audio file you can use PlaySound():
<a href="javascript:menubox_playsound('sound/click.wav');">Play Sound File</a>
Please refer to the HTML Window Mode and MenuBox Extended DOM reference sections of the MenuBox documentation for additional information.
Related Links
