Toolbar Applet documentation

Toolbar Applet documentation v. 1.0
Copyright SCAND LLC 2001

JTOOLBAR applet is useful component to create toolbars in internet/intranet application with flexible settings and rich functionality. One toolbar can contain different control elements at one time:

And more, you can specify more than one different toolbars for one applet and switch between there from JavaScript functions, depending on content. All events from toolbar elements can be processing in JavaScript with the help of notifications mechanism.

Initialization of the applet

Toolbar applet can load content in two modes:

initialize it from PARAM tags, present in HTML that contain the applet
insert items directly from HTML with help of applet's public methods

In both cases it is possible to manage items of the toolbar applet using public methods of it. This can be done as from another Java applet that uses Toolbar applet, so from browser using JavaScript. The public methods are described below.

Applet attributes

JTOOLBAR applet supports the next set of attributes:

BUTTONSTYLE

Style of applet. It can have two values: WINDOWS (default) or IE according to desired style.

BGCOLOR

Background color for the toolbar in HTML format.

Elements definition

To populate toolbar with buttons and choices you should specify parameters for each toolbar object in next format:

<param name="<object_name><number>" value="<object_attributes>">

where:

<object_name> is one of the next values:

toolbar - for Toolbar object inserting,
button - for TBButton object inserting,
separator - for TBSeparator object inserting, value of parameter is ignored,
choice - for TBChoice object inserting,
choiceitem - for choice element.
edit - for TBEdit element

<number> indicates the sequential number of an item in initialization list, starts from zero. All objects should be numbered sequentially.

<object_attributes> - item-depended properties of object in <name>='<value>' format.

Tags for choices, menubars and menus should have closing tag param with empty value.

Example 1. Toolbar with one button, one edit field and choice.

Events processing

For processing of events from menu you can specify the next names of script functions:

Parameter name	Source	Event
ON_LOAD	jtoolbar applet (no arguments)	All data have been loaded into the toolbar and you can call any applet's method.
ON_CLICK	TBButton element	Any button in menu is pressed (or push button changed it state)
ON_CHANGE	TBChoice element	Choice element changes selected item.
ON_FOCUS_GAINED	TBEdit element	Edit element gained input focus.
ON_FOCUS_LOST	TBEdit element	Edit element lost input focus.
ON_ENTER	TBEdit element	Enter key was pressed in edit box.

All functions (exclude ON_LOAD) receive single parameter - instance of event source object.

jtoolbar applet's methods

addToolbar

 public Toolbar addToolbar(String id)

Inserts new toolbar with identifier id into applet.

showToolbar

 public void showToolbar(String id)

Shows toolbar with specified id.

Toolbar's elements properties and methods

All elemets of toolbar have unique identifier, specified at initialization time and will not be changed later. For getting of it method getId() presents in all elements of toolbar.

Toolbar element

Declaration:

Toolbar element has only one property - unique identifier of toolbar. Bellow you can see example with declaration of empty toolbar:

Example 2. Declaration of empty toolbar

<param name=toolbar0 value="id='my_toolbar'"> <param name=toolbar1 value="">

Methods:

addButton

 public TBButton addButton(String id,
                           int width,
                           int height,
                           String strImage,
                           boolean isEnabled,
                           String status_msg,
                           String tooltip)

Appends toolbar with new button

Parameters:: id - the identifier for new item; width/height - - size of button; strImage - - name of image for button; isEnabled - - enabled flag; status_msg - - status message; tooltip - - hint message for button
Returns:: instance of new TBButton object

addPushButton

 public TBButton addPushButton(String id,
                               int width,
                               int height,
                               String strImage,
                               boolean isPushed,
                               boolean isEnabled,
                               String status_msg,
                               String tooltip)

Apends toolbar with new push button

Parameters:: id - the identifier for new item; width/height - - size of button; strImage - - name of image for button; isPushed - - pushed flag; isEnabled - - enabled flag; status_msg - - status message; tooltip - - hint message for button
Returns:: instance of new TBButton object

addChoice

 public TBChoice addChoice(String id,
                         String status_msg)

Apends toolbar with new choice element

Parameters:: id - the identifier for new item; status_msg - - status message
Returns:: instance of new TBChoice object

addEdit

 public TBEdit addChoice(String id, String label, String text [, int size])

Apends toolbar with new choice element

Parameters:: id - the identifier for new item; label - label for edit element; text - initial text for editbox; size - size of editbox

Returns:: instance of new TBEdit object

addSeparator

 public void addSeparator()

Apends toolbar with separator

TBButton element

Declaration:

TBButton element has next list of attributes

id - identifier of button
image - image name for button (path starts from applets code base)
width / height - size of button
statusmsg - message in status bar for this button
tooltip - hint message for this button
state - create 'push button'
pushed - sets initial state for pushbutton into 'Pushed'
disabled - sets initial state for button into 'Disabled'

Parameters id, image, width, height are mandatory for each button.

If many similar buttons are part of several toolbars, they can be described as named templates and used as references to template. Template for button can define all of button properties. Parameter for template has name tbutton<i> and has additional parameter name to define name of template. Then for this kind of button parameter name is necessary. Parameters state and pushed from template can be redefined in definition section.

Example 3. Button declaration

a. With all atributes:

<param name="button4" value="id='btn',image='icons/home.gif',width='27',height='26',id='home_button',statusmsg='Home', tooltip='Home'">

b. With using of template :

<param name="tbutton1" value="name='forward',image='icons/forward.gif',width='27',height='26',id='forward_button',statusmsg='Forward', tooltip='Forward'">

...
<param name="button3" value="name='forward'">

Methods:

getState

 public boolean getState()

Gets the state of push button

Returns:: true if button is pushed

setState

 public void setState(boolean isPushed)

Sets the state of push button

Parameters:: isPushed - new state of push button

setEnabled

 public void setEnabled(boolean isEnabled)

Enables or disables this component, depending on the value of the parameter b. An enabled component can respond to user input and generate events. Components are enabled initially by default.

Parameters:: b - - If true, this component is enabled; otherwise this component is disabled.

TBSeparator element

TBSeparator object describes as object with name separator. Value for it is ignoring. TBSeparator object has no methods.

Example 4. Separator declaration

<param name="separator4" value="">

TBChoice element

Choice element has the next set of attributes:

id - identifier of choice
statusmsg - message in status bar for this button

Each element of choice desribing in next format: <param name="choiceitem<i>" value="<item_name>">

Each choice should be closed by choice parameter with empty value.

Example 5. Choice declaration

<param name="choice3" value="id='choice1',statusmsg='Just combobox'"> <param name="choiceitem4" value="item1"> <param name="choiceitem5" value="item2"> <param name="choiceitem6" value="item3"> <param name="choiceitem7" value="item4"> <param name="choice8" value="">

TBChoice element extends standard java.awt.Choice class and all methods from it are available in TBChoice object (see JDK documentation)

TBEdit element

Declaration:

TBEdit element has the next set of attributes:

id - identifier of choice
label - label of edit element
text - initial text value
size- size of textbox

Methods:

getText

 public String getText()

Gets the text from editbox

setText

 public void setText(String text)

Sets the text in editbox