 |
arameter Descriptions
Each of the parameters for the Ultimate Button Bar applet tag is described in detail in this
section. You may click the arrow bullet to the left of a parameter name to jump to the
complete list of parameter.
 |
UBBdefnFile
The UBBdefnFile parameter identifies the button bar
definition file to load
(a button bar definition is a collection of tags that defines the button bar to be created).
The Ultimate Button Bar will always look for a UBBdefnFile parameter before looking
for a UBBdefn parameter. This means
that if you have both parameters specified, the UBBdefn parameter will be ignored.
If you specify only a file name (i.e., without including a file path) for
the UBBdefnFile parameter, then the applet will look for the button bar
definition file in the same directory that contains the Ultimate Button Bar Java code
(i.e., the directory that contains the "UBB.jar" file).
If a file path is specified, then the path root is the directory that contains the Java code.
For instance, suppose your site is laid out as follows:
|
The Ultimate Button Bar Java code is in the directory called
"Java," and the button bar definition file (named "MyButtonBar.txt")
is in the directory called "Definitions." Given this layout,
the applet tag would look something like:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar"
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBdefnFile"
VALUE="Definitions/MyButtonBar.txt">
</APPLET>
|
If the UBBdefnFile parameter is used, then the tag delimiters will default to
<, >, and " (see the
UBBdelimiters parameter for more
information).
If the UBBdefnFile parameter is not specified, and if the
UBBdefn parameter
is not specified, then the applet will create an empty <AREA>. If a color is specified
for the UBBappletBg parameter,
then the <AREA> will use this color for its background; otherwise the <AREA>
background will default to white.
|
|
|
UBBdefn
The UBBdefn parameter is used to enter button bar
definition tags that
define the button bar to be created.
The Ultimate Button Bar will always look for a
UBBdefnFile parameter before looking
for a UBBdefn parameter. This means
that if you have both parameters specified, the UBBdefn parameter will be ignored.
Here is an example of an applet tag that uses the UBBdefn parameter:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar"
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBdefn" VALUE="
[area]
[state all image=^UBB07.jpg^
textJustify=center textAlign=middle-1
fontStyle=bold fontColor=ffffff
fontSize=14]
[state out effects=^filter(color=x)
adjust(brightness=90)^]
[state down fontColor=ffff00
effects=^adjust(brightness=105)
tint(color=ffff00, percent=6)^]
[bar hSpace=5]
[button name=Home text=^Home^]
[/button]
[button name=Software text=^Software^]
[/button]
[button name=Mail text=^Mail^]
[/button]
[button name=Links text=^Links^]
[/button]
[/bar]
[/area]
">
</APPLET>
|
There are a couple of important points to note about placing the button bar definition in the HTML
using the UBBdefn parameter.
- Delimiters - Unless you specify otherwise using the
UBBdelimiters applet parameter,
the Ultimate Button Bar uses the delimiters [, ], and ^
to interpret the button bar definition.
- Line Breaks and Tabs - Some browsers may strip line break and tab characters out of applet
parameters. To prevent attributes from being run together (i.e., concatenated) when this occurs,
make sure that you place
at least one space character at the end of a line that ends with an attribute.
Don't forget to include the characters to close the UBBdefn applet parameter tag
(i.e, the characters "> ) -- it's easy to overlook them!
See the final [/area] tag in the example above to see how they should be specified.
If the UBBdefn parameter is not specified, and if the
UBBdefnFile parameter
is not specified, then the applet will create an empty <AREA>. If a color is specified
for the UBBappletBg parameter,
then the <AREA> will use this color for its background; otherwise the <AREA>
background will default to white.
|
|
|
UBBdelimiters
Delimiters are the characters used by the Ultimate Button Bar to identify where a tag or string
begins and ends.
When you use the
UBBdefnFile parameter,
the Ultimate Button Bar defaults to using the character
< to signify the start of a tag, the character > to signify the end of a tag,
and the character " to signify the start and end of a string. Here's an example:
|
<button name="Button1" text="Button One">
|
When you use the
UBBdefn parameter,
the Ultimate Button Bar defaults to using the character
[ to signify the start of a tag, the character ] to signify the end of a tag,
and the character ^ to signify the start and end of a string. Here's an example:
|
[button name=^Button1^ text=^Button One^]
|
The UBBdelimiters parameter allows you to use other characters as delimiters instead
of the default characters.
To specify delimiter characters, you place the three characters in the following order:
the start of tag character, the end of tag character, and the quotation mark character. For instance,
if you would like to use the { character as the start of tag character, the
} character as the end of tag character, and the % character as the
quotation mark character, then the UBBdelimiters parameter would be specified as:
|
<PARAM NAME="UBBdelimiters" VALUE="{}%">
|
and here's what a tag would look like using these delimiters:
|
{button name=%Button1% text=%Button One%}
|
Be sure that the characters you choose for
delimiters do not appear in the definition text.
The use of the letter "a" as a delimiter, for
instance, would not be a particularly good idea.
|
|
|
UBBtickTime
The UBBtickTime parameter defines the base clock rate or "frame delay" time for
animation in the applet. The higher (longer) the UBBtickTime value, the slower animation.
A low (short) UBBtickTime value will result in faster animation.
The value for the UBBtickTime parameter is expressed in milliseconds (1,000 milliseconds
equals one second). For instance, if you specified a value of 500 for UBBtickTime, then
each frame of animation will be displayed for 500 milliseconds (or ½ second). A UBBtickTime
setting of 500 milliseconds is equivalent to a frame rate of two frames per second.
Besides controlling the animation speed using the UBBtickTime parameter, you can
also control the animation speed by using the
<BUTTON> tag's
ticks attribute. Each "tick" has a duration equal to the delay
established by the UBBtickTime parameter. By specifying a value greater than one
for a ticks attribute, you can effectively slow down the
animation speed. Note that you cannot use the ticks attribute to increase the rate of animation
faster than the speed set by the UBBtickTime parameter, so the UBBtickTime parameter
should be set to the fastest frame rate that any animation in the button bar will use.
Optionally, the animation speed can also be changed by overriding the UBBtickTime using the
<ACTION> tag's
ticks attribute. Using this method, you can change the animation base clock rate for
the applet when a specific button event occurs (such as when the mouse enters a button or is
clicked in a button). This method of changing the animation speed affects all frames of
all animations in the applet since there is only one animation timer used for all animations.
If the UBBtickTime parameter is not specified, then the base tick time rate will
default to 100 milliseconds (equivalent to ten frames per second).
The fastest UBBtickTime that can be assigned is 33 milliseconds
(which is approximately equal to thirty frames per second).
|
|
|
UBBappletBg
The UBBappletBg parameter specifies the background color of the Ultimate Button Bar
applet area. Normally, the applet background is never seen because it is completely covered by the
button bar. There may, however, be brief moments when the applet background is visible.
Some occasions when the applet background might be visible could be when the applet is initializing,
when the applet is repainted, when the page is scrolled, or when the applet is resized.
The UBBappletBg parameter can be used to specify an applet background color to
minimize any potential distraction that might occur should one of the aforementioned events
cause the applet background to become briefly visible.
The color value for the UBBappletBg parameter can be expressed as either a hexadecimal value,
or as a decimal RGB value. For example, the color yellow in hexadecimal format would be specified as:
|
<PARAM NAME="UBBappletBg" VALUE="ffff00">
|
Note that when using hexadecimal values, you do not need to precede the value with a
# character as you do for HTML color values.
In decimal RGB format, the color yellow would be specified as:
|
<PARAM NAME="UBBappletBg" VALUE="255-255-0">
|
If this parameter is not specified, then the applet background color will
default to white.
|
|
|
UBBoption
The UBBoption parameter allows certain applet characteristics to be changed
during the time that you are developing button bar definitions.
It's conceivable that one or more options might be useful in a "live"
production environment, but generally speaking this parameter is most useful while you are designing your
button bar(s).
The valid values for this parameter are:
|
"1"
|
Disable caching -
Some browsers use an internal cache when reading network files.
Once the file is read into the cache, the browser might read the file from the cache instead of from the
network if the page is refreshed. While this is normally desirable, it might not be if you are making changes
to the file during the design process.
If you are using the
UBBdefnFile parameter, and if the
browser does not seem to be reading the most current version of the file, try using this option.
|
|
"2"
|
Re-initialize on start -
Normally when the Ultimate Button Bar applet is stopped (for instance
when you move off of a page that contains the applet), the applet goes into a suspended state. In this state,
all of the button images are saved so that the applet will initialize quickly if the page is viewed again.
Sometimes, especially during button bar design and development, this is not desirable.
By specifying option 2, the applet will dispose of all memory and resources that it has allocated.
This forces the applet to reconstruct the button bar from scratch the next time that the applet is displayed.
Obviously using this option this will slow down the applet initialization process,
but it is very useful while you are designing your button bar and in some special circumstances.
|
|
"4"
|
Log warnings -
The Ultimate Button Bar can log two types of messages to the
Java Log: error messages and warning messages.
Error messages are logged when the applet detects a condition that will prevent the button bar from
displaying, or a condition that will cause the button bar to display improperly.
Error messages are always logged.
Warning messages indicate that there might be a problem with a button bar definition. The button
bar will usually display, but perhaps not as you expect. Warning messages are logged only if the log
warnings option ("4") is specified.
|
|
"8"
|
Dump Definition on Tag Format Error -
If the Ultimate Button Bar detects an error in the tag structure of
a button bar definition (e.g., a closing tag is missing, or all tags are not enclosed within a single
<AREA> tag), then the applet will normally log a simple error message to the
Java Log.
If UBBoption 8 is specified, then in addition to logging the error message, the applet will
also write the complete button bar definition to the Java Log. This can be useful when debugging
as it saves you the trouble of locating and opening the button bar definition file or HTML page.
Also, if for some reason the button bar definition was corrupted during the read (e.g., due to
illegal characters in the definition or due to a network error), then viewing the button bar
definition that was actually read by the applet can be very helpful in determining what went wrong.
|
|
"develop"
|
Develop mode -
Specifying "develop" for the UBBoption value will enable
options "1," "2," "4," and "8" (see above).
When you are developing your button bar, it is recommended that you specify this option. Here is an
example of the applet tag with the "develop" option specified:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar"
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
</APPLET>
|
Once your button bar is finished, you can delete this parameter from the HTML.
|
Note that should you wish to combine any of the above options, you can do so by adding the option numbers
together. For instance an option of "3" is equivalent to option "1"
and option "2."
|
|
|
UBBjsInit
The UBBjsInit parameter defines the JavaScript function to call after the Ultimate Button Bar
applet has been initialized.
The applet is initialized by the browser when it is first loaded, and is initialized each time that
it is started if the UBBoption
parameter has been assigned a value of "develop" or "2".
The UBBjsInit parameter is useful if you want an action to take place once the applet
has been completely loaded and is ready for display. For instance, you might want to use
Dynamic HTML to make the applet invisible on the page until it is ready to be displayed so that
a blank area does not appear on the page during applet initialization.
If you specify a JavaScript function for the UBBjsInit parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBjsInit"
VALUE="appletInit()">
</APPLET>
|
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
|
UBBjsStart
The UBBjsStart parameter defines the JavaScript function to call when the Ultimate Button Bar
applet is started by the browser.
The applet generally is started by the browser when the page that contains the applet is loaded.
In addition, the browser might
stop and start the applet if the page is refreshed, or if the browser is restored after being
minimized. The events that cause an applet to be started will vary with each browser.
If the UBBjsInit parameter is
specified in addition to the UBBjsStart parameter, then the JavaScript function specified by
the UBBjsInit parameter will be called when the applet is initialized and started, and
the UBBjsStart parameter will be called when the applet is started (only). In other words,
when the applet initializes, only the UBBjsInit JavaScript function will be called (the
UBBjsStart will not be called).
The UBBjsStart parameter is useful if you want an action to take place each time that the
applet starts. For instance, you might to play an audio file whenever the applet is started.
If you specify a JavaScript function for the UBBjsStart parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBjsStart"
VALUE="appletStart()">
</APPLET>
|
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
|
UBBjsStop
The UBBjsStop parameter defines the JavaScript function to call when the Ultimate Button Bar
applet is stopped by the browser.
The applet generally is stopped by the browser when another page is loaded over the
page that contains the applet. In addition, the browser might
stop and start the applet if the page is refreshed, or if the browser is minimized.
The events that cause an applet to be stopped will vary with each browser.
The UBBjsStop parameter is useful if you want an action to take place each time that the
applet is stopped. For instance, you might to play an audio file whenever the applet stops.
If you specify a JavaScript function for the UBBjsStop parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBjsStop"
VALUE="appletStop()">
</APPLET>
|
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
|
UBBjsEnter
The UBBjsEnter parameter defines the JavaScript function to call when the mouse enters the
Ultimate Button Bar applet.
The UBBjsEnter parameter is useful if you want an action to take place each time that the
mouse moves into the applet area. For instance, you might to play an audio file or dynamically change
the web page whenever the mouse is moved over the applet.
If you specify a JavaScript function for the UBBjsEnter parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBjsEnter"
VALUE="enterApplet()">
</APPLET>
|
Note that the JavaScript function executed when the mouse enters the applet can be changed
while the applet is running by using the
jsEnter action.
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
|
UBBjsExit
The UBBjsExit parameter defines the JavaScript function to call when the mouse exits the
Ultimate Button Bar applet.
The UBBjsExit parameter is useful if you want an action to take place each time that the
mouse moves out of the applet area. For instance, you might to play an audio file or dynamically change
the web page whenever the mouse is moved out of the applet.
If you specify a JavaScript function for the UBBjsExit parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBjsExit"
VALUE="exitApplet()">
</APPLET>
|
Note that the JavaScript function executed when the mouse exits the applet can be changed
while the applet is running by using the
jsExit action.
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
|
UBBinitErr
The UBBinitErr parameter allows you to specify a web page to load
if the button bar cannot be created due to an error during applet initialization, or a
JavaScript function to call if an error occurs during initialization.
The UBBinitErr parameter is useful to help prevent unexpected conditions from
causing an empty "hole" to appear on your page if the applet cannot be run.
To cause a web page to be loaded in the event of an error condition, the file name of the
page to load, or a complete URL to load, may be specified as the parameter value. You may
optionally also specify a target for the page.
The format of the parameter value is identical to the format of the value for the
load attribute of the <ACTION> tag. See the documentation for the
load action for information
regarding how to specify a web page.
An example of an applet that loads another page over itself if an error occurs is:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar"
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBinitErr"
VALUE="AltPage.html@_self">
</APPLET>
|
In the above example, the page "AltPage.html" will replace the page that contains the
applet if an error occurs during applet initialization.
As mentioned, it is possible to call a JavaScript function if an error occurs during initialization
instead of loading a web page (of course the JavaScript function could load a web page, if desired).
Note that unlike the applet's other JavaScript parameters, the value for the UBBinitErr parameter
defines only a name for a function: the parameter does
not allow the specification of parameters to pass to the JavaScript
function. This is because the JavaScript function must have a fixed format.
The function specified for the UBBinitErr parameter must have a single string
variable specified for its parameter list. For example:
<SCRIPT LANGUAGE="JavaScript">
function functionName(message) {
alert(message);
}
<SCRIPT>
<APPLET CODE="UBBApplet.class" ... >
...
<PARAM NAME="UBBinitErr" VALUE="functionName">
</APPLET>
|
where functionName can be any valid JavaScript function name.
When the UBBinitErr JavaScript function is called (i.e., if an error occurs during initialization),
a string with a description of the error will be passed to the function. This allow you to examine
the error message in the JavaScript function (if desired) and take the appropriate action.
If you specify a JavaScript function name for the UBBinitErr parameter, then you
must specify the MAYSCRIPT attribute in the applet tag. For example:
<APPLET CODE="UBBApplet.class"
ARCHIVE="UBB.jar" MAYSCRIPT
WIDTH="415" HEIGHT="30">
<PARAM NAME="UBBoption"
VALUE="develop">
<PARAM NAME="UBBdefnFile"
VALUE="MyButtonBar.txt">
<PARAM NAME="UBBinitErr"
VALUE="errorFunction">
</APPLET>
|
For more information on using JavaScript with the Ultimate Button Bar, please see the
Working with JavaScript documentation.
|
|
