de.enough.polish.ui
Class Alert

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

All Implemented Interfaces:

AccessibleCanvas, javax.microedition.lcdui.CommandListener

public class Alert
extends Screen
implements javax.microedition.lcdui.CommandListener

An alert is a screen that shows data to the user and waits for a certain period of time before proceeding to the next Displayable. An alert can contain a text string and an image. The intended use of Alert is to inform the user about errors and other exceptional conditions.

The application can set the alert time to be infinity with setTimeout(Alert.FOREVER) in which case the Alert is considered to be modal and the implementation provide a feature that allows the user to "dismiss" the alert, whereupon the next Displayable is displayed as if the timeout had expired immediately.

If an application specifies an alert to be of a timed variety and gives it too much content such that it must scroll, then it automatically becomes a modal alert.

An alert may have an AlertType associated with it to provide an indication of the nature of the alert. The implementation may use this type to play an appropriate sound when the Alert is presented to the user. See AlertType.playSound().

An alert may contain an optional Image. The Image may be mutable or immutable. If the Image is mutable, the effect is as if a snapshot of its contents is taken at the time the Alert is constructed with this Image and when setImage is called with an Image. This snapshot is used whenever the contents of the Alert are to be displayed. Even if the application subsequently draws into the Image, the snapshot is not modified until the next call to setImage. The snapshot is not updated when the Alert becomes current or becomes visible on the display. (This is because the application does not have control over exactly when Displayables appear and disappear from the display.)

Activity Indicators

An alert may contain an optional Gauge object that is used as an activity or progress indicator. By default, an Alert has no activity indicator; one may be set with the setIndicator(javax.microedition.lcdui.Gauge) method. The Gauge object used for the activity indicator must conform to all of the following restrictions:

• it must be non-interactive;
• it must not be owned by another container (Alert or Form);
• it must not have any Commands;
• it must not have an ItemCommandListener;
• it must not have a label (that is, its label must be null;
• its preferred width and height must both be unlocked; and
• its layout value must be LAYOUT_DEFAULT.

It is an error for the application to attempt to use a Gauge object that violates any of these restrictions. In addition, when the Gauge object is being used as the indicator within an Alert, the application is prevented from modifying any of these pieces of the Gauge's state.

Commands and Listeners

Like the other Displayable classes, an Alert can accept Commands, which can be delivered to a CommandListener set by the application. The Alert class adds some special behavior for Commands and listeners.

When it is created, an Alert implicitly has the special Command DISMISS_COMMAND present on it. If the application adds any other Commands to the Alert, DISMISS_COMMAND is implicitly removed. If the application removes all other Commands, DISMISS_COMMAND is implicitly restored. Attempts to add or remove DISMISS_COMMAND explicitly are ignored. Thus, there is always at least one Command present on an Alert.

If there are two or more Commands present on the Alert, it is automatically turned into a modal Alert, and the timeout value is always FOREVER. The Alert remains on the display until a Command is invoked. If the Alert has one Command (whether it is DISMISS_COMMAND or it is one provided by the application), the Alert may have the timed behavior as described above. When a timeout occurs, the effect is the same as if the user had invoked the Command explicitly.

When it is created, an Alert implicitly has a CommandListener called the default listener associated with it. This listener may be replaced by an application-provided listener through use of the setCommandListener(javax.microedition.lcdui.CommandListener) method. If the application removes its listener by passing null to the setCommandListener method, the default listener is implicitly restored.

The Display.setCurrent(Alert, Displayable) method and the Display.setCurrent(Displayable) method (when called with an Alert) define special behavior for automatically advancing to another Displayable after the Alert is dismissed. This special behavior occurs only when the default listener is present on the Alert at the time it is dismissed or when a command is invoked. If the user invokes a Command and the default listener is present, the default listener ignores the Command and implements the automatic-advance behavior.

If the application has set its own CommandListener, the automatic-advance behavior is disabled. The listener code is responsible for advancing to another Displayable. When the application has provided a listener, Commands are invoked normally by passing them to the listener's commandAction method. The Command passed will be one of the Commands present on the Alert: either DISMISS_COMMAND or one of the application-provided Commands.

The application can restore the default listener by passing null to the setCommandListener method.

Note: An application may set a Ticker with Displayable.setTicker on an Alert, however it may not be displayed due to implementation restrictions.

copyright Enough Software 2005 - 2008

Since:

MIDP 1.0

Field Summary

static javax.microedition.lcdui.Command	DISMISS_COMMAND A Command delivered to a listener to indicate that the Alert has been dismissed.
static int	FOREVER FOREVER indicates that an Alert is kept visible until the user dismisses it.
protected javax.microedition.lcdui.Displayable	nextDisplayable

Fields inherited from class de.enough.polish.ui.Screen

background, border, container, contentHeight, contentWidth, contentX, contentY, cssSelector, fullScreenHeight, ignoreRepaintRequests, infoHeight, isInitRequested, isRepaintRequested, isScrollBackground, isSetFullScreenCalled, itemStateListener, keyPressedProcessed, keyReleasedProcessed, lastInteractionTime, lastTriggeredCommand, menuBarHeight, originalScreenHeight, paintScrollBarOnRightSide, screenHeight, screenOrientationDegrees, screenStateListener, screenWidth, scrollBar, scrollBarVisible, style, subTitleHeight, title, titleHeight, triggerReleasedKeyCode, 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

Alert(java.lang.String title)
Constructs a new, empty Alert object with the given title.

Alert(java.lang.String title, java.lang.String alertText, javax.microedition.lcdui.Image alertImage, javax.microedition.lcdui.AlertType alertType)
Constructs a new Alert object with the given title, content string and image, and alert type.

Alert(java.lang.String title, java.lang.String alertText, javax.microedition.lcdui.Image alertImage, javax.microedition.lcdui.AlertType alertType, Style style)
Constructs a new Alert object with the given title, content string and image, and alert type.

Alert(java.lang.String title, Style style)
Constructs a new, empty Alert object with the given title.

Method Summary

void	addCommand(javax.microedition.lcdui.Command cmd)
void	animate(long currentTime, ClippingRegion repaintRegion) Animates this screen.
void	commandAction(javax.microedition.lcdui.Command cmd, javax.microedition.lcdui.Displayable thisScreen)
protected java.lang.String	createCssSelector() Retrieves the CSS selector for this screen.
int	getDefaultTimeout() Gets the default time for showing an Alert, this is Alert.FOREVER in J2ME Polish.
javax.microedition.lcdui.Image	getImage() Gets the Image used in the Alert.
Gauge	getIndicator() Gets the activity indicator for this Alert.
java.lang.String	getString() Gets the text string used in the Alert.
int	getTimeout() Gets the time this Alert will be shown.
javax.microedition.lcdui.AlertType	getType() Gets the type of the Alert.
void	removeCommand(javax.microedition.lcdui.Command cmd)
void	setCommandListener(javax.microedition.lcdui.CommandListener listener)
static void	setCurrent(javax.microedition.lcdui.Display display, Alert alert, javax.microedition.lcdui.Displayable nextDisplayable) Makes the specified alert followed by the specified displayable visible.
void	setImage(javax.microedition.lcdui.Image img) Sets the Image used in the Alert.
void	setImage(javax.microedition.lcdui.Image img, Style style) Sets the Image used in the Alert.
void	setIndicator(Gauge indicator) Sets an activity indicator on this Alert.
void	setIndicator(Gauge indicator, Style style) Sets an activity indicator on this Alert.
void	setString(java.lang.String str) Sets the text string used in the Alert.
void	setString(java.lang.String str, Style style) Sets the text string used in the Alert.
void	setStyle(Style style) Sets the style of this screen.
void	setTimeout(int time) Set the time for which the Alert is to be shown.
void	setType(javax.microedition.lcdui.AlertType type) Sets the type of the Alert.
void	showNotify() Initialises this screen and informs all items about being painted soon.

Methods inherited from class de.enough.polish.ui.Screen

addCommand, addSubCommand, addSubCommand, animate, calculateContentArea, callCommandListener, checkForRequestInit, closeMenu, focus, focus, focus, focus, focus, getAvailableHeight, getCommandItem, getCommandListener, getCurrentIndex, getCurrentItem, getGameAction, getItemAt, getMenuBar, getPolishTicker, getRootItems, getScreenContentHeight, getScreenContentWidth, getScreenData, getScreenFullHeight, getScreenFullWidth, getScreenHeight, getScreenStyle, getScrollBarWidth, getScrollYOffset, getTitle, handleCommand, handleKeyPressed, handleKeyReleased, handleKeyRepeated, handlePointerPressed, handlePointerReleased, hideNotify, isGameActionFire, isKeyboardAccessible, isMenuOpened, isShown, isSoftKey, isSoftKey, isSoftKeyLeft, isSoftKeyMiddle, isSoftKeyRight, keyPressed, keyReleased, keyRepeated, notifyScreenStateChanged, notifyStateListener, paint, paintScreen, pointerDragged, pointerPressed, pointerReleased, releaseResources, removeAllCommands, removeItemCommands, requestInit, requestRepaint, requestRepaint, scrollRelative, setFullScreenMode, setInfo, setItemCommands, setItemStateListener, setItemStateListener, setMenuBarStyle, setMenuItemStyle, setPolishTicker, setPolishTicker, setScreenData, setScreenOrientation, setScreenStateListener, setScrollYOffset, setSubTitle, setTitle, setTitle, setTitle, sizeChanged

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

FOREVER

public static final int FOREVER

FOREVER indicates that an Alert is kept visible until the user dismisses it. It is used as a value for the parameter to setTimeout() to indicate that the alert is modal. Instead of waiting for a specified period of time, a modal Alert will wait for the user to take some explicit action, such as pressing a button, before proceeding to the next Displayable.

Value -2 is assigned to FOREVER.

See Also:

Constant Field Values

DISMISS_COMMAND

public static javax.microedition.lcdui.Command DISMISS_COMMAND

A Command delivered to a listener to indicate that the Alert has been dismissed. This Command is implicitly present an on Alert whenever there are no other Commands present. The field values of DISMISS_COMMAND are as follows:

• label = "" (an empty string)
• type = Command.OK
• priority = 0

The label value visible to the application must be as specified above. However, the implementation may display DISMISS_COMMAND to the user using an implementation-specific label.

Attempting to add or remove DISMISS_COMMAND from an Alert has no effect. However, DISMISS_COMMAND is treated as an ordinary Command if it is used with other Displayable types.

Since:

MIDP 2.0

nextDisplayable

protected javax.microedition.lcdui.Displayable nextDisplayable

Constructor Detail

Alert

public Alert(java.lang.String title)

Constructs a new, empty Alert object with the given title. If null is passed, the Alert will have no title. Calling this constructor is equivalent to calling

 Alert(title, null, null, null)
 

Parameters:

title - the title string, or null

See Also:

Alert(String, String, Image, AlertType)

Alert

public Alert(java.lang.String title,
             Style style)

Constructs a new, empty Alert object with the given title. If null is passed, the Alert will have no title. Calling this constructor is equivalent to calling

 Alert(title, null, null, null)
 

Parameters:

title - the title string, or null

style - the style of this Alert

See Also:

Alert(String, String, Image, AlertType)

Alert

public Alert(java.lang.String title,
             java.lang.String alertText,
             javax.microedition.lcdui.Image alertImage,
             javax.microedition.lcdui.AlertType alertType)

Constructs a new Alert object with the given title, content string and image, and alert type. The layout of the contents is implementation dependent. The timeout value of this new alert is the same value that is returned by getDefaultTimeout(). The Image provided may either be mutable or immutable. The handling and behavior of specific AlertTypes is described in AlertType. null is allowed as the value of the alertType parameter and indicates that the Alert is not to have a specific alert type. DISMISS_COMMAND is the only Command present on the new Alert. The CommandListener associated with the new Alert is the default listener. Its behavior is described in more detail in the section Commands and Listeners.

Parameters:

title - the title string, or null if there is no title

alertText - the string contents, or null if there is no string

alertImage - the image contents, or null if there is no image

alertType - the type of the Alert, or null if the Alert has no specific type

Alert

public Alert(java.lang.String title,
             java.lang.String alertText,
             javax.microedition.lcdui.Image alertImage,
             javax.microedition.lcdui.AlertType alertType,
             Style style)

Constructs a new Alert object with the given title, content string and image, and alert type. The layout of the contents is implementation dependent. The timeout value of this new alert is the same value that is returned by getDefaultTimeout(). The Image provided may either be mutable or immutable. The handling and behavior of specific AlertTypes is described in AlertType. null is allowed as the value of the alertType parameter and indicates that the Alert is not to have a specific alert type. DISMISS_COMMAND is the only Command present on the new Alert. The CommandListener associated with the new Alert is the default listener. Its behavior is described in more detail in the section Commands and Listeners.

Parameters:

title - the title string, or null if there is no title

alertText - the string contents, or null if there is no string

alertImage - the image contents, or null if there is no image

alertType - the type of the Alert, or null if the Alert has no specific type

style - the style of this Alert

Method Detail

addCommand

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

Overrides:

addCommand in class Screen

removeCommand

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

Overrides:

removeCommand in class Screen

setCommandListener

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

Overrides:

setCommandListener in class Screen

getDefaultTimeout

public int getDefaultTimeout()

Gets the default time for showing an Alert, this is Alert.FOREVER in J2ME Polish. This is either a positive value, which indicates a time in milliseconds, or the special value FOREVER, which indicates that Alerts are modal by default. The value returned will vary across implementations and is presumably tailored to be suitable for each.

Returns:

in J2ME Polish the default timeout is always FOREVER

getTimeout

public int getTimeout()

Gets the time this Alert will be shown. This is either a positive value, which indicates a time in milliseconds, or the special value FOREVER, which indicates that this Alert is modal. This value is not necessarily the same value that might have been set by the application in a call to setTimeout(int). In particular, if the Alert is made modal because its contents is large enough to scroll, the value returned by getTimeout will be FOREVER.

Returns:

timeout in milliseconds, or FOREVER

See Also:

setTimeout(int)

setTimeout

public void setTimeout(int time)

Set the time for which the Alert is to be shown. This must either be a positive time value in milliseconds, or the special value FOREVER.

Parameters:

time - - timeout in milliseconds, or FOREVER

Throws:

java.lang.IllegalArgumentException - - if time is not positive and is not FOREVER

See Also:

getTimeout()

getType

public javax.microedition.lcdui.AlertType getType()

Gets the type of the Alert.

Returns:

a reference to an instance of AlertType, or null if the Alert has no specific type

See Also:

setType(javax.microedition.lcdui.AlertType)

setType

public void setType(javax.microedition.lcdui.AlertType type)

Sets the type of the Alert. The handling and behavior of specific AlertTypes is described in AlertType.

Parameters:

type - - an AlertType, or null if the Alert has no specific type

See Also:

getType()

getString

public java.lang.String getString()

Gets the text string used in the Alert.

Returns:

the Alert's text string, or null if there is no text

See Also:

setString(java.lang.String)

setString

public void setString(java.lang.String str)

Sets the text string used in the Alert.

If the Alert is visible on the display when its contents are updated through a call to setString, the display will be updated with the new contents as soon as it is feasible for the implementation to do so.

Parameters:

str - the Alert's text string, or null if there is no text

See Also:

getString()

setString

public void setString(java.lang.String str,
                      Style style)

Sets the text string used in the Alert.

If the Alert is visible on the display when its contents are updated through a call to setString, the display will be updated with the new contents as soon as it is feasible for the implementation to do so.

Parameters:

str - the Alert's text string, or null if there is no text

style - the style

See Also:

getString()

getImage

public javax.microedition.lcdui.Image getImage()

Gets the Image used in the Alert.

Returns:

the Alert's image, or null if there is no image

See Also:

setImage(javax.microedition.lcdui.Image)

setImage

public void setImage(javax.microedition.lcdui.Image img)

Sets the Image used in the Alert. The Image may be mutable or immutable. If img is null, specifies that this Alert has no image. If img is mutable, the effect is as if a snapshot is taken of img's contents immediately prior to the call to setImage. This snapshot is used whenever the contents of the Alert are to be displayed. If img is already the Image of this Alert, the effect is as if a new snapshot of img's contents is taken. Thus, after painting into a mutable image contained by an Alert, the application can call

 alert.setImage(alert.getImage());    

to refresh the Alert's snapshot of its Image.

If the Alert is visible on the display when its contents are updated through a call to setImage, the display will be updated with the new snapshot as soon as it is feasible for the implementation to do so.

Parameters:

img - the Alert's image, or null if there is no image

See Also:

getImage()

setImage

public void setImage(javax.microedition.lcdui.Image img,
                     Style style)

Sets the Image used in the Alert. The Image may be mutable or immutable. If img is null, specifies that this Alert has no image. If img is mutable, the effect is as if a snapshot is taken of img's contents immediately prior to the call to setImage. This snapshot is used whenever the contents of the Alert are to be displayed. If img is already the Image of this Alert, the effect is as if a new snapshot of img's contents is taken. Thus, after painting into a mutable image contained by an Alert, the application can call

 alert.setImage(alert.getImage());    

to refresh the Alert's snapshot of its Image.

If the Alert is visible on the display when its contents are updated through a call to setImage, the display will be updated with the new snapshot as soon as it is feasible for the implementation to do so.

Parameters:

img - the Alert's image, or null if there is no image

style - the new style

See Also:

getImage()

setIndicator

public void setIndicator(Gauge indicator)

Sets an activity indicator on this Alert. The activity indicator is a Gauge object. It must be in a restricted state in order for it to be used as the activity indicator for an Alert. The restrictions are listed above. If the Gauge object violates any of these restrictions, IllegalArgumentException is thrown.

If indicator is null, this removes any activity indicator present on this Alert.

Parameters:

indicator - - the activity indicator for this Alert, or null if there is to be none

Throws:

java.lang.IllegalArgumentException - - if indicator does not meet the restrictions for its use in an Alert

Since:

MIDP 2.0

See Also:

getIndicator()

setIndicator

public void setIndicator(Gauge indicator,
                         Style style)

Sets an activity indicator on this Alert. The activity indicator is a Gauge object. It must be in a restricted state in order for it to be used as the activity indicator for an Alert. The restrictions are listed above. If the Gauge object violates any of these restrictions, IllegalArgumentException is thrown.

If indicator is null, this removes any activity indicator present on this Alert.

Parameters:

indicator - - the activity indicator for this Alert, or null if there is to be none

style - the style

Throws:

java.lang.IllegalArgumentException - - if indicator does not meet the restrictions for its use in an Alert

Since:

MIDP 2.0

See Also:

getIndicator()

getIndicator

public Gauge getIndicator()

Gets the activity indicator for this Alert.

Returns:

a reference to this Alert's activity indicator, or null if there is none

Since:

MIDP 2.0

See Also:

setIndicator( Gauge )

createCssSelector

protected java.lang.String createCssSelector()

Description copied from class: Screen

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

Specified by:

createCssSelector in class Screen

Returns:

the name of the appropriate CSS Selector for this screen.

animate

public void animate(long currentTime,
                    ClippingRegion repaintRegion)

Description copied from class: Screen

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

Overrides:

animate in class Screen

Parameters:

currentTime - the current time in milliseconds

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

commandAction

public void commandAction(javax.microedition.lcdui.Command cmd,
                          javax.microedition.lcdui.Displayable thisScreen)

Specified by:

commandAction in interface javax.microedition.lcdui.CommandListener

Overrides:

commandAction in class Screen

showNotify

public void showNotify()

Description copied from class: Screen

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

Specified by:

showNotify in interface AccessibleCanvas

Overrides:

showNotify in class Screen

setCurrent

public static void setCurrent(javax.microedition.lcdui.Display display,
                              Alert alert,
                              javax.microedition.lcdui.Displayable nextDisplayable)

Makes the specified alert followed by the specified displayable visible. This is a replacement for Display.setCurrent(Alert, Displayable), since the J2ME Polish alert is extending de.enough.polish.ui.Screen and not javax.microedition.lcdui.Alert.

Parameters:

display - the display

alert - the alert that should be shown, must not be null

nextDisplayable - the displayable that should be shown after the alert, can be null

setStyle

public void setStyle(Style style)

Description copied from class: Screen

Sets the style of this screen.

Overrides:

setStyle in class Screen

Parameters:

style - the style