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

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

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

CSS Attribute	Default	Values	Explanation
font-bitmap	-	string	Defines which bitmap (bmf) font should be used.
text-effect	-		Sets a text effect.
text-horizontal-adjustment	0	integer	Adjusts the text by the specified number of pixels horizontally. Negative values move the text to the left.
text-vertical-adjustment	0	integer	Adjusts the text by the specified number of pixels vertically. Negative values move the text to the top.
text-wrap	true	true, false	Determines wether the text should be wrapped or whether it should be kept on a single line, even when it is larger than the available width.
text-wrap-animate	true	true, false	You can deactivate animations for texts that should not be wrapped and which are too long for a single line.
Further CSS Attribute	Default	Values	Explanation
after	-	imageurl	The URL of the image that should be shown after the item in question.
always-include	false	true, false	Defines if a style should always be included, even if not used.
background	-	background definition	The background of an item or screen. The default background for items is "none", the default background for screens is a simple white background.
before	-	imageurl	The URL of the image that should be shown before the item in question.
colspan	1	integer	The number of columns wich are used by the item within a table.
complete-border	-	border	A border reference from the borders section. The border includes the label of the item and is independent of the item's normal border.
complete-background	-	background	A background name from the backgrounds section. The background includes the label of the item and is independent of the item's normal background.
border	-	border definition	The border of an item or screen. The default border is "none".
complete-background-padding	-	integer	The padding that is added to the complete-background and/or complete-border. Note that this does not change the size of the item, so you might need to adapt margins or normal paddings for your design.
focused-style	focused	style	The name of the style for the currently focused item, usually applied with a [style-name]:hover construct.
include-label	false	true, false	Usually the label of an item is rendered separately of the item's content. You can expand the background and border over the label as well using this attribute.
inherit	true	true, false	Defines if a style that extends this style should inherit all attributes.
label-style	label	style	The name of the style for the label of the corresponding Item.
max-height	-	integer	The maximum height of an item.
max-width	-	integer	The maximum width of an item.
min-height	-	integer	The minimum height of an item.
min-width	-	integer	The minimum width of an item.
opacity	255	integer	The opacity of an item between 0 (fully transparent) and 255 (fully opaque).
pressed-style	-	style	The style which indicates that an item is being pressed, usually applied with a [style-name]:pressed construct.
view-type	-	fade-in, fade-out, particle, size-decrease, size-increase	Defines another visualization for an Item or a Screen.

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" 
       		claspath="${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: