J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

Menubar & Menu Design

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.
Default Menubar
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:

CSS Attribute  DefaultValuesApplies To  Explanation
menubar-colorwhitecolor or transparentmenu or screen's style The color of the menubar. You might want to set it to transparent when using an image screen background.
font-colorblackcolor definitionmenu style The color of the menubar font.
font-sizemediumsmall, medium, largemenu style The size of the menubar font.
font-styleplainplain, bold, italic, underlinedmenu style The style of the menubar font.

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:
Extended Menubar
It's also possible to use advanced text designs like the shadow text-effect for the extended menubar:
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:

CSS Attribute  DefaultValuesApplies To  Explanation
overlay#a000ARGB color definitioncolors section When the extended menubar is opened, it will dim the screen's contents with the overlay color defined within the colors section of your polish.css file.
colors {
	/* create a white translucent overlay: */
	overlay: argb( 80, 255, 255, 255 );
}
overlay-background-Reference to background defined in the backgrounds section.Screens You can also defined a screen specific overlay background.
menubar-stylemenubarstyle referencescreen's style Changes the style of the menubar for the affected screens.

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" />

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:
menu

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:

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;
}

Ordering of 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).

Command Separators

You can also add separators to the native menu by adding a Command.SEPARATOR command:

import de.enough.polish.ui.Command;
[...]
	
//#style menuSeparator
Command cmdSeparator = new Command("", Command.SEPARATOR, 5 );
myScreen.addCommand( cmdSeparator );

The style .menuSeparator can then include your specific design.

Global Commands

If you are using the same command with the same logic in different locations of your applications, you can register a CommandListener or a ItemCommandListener directly on a Command as well:

import de.enough.polish.ui.Command;
[...]

final MIDlet midlet = this;
Command cmdExit = new Command("Exit", Command.EXIT, 10 );
cmdExit.setCommandListener( new CommandListener() { 
	public void commandAction( Command cmd, Screen scr) { 
		midlet.notifyDestroyed(); 
	}
} );

Default Commands

If you want to trigger a specific action when the user tabs an Item or presses FIRE on an Item, you can register a default command on the Item:

import de.enough.polish.ui.Command;
import de.enough.polish.ui.StringItem;
[...]
//#style button
StringItem item = new StringItem(null, "Start")
item.setDefaultCommand( this.cmdStart);

You can hide default commands from the menubar by setting the polish.Item.suppressDefaultCommand preprocessing variable in your build.xml script:

<variable name="polish.Item.suppressDefaultCommand" value="true" />

Execute Commands Asycnhronously

J2ME Polish executes commands asynchronously for you when you specify the polish.executeCommandsAsynchrone preprcessing variable:

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

In this case all CommandListener.commandAction(Command, Displayable) and ItemCommandListener.commandAction(Command, Item) will be executed in a different thread. This means that you can have long running code in your command handling code without blocking the user interface.

JavaDoc

back to top