Screen

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.enough.polish.ui
Class Screen

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

All Implemented Interfaces:: Animatable, Displayable, UiElement

Direct Known Subclasses:: Alert, Form, List, ProcessingScreen, SnapshotScreen, SplashScreen, TabbedList, TabbedPane, TextBox

public abstract class Screen
extends Canvas
implements UiElement, Animatable
extends Canvas
implements UiElement, Animatable

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 int`	`backgroundHeight`
`protected int`	`backgroundWidth`
`protected int`	`backgroundX`
`protected int`	`backgroundY`
`protected Border`	`border`
`protected Container`	`container`
`protected Background`	`contentBackground` the content's (container) background
`protected int`	`contentBackgroundAnchor`
`protected Dimension`	`contentBackgroundHeight`
`protected Dimension`	`contentBackgroundWidth`
`protected Border`	`contentBgBorder` the content's (container) border that is drawn before the content-background is drawn
`protected Border`	`contentBorder` the content's (container) border
`protected int`	`contentHeight`
`protected int`	`contentWidth`
`protected int`	`contentX`
`protected int`	`contentY`
`protected String`	`cssSelector`
`protected boolean`	`enableScreenChangeAnimation`
`protected int`	`fullScreenHeight` the real, complete height of the screen - this includes title, subtitle, content and menubar
`protected boolean`	`ignoreRepaintRequests`
`protected int`	`infoHeight` determines whether the info text should be shown
`protected boolean`	`isAnimated`
`protected boolean`	`isInitRequested` requests a call to calcuateContentArea() the next time this screen is being painted
`protected boolean`	`isRepaintRequested`
`protected boolean`	`isScrollBackground`
`protected ItemStateListener`	`itemStateListener`
`boolean`	`keyPressedProcessed` flag for key pressed events - only for internal usage on Android platforms!
`boolean`	`keyReleasedProcessed` flag for key released events - only for internal usage on Android platforms!
`protected Style`	`landscapeStyle`
`protected long`	`lastAnimateTime`
`protected long`	`lastInteractionTime` The last time in ms when the user interacted with this screen.
`protected Command`	`lastTriggeredCommand`
`protected int`	`menuBarHeight`
`protected int`	`originalScreenHeight` the screen height minus the height of the menu bar
`protected boolean`	`paintScrollBarOnRightSide`
`protected Style`	`portraitStyle`
`protected Background`	`previousScreenOverlayBackground`
`protected boolean`	`repaintPreviousScreen`
`protected int`	`screenHeight` the screen height minus the ticker height and the height of the menu bar
`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`
`protected ClippingRegion`	`userEventRepaintRegion`

Fields inherited from class de.enough.polish.ui.Canvas
`_commands, 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(String title, boolean createDefaultContainer)` Creates a new screen, this constructor can be used together with the //#style directive.
`Screen(String title, boolean createDefaultContainer, Style style)` Creates a new screen, this constructor can be used together with the //#style directive.
`Screen(String title, Style style, boolean createDefaultContainer)` Creates a new screen

Method Summary
`boolean`	`_keyPressed(int keyCode)` Handles key events.
`boolean`	`_keyReleased(int keyCode)` Is called when a key is released.
`boolean`	`_keyRepeated(int keyCode)` Just maps the event to the the keyPressed method.
`boolean`	`_pointerDragged(int x, int y)` Called when the pointer is dragged.
`boolean`	`_pointerPressed(int x, int y)` Called when the pointer is pressed.
`boolean`	`_pointerReleased(int x, int y)` Called when the pointer is released.
`void`	`addCommand(Command cmd)` Adds a command to this screen
`void`	`addCommand(Command cmd)` Adds a command to the `Displayable`.
`void`	`addCommand(Command cmd, Style commandStyle)` Adds a command to this screen with the specified style.
`void`	`addCommandSeparator(int priority)` Adds a command separator to the menu of this screen.
`void`	`addCommandSeparator(int priority, Style separatorStyle)` Adds a command separator to the menu of this screen.
`void`	`addCommandsLayer(Command[] commands)`
`void`	`addPermanentNativeItem(Item item)` Notifies this screen about the new item with a native componen that is added on BlackBerry platforms.
`void`	`addRelativeToContentRegion(ClippingRegion repaintRegion, int x, int y, int width, int height)` Adds a region relative to this screen's content x/y start position.
`void`	`addRepaintArea(ClippingRegion repaintArea)` UI ELEMENT INTERFACE
`void`	`addSubCommand(Command child, Command parent)` Adds the given command as a subcommand to the specified parent command.
`void`	`addSubCommand(Command child, Command parent, Style commandStyle)` Adds the given command as a subcommand to the specified parent command.
`protected void`	`adjustContentArea(int x, int y, int width, int height, Container cont)` Subclasses may override this to adjust the content area of a screen.
`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 initializes the content area for this screen.
`protected void`	`callCommandListener(Command cmd)` Calls the command listener with the specified command.
`protected boolean`	`canScrollDown()` Checks if this screen can currently scroll downwards.
`protected boolean`	`canScrollUp()` Checks if this screen can currently scroll upwards.
`protected boolean`	`checkForRequestInit(Item source)` Checks if this screen's content area should be refreshed when the specified item has changed it's size.
`protected void`	`clearItemCommands()` Removes commands from the complete focused item hierarchy
`void`	`closeMenu()` Closes the commands menu of this screen.
`void`	`commandAction(Command command, Displayable screen)`
`protected abstract String`	`createCssSelector()` Retrieves the CSS selector for this screen.
`void`	`destroy()` Destroys the screen
`void`	`fireEvent(String eventName, Object eventData)` Fires an event for this screen and all its components.
`void`	`fireEventForTitleAndMenubar(String eventName, Object eventData)` Fires an event for the title and menubar of the specified 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(Command command)` Retrieves the CommandItem used for rendering the specified command.
`CommandListener`	`getCommandListener()` Retrieves the asscociated command listener of this screen (if any).
`Object[]`	`getCommands()` Retrieves all commands as an object array which may contain null values
`int`	`getCurrentIndex()` Retrieves the index of the currently focused item.
`Item`	`getCurrentItem()` Retrieves the currently focused item.
`protected Command`	`getDefaultCommand(Item item)` Retrieves the default command of the specfied item.
`Item`	`getItemAt(int x, int y)` Locates and returns the item at the given coordinate.
`int`	`getKeyStates()` Gets the states of the physical game keys.
`MenuBar`	`getMenuBar()` Allows to access the menu bar.
`NativeScreen`	`getNativeScreen()` Species a native implementation for this screen.
`Object`	`getPaintLock()` Retrieves the lock object for the paint thread.
`Ticker`	`getPolishTicker()` Gets the ticker used by this Screen.
`Container`	`getRootContainer()` Retrieves the root container of 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.
`int`	`getScreenContentX()` Retrieves the horizontal start position of the screen's content area
`int`	`getScreenContentY()` Retrieves the vertical start position of the screen's content area
`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()`
`ScreenInitializerListener`	`getScreenInitializerListener()` Sets a new screen initializer listener.
`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
`protected int`	`getScrollDownBackgroundOffset()` Retrieves the scroll down offset
`int`	`getScrollHeight()` Retrieves this screen's actual content's height
`protected int`	`getScrollUpBackgroundOffset()` Retrieves the scroll up offset
`int`	`getScrollYOffset()` Retrieves the vertical scroll offset.
`Style`	`getStyle()` Retrieves the currently used style
`Item`	`getSubTitleItem()` Retrieves the subtitle of this screen.
`String`	`getTitle()` Gets the title of the Screen.
`int`	`getTitleHeight()` Retrieves the height of the title.
`Item`	`getTitleItem()` Retrieves this screen's title item (when the fullscreen mode of J2ME Polish is activated)
`UiEventListener`	`getUiEventListener()` Retrieves the UiEventListener for this screen
`protected boolean`	`handleCommand(Command cmd)` Tries to handle the specified command.
`protected boolean`	`handleCommand(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`	`handlePointerDragged(int x, int y)` Handles the dragging/movement of a pointer.
`protected boolean`	`handlePointerDragged(int x, int y, ClippingRegion repaintRegion)` Handles the dragging/movement of a pointer.
`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.
`protected boolean`	`handlePointerReleasedOutsideScreenArea(int x, int y)` Handles the release of a pointer outside of this screens area.
`boolean`	`handlePointerTouchDown(int x, int y)` Deprecated. as BlackBerry used to differentiate between click and touch only on its first Storm model
`boolean`	`handlePointerTouchUp(int x, int y)` Deprecated. as BlackBerry used to differentiate between click and touch only on its first Storm model
`void`	`hideNotify()` Unregisters this screen and notifies all items that they will not be shown anymore.
`protected void`	`init(int width, int height)` Initializes this screen before it is painted for the first time.
`protected void`	`initContent(Container cont)` Initializes the container and background position
`boolean`	`isActive()` Indicates if this screen is active (scrolling, key pressed etc.)
`boolean`	`isGameActionFire(int keyCode, int gameAction)` Determines whether the given key is really a Canvas.FIRE game action
`boolean`	`isInteracted(long timespan)` Indicates if this screen was interacted with in the given timespan
`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.
`protected boolean`	`isNativeUiShownFor(Item item)` Determines whether a native UI component is shown for the specified item.
`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`	`notifyDefaultCommand(Command cmd)` Informs this screen about a new default command for a focused item
`protected void`	`notifyFocusSet(Item item)` Notifies this screen about the new item that is focused on BlackBerry platforms.
`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(Graphics g)` Paints the screen.
`protected void`	`paintBackgroundAndBorder(Graphics g)` Paints the background and border for this screen.
`protected void`	`paintMenuBar(Graphics g)` Paints the menubar, if in fullscreen mode.
`protected void`	`paintScreen(Graphics g)` Paints the screen.
`protected void`	`paintScrollBar(Graphics g)` Paints the scrollbar of this screen.
`protected void`	`paintTitleAndSubtitle(Graphics g)` Paints the title (if in fullscreen mode) and the subtitle of this screen
`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(Command cmd)` Removes a command from the `Displayable`.
`void`	`removeCommandsLayer()`
`protected void`	`removeItemCommands(Item item)` Removes the commands of the given item.
`void`	`removePermanentNativeItem(Item item)` Notifies this screen about an item with a native componen that is removed on BlackBerry platforms.
`void`	`removeSubCommand(Command childCommand, Command parentCommand)` Removes the given command as a subcommand.
`protected void`	`requestInit()` Reinitializes this screen's content area.
`void`	`requestRepaint()` Forwards a repaint request only when those requests should not be ignored.
`void`	`requestRepaint(int x, int y, int width, int height)` Forwards a repaint request only when those requests should not be ignored.
`void`	`resetStyle(boolean recursive)` Resets the style of this screen and all its elements.
`void`	`scrollRelative(int amount)` Scrolls this screen by the given amount.
`void`	`scrollToBottom()` Scrolls this screen so that the last item is in the visible space
`void`	`setCommandListener(CommandListener listener)` Sets the commandlistener for this canvas
`void`	`setCommandListener(CommandListener listener)` Sets the command listener for this screen
`void`	`setFullScreenMode(boolean enable)` Controls whether the `Canvas` is in full-screen mode or in normal mode.
`void`	`setInfo(Item info)` Sets the information which should be shown to the user.
`void`	`setInfo(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(ItemStateListener iListener)` Sets the `ItemStateListener` for the `Screen`, replacing any previous `ItemStateListener`.
`void`	`setLastInteractionTime(long currentTimeMillis)` Sets the last interaction time for this screen.
`void`	`setMenuBarStyle(Style menuBarStyle)` Sets the style for the menubar.
`void`	`setMenuItemStyle(Style menuItemStyle)` Sets the style for menuItems.
`void`	`setNativeScreen(NativeScreen nativeScreen)` Species a native implementation for this screen.
`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`	`setRootContainer(Container cont)` Sets the root container of this screen
`void`	`setScreenData(Object data)` Attaches data to this screen.
`void`	`setScreenInitializerListener(ScreenInitializerListener listener)` Sets a new screen initializer listener.
`void`	`setScreenOrientation(int degrees)` Deprecated. use Display.getInstance().setScreenOrientation(int) instead
`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.
`void`	`setStyle(Style style, boolean resetStyle)` Sets the style with animatable CSS attributes of this user interface element.
`protected void`	`setSubTitle(Item subTitle)` Sets the subtitle element.
`void`	`setTitle(Item item)` Sets an Item as the title for this screen.
`void`	`setTitle(Item item, Style tStyle)` Sets an Item as the title for this screen.
`void`	`setTitle(String s)` Sets the title of the Screen.
`void`	`setTitle(String text, Style tStyle)` Sets the title of the Screen.
`void`	`setUiEventListener(UiEventListener listener)` Sets an UiEventListener for this screen and its items.
`void`	`showNotify()` Initialises this screen and informs all items about being painted soon.
`void`	`sizeChanged(int width, int height)` Adjusts the size of this screen.
`String`	`toString()`

Methods inherited from class de.enough.polish.ui.Canvas
`_hideNotify, _hideNotifyExternal, _showNotify, getGameAction, getHeight, getKeyCode, getKeyName, getWidth, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, hideNotifyExternal, isDoubleBuffered, isShown, keyPressed, keyReleased, keyRepeated, pointerDragged, pointerPressed, pointerReleased, repaint, setTicker`

Methods inherited from class javax.microedition.lcdui.Canvas
`repaint, repaint, serviceRepaints`

Methods inherited from class javax.microedition.lcdui.Displayable
`getTicker, removeCommand, setTicker`

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

Field Detail

title

protected Item title

subTitleHeight

protected int subTitleHeight

titleHeight

protected int titleHeight

background

protected Background background

backgroundX

protected int backgroundX

backgroundY

protected int backgroundY

backgroundWidth

protected int backgroundWidth

backgroundHeight

protected int backgroundHeight

border

protected Border border

style

protected Style style

contentBackgroundWidth

protected Dimension contentBackgroundWidth

contentBackgroundHeight

protected Dimension contentBackgroundHeight

contentBackgroundAnchor

protected int contentBackgroundAnchor

contentBackground

protected Background contentBackground

the content's (container) background

contentBorder

protected Border contentBorder

the content's (container) border

contentBgBorder

protected Border contentBgBorder

the content's (container) border that is drawn before the content-background is drawn

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 String cssSelector

container

protected Container container

lastTriggeredCommand

protected 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

determines whether the info text should be shown

keyPressedProcessed

public boolean keyPressedProcessed

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

keyReleasedProcessed

public boolean keyReleasedProcessed

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

contentX

protected int contentX

contentY

protected int contentY

contentWidth

protected int contentWidth

contentHeight

protected int contentHeight

repaintPreviousScreen

protected boolean repaintPreviousScreen

previousScreenOverlayBackground

protected Background previousScreenOverlayBackground

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

lastAnimateTime

protected long lastAnimateTime

isAnimated

protected boolean isAnimated

enableScreenChangeAnimation

protected boolean enableScreenChangeAnimation

landscapeStyle

protected Style landscapeStyle

portraitStyle

protected Style portraitStyle

userEventRepaintRegion

protected final ClippingRegion userEventRepaintRegion

Constructor Detail

Screen

public Screen(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(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(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

init

protected void init(int width,
                    int height)

Initializes this screen before it is painted for the first time.

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

public 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

public 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 initializes 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.

adjustContentArea

protected void adjustContentArea(int x,
                                 int y,
                                 int width,
                                 int height,
                                 Container cont)

Subclasses may override this to adjust the content area of a screen. The default implementation informs a ScreenInitializerListener

Parameters:: x - the contentX field; y - the contentY field; width - the contentWidth field; height - the contentHeight field; cont - the container, may be null
See Also:: setScreenInitializerListener(ScreenInitializerListener)

initContent

protected void initContent(Container cont)

Initializes the container and background position

Parameters:: cont - the container, may be null if no container is used at all.

showNotify

public void showNotify()

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

Overrides:: showNotify in class Canvas

hideNotify

public void hideNotify()

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

Overrides:: hideNotify in class Canvas

resetStyle

public void resetStyle(boolean recursive)

Resets the style of this screen and all its elements. This is useful when you have applied changes to this screen's style or one of its elements.

Parameters:: recursive - true when all subelements of this screen should reset their style as well.

setStyle

public void setStyle(Style style)

Sets the style of this screen.

Specified by:: setStyle in interface UiElement

Parameters:: style - the style
See Also:: setStyle(Style, boolean)

setStyle

public void setStyle(Style style,
                     boolean resetStyle)

Description copied from interface: UiElement

Sets the style with animatable CSS attributes of this user interface element.

Specified by:: setStyle in interface UiElement

Parameters:: style - the new style for this element.; resetStyle - true when style settings should be resetted. This is not the case when styles are animated, for example.

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.

Specified by:: animate in interface Animatable

Parameters:: currentTime - the current time in milliseconds; repaintRegion - the repaint area that needs to be updated when this item is animated
See Also:: Item.addRelativeToContentRegion(ClippingRegion, int, int, int, int)

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(Graphics g)

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

Specified by:: paint in class Canvas

Parameters:: g - the graphics context.
See Also:: paintScreen(Graphics)

paintScrollBar

protected void paintScrollBar(Graphics g)

Paints the scrollbar of this screen. Note: from J2ME Polish 2.2 this functionality will move into Item.

Parameters:: g - the Graphics context

paintMenuBar

protected void paintMenuBar(Graphics g)

Paints the menubar, if in fullscreen mode. Also scroll indicators are painted here, in case no scrollbar is being used

Parameters:: g - the graphics context

paintTitleAndSubtitle

protected void paintTitleAndSubtitle(Graphics g)

Paints the title (if in fullscreen mode) and the subtitle of this screen

Parameters:: g - the graphics context

paintBackgroundAndBorder

protected void paintBackgroundAndBorder(Graphics g)

Paints the background and border for this screen.

Parameters:: g - the graphics context

canScrollDown

protected boolean canScrollDown()

Checks if this screen can currently scroll downwards.

Returns:: true when scrolling down is possible.

canScrollUp

protected boolean canScrollUp()

Checks if this screen can currently scroll upwards.

Returns:: true when scrolling up is possible.

getScrollDownBackgroundOffset

protected int getScrollDownBackgroundOffset()

Retrieves the scroll down offset

Returns:: the offset in pixels until the bottom of the scrollable area, 0 if the bottom is reached, otherwise a positive number of pixels.

getScrollUpBackgroundOffset

protected int getScrollUpBackgroundOffset()

Retrieves the scroll up offset

Returns:: the offset in pixels until the top of the scrollable area, 0 if the top is reached, otherwise a positive number of pixels.

paintScreen

protected void paintScreen(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 String getTitle()

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

Specified by:: getTitle in interface Displayable
Overrides:: getTitle in class Canvas

Returns:: the title of this screen
See Also:: Displayable.setTitle(java.lang.String)

setTitle

public void setTitle(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.

Specified by:: setTitle in interface Displayable
Overrides:: setTitle in class Canvas

Parameters:: s - - the new title, or null for no title
See Also:: Displayable.getTitle()

setTitle

public void setTitle(String text,
                     Style tStyle)

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

setTitle

public void setTitle(Item item,
                     Style tStyle)

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; tStyle - the new style for the title, is ignored when null

getTitleItem

public Item getTitleItem()

Retrieves this screen's title item (when the fullscreen mode of J2ME Polish is activated)

Returns:: the title of this screen as an item

setInfo

public void setInfo(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

setInfo

public void setInfo(Item info)

Parameters:: info - the info item 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)

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.

Specified by:: getPolishTicker in interface Displayable
Overrides:: getPolishTicker in class Canvas

Returns:: ticker object used, or null if no ticker is present
See Also:: Displayable.setTicker(Ticker)

getKeyStates

public int getKeyStates()

Gets the states of the physical game keys. Each bit in the returned integer represents a specific key on the device. A key's bit will be 1 if the key is currently down or has been pressed at least once since the last time this method was called. The bit will be 0 if the key is currently up and has not been pressed at all since the last time this method was called. This latching behavior ensures that a rapid key press and release will always be caught by an application loop, regardless of how slowly the loop runs.

For example:

 
 // Get the key state and store it
 int keyState = getKeyStates();
 if ((keyState & UiAccess.LEFT_KEY) != 0) {
                positionX--;
 }
 else if ((keyState & UiAccess.RIGHT_KEY) != 0) {
                positionX++;
 }

Calling this method has the side effect of clearing any latched state. Another call to getKeyStates immediately after a prior call will therefore report the system's best idea of the current state of the keys, the latched bits having been cleared by the first call.

On J2ME Polish this method is implemented by monitoring key press and release events. Thus the state reported by getKeyStates might lag the actual state of the physical keys since the timeliness of the key information is be subject to the capabilities of each device. Also, some devices may be incapable of detecting simultaneous presses of multiple keys.

This method returns 0 unless the GameCanvas is currently visible as reported by Displayable.isShown(). Upon becoming visible, a GameCanvas will initially indicate that all keys are unpressed (0); if a key is held down while the GameCanvas is being shown, the key must be first released and then pressed in order for the key press to be reported by the GameCanvas.

Returns:: An integer containing the key state information (one bit per key), or 0 if the GameCanvas is not currently shown.
See Also:: UiAccess.UP_PRESSED, UiAccess.DOWN_PRESSED, UiAccess.LEFT_PRESSED, UiAccess.RIGHT_PRESSED, UiAccess.FIRE_PRESSED, UiAccess.GAME_A_PRESSED, UiAccess.GAME_B_PRESSED, UiAccess.GAME_C_PRESSED, UiAccess.GAME_D_PRESSED

_keyPressed

public boolean _keyPressed(int keyCode)

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

Overrides:: _keyPressed in class Canvas

Parameters:: keyCode - The code of the pressed key
Returns:: true when the event was handled/consumed

_keyRepeated

public boolean _keyRepeated(int keyCode)

Just maps the event to the the keyPressed method.

Overrides:: _keyRepeated in class Canvas

Parameters:: keyCode - the code of the key, which is pressed repeatedly
Returns:: true when the event was handled/consumed
See Also:: Canvas.hasRepeatEvents()

_keyReleased

public boolean _keyReleased(int keyCode)

Is called when a key is released.

Overrides:: _keyReleased in class Canvas

Parameters:: keyCode - the code of the key, which has been released
Returns:: true when the event was handled/consumed

createCssSelector

protected abstract 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(CommandListener listener)

Description copied from class: Canvas

Sets the commandlistener for this canvas

Specified by:: setCommandListener in interface Displayable
Overrides:: setCommandListener in class Canvas

Parameters:: listener - the listener, use null to remove command listener

setCommandListener

public void setCommandListener(CommandListener listener)

Sets the command listener for this screen

Overrides:: setCommandListener in class Displayable

Parameters:: listener - the listener

getCommandListener

public CommandListener getCommandListener()

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

Overrides:: getCommandListener in class Canvas

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

addCommand

public void addCommand(Command cmd)

Adds a command to this screen

Overrides:: addCommand in class Displayable

Parameters:: cmd - the command

addCommand

public void addCommand(Command cmd)

Description copied from interface: Displayable

Adds a command to the Displayable. The implementation may choose, for example, to add the command to any of the available soft buttons or place it in a menu. If the added command is already in the screen (tested by comparing the object references), the method has no effect. If the Displayable is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

Specified by:: addCommand in interface Displayable
Overrides:: addCommand in class Canvas

Parameters:: cmd - the command to be added

addCommand

public void addCommand(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(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.

getCommands

public Object[] getCommands()

Description copied from class: Canvas

Retrieves all commands as an object array which may contain null values

Overrides:: getCommands in class Canvas

Returns:: all registered commands, may be null

addSubCommand

public void addSubCommand(Command child,
                          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(Command child,
                          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:: IllegalStateException - when the parent command has not been added before

removeCommand

public void removeCommand(Command cmd)

Description copied from interface: Displayable

Removes a command from the Displayable. If the command is not in the Displayable (tested by comparing the object references), the method has no effect. If the Displayable is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so. If cmd is null, this method does nothing.

Specified by:: removeCommand in interface Displayable
Overrides:: removeCommand in class Canvas

Parameters:: cmd - the command to be removed

removeSubCommand

public void removeSubCommand(Command childCommand,
                             Command parentCommand)

Removes the given command as a subcommand.

Parameters:: childCommand - the command to remove; parentCommand - the parent command of the command to remove.
Throws:: IllegalStateException - when the command has not been added before

addCommandsLayer

public void addCommandsLayer(Command[] commands)

Parameters:: commands -

removeCommandsLayer

public void removeCommandsLayer()

setItemCommands

protected void setItemCommands(ArrayList commandsList,
                               Item item)

Sets the commands of the given item

Parameters:: commandsList - the commands that are added; item - the item which contains the specified commands
See Also:: removeItemCommands(Item)

notifyDefaultCommand

public void notifyDefaultCommand(Command cmd)

Informs this screen about a new default command for a focused item

Parameters:: cmd - the new default command

getDefaultCommand

protected Command getDefaultCommand(Item item)

Retrieves the default command of the specfied item. Default implementation just calls item.getDefaultCommand

Parameters:: item - the item
Returns:: the default command associated with the item, or null

clearItemCommands

protected void clearItemCommands()

Removes commands from the complete focused item hierarchy

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(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(Command command,
                          Displayable screen)

_pointerPressed

public boolean _pointerPressed(int x,
                               int y)

Description copied from class: Canvas

Called when the pointer is pressed. For backwards compatibility this method calls pointerPressed(int,int).

Overrides:: _pointerPressed in class Canvas

Parameters:: x - - the horizontal location where the pointer was pressed (relative to the Canvas); y - - the vertical location where the pointer was pressed (relative to the Canvas)

_pointerDragged

public boolean _pointerDragged(int x,
                               int y)

Description copied from class: Canvas

Called when the pointer is dragged. For backwards compatibility this method calls pointerDragged(int,int).

Overrides:: _pointerDragged in class Canvas

Parameters:: x - the horizontal location where the pointer was dragged (relative to the Canvas); y - the vertical location where the pointer was dragged (relative to the Canvas)

_pointerReleased

public boolean _pointerReleased(int x,
                                int y)

Description copied from class: Canvas

Called when the pointer is released. For backwards compatibility this method calls pointerReleased(int,int).

Overrides:: _pointerReleased in class Canvas

Parameters:: x - the horizontal location where the pointer was released (relative to the Canvas); y - the vertical location where the pointer was released (relative to the 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 screen.

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 release; y - the absolute y position of the pointer release
Returns:: true when releasing the pointer was actually handled by this screen.

handlePointerReleasedOutsideScreenArea

protected boolean handlePointerReleasedOutsideScreenArea(int x,
                                                         int y)

Handles the release of a pointer outside of this screens area. 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 fires the back command, if present. Otherwise it will fire the only command (when there is just one command on this screen).

Parameters:: x - the absolute x position of the pointer release (outside of this screen's area); y - the absolute y position of the pointer release (outside of this screen's area)
Returns:: true when releasing the pointer was actually handled by this screen.

handlePointerDragged

protected boolean handlePointerDragged(int x,
                                       int y,
                                       ClippingRegion repaintRegion)

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

Parameters:: x - the absolute x position of the pointer movement; y - the absolute y position of the pointer movement
Returns:: true when the dragging of the pointer was actually handled by this screen.

handlePointerDragged

protected boolean handlePointerDragged(int x,
                                       int y)

Parameters:: x - the absolute x position of the pointer movement; y - the absolute y position of the pointer movement
Returns:: true when the dragging of the pointer was actually handled by this screen.
See Also:: handlePointerDragged(int, int, ClippingRegion)

handlePointerTouchDown

public boolean handlePointerTouchDown(int x,
                                      int y)

Deprecated. as BlackBerry used to differentiate between click and touch only on its first Storm model

Handles a touch down/press event. This is similar to a pointerPressed event, however it is only available on devices with screens that differentiate between press and touch events (read: BlackBerry Storm).

Overrides:: handlePointerTouchDown in class Canvas

Parameters:: x - the absolute horizontal pixel position of the touch event; y - the absolute vertical pixel position of the touch event
Returns:: true when the event was handled

handlePointerTouchUp

public boolean handlePointerTouchUp(int x,
                                    int y)

Deprecated. as BlackBerry used to differentiate between click and touch only on its first Storm model

Handles a touch up/release event. This is similar to a pointerReleased event, however it is only available on devices with screens that differentiate between press and touch events (read: BlackBerry Storm).

Overrides:: handlePointerTouchUp in class Canvas

Parameters:: x - the absolute horizontal pixel position of the touch event; y - the absolute vertical pixel position of the touch event
Returns:: true when the event was handled

handleCommand

protected boolean handleCommand(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

handleCommand

protected boolean handleCommand(Command cmd)

Parameters:: cmd - the command
Returns:: true when the command has been handled by this screen

setFullScreenMode

public void setFullScreenMode(boolean enable)

Description copied from class: Canvas

Controls whether the Canvas is in full-screen mode or in normal mode.

Overrides:: setFullScreenMode in class Canvas

Parameters:: enable - true if the Canvas is to be in full screen mode, false otherwise

sizeChanged

public void sizeChanged(int width,
                        int height)

Adjusts the size of this screen.

Specified by:: sizeChanged in interface Displayable
Overrides:: sizeChanged in class Canvas

Parameters:: width - the new width of the screen; height - the new height of the screen
See Also:: in class Displayable

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.
See Also:: getSubTitleItem()

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.

destroy

public void destroy()

Destroys the screen

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
See Also:: setScrollYOffset(int, boolean)

scrollToBottom

public void scrollToBottom()

Scrolls this screen so that the last item is in the visible space

setScreenData

public void setScreenData(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 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(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 or when the screen is not yet initialized

getScreenContentHeight

public int getScreenContentHeight()

Retrieves the height of the content area.

Returns:: the height available for the content in pixels
See Also:: for retrieving the screen's actual content height

getScreenContentWidth

public int getScreenContentWidth()

Retrieves the width of the content area.

Returns:: the width available for the content

getScreenContentX

public int getScreenContentX()

Retrieves the horizontal start position of the screen's content area

Returns:: the horizontal start in pixels from the left

getScreenContentY

public int getScreenContentY()

Retrieves the vertical start position of the screen's content area

Returns:: the vertical start in pixels from the top

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.
See Also:: setScrollYOffset(int, boolean), getScrollHeight()

getScrollHeight

public int getScrollHeight()

Retrieves this screen's actual content's height

Returns:: the content's height, 0 if unknown or not initialized yet
See Also:: getScrollYOffset()

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
See Also:: getScrollYOffset()

isActive

public boolean isActive()

Indicates if this screen is active (scrolling, key pressed etc.)

Returns:: true, if the screen was active in the given interval, otherwise false

isInteracted

public boolean isInteracted(long timespan)

Indicates if this screen was interacted with in the given timespan

Parameters:: timespan - the timespan
Returns:: true, if the screen was active in the given interval, otherwise false

setScreenOrientation

public void setScreenOrientation(int degrees)

Deprecated. use Display.getInstance().setScreenOrientation(int) instead

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
See Also:: Display.setScreenOrientation(int)

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

notifyFocusSet

protected void notifyFocusSet(Item item)

Notifies this screen about the new item that is focused on BlackBerry platforms. This is only called for BlackBerry platforms - check for the preprocesing symbol polish.blackberry.

Parameters:: item - the item that has been focused

isNativeUiShownFor

protected boolean isNativeUiShownFor(Item item)

Determines whether a native UI component is shown for the specified item. This is currently only implemented for BlackBerry platforms - check for the preprocesing symbol polish.blackberry.

Parameters:: item - the item that has been focused

addPermanentNativeItem

public void addPermanentNativeItem(Item item)

Notifies this screen about the new item with a native componen that is added on BlackBerry platforms. This is only called for BlackBerry platforms - check for the preprocesing symbol polish.blackberry.

Parameters:: item - the item with a native component which needs to be displayed all the time.

removePermanentNativeItem

public void removePermanentNativeItem(Item item)

Notifies this screen about an item with a native componen that is removed on BlackBerry platforms. This is only called for BlackBerry platforms - check for the preprocesing symbol polish.blackberry.

Parameters:: item - the item with a native component which was displayed all the time.

addRepaintArea

public void addRepaintArea(ClippingRegion repaintArea)

UI ELEMENT INTERFACE

Specified by:: addRepaintArea in interface UiElement

Parameters:: repaintArea - the clipping rectangle to which the repaint area should be added

addRelativeToContentRegion

public void addRelativeToContentRegion(ClippingRegion repaintRegion,
                                       int x,
                                       int y,
                                       int width,
                                       int height)

Adds a region relative to this screen's content x/y start position.

Specified by:: addRelativeToContentRegion in interface UiElement

Parameters:: repaintRegion - the clipping region; x - horizontal start relative to this item's content position; y - vertical start relative to this item's content position; width - width; height - height
See Also:: getScreenContentWidth(), getScreenContentWidth()

getStyle

public Style getStyle()

Description copied from interface: UiElement

Retrieves the currently used style

Specified by:: getStyle in interface UiElement

Returns:: the style of this UI element

fireEvent

public void fireEvent(String eventName,
                      Object eventData)

Fires an event for this screen and all its components. This is typically used for triggering animations within screen components like its title or menubar. Since all screen components fire events, this method should be called within a background thread and never from within a de.enough.polish.event.EventListener.

Parameters:: eventName - the name of the event; eventData - the associated data of the event
See Also:: fireEventForTitleAndMenubar(String, Object)

fireEventForTitleAndMenubar

public void fireEventForTitleAndMenubar(String eventName,
                                        Object eventData)

Fires an event for the title and menubar of the specified screen. This is typically used for triggering animations for the title and/or menubar. Since all these screen components fire events, this method should be called within a background thread and never from within a de.enough.polish.event.EventListener.

Parameters:: eventName - the name of the event; eventData - the associated data of the event
See Also:: fireEvent(String, Object)

getPaintLock

public Object getPaintLock()

Retrieves the lock object for the paint thread. You can use this paint lock to synchronize with the paint method of this screen.

Returns:: the paint lock object

getRootContainer

public Container getRootContainer()

Retrieves the root container of this screen

Returns:: the root container, this might be null for some subclasses

setRootContainer

public void setRootContainer(Container cont)

Sets the root container of this screen

Parameters:: cont - the root container

getTitleHeight

public int getTitleHeight()

Retrieves the height of the title.

Returns:: the height of the title in pixels or 0 when the title is null or is not rendered by J2ME Polish

setLastInteractionTime

public void setLastInteractionTime(long currentTimeMillis)

Sets the last interaction time for this screen. This is being used for stopping animations after an activity timeout.

Parameters:: currentTimeMillis - the time for the last interaction, typically System.currentTimeMillis()

setUiEventListener

public void setUiEventListener(UiEventListener listener)

Sets an UiEventListener for this screen and its items.

Parameters:: listener - the listener, use null to remove a listener

getUiEventListener

public UiEventListener getUiEventListener()

Retrieves the UiEventListener for this screen

Returns:: the listener or null, if none has been registered

getSubTitleItem

public Item getSubTitleItem()

Retrieves the subtitle of this screen.

Returns:: the subtitle, may be null
See Also:: setSubTitle(Item)

setScreenInitializerListener

public void setScreenInitializerListener(ScreenInitializerListener listener)

Sets a new screen initializer listener.

Parameters:: listener - the screen initialization listener
See Also:: getScreenInitializerListener()

getScreenInitializerListener

public ScreenInitializerListener getScreenInitializerListener()

Sets a new screen initializer listener.

Returns:: listener the screen initialization listener
See Also:: setScreenInitializerListener(ScreenInitializerListener)

setNativeScreen

public void setNativeScreen(NativeScreen nativeScreen)

Species a native implementation for this screen. This method is only available when the preprocessing variable polish.useNativeGui is set to true.

Parameters:: nativeScreen - the native implementation

getNativeScreen

public NativeScreen getNativeScreen()

Species a native implementation for this screen. This method is only available when the preprocessing variable polish.useNativeGui is set to true.

Returns:: the native implementation, can be null

addCommandSeparator

public void addCommandSeparator(int priority)

Adds a command separator to the menu of this screen.

Parameters:: priority - the priority of the sepator, same as for Command

addCommandSeparator

public void addCommandSeparator(int priority,
                                Style separatorStyle)

Adds a command separator to the menu of this screen.

Parameters:: priority - the priority of the sepator, same as for Command; separatorStyle - the style of the separator

toString

public String toString()

Overrides:: toString in class Object

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

de.enough.polish.ui Class Screen

title

subTitleHeight

titleHeight

background

backgroundX

backgroundY

backgroundWidth

backgroundHeight

border

style

contentBackgroundWidth

contentBackgroundHeight

contentBackgroundAnchor

contentBackground

contentBorder

contentBgBorder

screenHeight

originalScreenHeight

screenWidth

cssSelector

container

lastTriggeredCommand

fullScreenHeight

menuBarHeight

scrollBar

paintScrollBarOnRightSide

scrollBarVisible

infoHeight

keyPressedProcessed

keyReleasedProcessed

contentX

contentY

contentWidth

contentHeight

repaintPreviousScreen

previousScreenOverlayBackground

screenStateListener

itemStateListener

lastInteractionTime

ignoreRepaintRequests

isRepaintRequested

isInitRequested

triggerReleasedKeyCode

triggerReleasedTime

isScrollBackground

lastAnimateTime

isAnimated

enableScreenChangeAnimation

landscapeStyle

portraitStyle

userEventRepaintRegion

Screen

Screen

Screen

init

requestInit

requestRepaint

requestRepaint

checkForRequestInit

calculateContentArea

adjustContentArea

initContent

showNotify

hideNotify

resetStyle

setStyle

setStyle

animate

animate

paint

paintScrollBar

paintMenuBar

paintTitleAndSubtitle

paintBackgroundAndBorder

canScrollDown

canScrollUp

getScrollDownBackgroundOffset

getScrollUpBackgroundOffset

paintScreen

de.enough.polish.ui
Class Screen