Guide to Customizing and Distributing Mozilla 1.4.1

Previous      Contents      Next

Chapter 11   Manually Customizing the CD Autorun Screen

The CD autorun screen automatically appears when a user inserts a customized Mozilla CD into a CD-ROM drive. The standard CD autorun screen lets your users easily install Mozilla or read installation instructions before they begin installation. You can customize some aspects of this screen, such as the title bar text and background, using the CCK tool.

If you're planning to distribute a Mozilla installer on a CD, you might want to make more customizations to the standard CD autorun screen than the CCK tool can implement. This chapter describes the manual customizations to the CD autorun screen that you can make, if you wish, to the installation files generated by the CCK tool.

This chapter contains these sections:

Why Manually Customize the Standard CD Autorun Screen?
Run The CCK Tool First
About the CD Autorun Files
Tools for Customizing the Standard Autorun Screen
Creating a CD Staging Area on Your Hard Disk
Understanding the rshell.ini File
Editing the rshell.ini File
Verifying Your CD Autorun Screen Manual Customizations

Why Manually Customize the Standard CD Autorun Screen?

---

Chapter 8 "Preparing to Customize the CD Autorun Screen" describes the following customizations that you can make to the standard CD autorun screen using the CCK tool:

• Customize the CD autorun screen's background bitmap image.


• Provide your own title bar text and text below the title bar.


• Customize the contents of the installation guide text file.

You can manually customize the standard CD autorun screen if you want to:

• Create additional screens that inform users about your products, services, and promotions.


• Include additional files or software on the CD. You can add new screens and buttons to the CD autorun screen that give users easy access to the directories on the CD that contain these files, so that users don't have to browse through the directories on the CD to find them. You can also include a button in the CD autorun screen that opens a readme.txt file, so users have easy access to information about these additional files. (For information about adding up to two additional installers with the CCK tool, see Chapter 9 "Preparing to Create the Installer."


• Installers for additional applications on the CD. You can add buttons and text to the standard CD autorun screen that inform users about these applications and make them convenient to install.

Run The CCK Tool First

---

Before manually customizing the standard CD autorun screen, use the CCK tool to create a Mozilla installer that includes the CD autorun screen. Make sure you select the checkbox labeled "Include CD autorun screen" on the Gathering Information screen. Checking this box causes CCK to include the files associated with the CD autorun screen when it creates your customized Mozilla installer. After the CCK tool builds the installer, verify that the CD autorun customizations are correct.

About the CD Autorun Files

---

The CD autorun screen is a standard Windows executable program that automatically launches when users insert the CD in a CD-ROM drive.

When you create your customized Mozilla installer, the CCK tool places the CD Autorun files in this location:

installation_directory\CCKTool\Configs\my_config\Output

When you are finished editing the CD autorun screen files, you use the contents of the Output directory to create your CD layout.

These files and directories are associated with the CD autorun screen:

• The Nsetup32.exe program (the Autorun program) and the rshell.ini file are both located in the directory Output\Shell\Nsetup32\. The rshell.ini file contains all of the custom settings and flags that control the appearance and function of the CD autorun screen.


• setup.exe, launch.ini, and autorun.inf are located in the Output directory, which is the root of the CD layout. They control the automatic launch of the Autorun program and the CD autorun screen. The launch.ini file points to the location of the Nsetup32.exe autorun program and its associated file, rshell.ini. If the Autorun screen doesn't automatically launch, users can double-click the setup.exe file.

In addition to controlling the appearance of the CD autorun screen, the rshell.ini file also links any number of CD autorun screens together using buttons. The buttons can also point to any installers or files included on your CD that you want users to be able to access.

For more information about preparing your CD layout, see Chapter 14 "Distributing Your Installers."

Tools for Customizing the Standard Autorun Screen

---

To customize the standard autorun screen or add new screens, you'll need:

• Aa standard text editor for editing the rshell.ini file.


• A graphics editing program, for creating any custom bitmap images that you want to include as background or button images in the Autorun screens.

You can include one or more directories inside the shell directory to store the custom bitmap images used by the autorun screens. Depending on the CD layout you want to create, you can also include directories for additional items such as applications that you want users to be able to install by clicking buttons in the CD autorun screen.

Creating a CD Staging Area on Your Hard Disk

---

Before you start editing the rshell.ini file, you'll need to determine the directory structure on the CD so that you know how to specify the pathnames of files that you want to be accessible through the Autorun screens. You do this by creating a staging area on your hard disk that exactly represents the final CD layout you intend to use.

To create a CD staging area:

1. Create a directory called Staging on your hard disk.


2. Locate the Output directory you created using the CCK tool.


3. Copy the contents of the Output directory into the Staging directory.


4. Inside the Staging directory, create a directory for each additional component that you want to include on the CD.

Inside the Staging\Shell directory, you'll find a directory called bmps in which you'll store the custom background bitmap images for any new CD autorun screens you create.

Understanding the rshell.ini File

---

Note: The rshell.ini file does not support the usage of double-byte character sets such as those used in the Chinese, Japanese, and Korean languages.

To understand the structure of the rshell.ini file, use a standard text editor such as NotePad to open Shell\Nsetup32\rshell.ini, and examine the descriptions contained in the file.

The rshell.ini file consists of two sections:

• The [General] section is where you specify the attributes of the control buttons (Browse CD, Back, and Exit) that appear at the bottom of the Autorun screens.


• The [Dialog] sections specify the attributes and behavior of each Autorun screen. Each [Dialog] section defines one Autorun screen, and you name the [Dialog] sections sequentially as [Dialog1], [Dialog2], [Dialog3], and so on, one for each Autorun screen.

General Settings in the rshell.ini File

This section describes the general settings in the rshell.ini file that apply to all dialogs.

Text for Browse, Back, and Exit Buttons

browse_button_text=text

back_button_text=text

exit_button_text=text

Specify the text displayed for the Browse, Back and Exit buttons. The Browse and Exit buttons appear on all dialogs. The Back button only appears if the rshell.ini file specifies more than one dialog.

Use an & (ampersand) in front of the character you want to assign as the keyboard shortcut for this button. For example, browse_button_text=Browse &CD sets C as the keyboard shortcut for this button.

Default Values
 

browse_button_text=Browse &CD

back_button_text=Back

exit_ button_text=Exit

Positions of Browse, Back, and Exit Buttons

browse_button_pos= x1,y1,x2,y2

back_button_pos= x1,y1,x2,y2

exit_button_pos= x1,y1,x2,y2

Specifies the position of the Browse, Back, and Exit buttons, relative to the top left corner (0,0) of the dialog. If not specified, button position is based on dialog size.

Values
 

x1,y1: The upper left coordinates of the button, in pixels, relative to the top left corner of the dialog.

x2,y2: The lower right coordinates of the button, in pixels, relative to the top left corner of the dialog. These coordinates are ignored if button bitmap files are specified using the browse_button_bitmaps, back_button_bitmaps, or exit_button_bitmaps setting.

Bitmaps for the Browse, Back, and Exit Buttons

browse_button_bitmaps=up.bmp,dn.bmp,sel.bmp,dis.bmp

back_button_bitmaps=up.bmp,dn.bmp,sel.bmp,dis.bmp

exit_button_bitmaps=up.bmp,dn.bmp,sel.bmp,dis.bmp

Specifies the button bitmaps used for the Browse, Back, and Exit buttons. Four bitmaps specify the four possible states of the button: up, down, selected, disabled. This setting is optional. If you don't specify bitmaps for a button, the dialog uses a standard Windows button with the text specified in browse_button_text, back_button_text, or exit_button_text.

Values
 

up.bmp: Specifies the bitmap associated with the up (unpressed) button state.

dn.bmp: Specifies the bitmap associated with the down (pressed) button state.

sel.bmp (optional): Specifies the bitmap associated with the selected (mouse-over) button state.

dis.bmp (optional): Specifies the bitmap associated with the disabled button state.

Dialog Settings

This section describes the global settings that apply within a dialog.

Caption Text

caption=caption text

Specifies the text that appears in the dialog's title bar.

Dialog Position

dialog_position=x1,y1,x2,y2

Specifies the position of the dialog on the monitor screen. If not specified, the dialog is displayed at the center of the monitor screen. If bk_bitmap is specified, x2,y2 is ignored.

Values
 

x1,y1: Specifies the coordinates, in pixels, relative to the top left corner (0,0) of the dialog.

x2,y2: Specifies the coordinates, in pixels, of the lower-right corner of the dialog.

Background Bitmap

bk_bitmap=background.bmp

Specifies the background bitmap file used for the dialog. If a background bitmap file is not specified, the dialog uses the system background color for its background color.

Button Gap

button_gap=y

Specifies the vertical gap (y), in pixels, between the buttons in the dialog.

Global Text Settings

This section describes the settings used for the title text in a dialog. You use these settings to include a line or paragraph of text that can appear anywhere within the dialog.

Dialog Title Text

dialog_title_text=text

Specifies the title text for the dialog.

Dialog Title Position

dialog_title_pos=x1,y1,x2,y2

Specifies the position in pixels, relative to the top left corner of the dialog, of the title text.

Values
 

x1,y1: Specifies the position of the top left corner of the text.

x2,y2: Specifies the position of the bottom right corner of the text.

Dialog Title Text Color

dialog_title_text_color=red,green,blue

dialog_title_shadow_color=red,green,blue

dialog_title_shadow_depth=red,green,blue

Specifies the text color, shadow color, and shadow depth of the dialog title text. You specify a number between 0 (black) and 255 (white) for each of the red, green, and blue values to get the overall pixel color.

Table 1 lists commonly-used colors from the standard Windows palette.

Table 11-1    Windows palette colors

Color	Red,Green,Blue values
Black	0,0,0
White	255,255,255
Red	255,0,0
Green	0,255,0
Blue	0,0,255
Yellow	255,255,0
Magenta	255,0,255
Cyan	0,255,255
Dark red	128,0,0
Dark green	0,128,0
Dark blue	0,0,128
Dark cyan	0,128,128
Dark gray	128,128,128
Dark magenta	128,0,128
Gray	192,192,192

Dialog Title Text Font

dialog_title_text_font=font,size

Specifies the font and font size used for the dialog's title text. It's best to use a standard font that you know will be available on end users' machines. If not specified, the system font and font size are used.

Dialog Title Text Style

dialog_title_font_bold=TRUE/FALSE

dialog_title_font_underline=TRUE/FALSE

dialog_title_font_italic=TRUE/FALSE

If set to TRUE, specifies the font style (bold, italic, underline) used for the dialog's title text. If not specified or if set to FALSE, the style is not applied.

Global Button Text Settings

This section describes the text settings used for all button text in a dialog.

Text Colors

text_color_default=red,green,blue

text_color_highlight=red,green,blue

Specifies the default text color and the mouse-over (highlight) text color of all button text in a dialog. You specify a number between 0 (black) and 255 (white) for each of the red, green, and blue values to get the overall pixel color. The text automatically changes to the mouse-over (highlight) text color when you position the mouse over a button in the dialog.

Table 11-1 lists commonly used colors from the standard Windows palette.

Button Title and Body Text

button_title_text_font=font,size

body_text_font=font,size

Specifies the font and size used for the dialog's button title text and button body text. It's best to use a standard font that you know will be available on end users' machines. If not specified, the system font and font size are used.

Button Title Font

button_title_font_bold=TRUE/FALSE

button_title_font_italic=TRUE/FALSE

button_title_font_underline=TRUE/FALSE

If set to TRUE, specifies the font style (bold, italic, underline) used for the dialog's button title text. If not specified or if set to FALSE, the style is not applied.

Button Body Text Style

body_text_font_bold=TRUE/FALSE

body_text_font_italic=TRUE/FALSE

body_text_font_underline=TRUE/FALSE

Specifies the font style (bold, italic, underline) used for the dialog's button body text. If not specified or set to FALSE, the style is not applied.

Column Settings Within a Dialog

This section describes the settings used for columns within a dialog. Each dialog can have one or more columns. The settings for the first (left-most) column all begin with col1; the settings for the second column all begin with col2, etc. If you only want one column of buttons in a dialog, delete all of the col2 and greater settings, or you can leave them blank.

Position of First Button in Column One

col1_button_pos=x,y

Specifies the position of the first button in column 1 of a dialog. You specify the x,y coordinates of the upper-left corner of the button, relative to the upper-left corner of the dialog (0,0). If you want, you can specify an offset position for an individual button using the button1_offset setting described later in this chapter.

Position of a Button's Descriptive Text

col1_text_offset=offset

col1_text_posx=x

You can use either of these settings to specify the position of the button's descriptive text. Use col1_text_offset if you want to specify the text's position by defining an offset between the button and the button text. Use col1_text_posx instead if you want to specify the absolute x position of the button's descriptive text.

If unspecified, the default is col1_text_offset=10. If both settings are specified, col1_text_offset is ignored and the absolute x position as specified in col1_text_posx is used.

Column Text Width

col1_text_width=x

Specifies the distance x, relative to the left edge of the dialog box, at which the button descriptive text wordwraps to the next line. If this setting is not specified, the text wordwraps when it is 10 pixels to the left of the right edge of the dialog.

Button Settings Within a Dialog

This section describes the settings used for buttons within a dialog. Each dialog can have one or more buttons. The settings for the first button all begin with button1, the settings for the second button all begin with button2, and so on. If you only want one button in a dialog, delete all of the button2 and greater settings, or leave them blank.

Button Bitmaps

button1_bitmaps= up.bmp,dn.bmp,sel.bmp,dis.bmp

Specifies the button bitmaps used for button1. Four bitmaps specify the four possible states of the button: up, down, selected, disabled. This setting is optional. If you don't specify bitmaps for a button, the dialog uses a standard Windows button with the text specified in button1_text_title.

Values
 

up.bmp: Specifies the bitmap associated with the up (unpressed) button state.

dn.bmp: Specifies the bitmap associated with the down (pressed) button state.

sel.bmp (optional): Specifies the bitmap associated with the selected (mouse-over) button state.

dis.bmp (optional): Specifies the bitmap associated with the disabled button state.

Button Action

button1_cmdline=action,target

Specifies the action you want to assign to the button. Clicking a button can cause one of seven possible actions, depending on the value you specify for the action argument. The possible button actions and arguments are:

• Launch a program (action=exe)



button1_cmdline=exe,path to executable file

Example: button1_cmdline=exe,..\..\Mozilla\setup.exe
 

• Go to a different dialog screen (action=window)



button1_cmdline=window,dialog#

Example: button1_cmdline=window,dialog2
 

• Open a file (action=open)



button1_cmdline=open, path to file

The file opens with whatever program the operating system has associated with the file's type. If a file type association doesn't exist, Windows asks the user to choose a program.
 

Example: button1_cmdline=open,..\..\install.txt
 

• Print a file (action=print)



button1_cmdline=print, path to file

The file is printed with whatever program the operating system has associated with the file's type. If a file type association doesn't exist, Windows asks the user to choose a program.
 

Note: You cannot print HTML files through Windows.
 

Example: button1_cmdline=print,..\..\install.txt
 

• Explore a directory on the CD (action=explore)



button1_cmdline=explore,directorypath

Opens the specified directory on the CD. The directory path must be specified as an absolute path from the root of the CD.
 

Example: button1_cmdline=explore,extras\clipart opens the extras\clipart directory, which is at the root level of the CD.
 

• Open a file in the Mozilla Browser (action=mozilla)



button1_cmdline=mozilla, path to file

Opens the specified file using the currently-installed version of the Mozilla Browser. The file type can be .html, .gif, .jpeg, or any other file type that the browser can open, such as .pdf (if the correct plug-in is already installed).
 

Example: button1_cmdline=mozilla,myfile.html
 

• Create a shortcut on the desktop (action=desktop)



button1_cmdline=desktop, file or directory name, shortcut name, path to icon file

When button1 is clicked, a shortcut is created on the desktop, using the specified shortcut name and icon file, that opens the specified file or directory on the CD. File or directory paths must be specified as absolute paths from the root of the CD.
 

Example: button1_cmdline=desktop,readme.txt,Read Me,\shell\icons\readme.ico
 

Button Text
 

button1_text_title=text

button1_text_body=text

Specifies the button title text and body text for button1.
 

Button Offset

button1_offset=x,y

Specifies the button's horizontal (x) and vertical (y) offset, in pixels, from the location specified in the col1_button_pos setting. If there is more than one button in column 1, and you only specify an offset for button1, the other buttons in the same column will use the same vertical (y) offset. You can change the offsets for the other buttons by specifying individual button offsets for each of them.

Editing the rshell.ini File

---

To edit the rshell.ini file:

1. Locate the Staging\Shell\nsetup32\rshell.ini file and open it using a standard text editor. Familiarize yourself with the settings in the rshell.ini file.


2. Decide how many dialog screens you want to use. If you need more dialog screens than are defined in the rshell.ini file, copy an entire [Dialogx] section (where x is a unique number associated with each dialog) and paste it as needed into the file. Each dialog screen must have a unique number. If you need fewer than are provided by default, remove entire [Dialogx] sections as necessary.


3. Design the layout, background images, buttons, and text for each dialog screen. Make the necessary customizations in the settings in the rshell.ini file.



Note: Rather than entering the text for a screen in the rshell.ini file, you may prefer to create your text as part of the background image using an image editing program such as Adobe Photoshop. Using an image editing program gives you more control over the appearance of the text, including fonts and colors.
 

4. Assign an action to each button in each dialog screen.


5. Save your changes to the rshell.ini file in place; do not move the file.

Adding a New Screen

The supplied rshell.ini file includes a second dialog, Dialog2, that is not visible by default. To enable it, locate the button3 settings that are commented out with semicolons (located within the section in the rshell.ini file called "Buttons 2 - 6 for Dialog 1"). Remove the semicolons in front of all the button3 settings, save your changes, and then launch the Autorun screen by double-clicking the file Shell\nsetup32\Nsetup32.exe file. Click the third button in the first screen (labeled Bonus Applications and Plug-ins) and you'll be able to see the second dialog.

To add a new Autorun screen:

1. Locate the file Staging\Shell\nsetup32\rshell.ini file and open it using a text editor.


2. Copy an entire [Dialogx] section and paste it into the rshell.ini file at the location where you want the new screen to appear.


3. Increment the value of x in the [Dialogx] identifier, so that the [Dialogx] section has a unique number. Each [Dialogx] section must have a unique number associated with it, such as[Dialogx], [Dialogx], [Dialogx].


4. Make the necessary customizations to each [Dialogx] section.


5. Save your changes to the rshell.ini file in place; do not move the file.

Adding A Background Image to a Dialog Screen

If you don't specify a background image for a new screen, the new screen uses the system background color. To add a background image to a new screen, follow these steps:

1. Using a graphic editing program, create a background bitmap that's 640 x 480 pixels, and save it as a .BMP format file in the shell\bmps\ directory.



Keep the following in mind:
 

• Keep your bitmap file sizes as small as possible by reducing the number of colors the images use or by removing (flattening) the layers if you created the images in Adobe Photoshop. If your images are too large, you may not be able to see them in the Autorun screen. If you cannot see a background image when you test the Autorun screen, open the image in a paint program and try reducing the number of colors to reduce the image's file size.
• To prevent palette-swapping when switching between Autorun screens, be sure to use a 256-color palette in each background image you create.
• Be sure to leave room at the bottom of the background bitmap (about 40 pixels in height, preferably black) for placement of the control buttons (Browse CD, Back, and Exit) specified in the rshell.ini file.

For example, here is an illustration of the background bitmap image used to create the standard Autorun screen. Note that a black area 40 pixels high was created at the bottom of the image, to allow placement of the control buttons.



 

2. Open the rshell.ini file using a text editor.


3. Locate the dialog section that you want to customize.


4. To the right of the bk_bitmap= setting, enter the path to the bitmap file, relative to the location of the shell directory. For example:



bk_bitmap=..\bmp\myinstall.bmp

5. Save your changes to the rshell.ini file in place; do not move the file.

Customizing a Screen's Title Bar Text

The title bar appears at the top of every autorun dialog screen. You may want to include your company's name in the title bar or provide other identifying information. For example, this screen shows customized text in a CD autorun screen's title bar:

To customize a screen's title bar:

1. Open the rshell.ini file using a text editor.


2. Locate the [Dialogx] section that you want to customize.


3. To the right of the caption= setting, enter the text that you want to appear in the screen's title bar.



For example, the text "MyISP" results in the title "Mozilla by MyISP"
 

caption=MyIsp

4. Save your changes to the rshell.ini file in place; do not move the file.

Adding a New Button to a Screen

You can add a button to an autorun screen that performs any of these functions:

• Launch an executable (.exe) program.



For example, if you want to include an installer for another application on the CD, you can add a button that users can click to launch the installer.
 

• Go to another screen



For example, if you're creating multiple CD autorun screens, you can add a button that users can click to go to a particular screen. (This is in addition to the standard Browse, Back, and Exit buttons that appear on each autorun screen.)
 

• Open a file



For example, you can add a button that opens a readme.txt file so that users can read installation instructions for another application you're providing on the CD.
 

• Print a text file



For example, you can add a button that prints the installation instructions.
 

• Explore a directory



For example, if you're including a directory of utilities on the CD, you can add a button that opens that directory so that user can view its contents.
 

• Open a file in the Mozilla Browser



For example, if you've provided an HTML or GIF format file on the CD that you want users to view in Navigator, you can add a button that opens the file using an already-installed version of Navigator.
 

• Create a shortcut on the user's desktop



For example, if there's a directory on the CD that you want users to have easy access to, you can create a desktop shortcut for that directory.
 

To add a new button to an Autorun dialog screen:

1. Open the rshell.ini file using a text editor.


2. Locate the dialog section where you want to add a new button.


3. Within the dialog section, locate the section where the buttons for the dialog are defined. Each button group begins with



button1_bitmaps=
 

4. Decide how many buttons you want to appear in the dialog.


5. If you need more buttons than are defined by default in the rshell.ini file, copy and paste new button groups and increment the button number for each new group you add.


6. To remove buttons, delete the button groups that are above the number you need, or simply leave their settings blank.


7. Assign an action to each button using the buttonx_cmdline= setting. You can define any one of seven different button actions. See the description of the buttonx_cmdline= setting earlier in this chapter, or by referring to the comments in the rshell.ini file.



For example, to have button1 go to the dialog2 screen, you would enter:
 

button1_cmdline=window,dialog2

For example, to have button1 launch a program named Setup.exe, you would enter:
 

button1_cmdline=exe,..\..\Mozilla\Setup.exe

8. When you have finished defining buttons and button actions, save your changes to the rshell.ini file.

Verifying Your CD Autorun Screen Manual Customizations

---

After you finish editing the rshell.ini file, you should view your custom Autorun screens so you can verify your customizations. Follow these steps:

1. Locate this directory:



intallation_directory\CCKTool\Configs\my_config\Output\Shell\

2. To test the CD autorun screens, launch the first screen by double-clicking the file \Shell\Nsetup32\Nsetup32.exe.


3. Verify the appearance of your CD autorun screen and test the action of each button.

Previous      Contents      Next     

---

Copyright © 2003 Netscape Communications Corp. All rights reserved.

Last Updated October 05, 2001