Menubar Applet documentation v

Menubar Applet documentation v. 1.0
Copyright SCAND LLC 2001

JMENUBAR applet is useful component to create menu components with any level of complexity in internet/intranet application with flexible settings and rich functionality. Applet supports all standard types of menu elements:

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

Initialization of the applet

Menubar applet can load content in two modes:

initialize it from PARAM tags, present in HTML that contain the applet (see Initializing from PARAM tags section);
initialize it from XML document (see Initializing from XML document section;
initialize with help of public methods of applet from JavaScript or another applet.

Initializing from PARAM tags

To populate menubar with menus and submenus you should specify parameters for each menu object in the following format:

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

where:

<object_name> is one of the next values:

menubar - for top-level Menubar object inserting,
menu - for Menu object inserting,
item - for MenuItem object inserting,
checkitem - for MenuCheckItem object inserting.

<number> indicates the sequential number of an item in initialization list. Starts from 0. All objects must be numbered continiously.

<object_attributes> - item-depended properties of object in <name>='<value>' format. Bellow you can see full list of attributes:

Attribute	Object	Required	Description
id	All objects (exclude separator)	Yes	Unique identifier of item.
name	Menu (exclude top-level), MenuItem, MenuCheckItem	Yes	Label of the item. At top level hot-key can be assigned in this parameter with help of ampersand symbol: name = '&File'
key	Menu and MenuItem (exclude top-level), MenuCheckItem	No	Code of shortcut key associated with this MenuItem. Can be specified in decimal (key='83') or hexadecimal (key='#A5') formats.
shiftkey	Menu and MenuItem (exclude top-level), MenuCheckItem	No	Code of shortcut key with shift modifier.
disabled	Menu (exclude top-level), MenuItem, MenuCheckItem	No	Makes this item disabled
checked	MenuCheckItem	No	Sets checked flag for MenuCheckItem
SEPARATOR	MenuItem (exclude top-level)	No	Creates separation line in current menu position. Example: <param name=item17 value="SEPARATOR">
im0, im1, im2	Menu and MenuItem at top level	No	Sets image at menu panel instead of text label. Three images should be specified for next states: normal mouse over mouse pressed

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

Example 1. Menu declaration example

<param name=menubar0 value="id='ie_menubar'">
	<param name=menu1 value="id='ie_file_menu',name='F&ile'">
		<param name=menu2 value="id='ie_file_new',name='New'">
			<param name=item3 value="id='ie_file_new_window',name='Window'">
			<param name=item4 value="SEPARATOR">
			<param name=item5 value="id='ie_file_new_message',name='Message'">
			<param name=item6 value="id='ie_file_new_internet_call',name='Internet Call'">
		<param name=menu7 value="">
		<param name=item8 value="id='ie_file_open',name='Open',shiftkey='#4f'">
		<param name=item9 value="id='ie_file_edit',name='Edit',disabled">
		<param name=item10 value="id='ie_file_save',name='Save',disabled">
		<param name=item11 value="id='ie_file_save_as',name='Save As'">
		<param name=item12 value="SEPARATOR">
		<param name=item13 value="id='ie_file_page_setup',name='Page Setup'">
		<param name=item14 value="id='ie_file_print',name='Print'">
		<param name=item15 value="SEPARATOR">
		<param name=checkitem16 value="id='ie_work_offline',name='Work offline'">
		<param name=item17 value="SEPARATOR">
		<param name=menu18 value="id='ie_file_send',name='Send'">
			<param name=item19 value="id='ie_file_page_email',name='Page by E-mail'">
			<param name=item20 value="id='ie_file_link_email',name='Link by E-mail'">
			<param name=item21 value="id='ie_file_st_ds',name='Shortcut to Desctop'">
		<param name=menu22 value="">
		<param name=item22 value="id='ie_file_imp_exp',name='Import and Export'">
	<param name=menu23 value="">
	<param name=menu24 value="id='ie_edit_menu',name='&Edit'">
		<param name=checkitem25 value="id='ie_view_view',name='View point'">
		<param name=item26 value="id='ie_edit_folders',name='Folders',CHECKED">
	<param name=menu27 value="">
	<param name=item28 value="id='ie_view_menu',name='&View',disabled">
<param name=menubar29 value="">

Initializing from XML document

Tree structure can be loaded from separated XML document. In this case applet should have only one parameter - XML - wich describes location of xml document, started from html document base. Important: this possibily can be used only in internet or intranet applications, becouse applet can't load another file from local drive. Below you can see simple example of xml document for menubar:

Example 1. XML-code with simple menu structure

<menuapplet>
	<menubar id='ie_menubar'>
		<menu id='ie_file_menu' name='F&amp;ile'>
			<menu id='ie_file_new' name='New'>
				<item id='ie_file_new_window' name='Window'/>
				<separator/>
				<item id='ie_file_new_message' name='Message'/>
				<item id='ie_file_new_internet_call' name='Internet Call'/>
			</menu>
			<item id='ie_file_open' name='Open' shiftkey='#4f'/>
			<item id='ie_file_edit' name='Edit' disabled='1'/>
			<item id='ie_file_save' name='Save' disabled='1'/>
			<item id='ie_file_save_as' name='Save As'/>
			<separator/>
			<item id='ie_file_page_setup' name='Page Setup'/>
			<item id='ie_file_print' name='Print'/>
			<separator/>
			<menu id='ie_file_send' name='Send'>
				<item id='ie_file_page_email' name='Page by E-mail'/>
				<item id='ie_file_link_email' name='Link by E-mail'/>
				<item id='ie_file_st_ds' name='Shortcut to Desctop'/>
			</menu>
			<item id='ie_file_imp_exp' name='Import and Export'/>
		</menu>
		<menu id='ie_edit_menu' name='&amp;Edit'>
			<checkitem id='ie_view_view' name='View point'/>
		</menu>
		<item id='ie_view_menu' name='&amp;View' disabled='1'/>
	</menubar>
</menuapplet>

XML document contains the next tags for menu structure:

Tag	Inserting object	Is terminal	Description
menuapplet	-	No	Describes applet's attributes. See Attributes and events processing section for details. Single XML document can have only one couple of this tags.
menubar	Menu	No	Inserts top-level menu element
menu	Menu	No
item	MenuItem	Yes
checkitem	MenuCheckItem	Yes
separator	MenuItem	Yes

All tags can have attributes, described in Initializaing from PARAM tags section

Attributes and events processing

Menubar applet can have the next set of attributes, that should be specified as PARAM tags (initialization from applet's parameters) or as attributes of menuapplet XML tag (initialization from XML document):

Attribute	Description
BGCOLOR	Background color of the applet in HTML format
SHOW	Ide
ON_LOAD	Name of JavaScript function, wich will be called when applet initialization is finished
ON_SELECT	Name of JavaScript function, wich will be called when menu item is checking. Receiving single parameter - selected item object.
ON_CHECK	Name of JavaScript function, wich will be called when check state of MenuCheckItem is changed. Receiving single parameter - selected MenuCheckItem object.

Menu components and methods

Menu applet public methods

addMenubar

 public Menubar addMenubar(String id)

Inserts new menubar with specified identifier into applet.

Parameters:: id - identifier of Menubar

showMenu

 public void showMenu(String id)

Shows menubar with specified identifier

Parameters:: id - identifier of Menubar

findObject

 public MenuElement findObject(String id)

Returns object with specified id

Parameters:: id - identifier for search
Returns:: Object with identifier id or null if not found

findMenubar

 public MenuElement findMenubar(String id)

Returns Menubar with specified id

Parameters:: id - identifier for search
Returns:: Menubar with identifier id or null if not found

findMenu

 public MenuElement findMenu(String id)

Returns Menu object with specified id

Parameters:: id - identifier for search
Returns:: Menu object with identifier id or null if not found

findItem

 public MenuElement findItem(String id)

Returns terminal item (Item orCheckitem) with specified id

Parameters:: id - identifier for search
Returns:: Object with identifier id or null if not found

MenuElement interface

MenuElement is base class for all menu objects - they are implement methods from this class. Bellow you can see full set of methods, wich can be using for all menu components.

Method	Description	Restrictions
String getId()	Gets the identifier of the menu element.
boolean isMenubar()	Checks item for Menubar type.
boolean isMenu()	Checks item for Menu type.
boolean isItem()	Checks item for Menu type.
String getItemName()	Gets the name of the menu element.	Not applicable for Menubar
void setItemName(String name)	Sets the name of the menu element.	Not applicable for Menubar
MenuElement getParentItem()	Gets the parent of menu item.
void addShortcut(int key, boolean useShiftModifier)	Adds a new MenuShortcut with the specified key for this component. Parameters: key - the raw keycode for this MenuShortcut, as would be returned in the keyCode field of a KeyEvent if this key were pressed. useShiftModifier - indicates whether this MenuShortcut is invoked with the SHIFT key down.	Not applicable for Menubar

MenuContainer interface

MenuContainer is base class for all non-terminal points in menu - for menubar, menus and all submenus. It has the next set of methods, wich implemented in child classes:

Method	Description
int getItemsCount()	Gets the count of children (submenu and items) for menu component
MenuElement getItemAt(int num)	Gets the child item from menu at specified position
MenuElement findItem(String id)	Finds item with specified id in menu component (not recursive)
MenuElement findItemName(String name)	Finds item with specified name in menu component (not recursive)
MenuElement addItem([int pos, ] String text, String id, boolean isEnabled)	Inserts new MenuItem object with specified identifier, name and enable flag into this menu component at specified position
MenuElement addSubmenu([int pos, ] String text, String id, boolean isEnabled)	Inserts new Menu object with specified identifier, name and enable flag into this menu component at specified position
MenuElement addCheckItem([int pos, ] String text, String id, boolean isChecked, boolean isEnabled)	Inserts new MenuCheckItem object with specified identifier, name, state and enable flag into this menu component at specified position
void addSeparatorItem()	Appends this menu component with separator
void deleteItem(String id)	Removes item with specified id from this menu component
void deleteItemAt(int pos)	Removes item at specified position from this menu component

Menubar object

Menubar class implements top-level menu element. It contains all methods from MenuElement and MenuContainer interfaces.

Menu object

Menu class implements submenu functionality. It contains all methods from MenuElement and MenuContainer interfaces, and more, it extends standard java.awt.Menu class and all methods from it are available (see JDK documentation).

MenuItem object

Menu class implements terminal menu element. It contains all methods from MenuElement interface, and more, it extends standard java.awt.MenuItem class and all methods from it are available (see JDK documentation).

MenuCheckItem object

Menu class implements terminal menu element. It contains all methods from MenuElement interface, and more, it extends standard java.awt.CheckboxMenuItem class and all methods from it are available (see JDK documentation).