J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

StringItem

The StringItem is responsible for viewing text and is used as a basis for many J2ME Polish components like TextFields, screen titles, screen tickers, or item labels.

Design

A StringItem with an alien-glow text-effect

You can vary the design of StringItems greatly by using bitmapfonts or text-effects, the above design uses the following settings:

title {
        //#if polish.midp2 and polish.hasFloatingPoint
                text-effect: alien-glow;
        //#endif
        layout: horizontal-center | horizontal-expand;
        font {
                face: proportional;
                size: large;
                style: bold;
                color: #fff;
        }
        background-color: #fff;
}

On MIDP devices there are 3 different font sizes available: small, medium and large. When you specify the size in pixel like font-size: 22px; J2ME Polish will pick the most appropriate font instead. BlackBerry and Android platforms support the pixel size values directly.

Here's a list of all StringItem specific design attributes:

Bitmap Fonts

Bitmap fonts allow you to use any True Type Font in your application. Use the font-editor situated in the ${polish.home}/bin folder to create bitmap fonts (*.bmf) out of any true type fonts. Such bitmap fonts can be used by the J2ME Polish GUI with the font-bitmap CSS-attribute or directly with the de.enough.polish.util.BitMapFont utiliy class.

The font editor in action.

Since the font-editor does no yet optimize the generated font-images, you might want to optimize the images outside of the editor: Just select "File -> Save PNG-Image As..." and edit the image in your favorite image editing program. You might also want to use a PNG-image optimizer like PNG-Crush (http://pmt.sourceforge.net/pngcrush/) or PNG-Out (http://advsys.net/ken/utils.htm#pngout). When you're done, reload the PNG-image by selecting "File -> Open PNG-Image".

You can also fine-tune every aspect of the bitmap-font by opening it in the BinaryEditor: select "File -> Open in Binary Editor" to do so.

While editing bitmap fonts you have to take into account any character that you may need to render with that font. You need to include these characters in the font editor.

font-bitmap: url( fantasy.bmf );

Thanks to Vera Wahler (thanks!) you can also use an Ant task for generating many bitmap fonts in one go or as part of the build process:

       <taskdef name="bmfcreate" 
       		classname="de.enough.polish.font.BmfCreationTask" 
       		classpath="${polish.home}/lib/enough-j2mepolish-build.jar" />
        <target name="convertfonts">
                <bmfcreate 
                color="#ff0" 
                size="12" 
                antialiased="true"
                characterSpacing="3" 
                input="resources/test.ttf"
                output="/Users/vera/Desktop/test.bmf">ABCDEFGHIJ...</bmfcreate>
        </target>

Text Effects

Text effects provide you with an easy way to spice up your fonts without needing to care about sizes and availability of characters like for bitmap fonts. You can even go and code your own text-effect!

Please look here for a complete list of available text-effects.

Programming

Program StringItems with J2ME Polish like normal MIDP 2.0 StringItems, for example:

//#style itemText
StringItem item = new StringItem("info: ", "Welcome to J2ME Polish!");
form.append( item );

Text Wrapping

Usually text is wrapped automatically when it is too long for a single row. You can deactivate this default behavior by setting the text-wrap CSS attribute to false. In TextFields with enabled direct input mode the cursor will be kept in the visible area, for other texts only parts remain visible. You could use this feature to show only the beginning of a message when an item is not focused and show the complete text (by turning on text-wrap again) when an item is focused, for example:

.messageItem {
	text-wrap: false;
}
.messageItem:hover {
	text-wrap: true;
}

Alternatively you might want to use the max-lines CSS property. This will limit the lines to the given number and end the last last line with a .../TextUtil.MAXLINES_APPENDIX or the ending specified in max-lines-appendix. By setting max-lines to 0 or to a negative number, you will not limit the number of lines anymore.
If you want to give all items the same height you can either use the min-height CSS attribute or use force-lines for expanding StringItems with less text lines to the number defined in max-lines.

.messageItem {
	max-lines: 1;
	max-lines-appendix: ..;
}
.messageItem:hover {
	max-lines: -1;
}

JavaDoc

back to top