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.
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, how
the browser window has to look like, etc.
Here is the information we will need:
- MenuBox software license key, if available. We'll assume
that it is 12345-12345-12345-12345. If you did not register the
software, simply ignore the line with the license key (don't use
this sample key, as it will not work).
- 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
browser window 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:
[Publisher]
License = "12345-12345-12345-12345"
[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 = NoBrowserWindow
[BrowserWindow]
Title = "My Project"
Icon = "MyProject.ico"
Width = 540
Height = 400
URL = "MyProject.html"
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 browser 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 browser 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" fptype="menubox"
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
browser 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 Browser Window Mode and MenuBox Extended
DOM reference sections of the MenuBox documentation for
additional information.
Also see:
- 3-186 - Tutorial: Using MenuBox
on AutoRun CDs and DVDs
- 3-187 - Scrollbars in MenuBox
Browser Container
- 3-188 - AutoRun and Full Screen
MenuBox Browser Container
