FormLayoutPolicy (Mobile Information Device Profile 3.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.microedition.lcdui
Class FormLayoutPolicy

java.lang.Object
  javax.microedition.lcdui.FormLayoutPolicy

Direct Known Subclasses:: TableLayoutPolicy

public abstract class FormLayoutPolicy
extends java.lang.Object
extends java.lang.Object

FormLayoutPolicy is subclassed to provide custom layout algorithms. Form delegates layout functions to an instance of FormLayoutPolicy. Each FormLayoutPolicy is bound to a single Form when it is created.

The Items in the Form are accessed via the Form instance using the Form.size and Form.get methods. Each Item has methods to access layout directives and to the contents. Each FormLayoutPolicy subclass defines the effect of each layout directive.

The layout algorithm is implemented by subclasses in the doLayout method. The doLayout method is called when the layout of items is invalid and needs to be updated. The position and size of each Item is made available through the getX, getY, getWidth, getHeight methods. The x, y, width, and height are set with the setPosition and setSize methods. Setting and updating the position and size of each Item is the responsibility of the FormLayoutPolicy subclass. The values are initially zero, the values are only modified by the layout policy and otherwise remain unmodified. The methods to get and set Item position, size, or validity must not be called outside of the scope of a call to the doLayout or getTraverse methods.

When the contents or size of Items change it maybe necessary to update the layout. When items change in a way that might require the layout to be updated the Items MUST be marked invalid by calling setValid(item, false). When a valid layout is needed, for example to display the Form, the doLayout method is called to compute and update, as necessary, the position and size of invalid Items. Only the doLayout method should set the valid item to true.

When a Form is active on a display, updates to the Items or Form take place as soon as it is feasible for the implementation to do so. The doLayout method is called to recompute the layout when there are invalid Items and the display needs to be updated. Calls to doLayout may result from calls to Display.setCurrent, Form.delete, Form.insert, Form.append, Form.set, Displayable.setTitle, Displayable.setTicker, Item methods for setting labels, commands, preferred size, contents, etc.

After doLayout returns, the caller can assume that all of the Items within the viewport are valid and have valid positions and sizes and may display them as necessary; though the actual valid flags may not be set to true. Items that extend beyond the viewport MUST be clipped when rendered.

If the doLayout or traverse methods throw runtime exceptions the Form MUST set the layout policy to null and revert the layout to the default layout policy.

Since:: MIDP 3.0
See Also:: Form

Field Summary
`static int`	`DIRECTION_LTR` Indicates left-to-right mode for layout direction.
`static int`	`DIRECTION_RTL` Indicates right-to-left mode for layout direction.

Constructor Summary
`protected`	`FormLayoutPolicy(Form form)` Creates a new instance of FormLayoutPolicy and binds it to the Form.

Method Summary
`protected abstract void`	`doLayout(int viewportX, int viewportY, int viewportWidth, int viewportHeight, int[] totalSize)` Compute or update the position and size of Items in the Form within the viewport.
`protected Form`	`getForm()` Gets the `Form` for which this FormLayoutPolicy is handling the layout.
`protected int`	`getHeight(Item item)` Gets the height of the Item.
`static int`	`getLayoutDirection()` Gets the layout direction determined by the platform, either `DIRECTION_LTR` or `DIRECTION_RTL`.
`protected abstract Item`	`getTraverse(Item item, int dir)` Gets the Item logically adjecent to an existing Item in the traversal direction.
`protected int`	`getWidth(Item item)` Gets the current width of the Item.
`protected int`	`getX(Item item)` Gets the x position of the Item.
`protected int`	`getY(Item item)` Gets the y position of the Item.
`protected boolean`	`isValid(Item item)` Returns `true` if the position and of the Item are valid.
`protected void`	`setPosition(Item item, int x, int y)` Sets the position of the Item.
`protected void`	`setSize(Item item, int width, int height)` Sets the width and height of the Item.
`protected void`	`setValid(Item item, boolean valid)` Sets the validity of the Item.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

DIRECTION_LTR

public static final int DIRECTION_LTR

Indicates left-to-right mode for layout direction.

Value 0 is assigned to DIRECTION_LTR.

Since:: MIDP 3.0
See Also:: Constant Field Values

DIRECTION_RTL

public static final int DIRECTION_RTL

Indicates right-to-left mode for layout direction.

Value 1 is assigned to DIRECTION_RTL.

Since:: MIDP 3.0
See Also:: Constant Field Values

Constructor Detail

FormLayoutPolicy

protected FormLayoutPolicy(Form form)

Creates a new instance of FormLayoutPolicy and binds it to the Form.

Parameters:: form - the Form bound to this layout.
Throws:: java.lang.NullPointerException - if form is null.

Method Detail

doLayout

protected abstract void doLayout(int viewportX,
                                 int viewportY,
                                 int viewportWidth,
                                 int viewportHeight,
                                 int[] totalSize)

Compute or update the position and size of Items in the Form within the viewport. The viewport is defined by a width and height and its x and y position within the form. The implementation of this method is expected to set the position and size of Items so that they do not overlap, if not, the layout is in error and its appearance may be unpredictable. The Items SHOULD be placed within the viewport but some visual arrangements cannot by their nature be fit within a specified fixed area, for example, a spreadsheet with a large number of rows or columns.

The initial position and size of each Item is zero until updated by the layout algorithm. The values are only modified by the layout algorithm and will be valid from the previous layout. Any Item that has changed is invalid and its position and size may need to be updated and set as valid. The size of the screen available to display the items of the Form is provided as a viewport width and height. To support scrolling, this method must return the total width and height required for the complete form, including all items. The implementation can use the returned total width and height to provide feedback if scrolling is supported. Only items within the viewport need to be made valid by each doLayout method call.

The doLayout method should not make any changes to Item contents or invalidate Items. Changes might affect the layout and can cause an unstable layout.

Parameters:: viewportX - The x offset of the viewport on the form.; viewportY - The y offset of the viewport on the form.; viewportWidth - the width of the viewport; viewportHeight - the height of the viewport; totalSize - an output parameter to be set to the full width and height required for all items in the form. The subclass stores the width in totalSize[0] and the subclass stores the height in totalSize[1].
Throws:: java.lang.ArrayIndexOutOfBoundsException - is thrown if the length of the totalSize array is less than 2.
See Also:: isValid(javax.microedition.lcdui.Item), setValid(javax.microedition.lcdui.Item, boolean), getWidth(javax.microedition.lcdui.Item), getHeight(javax.microedition.lcdui.Item), getX(javax.microedition.lcdui.Item), getY(javax.microedition.lcdui.Item), setSize(javax.microedition.lcdui.Item, int, int), setPosition(javax.microedition.lcdui.Item, int, int), getLayoutDirection()

getTraverse

protected abstract Item getTraverse(Item item,
                                    int dir)

Gets the Item logically adjecent to an existing Item in the traversal direction. The getTraverse method is overridden by subclasses so that the next item in any direction is consistent with the layout and the user concept of the next Item in each direction taking into account wrapping between left/right and top/bottom and progression, if any, to the next line. For example, if the current item is the last item in a row then the next Item to the right is most likely the first Item in the next row.

The traversal direction must be one of four directions Canvas.UP, Canvas.DOWN, Canvas.LEFT, or Canvas.RIGHT.

Parameters:: item - a current Item; dir - the traversal direction from the item to the adjecent item
Returns:: the item in the traversal direction requested; may be null.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if dir is not one of Canvas.UP, Canvas.DOWN, Canvas.LEFT, or Canvas.RIGHT.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.

getForm

protected final Form getForm()

Gets the Form for which this FormLayoutPolicy is handling the layout.

Returns:: The Form for which this instance is handling the layout.

getLayoutDirection

public static final int getLayoutDirection()

Gets the layout direction determined by the platform, either DIRECTION_LTR or DIRECTION_RTL. The layout direction should be based on the current language convention in use.

Returns:: the layout direction DIRECTION_LTR or DIRECTION_RTL.
Since:: MIDP 3.0

getWidth

protected final int getWidth(Item item)

Gets the current width of the Item.

Parameters:: item - The item for which to get the width.
Returns:: The width of the Item.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.

getHeight

protected final int getHeight(Item item)

Gets the height of the Item.

Parameters:: item - The item from which to get the height.
Returns:: The height of the Item.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.

setSize

protected final void setSize(Item item,
                             int width,
                             int height)

Sets the width and height of the Item.

Parameters:: item - The Item for which to set the width and height; MUST NOT be null.; width - The new width of the Item.; height - The new height of the Item.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.; java.lang.IllegalArgumentException - if width is less than the Item's Item.getMinimumWidth or height is less than the Item.getMinimumHeight; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.

getX

protected final int getX(Item item)

Gets the x position of the Item.

Parameters:: item - The item for which to get the x position.
Returns:: The x position of the item.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.

getY

protected final int getY(Item item)

Gets the y position of the Item.

Parameters:: item - The item for which to get the y position.
Returns:: The y position of the Item.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.

setPosition

protected final void setPosition(Item item,
                                 int x,
                                 int y)

Sets the position of the Item.

Parameters:: item - The item to be positioned at x and y.; x - The new x position of the Item; MUST be greater than or equal to zero.; y - The new y position of the Item; MUST be greater than or equal to zero.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.; IllegalArgumentExcedption - if x or y is less than zero.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.

isValid

protected final boolean isValid(Item item)

Returns true if the position and of the Item are valid.

Parameters:: item - The item for which to get the validity.
Returns:: true if the position and size are valid; false otherwise.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.

setValid

protected final void setValid(Item item,
                              boolean valid)

Sets the validity of the Item.

Parameters:: item - The Item for which to set the validity.; valid - true if the position and size are valid; false otherwise.
Throws:: java.lang.NullPointerException - if item is null.; java.lang.IllegalArgumentException - if item is not an Item in this layout's form.; java.lang.IllegalStateException - if called outside of the scope of a call to getTraverse or doLayout.