Menubar & Menu Design

• Related Topics:
• Scrollbar
• Screen Background
• numbered view-type
• slide-up view-type
• Text Design
• CSS Basics

J2ME Polish allows you to choose between 3 different options for realizing the menu:

• Default Menu: The default menu uses a structure similar to Nokia implementations and offers the same look and feel on all devices.
• Extended Menu: The extended menu offers additional design options and provides device dependent implementations, so that the "feel" does not differ from native menus. This brings an overhead of around 2kb for the JAR size.
• Native Menu: The native menu uses the device-dependent implementation, which provides the best native integration but no design options at all.

Default Menu

Design of the Default Menubar

The default menubar uses a structure similar to Nokia implementations and offers the same look and feel on all devices.

The above design has been realized with these polish.css and build.xml settings:

polish.css:
colors {
	fontColor: #333;
}
menu {
	font-color: fontColor;
	font-style: bold;
	menubar-color: yellow;
}

build.xml:
<variable name="polish.MenuBar.PaddingLeft" value="5" />
<variable name="polish.MenuBar.PaddingRight" value="5" />
<variable name="polish.MenuBar.PaddingTop" value="5" />
<variable name="polish.MenuBar.PaddingBottom" value="1" />

The font of the default menubar is defined in the "menu" style, which is also responsible for the command popup screen. Additionally you can specify the menubar-color in either the "menu" style or in the corresponding screen's style:

Configuration of the Default Menubar

The default menu has to be activated by setting the "fullscreen" attribute of the <build> element to true in your build.xml script:

<build 
	usePolishGui="true" 
	fullscreen="menu"
	...>

Alternatively you can set the "polish.useMenuFullScreen" variable to true:

<variable name="polish.useMenuFullScreen" value="true" />

You can specify the used paddings between the screen's border and the default menubar by defining "polish.MenuBar.PaddingLeft" etc:

<variable name="polish.MenuBar.PaddingLeft" value="3" />
<variable name="polish.MenuBar.PaddingRight" value="3" />
<variable name="polish.MenuBar.PaddingTop" value="3" />
<variable name="polish.MenuBar.PaddingBottom" value="3" />

Extended Menubar

Design of the Extended Menubar

The extended menubar offers some additional design options and provides device dependent implementations, so that the "feel" does not differ from native menus. You can use any backgrounds for the extended menubar:

It's also possible to use advanced text designs like the shadow text-effect for the extended menubar:

The above design has been realized with these polish.css settings:

colors {
	fontColor: #333;
}

/** The extended menu bar */
menubar
{
	margin: 0;
	padding: 2;
	padding-top: 3;
	background {
		type: vertical-gradient;
		top-color: #ccc;
		bottom-color: #fff;
		start: 10%;
		end: 90%;
	}
}

/**
 * Commands within the extended menubar on the left side
 */
leftcommand
{
	margin: 0;
	padding-top: 3;
	padding-bottom: 0;
	font-color: fontColor;
	font-style: bold;
	text-effect: shadow;
	text-shadow-color: #ff0;
}

/**
 * Commands within the extended menubar on the right side
 */
rightcommand extends leftcommand
{
	layout: right;
}

The background, paddings, margins and borders of the menubar are designed within the menubar style. Note that the CSS attribute menubar-color has no effect, when using the extended menubar, as you can now use any background. The text on the left side within the menubar is designed with the leftcommand, the one on the right side accordingly with the rightcommand style.

Following further CSS attributes can be used to adjust the menubar design:

colors {
	/* create a white translucent overlay: */
	overlay: argb( 80, 255, 255, 255 );
}

For the design options for leftcommand and rightcommand, please refer to the design guide for StringItem.

Configuration of the Extended Menubar

The extended menubar has to be activated in your build.xml script by setting the "polish.MenuBar.useExtendedMenuBar" to "true":

<variable name="polish.MenuBar.useExtendedMenuBar" value="true" />

Additionally the general usage of the menu has to be activated by setting the "fullscreen" attribute of the <build> element to true in your build.xml script:

<build 
	usePolishGui="true" 
	fullscreen="menu"
	...>

Alternatively you can set the "polish.useMenuFullScreen" variable to true:

<variable name="polish.useMenuFullScreen" value="true" />

You can specify the positioning of the menu for the extended menubar by setting the appropriate preprocessing variables:

<variable name="polish.MenuBar.OptionsPosition" value="left" />
<variable name="polish.MenuBar.OkPosition" value="left" />

Menu

Designing the Menu

When you have activated the default or the extended menubar, you can also design your menu using the menu and menuitem styles in your polish.css file.

When the menu is opened (and you use the extended menubar), the shown screen will be dimmed by painting the screen with a translucent overlay color, if the device supports translucency. The default overlay color is argb( 136, 0, 0, 0 ), you can specify it differently within the colors section of your polish.css file:

colors {
	overlay: argb( 136, 0, 0, 0 );
}
menu {
	margin-left: 4;
	margin-right: 4;
	margin-bottom: -4; /* for the border */
	min-width: 100;
	padding: 2;
	font-color: focusedFontColor;
	font-size: small;
	view-type: slide-up;
	border {
		type: drop-shadow;
		width: 4;
		start-color: #aeee;
		end-color: #2222;
		orientation: top-right;
	}
	background {
		type: horizontal-stripes;
		first-top-color: screenColorTop1;
		first-bottom-color: screenColorBottom1;
		second-top-color: screenColorTop2;
		second-bottom-color: screenColorBottom2;
	}
}


/**
  * The menuItem style is a predefined style
  * for the actual commands in a fullscreen-menu.
  * When the menuItem style is not defined,
  * the menu style will be used instead. 
  */
menuItem {
	padding: 3;
	padding-left: 10;
	padding-right: 10;
	font {
		color: fontColor;
		size: small;
		style: bold;
	}
	layout: left;
	//#if ${ exists( arrowRight.png ) }
		command-child-indicator: url(arrowRight.png);
	//#else
		command-child-indicator-color: blue;
		command-child-indicator-width: 8;
		command-child-indicator-height: 10;
	//#endif
}

.menuItem:hover {
	padding: 2;
	padding-left: 9;
	padding-right: 9;
	background {
		type: round-rect;
		color: focusedBackgroundColor;
		border-color: focusedBorderColor;
	}
	font {
		style: bold;
		size: small;
		color: focusedFontColor;
	}
	layout: left | horizontal-expand;
}

All comand- / menu-items do support normal text design. Additionally you can design the indicators that show the availability of subcommands with the child-indicator CSS attributes:

Animating the Menu

You can use any animation for animating the menu. A commonly used animation is the "slide-up" animation, that scrolls the menu upwards when the user opens the menu:

menu {
	margin-left: 4;
	margin-right: 4;
	margin-bottom: -4; /* for the border */
	min-width: 100;
	padding: 2;
	font-color: focusedFontColor;
	font-size: small;
	view-type: slide-up;
	border {
		type: drop-shadow;
		width: 4;
		start-color: #aeee;
		end-color: #2222;
		orientation: top-right;
	}
	background {
		type: horizontal-stripes;
		first-top-color: screenColorTop1;
		first-bottom-color: screenColorBottom1;
		second-top-color: screenColorTop2;
		second-bottom-color: screenColorBottom2;
	}
}

Configuration of the Menu

The position of the menu is defined within the device dabatase with following capabilities:

<capability name="MenuBar.OptionsPosition" value="right" />
<capability name="MenuBar.OkPosition" value="left" />

You can override the positioning of the menu for the extended menubar by setting the appropriate preprocessing variables:

<variable name="polish.MenuBar.OptionsPosition" value="left" />
<variable name="polish.MenuBar.OkPosition" value="left" />

Localization of the Menu

Since the menu implementation uses some texts like "Select" and "Cancel", you might want to localize or change these text. Please refer to the Localization Guide for detailed information. Following localization properties are used by the J2ME Polish Menu in the messages.txt file:

polish.command.ok=OK
polish.command.cancel=Cancel
polish.command.select=Select
polish.command.options=Options

Programming

Styling Specific Commands

When adding commands or subcommands you can use the #style preprocessing directive for applying specialized styles:

Form form = new Form("Hello World");
//#style helloCommand
form.addCommand( this.cmdHello );
// using the default "menuitem" style:
form.addCommand( this.cmdExit );

You can add subcommands by calling UiAccess.addSubCommand( Command child, Command parent, Screen screen ):

//#style onlineCmd
UiAccess.addSubCommand( this.cmdStatusOnline, this.cmdStatus, form );
// using the default "menuitem" style:
UiAccess.addSubCommand( this.cmdStatusOffline, this.cmdStatus, form );

You can use the .menu1 style for designing the background and layout of the first layer of subcommands, .menu2 for the second, and .menu3 for the third level of subcommands:

/** design the first level of subcommands: */
.menu1 extends menu {
	background-color: #ddd;
}

Order Commands

The order of commands is specified using the priorities of commands. A command with a higher numerical value will be placed below a command with a lower value.

Deactivate Commands

You can deactivate specific commands by calling UiAccess.setAccessible( Screen screen, Command command, boolean accessible ):

//#style commandInactive
UiAccess.setAccessible( myForm, cmdForward, false );
	

Please note that you need to use the extended menubar when you want to deactivate commands that are shown directly (not within the Options menu).

JavaDoc

UiAccess
MenuBar