Create New Backgrounds

Realize your vision by creating a background. You can use your own background for any item or screen.

Concepts of Backgrounds

Realizing your own background is fairly simple:

Implement your background by extending de.enough.polish.ui.Background.
Register the background in ${polish.home}/custom-css-attributes.xml.
Apply your background by specifying the background CSS attribute in your project's polish.css file.

Implementing your Background

Create your own background by extending de.enough.polish.ui.Background. You only need to implement the paint( int x, int y, int width, int height, Graphics g ) method.
You can override the releaseResources() method for freeing any stray resources when your background is not used anymore.

In this example we implement a very simple background that paints a triangle.
the finished triangle background
Note that the triangle requires a color and can point into four different directions (to the top, bottom, left or right), so the constructor reads:

public TriangleBackground( int color, int orientation )

Also note that the Graphics.fillTriangle() method is only available for MIDP 2.0 and higher devices, so we use DrawUtil.fillTriangle() instead on other devices:

//#if polish.midp2
	g.fillTriangle( x1, y1, x2, y2, x3, y3 );
//#else
	DrawUtil.fillTriangle(x1, y1, x2, y2, x3, y3, g);
//#endif

Now for all the gory details:

//#condition polish.usePolishGui
package de.enough.polish.ui.backgrounds;

import javax.microedition.lcdui.Graphics;

import de.enough.polish.ui.Background;
import de.enough.polish.util.DrawUtil;

/**
 * Paints a filled rectangle as a background in a specific color and orientation.
 */
public class TriangleBackground 
extends Background 
{
	private final static int TOP = 0; 
	private final static int BOTTOM = 1;
	private final static int LEFT = 2;
	//private final static int RIGHT = 3; not used
	
	private int color;
	private final int orientation;
	

	/**
	 * Creates a new triangle background.
	 * 
	 * @param color the color of the background in RGB, e.g. 0xFFDD11
	 * @param orientation the orientation, either TOP, BOTTOM, LEFT, RIGHT
	 */
	public TriangleBackground( int color, int orientation ) {
		this.color = color;
		this.orientation = orientation;
	}

	
	/* (non-Javadoc)
	 * @see de.enough.polish.ui.Background#paint(int, int, int, int, javax.microedition.lcdui.Graphics)
	 */
	public void paint(int x, int y, int width, int height, Graphics g) {
		g.setColor( this.color );
		int x1, y1, x2, y2, x3, y3;
		switch (this.orientation) {
		case TOP:
			x1 = x + (width >>> 1);
			y1 = y;
			x2 = x;
			y2 = y + height;
			x3 = x + width;
			y3 = y2;
			break;
		case BOTTOM:
			x1 = x + (width >>> 1);
			y1 = y + height;
			x2 = x;
			y2 = y;
			x3 = x + width;
			y3 = y2;
			break;
		case LEFT:
			x1 = x;
			y1 = y + (height >>> 1);
			x2 = x + width;
			y2 = y;
			x3 = x2;
			y3 = y + height;
			break;
		default: // == RIGHT
			x1 = x + width;
			y1 = y + (height >>> 1);
			x2 = x;
			y2 = y;
			x3 = x;
			y3 = y + height;
		}
		//#if polish.midp2
			g.fillTriangle( x1, y1, x2, y2, x3, y3 );
		//#else
			DrawUtil.fillTriangle(x1, y1, x2, y2, x3, y3, g);
		//#endif
	}

}

Registering Your Background

After implementing your background you need to register it in ${polish.home}/custom-css-attributes.xml:

<attribute name="background">
	<mapping from="triangle" to="de.enough.polish.ui.backgrounds.TriangleBackground">
		<param name="color" type="color" primitive="true" default="white" />
		<param name="orientation" type="integer" values="top,bottom,left,right" primitive="true" default="top" />
	</mapping>
</attribute>

Background Parameters

Along with the background class you need to register all parameters of your constructor, so that J2ME Polish can automatically instantiate your background. For each parameter you add one <param> element. Parameters can have different types - some types are additionally available as primitives as well as objects. Take for example java.lang.Integer and int. Both are modeled using the integer type, but for using the primitive version, we additionally need to specify primitive="true". Parameter types that are available as primitives as well as objects include integer, color, boolean and char:

<param name="color" type="color" primitive="true" default="white" />

integer paramters can be additionally populated using strings, when only some strings are allowed. In that case you have to specify the allowed values - the first value will be tranformed to 0, the second one to 1 and so on. This technology helps to minimize the memory and performance impact of UI elements:

<param name="orientation" type="integer" values="top,bottom,left,right" primitive="true" default="top" />

Last but not least you can specify default values for parameters using the default attribute.

Background Parameter Types

The following table shows you the available parameter types that you can use for your background constructors.

Type	Supports Primitive	Additional Attributes	Example	Explanation
integer	true	`values`: comma separated allowed string values that are transformed into integer values.	`<param name="orientation" type="integer" values="top,bottom,left,right" primitive="true" default="top" />`	An integer value - either `int` or `java.lang.Integer`.
color	true	`translucent`: true when corresponding color can be translucent (ARGB).	`<param name="color" type="color" translucent="true" primitive="true" default="#8f00" />`	A color value - either `int` or `de.enough.polish.ui.Color`. In the polish.css file you can specify colors in different ways, e.g. `argb( 70%, 100%, 0%, 0%)` or `#a833`.
string	false	n/a	`<param name="format" type="string" default="hh:mm:ss" />`	A string value.
char	true	n/a	`<param name="first-letter" type="char" default="a" />`	A character value, either `char` or `java.lang.Character`.
boolean	true	n/a	`<param name="expand" type="boolean" default="false" />`	A boolean value, either `boolean` or `java.lang.Boolean`.
image-url	false	n/a	`<param name="image" type="image-url" />`	The URL of an image, is provided as a String value containing the path, e.g. `"/myimage.png"`.

Using Your Background

After registration you can apply your background to any item's or screen's style in your polish.css file:

.myItem {
	padding: 3;
	background {
		type: triangle;
		color: red;
		orientation: bottom;
	}
}

That's it - you've done it!
the finished triangle background

Animations in Backgrounds

You can realize animations by overriding either public boolean animated() or public void animate(Screen screen, Item parent, long currentTime, ClippingRegion repaintRegion) in your implementation:

public boolean animate() causes a refresh of the whole background area when you return true.
public void animate(Screen screen, Item parent, long currentTime, ClippingRegion repaintRegion) allows you to refresh only parts of your background or an area that is outside of the parent item's original area. You have to specify the area that requires a refresh by calling repaintRegion.addRegion( int x, int y, int width, int height ) or by calling parent.addRelativeToBackgroundRegion( repaintRegion, x, y, width, height ). You can request a full refresh by calling parent.addRelativeToBackgroundRegion( repaintRegion, 0, 0, parent.getBackgroundWidth(), parent.getBackgroundHeight() ).

If you want to trigger your animation only when the corresponding item or screen is made visible or when a focused/hover style along with your background moves to a new item, you can override public void showNotify() and public void hideNotify() in your implementation.

For a complete animation example, please refer to the border documentation.

Username:
Password: