de.enough.polish.ui
Class Screen

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Canvas
          de.enough.polish.ui.Screen

All Implemented Interfaces:

AccessibleCanvas

Direct Known Subclasses:

Alert, Form, List, SnapshotScreen, SplashScreen, TabbedList, TextBox

public abstract class Screen
extends javax.microedition.lcdui.Canvas
implements AccessibleCanvas

The common superclass of all high-level user interface classes. The contents displayed and their interaction with the user are defined by subclasses.

Using subclass-defined methods, the application may change the contents of a Screen object while it is shown to the user. If this occurs, and the Screen object is visible, the display will be updated automatically. That is, the implementation will refresh the display in a timely fashion without waiting for any further action by the application. For example, suppose a List object is currently displayed, and every element of the List is visible. If the application inserts a new element at the beginning of the List, it is displayed immediately, and the other elements will be rearranged appropriately. There is no need for the application to call another method to refresh the display.

It is recommended that applications change the contents of a Screen only while it is not visible (that is, while another Displayable is current). Changing the contents of a Screen while it is visible may result in performance problems on some devices, and it may also be confusing if the Screen's contents changes while the user is interacting with it.

In MIDP 2.0 the four Screen methods that defined read/write ticker and title properties were moved to Displayable, Screen's superclass. The semantics of these methods have not changed.

Since:

MIDP 1.0

Field Summary

protected Background	background
protected Border	border
protected Container	container
protected int	contentHeight
protected int	contentWidth
protected int	contentX
protected int	contentY
protected java.lang.String	cssSelector
protected int	fullScreenHeight the real, complete height of the screen - this includes title, subtitle, content and menubar
protected boolean	ignoreRepaintRequests
protected int	infoHeight
protected boolean	isInitRequested requests a call to calcuateContentArea() the next time this screen is being painted
protected boolean	isRepaintRequested
protected boolean	isScrollBackground
protected boolean	isSetFullScreenCalled
protected ItemStateListener	itemStateListener
boolean	keyPressedProcessed flag for key pressed events - only for internal usage on BlackBerry platforms!
boolean	keyReleasedProcessed flag for key released events - only for internal usage on BlackBerry platforms!
protected long	lastInteractionTime The last time in ms when the user interacted with this screen.
protected javax.microedition.lcdui.Command	lastTriggeredCommand
protected int	menuBarHeight
protected int	originalScreenHeight the screen height minus the height of the menu bar
protected boolean	paintScrollBarOnRightSide
protected int	screenHeight the screen height minus the ticker height and the height of the menu bar
protected int	screenOrientationDegrees
protected ScreenStateListener	screenStateListener
protected int	screenWidth
protected ScrollBar	scrollBar
protected boolean	scrollBarVisible
protected Style	style
protected int	subTitleHeight
protected Item	title
protected int	titleHeight
protected int	triggerReleasedKeyCode
protected long	triggerReleasedTime

Fields inherited from class javax.microedition.lcdui.Canvas

DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP

Constructor Summary

Screen(java.lang.String title, boolean createDefaultContainer)
Creates a new screen, this constructor can be used together with the //#style directive.

Screen(java.lang.String title, boolean createDefaultContainer, Style style)
Creates a new screen, this constructor can be used together with the //#style directive.

Screen(java.lang.String title, Style style, boolean createDefaultContainer)
Creates a new screen

Method Summary

void	addCommand(javax.microedition.lcdui.Command cmd)
void	addCommand(javax.microedition.lcdui.Command cmd, Style commandStyle) Adds a command to this screen with the specified style.
void	addSubCommand(javax.microedition.lcdui.Command child, javax.microedition.lcdui.Command parent) Adds the given command as a subcommand to the specified parent command.
void	addSubCommand(javax.microedition.lcdui.Command child, javax.microedition.lcdui.Command parent, Style commandStyle) Adds the given command as a subcommand to the specified parent command.
boolean	animate() Animates this Screen.
void	animate(long currentTime, ClippingRegion repaintRegion) Animates this screen.
protected void	calculateContentArea(int x, int y, int width, int height) Calculates and sets the content area for this screen.
protected void	callCommandListener(javax.microedition.lcdui.Command cmd) Calls the command listener with the specified command.
protected boolean	checkForRequestInit(Item source) Checks if this screen's content area should be refreshed when the specified item has changed it's size.
void	closeMenu() Closes the commands menu of this screen.
void	commandAction(javax.microedition.lcdui.Command command, javax.microedition.lcdui.Displayable screen)
protected abstract java.lang.String	createCssSelector() Retrieves the CSS selector for this screen.
void	focus(int index) Focuses the specified item.
void	focus(int index, boolean force) Focuses the specified item.
void	focus(int index, Item item, boolean force) Focuses the specified item.
void	focus(Item item) Focuses the specified item.
void	focus(Item item, boolean force) Focuses the specified item.
int	getAvailableHeight() Retrieves the available height for this screen.
CommandItem	getCommandItem(javax.microedition.lcdui.Command command) Retrieves the CommandItem used for rendering the specified command.
javax.microedition.lcdui.CommandListener	getCommandListener() Retrieves the asscociated command listener of this screen (if any).
int	getCurrentIndex() Retrieves the index of the currently focused item.
Item	getCurrentItem() Retrieves the currently focused item.
int	getGameAction(int keyCode)
Item	getItemAt(int x, int y) Locates and returns the item at the given coordinate.
MenuBar	getMenuBar() Allows to access the menu bar.
Ticker	getPolishTicker() Gets the ticker used by this Screen.
protected Item[]	getRootItems() Retrieves all root-items of this screen.
int	getScreenContentHeight() Retrieves the height of the content area.
int	getScreenContentWidth() Retrieves the width of the content area.
java.lang.Object	getScreenData() Retrieves screen specific data.
int	getScreenFullHeight() Retrieves the height that the complete screen uses, including title, menubar, ticker, etc.
int	getScreenFullWidth() Retrieves the width that the complete screen uses, including scrollbar, etc.
int	getScreenHeight()
Style	getScreenStyle() Retrieves the style currently used by this screen.
protected int	getScrollBarWidth() Retrieves the width of the scrollbar Note that you need to activate the usage of the scrollbar by setting polish.useScrollbar=true
int	getScrollYOffset() Retrieves the vertical scroll offset.
java.lang.String	getTitle() Gets the title of the Screen.
protected boolean	handleCommand(javax.microedition.lcdui.Command cmd) Tries to handle the specified command.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handleKeyReleased(int keyCode, int gameAction) Handles the key-released event.
protected boolean	handleKeyRepeated(int keyCode, int gameAction) Handles the key-repeated event.
protected boolean	handlePointerPressed(int x, int y) Handles the pressing of a pointer.
protected boolean	handlePointerReleased(int x, int y) Handles the release of a pointer.
void	hideNotify() Unregisters this screen and notifies all items that they will not be shown anymore.
boolean	isGameActionFire(int keyCode, int gameAction) Determines whether the given key is really a Canvas.FIRE game action
protected boolean	isKeyboardAccessible() Checks if the keyboard (if any) is currently accessible by the application.
boolean	isMenuOpened() Checks whether the commands menu of the screen is currently opened.
boolean	isShown() Determines whether the screen is currently shown.
boolean	isSoftKey(int keyCode) Determines if the given keycode belongs to a softkey
boolean	isSoftKey(int keyCode, int gameAction) Determines if the given keycode belongs to a soft key
boolean	isSoftKeyLeft(int keyCode, int gameAction) Checks if the given keycode is the left softkey
boolean	isSoftKeyMiddle(int keyCode, int gameAction) Checks if the given keycode is the middle softkey
boolean	isSoftKeyRight(int keyCode, int gameAction) Checks if the given keycode is the right softkey
void	keyPressed(int keyCode) Handles key events.
void	keyReleased(int keyCode) Is called when a key is released.
void	keyRepeated(int keyCode) Just maps the event to the the keyPressed method.
void	notifyScreenStateChanged() Notifies the screen state change listener about a change in this screen.
protected void	notifyStateListener(Item item) Adds the given item to the queue for state notifications.
void	paint(javax.microedition.lcdui.Graphics g) Paints the screen.
protected void	paintScreen(javax.microedition.lcdui.Graphics g) Paints the screen.
void	pointerDragged(int x, int y)
void	pointerPressed(int x, int y)
void	pointerReleased(int x, int y)
void	releaseResources() Releases all (memory intensive) resources such as images or RGB arrays of this item.
void	removeAllCommands() Removes all commands from this screen.
void	removeCommand(javax.microedition.lcdui.Command cmd)
protected void	removeItemCommands(Item item) Removes the commands of the given item.
protected void	requestInit() Reinitializes this screen's content area.
protected void	requestRepaint() Forwards a repaint request only when those requests should not be ignored.
protected void	requestRepaint(int x, int y, int width, int height) Forwards a repaint request only when those requests should not be ignored.
void	scrollRelative(int amount) Scrolls this screen by the given amount.
void	setCommandListener(javax.microedition.lcdui.CommandListener listener)
void	setFullScreenMode(boolean enable)
void	setInfo(java.lang.String infoText) Sets the information which should be shown to the user.
protected void	setItemCommands(ArrayList commandsList, Item item) Sets the commands of the given item
void	setItemStateListener(ItemStateListener iListener) Sets the ItemStateListener for the Screen, replacing any previous ItemStateListener.
void	setItemStateListener(javax.microedition.lcdui.ItemStateListener iListener) Sets the ItemStateListener for the Screen, replacing any previous ItemStateListener.
void	setMenuBarStyle(Style menuBarStyle) Sets the style for the menubar.
void	setMenuItemStyle(Style menuItemStyle) Sets the style for menuItems.
void	setPolishTicker(Ticker ticker) Set a ticker for use with this Screen, replacing any previous ticker.
void	setPolishTicker(Ticker ticker, Style tickerStyle) Set a ticker for use with this Screen, replacing any previous ticker.
void	setScreenData(java.lang.Object data) Attaches data to this screen.
void	setScreenOrientation(int degrees) Sets the screen orientation in 90 degrees steps.
void	setScreenStateListener(ScreenStateListener listener) Sets the screen listener for this screen.
void	setScrollYOffset(int offset, boolean smooth) Sets the vertical scrolling offset of this screen.
void	setStyle(Style style) Sets the style of this screen.
protected void	setSubTitle(Item subTitle) Sets the subtitle element.
void	setTitle(Item item) Sets an Item as the title for this screen.
void	setTitle(java.lang.String s) Sets the title of the Screen.
void	setTitle(java.lang.String text, Style tStyle) Sets the title of the Screen.
void	showNotify() Initialises this screen and informs all items about being painted soon.
void	sizeChanged(int width, int height)

Methods inherited from class javax.microedition.lcdui.Canvas

getKeyCode, getKeyName, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, isDoubleBuffered, repaint, repaint, serviceRepaints

Methods inherited from class javax.microedition.lcdui.Displayable

getHeight, getTicker, getWidth, setTicker

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

title

protected Item title

subTitleHeight

protected int subTitleHeight

titleHeight

protected int titleHeight

background

protected Background background

border

protected Border border

style

protected Style style

screenHeight

protected int screenHeight

the screen height minus the ticker height and the height of the menu bar

originalScreenHeight

protected int originalScreenHeight

the screen height minus the height of the menu bar

screenWidth

protected int screenWidth

cssSelector

protected java.lang.String cssSelector

container

protected Container container

lastTriggeredCommand

protected javax.microedition.lcdui.Command lastTriggeredCommand

fullScreenHeight

protected int fullScreenHeight

the real, complete height of the screen - this includes title, subtitle, content and menubar

menuBarHeight

protected int menuBarHeight

scrollBar

protected final ScrollBar scrollBar

paintScrollBarOnRightSide

protected boolean paintScrollBarOnRightSide

scrollBarVisible

protected boolean scrollBarVisible

infoHeight

protected int infoHeight

keyPressedProcessed

public boolean keyPressedProcessed

flag for key pressed events - only for internal usage on BlackBerry platforms!

keyReleasedProcessed

public boolean keyReleasedProcessed

flag for key released events - only for internal usage on BlackBerry platforms!

contentX

protected int contentX

contentY

protected int contentY

contentWidth

protected int contentWidth

contentHeight

protected int contentHeight

isSetFullScreenCalled

protected boolean isSetFullScreenCalled

screenOrientationDegrees

protected int screenOrientationDegrees

screenStateListener

protected ScreenStateListener screenStateListener

itemStateListener

protected ItemStateListener itemStateListener

lastInteractionTime

protected long lastInteractionTime

The last time in ms when the user interacted with this screen. This value is used for stopping animations after a period of inactivity. This defaults to 3 minutes, but it can be set with the preprocessing variable polish.Animation.MaxIdleTime (integer with the number of ms, 60000 is one minute).

ignoreRepaintRequests

protected boolean ignoreRepaintRequests

isRepaintRequested

protected boolean isRepaintRequested

isInitRequested

protected boolean isInitRequested

requests a call to calcuateContentArea() the next time this screen is being painted

triggerReleasedKeyCode

protected int triggerReleasedKeyCode

triggerReleasedTime

protected long triggerReleasedTime

isScrollBackground

protected boolean isScrollBackground

Constructor Detail

Screen

public Screen(java.lang.String title,
              boolean createDefaultContainer)

Creates a new screen, this constructor can be used together with the //#style directive.

Parameters:

title - the title, or null for no title

createDefaultContainer - true when the default container should be created.

Screen

public Screen(java.lang.String title,
              boolean createDefaultContainer,
              Style style)

Creates a new screen, this constructor can be used together with the //#style directive.

Parameters:

title - the title, or null for no title

style - the style of this screen

createDefaultContainer - true when the default container should be created.

Screen

public Screen(java.lang.String title,
              Style style,
              boolean createDefaultContainer)

Creates a new screen

Parameters:

title - the title, or null for no title

style - the style of this screen

createDefaultContainer - true when the default container should be created.

Method Detail

requestInit

protected void requestInit()

Reinitializes this screen's content area. This call returns immediately and results in a run of the initialization at some later point in some screen subclasses or when this screen has a shrink layout.

requestRepaint

protected void requestRepaint()

Forwards a repaint request only when those requests should not be ignored. Requests should be usually ignored during the event handling, for example.

See Also:

ignoreRepaintRequests

requestRepaint

protected void requestRepaint(int x,
                              int y,
                              int width,
                              int height)

Forwards a repaint request only when those requests should not be ignored. Requests should be usually ignored during the event handling, for example.

Parameters:

x - the x coordinate of the area that needs to be refreshed

y - the y coordinate of the area that needs to be refreshed

width - the width of the area that needs to be refreshed

height - the height of the area that needs to be refreshed

See Also:

ignoreRepaintRequests

checkForRequestInit

protected boolean checkForRequestInit(Item source)

Checks if this screen's content area should be refreshed when the specified item has changed it's size.

Parameters:

source - the source of the event

Returns:

true when the source is a directly visible element (default container or title, for example)

calculateContentArea

protected void calculateContentArea(int x,
                                    int y,
                                    int width,
                                    int height)

Calculates and sets the content area for this screen. Usually no items are painted outside of the specified area. This method knows about the title, subtitle, infoarea and ticker and adjusts the content area accordingly

Parameters:

x - left start of the content area, might later be adjusted by an external scrollindicator

y - top start of the content area, is adjusted by the top margin, title height, subtitle height, info height and maybe ticker height (when the ticker should be painted at the top).

width - width of the content area, might later be adjusted by an external scrollindicator

height - height of the content area, is adjusted by the title height, subtitle height, info height and ticker height.

showNotify

public void showNotify()

Initialises this screen and informs all items about being painted soon.

Specified by:

showNotify in interface AccessibleCanvas

Overrides:

showNotify in class javax.microedition.lcdui.Canvas

hideNotify

public void hideNotify()

Unregisters this screen and notifies all items that they will not be shown anymore.

Specified by:

hideNotify in interface AccessibleCanvas

Overrides:

hideNotify in class javax.microedition.lcdui.Canvas

setStyle

public void setStyle(Style style)

Sets the style of this screen.

Parameters:

style - the style

animate

public void animate(long currentTime,
                    ClippingRegion repaintRegion)

Animates this screen. Subclasses can override this method to create animations. All embedded items are also animated.

Parameters:

currentTime - the current time in milliseconds

repaintRegion - the repaint area that needs to be updated when this item is animated

animate

public boolean animate()

Animates this Screen. It's recommended to use animate( long, ClippingRegion ) instead for performance reasons.

Returns:

true when at least one animated item needs a redraw/repaint.

See Also:

animate(long, ClippingRegion)

paint

public void paint(javax.microedition.lcdui.Graphics g)

Paints the screen. When you subclass Screen you should override paintScreen(Graphics g) instead, if possible.

Specified by:

paint in interface AccessibleCanvas

Specified by:

paint in class javax.microedition.lcdui.Canvas

Parameters:

g - the graphics context.

See Also:

paintScreen(Graphics)

paintScreen

protected void paintScreen(javax.microedition.lcdui.Graphics g)

Paints the screen. This method also needs to set the protected variables paintScrollIndicator, paintScrollIndicatorUp and paintScrollIndicatorDown.

Parameters:

g - the graphics on which the screen should be painted

See Also:

contentX, contentY, contentWidth, contentHeight, paintScrollIndicator, paintScrollIndicatorUp, paintScrollIndicatorDown

getTitle

public java.lang.String getTitle()

Gets the title of the Screen. Returns null if there is no title.

Overrides:

getTitle in class javax.microedition.lcdui.Displayable

Returns:

the title of this screen

setTitle

public void setTitle(java.lang.String s)

Sets the title of the Screen. If null is given, removes the title. If the Screen is physically visible, the visible effect should take place no later than immediately after the callback or startApp returns back to the implementation.

Overrides:

setTitle in class javax.microedition.lcdui.Displayable

Parameters:

s - - the new title, or null for no title

setTitle

public void setTitle(java.lang.String text,
                     Style tStyle)

Sets the title of the Screen. If null is given, removes the title. If the Screen is physically visible, the visible effect should take place no later than immediately after the callback or startApp returns back to the implementation.

Parameters:

text - the new title, or null for no title

tStyle - the new style for the title, is ignored when null

setTitle

public void setTitle(Item item)

Sets an Item as the title for this screen. WARNING: You must not call setTitle(String) after calling this method anymore!

Parameters:

item - the title Item

setInfo

public void setInfo(java.lang.String infoText)

Sets the information which should be shown to the user. The info is shown below the title (if any) and can be designed using the predefined style "info". At the moment this feature is only used by the TextField implementation, when the direct input mode is enabled. A repaint is not triggered automatically by calling this method.

Parameters:

infoText - the text which will be shown to the user

setPolishTicker

public void setPolishTicker(Ticker ticker)

Set a ticker for use with this Screen, replacing any previous ticker. If null, removes the ticker object from this screen. The same ticker is may be shared by several Screen objects within an application. This is done by calling setTicker() on different screens with the same Ticker object. If the Screen is physically visible, the visible effect should take place no later than immediately after the callback or startApp returns back to the implementation.

Parameters:

ticker - - the ticker object used on this screen

setPolishTicker

public void setPolishTicker(Ticker ticker,
                            Style tickerStyle)

Set a ticker for use with this Screen, replacing any previous ticker. If null, removes the ticker object from this screen. The same ticker is may be shared by several Screen objects within an application. This is done by calling setTicker() on different screens with the same Ticker object. If the Screen is physically visible, the visible effect should take place no later than immediately after the callback or startApp returns back to the implementation.

Parameters:

ticker - the ticker object used on this screen

tickerStyle - the style of the ticker

getPolishTicker

public Ticker getPolishTicker()

Gets the ticker used by this Screen.

Returns:

ticker object used, or null if no ticker is present

getGameAction

public int getGameAction(int keyCode)

Overrides:

getGameAction in class javax.microedition.lcdui.Canvas

keyPressed

public void keyPressed(int keyCode)

Handles key events. WARNING: When this method should be overwritten, one need to ensure that super.keyPressed( int ) is called!

Specified by:

keyPressed in interface AccessibleCanvas

Overrides:

keyPressed in class javax.microedition.lcdui.Canvas

Parameters:

keyCode - The code of the pressed key

keyRepeated

public void keyRepeated(int keyCode)

Just maps the event to the the keyPressed method.

Specified by:

keyRepeated in interface AccessibleCanvas

Overrides:

keyRepeated in class javax.microedition.lcdui.Canvas

Parameters:

keyCode - the code of the key, which is pressed repeatedly

keyReleased

public void keyReleased(int keyCode)

Is called when a key is released.

Specified by:

keyReleased in interface AccessibleCanvas

Overrides:

keyReleased in class javax.microedition.lcdui.Canvas

Parameters:

keyCode - the code of the key, which has been released

createCssSelector

protected abstract java.lang.String createCssSelector()

Retrieves the CSS selector for this screen. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the screen and not by a predefined style-name. With the #style preprocessing command styles are set in a static way, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "form>p", than the selector of the screen is needed. This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles

Returns:

the name of the appropriate CSS Selector for this screen.

getRootItems

protected Item[] getRootItems()

Retrieves all root-items of this screen. The root items are those in first hierarchy, in a Form this is a Container for example. The default implementation does return an empty array, since apart from the container no additional items are used. Subclasses which use more root items than the container needs to override this method.

Returns:

the root items an array, the array can be empty but not null.

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed.

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key-event was processed

handleKeyRepeated

protected boolean handleKeyRepeated(int keyCode,
                                    int gameAction)

Handles the key-repeated event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed.

Parameters:

keyCode - the code of the repeated key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key-event was processed

handleKeyReleased

protected boolean handleKeyReleased(int keyCode,
                                    int gameAction)

Handles the key-released event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed.

Parameters:

keyCode - the code of the released key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key-event was processed

setScreenStateListener

public void setScreenStateListener(ScreenStateListener listener)

Sets the screen listener for this screen.

Parameters:

listener - the listener that is notified whenever the user changes the internal state of this screen.

notifyScreenStateChanged

public void notifyScreenStateChanged()

Notifies the screen state change listener about a change in this screen.

setCommandListener

public void setCommandListener(javax.microedition.lcdui.CommandListener listener)

Overrides:

setCommandListener in class javax.microedition.lcdui.Displayable

getCommandListener

public javax.microedition.lcdui.CommandListener getCommandListener()

Retrieves the asscociated command listener of this screen (if any).

Returns:

the command listener or null when none has been registered before.

addCommand

public void addCommand(javax.microedition.lcdui.Command cmd)

Overrides:

addCommand in class javax.microedition.lcdui.Displayable

addCommand

public void addCommand(javax.microedition.lcdui.Command cmd,
                       Style commandStyle)

Adds a command to this screen with the specified style.

Parameters:

cmd - the command

commandStyle - the style for the command

getCommandItem

public CommandItem getCommandItem(javax.microedition.lcdui.Command command)

Retrieves the CommandItem used for rendering the specified command.

Parameters:

command - the command

Returns:

the corresponding CommandItem or null when this command is not present in this MenuBar.

removeAllCommands

public void removeAllCommands()

Removes all commands from this screen. This option is only available when the "menu" fullscreen mode is activated.

addSubCommand

public void addSubCommand(javax.microedition.lcdui.Command child,
                          javax.microedition.lcdui.Command parent)

Adds the given command as a subcommand to the specified parent command.

Parameters:

child - the child command

parent - the parent command

addSubCommand

public void addSubCommand(javax.microedition.lcdui.Command child,
                          javax.microedition.lcdui.Command parent,
                          Style commandStyle)

Adds the given command as a subcommand to the specified parent command.

Parameters:

child - the child command

parent - the parent command

commandStyle - the style for the command

Throws:

java.lang.IllegalStateException - when the parent command has not been added before

removeCommand

public void removeCommand(javax.microedition.lcdui.Command cmd)

Overrides:

removeCommand in class javax.microedition.lcdui.Displayable

setItemCommands

protected void setItemCommands(ArrayList commandsList,
                               Item item)

Sets the commands of the given item

Parameters:

commandsList -

item - the item which has at least one command

See Also:

removeItemCommands(Item)

removeItemCommands

protected void removeItemCommands(Item item)

Removes the commands of the given item.

Parameters:

item - the item which has at least one command

See Also:

setItemCommands(ArrayList,Item)

callCommandListener

protected void callCommandListener(javax.microedition.lcdui.Command cmd)

Calls the command listener with the specified command.

Parameters:

cmd - the command wich should be issued to the listener

getAvailableHeight

public int getAvailableHeight()

Retrieves the available height for this screen. This is equivalent to the Canvas#getHeight() method. This method cannot be overriden for Nokia's FullScreen though. So this method is used insted.

Returns:

the available height in pixels.

commandAction

public void commandAction(javax.microedition.lcdui.Command command,
                          javax.microedition.lcdui.Displayable screen)

pointerPressed

public void pointerPressed(int x,
                           int y)

Specified by:

pointerPressed in interface AccessibleCanvas

Overrides:

pointerPressed in class javax.microedition.lcdui.Canvas

pointerDragged

public void pointerDragged(int x,
                           int y)

Specified by:

pointerDragged in interface AccessibleCanvas

Overrides:

pointerDragged in class javax.microedition.lcdui.Canvas

pointerReleased

public void pointerReleased(int x,
                            int y)

Specified by:

pointerReleased in interface AccessibleCanvas

Overrides:

pointerReleased in class javax.microedition.lcdui.Canvas

handlePointerPressed

protected boolean handlePointerPressed(int x,
                                       int y)

Handles the pressing of a pointer. This method should be overwritten only when the polish.hasPointerEvents preprocessing symbol is defined. When the screen could handle the pointer pressing, it needs to return true. The default implementation returns the result of calling the container's handlePointerPressed-method

Parameters:

x - the absolute x position of the pointer pressing

y - the absolute y position of the pointer pressing

Returns:

true when the pressing of the pointer was actually handled by this item.

handlePointerReleased

protected boolean handlePointerReleased(int x,
                                        int y)

Handles the release of a pointer. This method should be overwritten only when the polish.hasPointerEvents preprocessing symbol is defined. When the screen could handle the pointer release, it needs to return true. The default implementation returns the result of calling the container's handlePointerReleased-method

Parameters:

x - the absolute x position of the pointer pressing

y - the absolute y position of the pointer pressing

Returns:

true when the pressing of the pointer was actually handled by this item.

handleCommand

protected boolean handleCommand(javax.microedition.lcdui.Command cmd)

Tries to handle the specified command. The default implementation forwards the call to the container. When the container is unable to process the command, it will be forwarded to an external command listener that has been set using setCommandListener(..)

Parameters:

cmd - the command

Returns:

true when the command has been handled by this screen

setFullScreenMode

public void setFullScreenMode(boolean enable)

Overrides:

setFullScreenMode in class javax.microedition.lcdui.Canvas

sizeChanged

public void sizeChanged(int width,
                        int height)

Specified by:

sizeChanged in interface AccessibleCanvas

Overrides:

sizeChanged in class javax.microedition.lcdui.Canvas

getScreenHeight

public int getScreenHeight()

Returns:

the usable screen height

focus

public void focus(Item item)

Focuses the specified item.

Parameters:

item - the item which is already shown on this screen.

focus

public void focus(Item item,
                  boolean force)

Focuses the specified item.

Parameters:

item - the item which is already shown on this screen.

force - true when the item should be focused even when it is inactive (like a label for example)

focus

public void focus(int index)

Focuses the specified item.

Parameters:

index - the index of the item which is already shown on this screen.

focus

public void focus(int index,
                  boolean force)

Focuses the specified item.

Parameters:

index - the index of the item which is already shown on this screen.

force - true when the item should be focused even when it is inactive (like a label for example)

focus

public void focus(int index,
                  Item item,
                  boolean force)

Focuses the specified item.

Parameters:

index - the index of the item which is already shown on this screen.

item - the item which is already shown on this screen.

force - true when the item should be focused even when it is inactive (like a label for example)

setSubTitle

protected void setSubTitle(Item subTitle)

Sets the subtitle element. The subtitle is drawn directly below of the title (above the info-item, if there is any) and is always shown (unless it is null).

Parameters:

subTitle - the new subtitle element.

isShown

public boolean isShown()

Determines whether the screen is currently shown. When the screen is shown but the menu is openend, this method return false.

Overrides:

isShown in class javax.microedition.lcdui.Displayable

Returns:

true if the screen is currently shown, false otherwise

See Also:

Displayable.isShown()

getCurrentItem

public Item getCurrentItem()

Retrieves the currently focused item.

Returns:

the currently focused item, null when none is focused.

getCurrentIndex

public int getCurrentIndex()

Retrieves the index of the currently focused item.

Returns:

the index of the currently focused item, -1 when no item has been selected

isMenuOpened

public boolean isMenuOpened()

Checks whether the commands menu of the screen is currently opened. Useful when overriding the keyPressed() method.

Returns:

true when the commands menu is opened.

closeMenu

public void closeMenu()

Closes the commands menu of this screen. This can only be done when the fullscreen mode is set to "menu" in your build.xml script.

releaseResources

public void releaseResources()

Releases all (memory intensive) resources such as images or RGB arrays of this item. The default implementation does release any background resources. This method must not be called from within a paint call, as this will result in a dead lock.

scrollRelative

public void scrollRelative(int amount)

Scrolls this screen by the given amount.

Parameters:

amount - the number of pixels, positive values scroll upwards, negative scroll downwards

setScreenData

public void setScreenData(java.lang.Object data)

Attaches data to this screen. This mechanism can be used to add business logic to screens.

Parameters:

data - the screen specific data

See Also:

UiAccess.setData(Screen, Object), UiAccess.getData(Screen)

getScreenData

public java.lang.Object getScreenData()

Retrieves screen specific data. This mechanism can be used to add business logic to screens.

Returns:

any screen specific data or null when no data has been attached before

See Also:

UiAccess.setData(Screen, Object), UiAccess.getData(Screen)

getItemAt

public Item getItemAt(int x,
                      int y)

Locates and returns the item at the given coordinate.

Parameters:

x - horizontal position in pixels

y - vertical position in pixels

Returns:

the found item or null when no item is at the specific coordinate

getScreenStyle

public Style getScreenStyle()

Retrieves the style currently used by this screen.

Returns:

this screen's style

setItemStateListener

public void setItemStateListener(ItemStateListener iListener)

Sets the ItemStateListener for the Screen, replacing any previous ItemStateListener. If iListener is null, simply removes the previous ItemStateListener.

Parameters:

iListener - the new listener, or null to remove it

setItemStateListener

public void setItemStateListener(javax.microedition.lcdui.ItemStateListener iListener)

Sets the ItemStateListener for the Screen, replacing any previous ItemStateListener. If iListener is null, simply removes the previous ItemStateListener.

Parameters:

iListener - the new listener, or null to remove it

notifyStateListener

protected void notifyStateListener(Item item)

Adds the given item to the queue for state notifications. The ItemStateListener will be called at the next possibility.

Parameters:

item - the item which contents have been edited.

isKeyboardAccessible

protected boolean isKeyboardAccessible()

Checks if the keyboard (if any) is currently accessible by the application. This is useful for devices that can be opened by the user like the Nokia/E70.

Returns:

true when the keyboard (if there is one) is accessible by the application.

getScrollBarWidth

protected int getScrollBarWidth()

Retrieves the width of the scrollbar Note that you need to activate the usage of the scrollbar by setting polish.useScrollbar=true

Returns:

the width of the scrollbar, 0 when none is used

getScreenContentHeight

public int getScreenContentHeight()

Retrieves the height of the content area.

Returns:

the height available for the content

getScreenContentWidth

public int getScreenContentWidth()

Retrieves the width of the content area.

Returns:

the width available for the content

getScreenFullHeight

public int getScreenFullHeight()

Retrieves the height that the complete screen uses, including title, menubar, ticker, etc.

Returns:

the fully available height.

getScreenFullWidth

public int getScreenFullWidth()

Retrieves the width that the complete screen uses, including scrollbar, etc.

Returns:

the fully available width.

setMenuItemStyle

public void setMenuItemStyle(Style menuItemStyle)

Sets the style for menuItems. This can only be used within the menu fullscreen mode and when the external menu bar is used.

Parameters:

menuItemStyle - the style for menu items

getMenuBar

public MenuBar getMenuBar()

Allows to access the menu bar. This can only be used within the menu fullscreen mode and when the external menu bar is used.

Returns:

the menubar instanse

setMenuBarStyle

public void setMenuBarStyle(Style menuBarStyle)

Sets the style for the menubar. A full style is only applied when the external menubar is used, set the preprocessing variable polish.MenuBar.useExtendedMenuBar to true for this.

Parameters:

menuBarStyle -

getScrollYOffset

public int getScrollYOffset()

Retrieves the vertical scroll offset.

Returns:

the vertical scroll offset in pixels.

setScrollYOffset

public void setScrollYOffset(int offset,
                             boolean smooth)

Sets the vertical scrolling offset of this screen.

Parameters:

offset - either the new offset

smooth - scroll to this new offset smooth if allowed

setScreenOrientation

public void setScreenOrientation(int degrees)

Sets the screen orientation in 90 degrees steps. The preprocessing variable "polish.ScreenOrientationCanChangeManually" needs to be set to "true" for supporting this mode.

Parameters:

degrees - the screen orientation in degrees: 90, 180, 270 or 0

isGameActionFire

public boolean isGameActionFire(int keyCode,
                                int gameAction)

Determines whether the given key is really a Canvas.FIRE game action

Parameters:

keyCode - the key code

gameAction - the game action

Returns:

true when the gameAction is Canvas.FIRE and the given key is not '5' or a soft key

isSoftKeyLeft

public final boolean isSoftKeyLeft(int keyCode,
                                   int gameAction)

Checks if the given keycode is the left softkey

Parameters:

keyCode - the key code

gameAction - the associated game action

Returns:

true when the key is the left soft key

isSoftKeyRight

public final boolean isSoftKeyRight(int keyCode,
                                    int gameAction)

Checks if the given keycode is the right softkey

Parameters:

keyCode - the key code

gameAction - the associated game action

Returns:

true when the key is the right soft key

isSoftKeyMiddle

public final boolean isSoftKeyMiddle(int keyCode,
                                     int gameAction)

Checks if the given keycode is the middle softkey

Parameters:

keyCode - the key code

gameAction - the associated game action

Returns:

true when the key is the middle soft key

isSoftKey

public boolean isSoftKey(int keyCode)

Determines if the given keycode belongs to a softkey

Parameters:

keyCode - the keycode

Returns:

true when the key code represents a softkey

isSoftKey

public boolean isSoftKey(int keyCode,
                         int gameAction)

Determines if the given keycode belongs to a soft key

Parameters:

keyCode - the key code

gameAction - the associated game action

Returns:

true when the given key is a keycode