CSS Basics

J2ME Polish uses the same syntax for CSS declarations as web browsers.

Structure of a CSS Declaration

.myStyle   {   font-color: black;   }

SELECTOR/      ATTRIBUTE   VALUE
NAME

Every style starts with the selector followed by an opening curved parenthesis, a number of attribute-value pairs and a closing curved parenthesis. The selector can consist of several item-names and contain an "extends" clause. Each attribute-value pair needs to be finished by a semicolon.

Naming and Style Types

J2ME Polish differentiates between different style types:

Static styles: start their name with a dot (e.g. .mainMenuItem) and are used with the //#style preprocesing directive, e.g. //#style mainMenuItem.
Predefined styles: are used by some UI elements, examples include title, menubar or menu. In contrast to static styles, predefined ones don't start with a dot.
Dynamic styles: are resolved during runtime when a UI element has no associated style. Examples include form for designing Forms or form p for designing StringItems within forms. Dynamic names do not start with a dot.
Pseudo styles: can be used to extend static or predefined styles. Examples are .mainMenuItem:hover or .mainMenuItem:pressed. Pseudo styles use a colon between the style's basic name and its pseudo name.

Styles can use any names, as long as they consist of alphanumeric and underline (_) characters only. Names are not case-sensitive. All Java keywords like "class", "int" or "boolean" etcetera are not allowed as style names.

Predefined Styles

There are several predefined styles which you can look up in the visual guide for the respective components. Some commonly used predefined styles are:

title: designs the title of screens, can be overridden using the title-style attribute that points to a static style.
menubar: designs the menubar of screens when using the extended menubar implementation, can be overriden using the menubar-style that points to a static style.
scrollbar: designs the scrollbar for screens.
focused: the default style for focused UI elements that do not specify a [style-name]:hover pseudo style.

Static Styles

Static styles are applied with the #style directive in your Java code - note that the the style name needs to start with a dot in the polish.css file, but not necessarily in the #style directive:

//#style mainScreen
Form form = new Form("Hello World");
//#style info
form.append("Welcome to your first app.");

In the polish.css you need to define the corresponding styles:

.mainScreen {
	background-color: #ddd;
	padding-left: 10%;
	padding-right: 10%;
}

.info {
	font-style: italic;
	font-color: #333;
}

Dynamic Styles

Dynamic styles are resolved during runtime. They are good for designing applications that don't use #style preprocessing directives. However since they resolved during runtime they are not as effective as static styles. In general we don't recommend the usage of dynamic styles, therefore.

Pseudo Styles

Pseudo styles are used to design UI elements in different states, e.g. when they are focused. Pseudo styles use a colon between the basic style name and the pseudo style, for example .myItem:hover or .myItem:pressed. Pseudo styles inherit all settings of the basic element There are a couple of pseudo styles available:

:hover

:hover designs the focused state of the UI element. You should strive to keep the :hover state of a UI element the same size as in the normal style, otherwise UI elements will seem to 'jump' around when moving the focus. Here's an example in which we use a margin in the unfocused state to compensate for a border in the focused state:

.mainMenuItem {
	margin: 2px;
	font-color: #333;
	layout: expand;
}
.mainMenuItem:hover {
	margin: 0px;
	font-color: #eee;
	background-color: #333;
	border-color: #600;
	border-width: 2px;
}

:pressed

:pressed defines the design for an element when it is pressed, meaning the user selects it by holding down a pointer or a key. Typically the :pressed style is applied when the element is already focused, so you either need to make sure that you copy the :hover settings manually or nest styles, like .mainMenuItem:hover:pressed. This is not true for all cases, e.g. leftcommand etc are never focused, but they have a pressed style: leftcommand:pressed:

leftcommand {
	font-style: bold;
	font-color: #00aeef;
}
leftcommand:pressed {
	font-color: #fff;
}
rightcommand extends leftcommand {
	layout: right;
}
rightcommand:pressed {
	font-color: #fff;
}
middlecommand extends leftcommand {
	layout: center;
}
middlecommand:pressed {
	font-color: #fff;
}

:visited

:visited. Use the :visited style for changing the design of a UI item after its default command has been triggered. Here's an example for links within the browser:

.browserlink {
	padding-left: 4%;
	padding-right: 4%;
	layout: expand;
	font {
		style: bold;
		color: #00aeef;
	}
}
.browserlink:hover {
	font-color: #fff;
	background-color: #f26522;
}
.browserlink:pressed {
	background-color: #f26522;
	font-color: #333;
}
.browserlink:visited {
	font-color: #999;
}
.browserlink:hover:visited {
	font-color: #999;
}

:landscape and :portrait

:landscape allows you to change the design for landscape screen orientations. This is useful for differentiating your design between portrait and landscape modes, e.g. displaying icon texts in landscape mode but not in portrait mode:

.tabIcon {
	margin: 1px;
	padding: 2px;
	icon-image: url( Tab%INDEX%.png );
	icon-image-align: top;
	max-width: 25%;
	font-bitmap: url( arialsmall.bmf );
	layout: expand | center | vertical-center;
}

.tabIcon:hover {
	padding: 1px;
	background {
		type: round-rect;
		arc: 8;
		color: #f1f1f1;
	}
	border {
		type: round-rect;
		arc: 8;
		color: #aeaeae;
	}
	icon-image: url( TabFoc%INDEX%.png );
}

.tabIcon:landscape {
	text-visible: false;
}

.tabIcon:landscape:hover {
	padding: 1px;
	background {
		type: round-rect;
		arc: 8;
		color: #f1f1f1;
	}
	border {
		type: round-rect;
		arc: 8;
		color: #aeaeae;
	}
	icon-image: url( TabFoc%INDEX%.png );
}

:portrait works the same as :landscape pseudo styles, but only for portrait resolutions.

You can also nest pseudo styles, e.g. for designing the :visited style of .myItem:hover just define the style .myItem:hover:visited.

Here's the :landscape pseudo style in action:

See the :visited pseudo style here:

Locking the Screen Orientation

This is a bit off-topic here, but it relates to landscape and portrait modes:
You can lock the screen orientation on some devices using vendor specific JAD attributes. Define these attributes within the <jad> section in your build.xml script:

<jad>
    <attribute name="Nokia-MIDlet-App-Orientation" value="portrait" />   <!-- Nokia -->
    <attribute name="LGE-MIDlet-Display-Mode" value="portrait" />  <!-- LG -->
    <attribute name="MIDlet-ScreenMode" value="Portrait" /> <!-- Samsung -->
</jad>

Grouping of Attributes

Attributes can be grouped for easier handling:

.mainItem {
	font-color: black;
	font-size: medium;
	font-style: italic;
	font-face: system;
}

The above code is equivalent with the following:

.mainItem {
	font {
		color: black;
		size: medium;
		style: italic;
		face: system;
	}
}

The grouping makes the declarations better readable for humans.

Referring to Other Styles

When another style is referred, the dots of static styles do not need to be written. Styles can be referred in attributes or after the extends keyword in the selector of a style.

.mainItem {
	font-color: black;
	font-size: medium;
}

.menuItem extends mainItem {
	font-color: #333;
}

Comments

Comments can be inserted at any place and start with "/*" and stop with "*/". Everything between these boundaries is ignored:

/**
  * this style designs the items in the main screen, 
  * use //#style mainItem to bind this style to a UI element in your Java code: 
  */
.mainItem {
	/* defining the color of a font: */
	font-color: black;
	/* sizes are small, medium and large: */
	font-size: medium;
	/* styles are plain, bold, italic or underlined, combine them using | or & : */
	font-style: italic;
	/* the face can either be system, proportional or monospace: */
	font-face: system;
}

CSS Box Model

J2ME Polish supports the same box model as HTML browsers:
CSS box model
The margin describes the gap to other UI elements. The padding describes the gap between the border of the item and the actual content of that item. The margin defaults to 0 pixels, whereas any padding defaults to 1 pixel. Next to the left, right, top and bottom padding, J2ME Polish also knows the vertical and the horizontal paddings. These define the gaps between different content sections. The gap between the label of an item and the actual content is defined by the horizontal padding. Another example is an icon (IconCustomItem/IconItem), which consists of an image and a text. Depending on the align of the image, either the vertical or the horizontal padding fills the space between the icon-image and the icon-text. In the following example, the top, right and bottom margin is 5 pixels, whereas the left margin is 10 pixels:

.myStyle {
	margin: 5px;
	margin-left: 10px;
	font-color: black;
}

Percentage values can also be used. Like in the standard CSS 2.1, percentage values are calculated relative to the available width of the corresponding UI element, even for top and bottom values.

.myStyle {
	padding: 2.8%;
	padding-left: 2%;
	padding-right: 2%;
	padding-vertical: 1%;
	font-color: black;
}

Structure of polish.css

You specify the design your application in the polish.css file, which by default is located in resources/polish.css. This file can contain different sections:

colors: The colors section contains the definition of colors.
fonts: The fonts section contains font definitions.
backgrounds: The backgrounds section contains background definitions that are referenced in other styles.
borders: The borders section contains definition of borders.
rest: The rest of polish.css contains the actual style definitions.

The defined colors, fonts, backgrounds and borders can be referenced in the actual style definitions. This makes changes very easy, since you need to change the value only in one position.

The Layout Attribute

The layout attribute defines how the affected item should be aligned and laid out. Possible layout values are for example left, right or center. All layout values of the MIDP 2.0 standard can be used:

Layout	Alternative-Names	Explanation
left	-	The affected items should be left-aligned.
right	-	The affected items should be right-aligned.
center	horizontal-center, hcenter	The affected items should be centered horizontally.
expand	horizontal-expand, hexpand	The affected items should use the whole available width (i.e. should fill the complete row).
shrink	horizontal-shrink, hshrink	The affected items should use the minimum width possible.
top	-	The affected items should be top-aligned.
bottom	-	The affected items should be bottom-aligned.
vcenter	vertical-center	The affected items should be centered vertically.
vexpand	vertical-expand	The affected items should use the whole available height (i.e. should fill the complete column).
vshrink	vertical-shrink	The affected items should use the minimum height possible.
newline-after	-	Items following an item with a newline-after layout should be placed on the next line. This can be used for labels or for item within a `midp2` `view-type`, for example.
newline-before	-	The affected items should always start on a new line (when there are any items in front of it). This can be used for labels or for item within a `midp2` `view-type`, for example.

Layout values can also be combined, using either the "||", "|", "or" or "and" operators. All operators result in the same combination. An item can be centered and using the whole available width with following example:

.myStyle {
	layout: center | expand;
}

Colors

Colors can be defined in the colors section and in each attribute which ends on "-color", e.g. "font-color", "border-color" etc.

Predefined Colors

The 16 standard windows colors are predefined:

Name	Hex-Value	Name	Hex-Value
white	#FFFFFF	yellow	#FFFF00
black	#000000	maroon	#800000
red	#FF0000	purple	#800080
lime	#00FF00	fuchsia	#FF00FF
blue	#0000FF	olive	#808000
green	#008000	navy	#000080
silver	#C0C0C0	teal	#008080
gray	#808080	aqua	#00FFFF

Another predefined color is transparent, which results in an transparent area. transparent is only supported by some UI elements like a image background.

The colors Section

The colors section of the polish.css file can contain colors, which can be referenced in the styles, fonts, border and background sections. You can even overwrite the predefined colors to confuse other designers!

colors {
	bgColor: #50C7C7;
	bgColorFocused: #50D9D9;
	textColor: #7F7F7F;
}

How to Define Colors

A color can be defined in many different ways:

.myStyle {
	font-color: white; 	/* the name of the color */
	border-color: #80FF80; 	/* a rgb hex value */
	start-color: #F00; 	/* a short rgb-hex-value - this is red */
	menu-color: #7F80FF80; 	/* an alpha-rgb hex value */
	background-color: rgb( 255, 50, 128 );  /* a rrr,ggg,bbb value */
	fill-color: rgb( 100%, 30%, 50% ); 	    /* a rgb-value with percentage */
	label-color: argb( 128, 255, 50, 128 ); /* a aaa, rrr, ggg, bbb value */
}

Color names refer to one of the predefined colors or a color which has been defined in the colors-section:

color: black; or 
color: darkBackgroundColor;

The hex-value defines a color with two hexadecimal digits for each color (RRGGBB). Additionally the alpha blending-component can be added (AARRGGBB).

color: #FF000;     /*  defines red.                    */
color: #7FFF0000;  /*  defines a half transparent red. */

The shortened hex-value defines a color by a RGB-value in hexadecimal. Every digit will be doubled to retrieve the full hex-value:

color: #F00; is equivalent with color: #FF0000; 
color: #0D2; is equivalent with color: #00DD22;  /* and so on. */

A rgb-value starts with "rgb(" and then lists the decimal value of each color from 0 up to 255:

color: rgb( 255, 0, 0 );  /*  defines red.            */
color: rbg( 0, 0, 255);   /*  defines blue and so on.  */

Alternatively percentage values can be used for rgb-colors:

color: rgb( 100%, 0%, 0% );         /* defines red as well as */
color: rgb( 100.00%, 0.00%, 0.00% );

Alpha-RGB colors can be defined with the argb()-construct:

color: argb( 128, 255, 0, 0 );

defines a half transparent red. For the argb-construct percentage values can be used as well.

Alpha Blending

Colors with alpha blending can be defined with hexadecimal or argb-definitions (see above). An alpha value of 0 results in fully transparent pixels, whereas the value FF (or 255 or 100%) results in fully opaque pixels. Some devices support values between 0 and FF, which results in translucent colors. Colors with a specified alpha channel can only be used by specific GUI items. Please refer to the documentation of the specific design attributes.

Text Rendering

The base class for rendering texts in J2ME Polish is a StringItem, please refer to the String Item documentation for all design options.

The most important settings are:

Attribute	Possible Values	Explanation
font-color	Reference to a color or direct declaration of the color.	Depending on the number of colors the device supports, colors can look differently on the actual device.
font-face	system (default, normal)	The default font-face which is used when the font-face or label-face attribute is not set.
	proportional	A proportional face. This is on some devices actually the same font-face as the system-font.
	monospace	A font-face in which each character has the same width.
font-size	small	The smallest possible font.
	medium (default, normal)	The default size for texts.
	large (big)	The largest possible font size.
	px	When you specify the size in pixel like `font-size: 22px;` J2ME Polish will pick the most appropriate font instead on MIDP devices. BlackBerry and Android platforms support the pixel size values directly.
font-style	plain (default, normal)	The default style.
	bold	A bold thick style
	italic (cursive)	A cursive style.
	underlined	Not really a style, just an underlined text.
font-bitmap	The name of the bitmap font.	With the `bitmap` attribute a bitmap font can be used instead of the system, proportional and monospace fonts. Please note that bitmap fonts cannot be changed in neither size or style. You can only change the color of a bitmap font when it has been saved with a black color.
text-effect	The name of effect for the text.	You can apply a large number of text-effects.

Access Styles Programmatically

You can apply and read styles programmatically in several ways:

#style directive: use the style directive to apply static styles in the constructor of UI elements or in many screen methods or in UiAccess.setStyle(Item, Style):
```
//#style mainMenuItem
UiAccess.setStyle( myMenuItem );
```
To load styles dynamically use StyleSheet.getStyle(String name) to access styles by their name. Please note that J2ME Polish optimizes away styles that are not used within your project directly. To force the inclusion of a style that is accessed only programmatically, you need to define it's always-include CSS property:
```
.menubarFacebook {
	always-include: true;
	...
}
```
To create styles dynamically just use the Style constructor and add settings using the .addAttribute(String name, Object property) method. Note that the name of your style needs to end on style, since J2ME Polish replaces CSS attribute names with short IDs during the build process using preprocessing.
```
Style myStyle = new Style();
myStyle.addAttribute("padding", new Dimension("20%") );
myStyle.addAttribute("font-color", new Color(0x333333) );
myStyle.background = new SimpleBackground( new Color(0xffdddd) );
```

Sample polish.css

Let's have a look at a full example:

colors {
	fontColor: #333;
	fontColorFocused: #ddd; 
	fontColorPressed: #600;
}

backgrounds {
	screenBg {
		type: vertical-gradient;
		top-color: #fff;
		bottom-color: #ccc;
	}
}

.mainScreen {
	background: screenBg;
}

.mainItem {
	font-color: fontColor;
	font-style: bold;
	layout: expand;
	padding-left: 10%;
}
.mainItem:hover {
	font-color: fontColorFocused;
	background-color: #333;
}
.mainItem:pressed {
	font-color: fontColorPressed;
	background-color: #333;
}

title {
	background-color: #333;
	font-color: fontColorFocused;
	layout: expand | center;  
}

Products - J2ME Polish