Specific Design Attributes

Many GUI items support specific CSS attributes.

Backgrounds

There are many different background-types which make use of specific CSS attributes. When another background than the default simple background or the image background should be used, the background-type attribute needs to be declared. When no background at all should be used, the background: none; declaration can be used.

Simple Background

The simple background just fills the background with one color. When no background type is specified, the simple background is used by default, unless the "background-image" attribute is set. In the later case the image background will be used. The simple background supports the color attribute:

Attribute  Required  Explanation
color Yes The color of the background, either the name of the color or a direct definition.

The following styles use a yellow background:

.myStyle {
	background-color: yellow;
}
.myOtherStyle {
	background-color: rgb( 255, 255, 0 );
}

Round-Rect Background

The round-rect background paints a rectangular background with round edges. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "round-rect" or "roundrect"
color No The color of the background, either the name of the color or a direct definition. The default color is white.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.

This example creates a purple background with an arc diameter of 6 pixels:

.myStyle {
	background {
		type: round-rect;
		color: purple;
		arc: 6;
	}
}

The following example uses a different horizontal arc diameter:

.myStyle {
	background-type: round-rect;
	background-color: purple;
	background-arc: 6;
	background-arc-width: 10;
}

Image Background

The image background uses an image for painting the background. This background type is used by default when no type is set and the "background-image" attribute is set. The background supports following attributes:

Attribute  Required  Explanation
type No When used needs to be "image".
color No The color of the background, either the name of the color, a direct definition or "transparent". The default color is white. This color can only be seen when the image is not big enough.
image Yes The URL of the image, e.g. "url( background.png )"
anchor No The anchor of the image - when not specified the image will be centered ("horizontal-center | vertical-center"). You can use a combination of "top", "vertical-center" (="vcenter"), "bottom" and "left", "horizontal-center" (= "hcenter" = "center"), "right". E.g. "top | left".
repeat No Either "repeat", "no-repeat", "repeat-x"/"repeat-horizontal" or "repeat-y"/"repeat-vertical". Determines whether the background should be repeated, repeated horizontally or repeated vertically. Default is no repeat.
padding-horizontal No The horizontal gap between tiles, can be negative for overlapping the tiles. Defaults to 0. Is only applicable when the repeat mode is activated.
padding-vertical No The vertical gap between tiles, can be negative for overlapping the tiles. Defaults to 0. Is only applicable when the repeat mode is activated.
overlap No Defines whether the tiles should overlap over the actual background-area when they don't fit exactly into the actual background-area. Either "true"/"yes" or "no"/"false". Defaults to false. Is only applicable when the repeat mode is activated.

The following style uses the image "gradient.png" as a background:

.myStyle {
	background-image: url( gradient.png );
	background-anchor: top | center;
	background-color: rgb( 69, 81, 77 );
}

This style uses the image "heart.png" as a repeated background:

.myStyle {
	background-image: url( heart.png );
	background-repeat: repeat;
}

Circle Background

The circle background paints a circular or elliptical background. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "circle".
color No The color of the background, either the name of the color or a direct definition. Defaults to white.
diameter No With the "diameter" attribute it can be ensured that always a circle and never an ellipse is painted. The diameter then defines the diameter of the circle.

The following example uses a green circle background with a diameter of 20 pixels:

.myStyle {
	background-type: circle;
	background-color: green;
	background-diameter: 20;
}

Pulsating Background

The pulsating background animates the color of the background. The color is changing from a start-color to an end-color. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "pulsating".
start-color Yes The color of the background at the beginning of the animation sequence.
end-color Yes The color of the background at the end of the animation sequence.
steps Yes Defines how many color-shades between the start- and the end-color should be used.
repeat No Either "yes"/"true" or "no"/"false". Determines whether the animation should be repeated. Defaults to "yes".
back-and-forth No Either "yes"/"true" or "no"/"false. Determines whether the animation sequence should be running backwards to the start-color again, after it reaches the end-color. When "no" is selected, the animation will jump from the end-color directly to the start-color (when repeat is enabled). Defaults to "yes".

The following style starts with a white background and stops with a yellow background:

.myStyle {
	background {
		type: pulsating;
		start-color: white;
		end-color: yellow;
		steps: 15;
		repeat: false;
		back-and-forth: false;
	}
}

Pulsating Circle Background

The pulsating circle background paints a circular or background which size constantly increases and decreases. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "pulsating-circle".
color No The color of the background, either the name of the color or a direct definition. Defaults to white.
min-diameter Yes The minimum diameter of the circle.
max-diameter Yes The maximum diameter of the circle.

The following example uses a green pulsating circle background with a minimum diameter of 20 pixels and a maximum diameter of 40 pixels:

.myStyle {
	background-type: pulsating-circle;
	background-color: green;
	background-min-diameter: 20;
	background-max-diameter: 40;
}

Pulsating Circles Background

The pulsating circles background paints an animated background of ever-growing circles. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "pulsating-circles".
first-color Yes The first circle-color, either the name of the color or a direct definition.
second-color Yes The second circle-color, either the name of the color or a direct definition.
min-diameter Yes The minimum diameter of the circle.
max-diameter Yes The maximum diameter of the circle.
circles-number Yes The number of circles which should be painted.
step No The number of pixels each circle should grow in each animation phase. Float-values like "1.5" are also allowed. This defaults to "1" pixel.

The following example uses a green pulsating circle background with a minimum diameter of 20 pixels and a maximum diameter of 40 pixels:

.myStyle {
	background-type: pulsating-circle;
	background-color: green;
	background-min-diameter: 20;
	background-max-diameter: 40;
}

Opening Background

The opening background paints an animated background which height starts small and then increases whenever it changes the position. Its primary use is for the "focused"-style. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "opening".
color Yes The background color, either the name of the color or a direct definition.
start-height No The height of the background immediately after it has changed its position. This defaults to 1 pixel.
steps No The number of pixels by which the height should be increased in each animation step. This defaults to 4 pixels. When the height is as big as the normal background-height, the animation is stopped.

The following example uses the opening background:

.myStyle {
	background {
		type: opening;
		color: bgColor;
		start-height: 2;
		steps: 4;
	}
}

Opening-Round-Rect Background

The opening round rectangle background paints an animated background which height starts small and then increases whenever it changes the position. Its primary use is for the "focused"-style. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "opening-round-rect".
color Yes The background color, either the name of the color or a direct definition.
start-height No The height of the background immediately after it has changed its position. This defaults to 1 pixel.
steps No The number of pixels by which the height should be increased in each animation step. This defaults to 4 pixels. When the height is as big as the normal background-height, the animation is stopped.
border-width No The width of the border, defaults to 0 (no border).
border-color No The color of the border, defaults to black.
arc No The diameter of the arc at the four corners. Defaults to 10�pixels, when none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.

The following example uses the opening-round-rect background:

.myStyle {
	background {
		type: opening-round-rect;
		color: bgColor;
		start-height: 2;
		steps: 4;
		border-width: 2;
		border-color: darkBgColor;
	}
}

Round-Tab Background

The round-tab background paints a rectangular background where the top edges are rounded. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "round-tab"
color No The color of the background, either the name of the color or a direct definition. The default color is white.
arc No The diameter of the arc at the four corners. Defaults to 10�pixels, when none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.

This example creates a purple background with an arc diameter of 6 pixels:

.myStyle {
	background {
		type: round-tab;
		color: purple;
		arc: 6;
	}
}

The following example uses a different horizontal arc diameter:

.myStyle {
	background-type: round-tab;
	background-color: purple;
	background-arc: 6;
	background-arc-width: 10;
}

Smooth-Color Background

The smooth-color background paints an gradient background. It supports following attributes:

Attribute  Required  Explanation
color Yes The color of the background, either the name of the color or a direct definition.
gradient-color Yes The color for the gradient, either the name of the color or a direct definition.
stroke No The default value is 0.For effects set stroke 1.

This example creates a red background with an gradient to yellow:

.myStyle {
	background {
		type: smooth-color;
	 	color: red;
	 	gradient-color: yellow;
	 	
	}
}

Tiger-Stripes Background

The tiger-stripes background paints an background with randomized numbers of Stripes. It supports following attributes:

Attribute  Required  Explanation
color Yes The color of the background, either the name of the color or a direct definition.
stripes-color Yes The color for the stripes, either the name of the color or a direct definition.
number Yes The posible number of stripes that can be displayed.

This example creates a red background with an maximum of 25 black stripes:

.myStyle {
	background {
		type: tiger-stripes;	
		color: red;
		stripe-color: black;
		number: 25;
	}
}

Ball-Games Background

The ball-games background paints an animated background with an number of sprites which moving through the background. It supports following attributes:

Attribute  Required  Explanation
color Yes The color of the background, either the name of the color or a direct definition.
number Yes The number of sprites that were displayed.
border-color Yes The border color from the background.
image Yes The image for the sprite.
image-width Yes The width for the sprite.
image-height Yes The height for the sprite.

This example creates blue background with 25 sprites.The sprites include the given image(player.png):

.myStyle {
	background {
		type: ball-games;
		image: url( player.png );	
		image-width: 15;
		image-height: 15;
		color: blue;
		number: 25;
		border-color: green;

	 	
	}
}

Borders

There are many different border-types which make use of specific CSS attributes. When another border than the default simple border should be used, the border-type attribute needs to be declared. When no border at all should be used, the border: none; declaration can be used.

Simple Border

The simple border paints a rectangle border in one color. The type attribute does not need to be set for the simple border, since this is the default border. The only supported attributes are the color and the width of the border:

Attribute  Required  Explanation
color Yes The color of the border, either the name of the color or a direct definition.
width No The width of the border in pixels. Defaults to 1.

The following style uses a black border which is 2 pixels wide:

.myStyle {
	border-color: black;
	border-width: 2;
}

Round-Rect Border

The round-rect border paints a rectangular border with round edges. It supports following attributes:

Attribute  Required  Explanation
type Yes The type needs to be "round-rect" or "roundrect"
color Yes The color of the border, either the name of the color or a direct definition.
width No The width of the border in pixels. Defaults to 1.
arc No The diameter of the arc at the four corners. Defaults to 10 pixels, when none is specified.
arc-width No The horizontal diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.
arc-height No The vertical diameter of the arc at the four corners. Defaults to the arc-value, when none is specified.

This example creates a 2 pixels wide purple border with an arc diameter of 6 pixels:

.myStyle {
	border {
		type: round-rect;
		color: purple;
		width: 2;
		arc: 6;
	}
}

The following example uses a different horizontal arc diameter:

.myStyle {
	border-type: round-rect;
	border-color: purple;
	border-width: 2;
	border-arc: 6;
	border-arc-width: 10;
}

Shadow Border

The shadow border paints a shadowy border. Following attributes are supported:

Attribute  Required  Explanation
type Yes The type needs to be "shadow", "bottom-right-shadow" or "right-bottom-shadow".
color Yes The color of the border, either the name of the color or a direct definition.
width No The width of the border in pixels. Defaults to 1.
offset No The offset between the corner and the start of the shadow. Defaults to 1 pixel, when none is specified.

Currently only a "bottom-right-shadow" is supported, so the border is painted below the item and right of the item. The following example uses a green shadow border:

.myStyle {
	border-type: shadow;
	border-color: green;
	border-width: 2;
	border-offset: 2;
}

Top, Bottom, Left and Right Border

These border paints a simple border on one side the corresponding item. Following attributes are supported:

Attribute  Required  Explanation
type Yes The type needs to be "top", "bottom", "left" or "right".
color Yes The color of the border, either the name of the color or a direct definition.
width No The width of the border in pixels. Defaults to 1.

The following example uses a green border on the bottom of the title:

title {
	border-type: bottom;
	border-color: green;
	border-width: 2;
}

Circle Border

The circle border paints a round or elliptical border and supports following attributes:

Attribute  Required  Explanation
type Yes The border-type needs to be "circle".
color No The color of the border, either the name of the color or a direct definition. Defaults to black.
width No The width of the border in pixels. Defaults to 1.
stroke-style No Either "solid" or "dotted". Defines the painting style of the border. Defaults to "solid".

The following example uses a green circle border with a two pixel wide dotted line:

.myStyle {
	border-type: circle;
	border-color: green;
	border-width: 2;
	border-stroke-style: dotted;
}

Screens: List, Form and TextBox

Predefined Styles for Lists, Forms and TextBoxes

All screens have a title and one or several embedded GUI items. In a Form or List one item is usually focused. Screens can also have a designable menu, when the application uses a full-screen-mode. Some of the used styles can also use additional attributes.

Style-Name  Add. Attributes  Explanation
title - The title of a screen.
focused - The style of the currently focused item in the screen.
menu   The style of the full-screen menu.
focused-style The name of the style for the currently focused menu item.
menubar-color The background color of the menu-bar. Either the name or the definition of a color or "transparent". Defaults to "white".
label-color, label-face, label-size, label-style The font of the menu-commands (like "Select" or "Cancel"). Default color is "black", default font is the system font in a bold style and medium size.
menuItem - The style for the commands in the menu. When not defined, the menu-style will be used.

Please refer to the Menubar section for more info about designing the menu bar.

Additional Attributes for Screens

Each screen itself can have some additional attributes:

Attribute  Required  Explanation
focused-style No The name of the style for the currently focused menu item. Defaults to the predefined "focused" style.
title-style No The name of the custom style for the title of the screen. This defaults to the predefined "title" style.
view-type No The view-type can be used for defining very different and even animated views of the items in a screen. An example is the "dropping" view-type in which the contained items seem to fall from the top to their positions. Please note that not all view-types support the "columns" and "columns-width"-attributes.
columns No The number of columns. This can be used to layout the items in a table. Defaults to 1 column.
columns-width No Either "normal", "equal" or the width for each column in a comma separated list (e.g. "columns-width: 60,60,100;"). Defaults to "normal", meaning that each column uses as much space as the widest item of that column needs. The "equal" width leads to columns which have all the same width. The explicit list of column-widths results in the usage of those widths.
menubar-color No The color of the menu-bar. This overrides the settings in the predefined style "menu". This attribute is only used, when the "menu" fullscreen setting is activated in the "build.xml" file.
scrollindicator-color No The color of the element which is shown when the screen can be scrolled. The default color is "black".
show-text-in-title No An attribute for Lists only, which can be either "true" or "false". When "true" is given, only the image-elements of the List will be shown and the text-elements will be used as titles. The title will be updated with each new selection.
foreground-image No The URL of a image that should be painted at the very front of the screen, e.g. "url( mascot.png )".
foreground-x No The x-position of the foreground image in pixels from the the left border.
foreground-y No The y-position of the foreground image in pixels from the the top border.

The following example uses some of these additional attributes:

list {
	background-image: url( bg.png );
	columns: 2;
	columns-width: equal;
	focused-style: .listFocusStyle; /* this style needs to be defined, too */
}

TextBoxes also support a direct input mode and all CSS-attributes of the text-field.

Dynamic Styles for Screens

Dynamic styles can be used when no styles are explicitly set in the application code (compare CSS styles). A list uses the dynamic selector "list" and always contains choice-items. The selector of these items depends on the type of the list. An implicit list contains a "listitem", a multiple list contains a "checkbox" and an exclusive list contains a "radiobox".

list {
	background-color: pink;
}

defines the background color for screens of the type "List".

listitem { /* you could also use "list listitem" */
	font-style: bold;
}

defines the font style for the items in an implicit list.


A form uses the dynamic selector "form" and can contain different GUI items.

form {
	background-color: pink;
}

defines the background color for screens of the type "Form".

form p {
	font-style: bold;
}

defines the font style for normal text items in a "Form".


A TextBox uses the dynamic selector "textbox" and contains a single "textfield" item.

Example

The following example designs the main menu of an application, which is implemented using a List.

colors {
	pink:  rgb(248,39,186);
	darkpink:  rgb(185,26,138);
}

menu {
	margin-left: 2;
	padding: 2;
	background {
		type: round-rect;
		color: white;
		border-width: 2;
		border-color: yellow;
	}
	focused-style: .menuFocused;
	menubar-color: transparent;
	menufont-color: white;
}

menuItem {
	margin-top: 2;
	padding: 2;
	padding-left: 5;
	font {
		color: black;
		size: medium;
		style: bold;
	}
	layout: left;
}

.menuFocused extends .menuItem {
	background-color: black;
	font-color: white;
	layout: left | horizontal-expand;
	after: url(heart.png);
}

title {
	padding: 2;
	margin-top: 0;
	margin-bottom: 5;
	margin-left: 0;
	margin-right: 0;
	font-face: proportional;
	font-size: large;
	font-style: bold;
	font-color: white;
	background {
		color: darkpink;
	}
	border: none;
	layout: horizontal-center | horizontal-expand;
}

focused {
	padding: 2;
	padding-vertical: 3;
	padding-left: 3;
	padding-right: 3;
	padding-top: 10;
	padding-bottom: 10;
	background-type: round-rect;
	background-arc: 8;
	background-color: pink;
	border {
		type: round-rect;
		arc: 8;
		color: yellow;
		width: 2;
	}
	font {
		style: bold;
		color: black;
		size: small;
	}
	layout: expand | center;
}

list {
	padding-left: 5;
	padding-right: 5;
	padding-vertical: 10;
	padding-horizontal: 10;
	background {
		color: pink;
		image: url( heart.png );
	}
	columns: 2;
	columns-width: equal;
	layout: horizontal-expand | horizontal-center | vertical-center;
}

listitem {
	margin: 2; /* for the border of the focused style */
	padding: 2;
	padding-vertical: 3;
	padding-left: 3;
	padding-right: 3;
	padding-top: 10;
	padding-bottom: 10;
	background: none;
	font-color: white;
	font-style: bold;
	font-size: small;
	layout: center;
	icon-image: url( %INDEX%icon.png );
	icon-image-align: top;
}

View Types

View-types can be used for animating Forms, Lists, ChoiceGroups or even menus. There are several view-types available, which are usually defined in a screen-style, e.g.:

.mainScreen {
	padding-left: 5;
	padding-right: 5;
	view-type: dropping;
}

You can use either a (predefined) name of the view-type or the fully qualified class-name of that type, which needs to extend the de.enough.polish.ui.ContainerView class.

Dropping View

The dropping view shows an animation of dropping and bouncing items. It is activated by specifying the "dropping" view-type and supports following additional attributes:

Attribute  Required  Explanation
droppingview-speed No The speed in pixels per animation-step. The default speed is 10.
droppingview-repeat-animation No Defines whether the animation should be repeated each time the screen is shown. Possible values are "true" and "false". This defaults to "false".
droppingview-maximum No The maximum bouncing-height in pixels. This defaults to 30.
droppingview-damping No The value by which the maximum is decreased for each following item. By having a damping, the top items seem to bounce higher than lower ones. The default damping is 10.
droppingview-maxperiode No The maximum allowed number of bounces. This defaults to 5.
No

.mainScreen {
	padding-left: 5;
	padding-right: 5;
	view-type: dropping;
	droppingview-speed: 15;
	droppingview-damping: 5;
	droppingview-maxperiode: 2;
}

Shuffle View

The shuffle view animates the items by moving them from the left and right side into their final target-position. It is activated by specifying the "shuffle" view-type and supports following additional attributes:

Attribute  Required  Explanation
shuffleview-speed No The speed in pixels per animation-step. The default speed is 10.
shuffleview-repeat-animation No Defines whether the animation should be repeated each time the screen is shown. Possible values are "true" and "false". This defaults to "false".

.mainScreen {
	padding-left: 5;
	padding-right: 5;
	view-type: shuffle;
	shuffleview-speed: 15;
}

MIDP/2.0 View

The MIDP/2.0 view arranges the items just like the MIDP/2.0 standard encourages it: the items are all lined up into one row until there is not enough space anymore or until an item with a "newline-after" or "newline-before" layout is inserted. It is activated by specifying the "midp2" view-type and supports no additional attributes.

.mainScreen {
	padding-left: 5;
	padding-right: 5;
	view-type: midp2;
}

The StringItem: Text, Hyperlink or Button

Texts have no specific attributes, but the padding-vertical attribute has a special meaning:

Attribute  Required  Explanation
padding-vertical No The space between the lines when there the text contains line-breaks.

Depending on the appearance mode of the text, either the "p", the "a" or the "button" selector is used for dynamic styles:

Dynamic Selector  Explanation
p The "p" selector is used for normal texts.
a The "a" selector is used for hyperlinks.
button The "button" selector is used for buttons.

The IconItem

Icons can only be used directly. Icons support following additional attributes:

Attribute  Required  Explanation
icon-image No The URL of the image, e.g. "icon-image: url(icon.png);". The keyword %INDEX% can be used for adding the position of the icon to the name, e.g. "icon-image: url(icon%INDEX%.png);". The image used for the first icon will be "icon0.png", the second icon will use the image "icon1.png" and so on.
icon-image-align No The position of the image relative to the text. Either "top", "bottom", "left" or "right". Defaults to "left", meaning that the image will be drawn left of the text.

This example uses the attributes for designing all icons:

icon {
	background: none;
	font-color: white;
	font-style: bold;
	icon-image: url( %INDEX%icon.png );
	icon-image-align: top;
}

When the icon-item has a "right" image align and the layout is set to "horizontal-expand", the image will be drawn directly at the right border of the item (with a gap specified by the padding-right attribute). Otherwise the image will be drawn right of the text with the specified horizontal padding.

The ChoiceItem

The ChoiceItem is used in lists and in choice groups. It supports following additional attributes:

Attribute  Required  Explanation
icon-image No The URL of the image, e.g. "icon-image: url(icon.png);". The keyword %INDEX% can be used for adding the position of the icon to the name, e.g. "icon-image: url(icon%INDEX%.png);". The image used for the first icon will be "icon0.png", the second icon will use the image "icon1.png" and so on.
icon-image-align No The position of the image relative to the text. Either "top", "bottom", "left" or "right". Defaults to "left", meaning that the image will be drawn left of the text.
choice-color No The color in which the check- or radio-box will be painted. Defaults to black.
checkbox-selected
radiobox-selected
No The URL of the image for a selected item. This will be used only when the type of the list or of the choice group is either exclusive or multiple. Default is a simple image drawn in the defined choice-color.
checkbox-plain
radiobox-plain
No The URL of the image for a not-selected item. This will be used only when the type of the list or of the choice group is either exclusive or multiple. Default is a simple image drawn in the defined choice-color. When "none" is given, no image will be drawn for not-selected items. Only the image for selected items will be drawn in that case.

Depending on the type of the corresponding list or choice group, different dynamic selectors are used by a choice item:

Type of List or ChoiceGroup  Selector
implicit listitem
exclusive radiobox
multiple checkbox
popup popup

The ChoiceGroup

A choice group contains several choice items. It supports the "focused-style" attribute:

Attribute  Required  Explanation
focused-style No The name of the style for the currently focused item.
columns No The number of columns. This can be used to layout the items in a table. Defaults to 1 column.
columns-width No Either "normal", "equal" or the width for each column in a comma separated list (e.g. "columns-width: 60,60,100;"). Defaults to "normal", meaning that each column uses as much space as the widest item of that column needs. The "equal" width leads to columns which have all the same width. The explicit list of column-widths results in the usage of those widths.
view-type No The view-type of this choice group.
popup-image No The URL to the image which should be shown in the closed popup-group. Per default a simple dropdown image will be used.
popup-color No The color for the arrow in the dropdown-image of a closed popup-group. Defaults to black.
popup-background-color No The color for the background in the dropdown-image of a closed popup-group. Defaults to white.

The Gauge

A Gauge shows a progress indicator. It supports following additional attributes:

Attribute  Required  Explanation
gauge-image No The URL of the image, e.g. "gauge-image: url(progress.png);". When no gauge-width is defined, the width of this image will be used instead.
gauge-color No The color of the progress bar. Defaults to blue.
gauge-width No The width of the gauge element in pixels. When no width is defined, either the available width or the width of the provided image will be used.
gauge-height No The height of the gauge element in pixels. Defaults to 10. When an image is provided, the height of the image will be used.
gauge-mode No Either "chunked" or "continuous". In the continuous mode only the gauge-color will be used, whereas the chunked mode intersects the indicator in chunks. The setting is ignored when an image is provided. Default value is "chunked".
gauge-gap-color No The color of gaps between single chunks. Only used in the "chunked" gauge-mode or when a gauge with an indefinite range is used. In the latter case the provided color will be used to indicate the idle state. Default gap-color is white.
gauge-gap-width No The width of gaps in pixels between single chunks. Only used in the "chunked" gauge-mode. Defaults to 3.
gauge-chunk-width No The width of the single chunks in the "chunked" gauge-mode.
gauge-show-value No Either "true" or "false". Determines whether the current value should be shown. This defaults to true for all definite gauge items.
gauge-value-align No Either "left" or "right". Defines where the current value of the gauge should be displayed. Defaults to "left", that is left of the actual gauge item.

The following example shows the use of the gauge attributes:

.gaugeStyle {
	padding: 2;
	border-color: white;
	gauge-image: url( indicator.png ); 
	gauge-color: rgb( 86, 165, 255 );
	gauge-width: 60;
	gauge-gap-color: rgb( 38, 95, 158 );
	/* these setting are ignored, since an image is provided:
	gauge-height: 8; 
	gauge-mode: chunked;
	gauge-gap-width: 5;
	gauge-chunk-width: 10;
	*/
}

When the Gauge item is used with an indefinite range, the gauge-gap-color will be used to indicate the idle state. When the "continuous running" state is entered and an image has been specified, the image will "fly" from the left to the right of the indicator.

The TextField

A TextField is used to get user input. You can choose whether the native input methods or a direct input mode should be used. When the native mode is activated, a new input screen will pop up for the user and special input modes like T9 or handwriting recognition can be used. When the direct input mode is used instead, no extra screen will be shown and J2ME Polish accepts the entered character directly. Please compare the following subsection Direct Input Mode for more information.

The TextField supports following additional attributes:

Attribute  Required  Explanation
textfield-width No The minimum width of the textfield-element in pixels.
textfield-height No The minimum height of the textfield-element in pixels. Defaults to the height of the used font.
textfield-direct-input No Defines whether the direct input mode should be activated. Possible values are either "false" or "true". By default the direct input mode is deactivated ("false").
textfield-caret-color No The color of the caret which indicates the editing position. This defaults to the color of the used font.
textfield-caret-char No The character which indicates the editing position. This defaults to "|".
textfield-show-length No Determines whether the length of the entered text should be shown during the editing of this field. This has an effect only when the direct input mode is used.

The following example shows the use of the TextField attributes:

.inputStyle {
	padding: 2;
	background-color: white;
	border-color: black;
	textfield-height: 15; 
	textfield-width: 40;
	textfield-direct-input: true;
	textfield-caret-color: red;
	textfield-caret-char: >;
	textfield-show-length: true;
}

TextField-Commands

A TextField adds the "Clear"- and "Delete"-commands to the menu by default. The names of these commands can be changed easily. If you want to suppress the commands completely, the "polish.TextField.suppressCommands"-variable has to be set:

<variable name="polish.TextField.suppressCommands" value="true"/>

Direct Input Mode

The direct input mode can be activated for TextFields as well as for TextBoxes using the CSS-attribute "textfield-direct-input" or by defining the preprocessing-variable "polish.TextField.useDirectInput" in the build.xml file:

<variable name="polish.TextField.useDirectInput" value="true"/>

When the direct input mode is used, no extra screen will be used for editing the text and all designing possibilities of J2ME Polish can be used. When the TextField is used within a Form, the associated ItemStateListener will be notified after each change of the text.

On stylus-based devices, this mode should not be used since these devices often rely on native input methods like handwriting recognition. This can be ensured by setting the preprocessing variable only for devices which have no pointer-events:

<variable name="polish.TextField.useDirectInput" value="true" if="!polish.hasPointerEvents"/>

The direct input should not be used for editing longs texts (i.e. TextBoxes), since T9 and similar input helpers cannot be used in this mode.

The user can change the input mode from lowercase ("abc") to initial-letter uppercase ("Abc") to uppercase ("ABC") and to numeric ("123"). The current input mode is shown below the title in an extra StringItem. This item can be designed using the predefined CSS-style "info":

info {
	padding-right: 10;
	background: none;
	border-color: black;
	font-style: plain; 
	font-face: proportional; 
	font-size: small; 
	font-color: fontColor; /* a color defined in the "colors" section */
	layout: right;
}

The info-item can be deactivated globally by setting the "polish.TextField.showInputInfo"-variable to "false":

<variable name="polish.TextField.showInputInfo" value="false" />

Next to using the CSS-attributes "textfield-caret-color", "textfield-caret-char" and "textfield-show-length" the behavior of the direct input mode can be adjusted using several preprocessing variables. Especially the available character can be changed, which can be necessary for localizing the direct input.

Following variables can be set:

Variable  Default  Explanation
polish.TextField.InputTimeout "1000" The timeout in milliseconds after which a chosen character is inserted into the text automatically.
polish.TextField.showInputInfo "true" Defines whether the box showing the current input mode (e.g. "123", "Abc", "abc", "ABC") should be shown at all. You can deactivate the box globally by setting the "polish.TextField.showInputInfo" variable to "false".
polish.key.ChangeInputModeKey Varying The key which is used for changing the input mode between lowercase ("abc"), uppercase ("ABC"), initial-letter uppercase ("Abc") and numeric ("123"). On Sony-Ericsson devices Canvas.KEY_STAR (42), on Motorola devices Canvas.KEY_NUM0 (48) and on all other devices Canvas.KEY_POUND (35) is used.
polish.TextField.charactersKey1 ".,!?:/@_-+1" The characters which are available when the key "1" is pressed.
polish.TextField.charactersKey2 "abc2" The characters which are available when the key "2" is pressed. It might be useful to add local specific umlauts here.
polish.TextField.charactersKey3 "def3" The characters which are available when the key "3" is pressed.
polish.TextField.charactersKey4 "ghi4" The characters which are available when the key "4" is pressed.
polish.TextField.charactersKey5 "jkl5" The characters which are available when the key "5" is pressed.
polish.TextField.charactersKey6 "mno6" The characters which are available when the key "6" is pressed.
polish.TextField.charactersKey7 "pqrs7" The characters which are available when the key "7" is pressed.
polish.TextField.charactersKey8 "tuv8" The characters which are available when the key "8" is pressed.
polish.TextField.charactersKey9 "wxyz9" The characters which are available when the key "9" is pressed.
polish.TextField.charactersKey0 " 0" The characters which are available when the key "0" is pressed. On Motorola devices this key is used for switching the input mode.
polish.TextField.charactersKeyStar ".,!?:/@_-+" The characters which are available when the key "*" is pressed. On Motorola devices this key is used for entering spaces (" ").
polish.TextField.charactersKeyPound (none) The characters which are available when the key "#" is pressed. On Sony-Ericsson devices this key is used for entering spaces (" ").

The DateField

A DateField is used to enter date or time information. Currently the input is done with the use of the native functions, so that special input modes can be used (like T9). The DateField supports following additional attributes:

Attribute  Required  Explanation
datefield-width No The minimum width of the datefield-element in pixels.
datefield-height No The minimum height of the datefield-element in pixels. Defaults to the height of the used font.

The following example shows the use of the DateField attributes:

.inputStyle {
	padding: 2;
	background-color: white;
	border-color: black;
	datefield-height: 15; 
	datefield-width: 40;
}

The appearance of the datefield can also be adjusted using the preprocessing variable "polish.DateFormat", which can be defined in the <variables> section of the J2ME Polish task:

  • <variable name="polish.DateFormat" value="us" />: The US standard of MM-DD-YYYY is used, e.g. "12-24-2004".
  • <variable name="polish.DateFormat" value="de" />: The German standard of DD.MM.YYYY is used, e.g. "24.12.2004".
  • <variable name="polish.DateFormat" value="fr" />: The French standard of DD/MM/YYYY is used, e.g. "24/12/2004".
  • All other settings: The ISO 8601 standard of YYYY-MM-DD is used, e.g. "2004-12-24".

The Ticker

A Ticker scrolls a text over the current screen. In J2ME Polish the ticker is situated right above the menu-bar on the bottom of a screen. Following attribute is supported:

Attribute  Required  Explanation
ticker-step No The number of pixels by which the ticker is shifted at each update. Defaults to 2 pixels.

In the menu bar the commands reside that have been added to a screen. This bar can be designed using the predefined "menu" style. The font-settings in this style are used to render the actual commands, and the CSS attrbute "menubar-color" defines the color of the menu-bar. The color can have any setting including "transparent", which is useful when the background of the corresponding screen should be shown. The "menubar-color" defaults to white by the way. When this attribute is also defined in a screen-style, it will override the setting in the "menu" style for the corresponding screen. Let me demonstrate:

menu {
	padding: 5;
	background: none;
	/* The design of the commands in the menu-bar: */
	font-style: bold; 
	font-face: proportional; 
	font-size: small; 
	font-color: red;
	/* The color of the menubar background:  */
	menubar-color: black;
}

.myScreenStyle {
	background-image: url( bg.png );
	/* use a transparent menubar for screens with this style,
         so that the bg.png image is shown in the menubar as well: */
	menubar-color: transparent;
}

When there is more than one item available in the menu, an "Options" menu will be shown automatically, which opens the real menu when pressed (like shown in the following figures).

The closed menu.The opened menu.

The items in the opened menu are designed using the predefined "menuitem" style. The background and the border of the opened menu is designed using the "menu" style. You can change the names of the "Options", "Select" and "Cancel" commands by the way, this is explained in the localization chapter.

The Extended Menu Bar

You can use the extended menu bar in cases when the design possibilities of the normal menu bar are not sufficient for you. In contrast to the normal menu bar, the extended menu bar is a full blown item and can, therefore, be designed just like any other item. The price for using the extended menu bar is to have an additional 2 kb class file in your JAR.

For using the extended menu-bar instead of the normal one, you need to set the "polish.MenuBar.useExtendedMenuBar" preprocessing variable to "true" in the <variables> section of the build.xml file:

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

The menu bar can be designed using the predefined styles "menubar", "leftcommand" and "rightcommand":

Style  Description
menubar This design of the menu-bar itself.
leftcommand Designs the left command ("Options", "Select" and user-defined commands). Accepts all attributes of the IconItem.
rightcommand Designs the right command ("Cancel" and user-defined BACK or CANCEL commands). Accepts all attributes of the IconItem.

The menubar-style offers following additional attributes:

Attribute  Required  Explanation
menubar-options-image No Defines the image-URL for the options-image of the extended menubar.
menubar-select-image No Defines the image-URL for the select-image of the extended menubar.
menubar-cancel-image No Defines the image-URL for the cancel-image of the extended menubar.
menubar-show-image-and-text No Determines whether the text should be shown as well in the menubar, when an image has been defined for the corresponding action. Defaults to "false".

The following example demonstrates the design of the extended menu-bar:

menubar {
	margin-top: 0;
	margin-bottom: 0;
	margin-left: 2;
	margin-right: 2;
	padding: 0;
	background: none;
	menubar-options-image: url( options.png );
	/*
	menubar-select-image: url( checked.png );
	menubar-cancel-image: url( cancel.png );
	menubar-show-image-and-text: true;
	*/
}

leftcommand {
	padding-horizontal: 4;
	padding-bottom: 0;
	font-color: fontColor;
	font-style: bold;
	background: none;
}

rightcommand {
	padding-horizontal: 4;
	padding-bottom: 0;
	font-color: fontColor;
	font-style: bold;
	background: none;
}

Tabbed Form

The tabbed form can be designed like any Form and accepts the very same CSS-attributes. Additionally the predefined styles "tabbar", "activetab" and "inactivetab" can be used to design the additional elements of a tabbed form.

Style  Description
tabbar This style designs the tab-bar of a TabbedForm.
activetab Designs the currently active tab of a TabbedForm.
inactivetab Designs all tabs but the currently selected one of a TabbedForm.

You can set the color of the scrolling indicator within the tabbar-style with the tabbar-scrolling-indicator-color attribute:

tabbar {
	background-color: white;
	layout: expand;
	padding-bottom: 0;
	tabbar-scrolling-indicator-color: black;
}

activetab {
	background-type: round-tab;
	background-color: silver;
	background-arc: 8;
	font-color: white;
	padding-left: 10;
	padding-right: 8;
}

inactivetab {
	padding-left: 6;
	padding-right: 4;
	margin-left: 2;
	margin-right: 2;
	background-type: round-tab;
	background-color: gray;
	background-arc: 8;
	font-color: silver;
}

The de.enough.polish.ui.TabbedForm supports all Form methods and some additional methods for handling the tabs:

Method  Example  Explanation
TabbedForm( String title, String[] tabNames, Image[] tabImages ) //#style myTabbedForm
TabbedForm form = new TabbedForm( "Hello", new String[] {"First Tab", "another tab"}, null );
Creates a new TabbedForm.
append( int tabIndex, Item item ) form.append( 2, myStringItem ); Adds the item to the specified tab. The first tab has got the index 0.
set( int tabIndex, int itemIndex, Item item ) form.set( 2, 1, myStringItem ); Sets the item to the specified index on the given tab.
delete( int tabIndex, Item item ) form.delete( 2, myStringItem ); Deletes the given item from the specified tab.

The following listing demonstrates the usage of the TabbedForm:

package de.enough.polish.demo;

import javax.microedition.lcdui.Choice;
import javax.microedition.lcdui.ChoiceGroup;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.DateField;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.StringItem;
import javax.microedition.lcdui.TextField;
import javax.microedition.lcdui.Item;
import javax.microedition.lcdui.ItemStateListener;

import de.enough.polish.ui.TabbedForm;

public class TabbedFormDemo implements ItemStateListener {
	

	private TextField nameField;

	public TabbedFormDemo(  DemoMidlet midlet, Display display, Command returnCmd ) {
		String[] tabNames = new String[]{ "Input", "Choice", 
			"Connection", "Test", "Settings", 
			"Internet" };
		//#style tabbedScreen
		TabbedForm form = new TabbedForm("TabbedDemo", tabNames, null );
		//#style label
		StringItem label = new StringItem( null, "name:" );
		form.append( 0, label );
		//#style input
		this.nameField = new TextField( null, "Robert", 
			30, TextField.ANY | TextField.INITIAL_CAPS_WORD );
		form.append(0, this.nameField);
		//#style label
		label = new StringItem( null, "birthday:" );
		form.append( 0, label );
		//#style input
		DateField birthdate = new DateField( null, DateField.DATE );
		form.append( 0, birthdate );
		
		//#style label
		label = new StringItem(null, "What kind of animals do you like:");
		form.append( 1, label );
		//#style multipleChoice
		ChoiceGroup choice = new ChoiceGroup( null, Choice.MULTIPLE );
		//#style choiceItem
		choice.append("dogs", null);
		//#style choiceItem
		choice.append("cats", null);
		//#style choiceItem
		choice.append("birds", null);
		form.append(1, choice);
		
		//#style label
		label = new StringItem(null, "Connection:");
		form.append( 2, label );
		//#style multipleChoice
		choice = new ChoiceGroup( null, Choice.MULTIPLE );
		//#style choiceItem
		choice.append("ISDN", null);
		//#style choiceItem
		choice.append("DSL", null);
		//#style choiceItem
		choice.append("Cable", null);
		form.append(2, choice);
		

		
		form.addCommand(returnCmd);
		form.setCommandListener(midlet);
		form.setItemStateListener( this );
		display.setCurrentItem( choice );
	}

	public void itemStateChanged(Item item) {
		if (item instanceof TextField) {
			TextField field = (TextField) item;
			System.out.println("Item State Changed: " + field.getString() );
		} else {
			System.out.println("Item State Changed: " + item );
		}
	}
}