org.j4me.ui
Class Dialog

java.lang.Object
  extended by org.j4me.ui.DeviceScreen
      extended by org.j4me.ui.Dialog
Direct Known Subclasses:
Menu

public abstract class Dialog
extends DeviceScreen

The Dialog class is a base class for any screen that accepts user input using standard components like the text box. It is similar to the MIDP Form class except that it uses the J4ME control flow and has an OK and Cancel button built in.

Form classes can only have component objects, like the text box or label, placed on them. The class handles layout, painting, and management of the components. If you need direct control over the appearance of the screen use the DeviceScreen class.

See Also:
Form

Field Summary
 
Fields inherited from class org.j4me.ui.DeviceScreen
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, MENU_LEFT, MENU_RIGHT, RIGHT, UP
 
Constructor Summary
Dialog()
          Implicitly called by derived classes to setup a new J4ME form.
 
Method Summary
 void append(Component component)
          Adds the component to the end of this form.
 java.util.Enumeration components()
          Returns an enumeration of the components on this form.
 void delete(Component component)
          Removes the first occurrence of the component from this form.
 void delete(int index)
          Deletes the component at the specified index.
 void deleteAll()
          Removes all of the components from this form.
 Component get(int index)
          Returns the component at the specified index.
 int getMargin()
          Returns the margin for the left and right of the screen.
 int getSelected()
          Returns the index of the currently selected component.
 int getSpacing()
          Returns the vertical spacing between components.
 int getWidth()
          Returns the width of the usuable portion of this form.
 boolean hasVerticalScrollbar()
          Determines if the height of all the components is greater than the height of the screen.
 void hideNotify()
          Called immediately before this screen is replaced by another screen.
 void insert(Component component, int index)
          Inserts the component in this form at the specified index.
 void invalidate()
          Forces the layout of all components to be recalculated.
protected  void keyPressed(int keyCode)
          Called when a key is pressed.
protected  void keyReleased(int keyCode)
          Called when a key is released.
protected  void keyRepeated(int keyCode)
          Called when a key is repeated (held down).
protected  void paint(javax.microedition.lcdui.Graphics g)
          Paints the form and its components.
protected  void paintVerticalScrollbar(javax.microedition.lcdui.Graphics g, int x, int y, int width, int height, int offset, int formHeight)
          Paints the vertical scrollbar.
protected  void pointerDragged(int x, int y)
          Called when the pointer is dragged.
protected  void pointerPressed(int x, int y)
          Called when the pointer is pressed.
protected  void pointerReleased(int x, int y)
          Called when the pointer is released.
 void set(Component component, int index)
          Sets the component in this form at the specified index.
 void setFullScreenMode(boolean mode)
          Shows or hides the menu bar at the bottom of the screen.
 void setMargin(int margin)
          Sets the margin for the left and right of the screen.
 void setMenuText(java.lang.String left, java.lang.String right)
          Sets the menu bar text.
 void setSelected(Component component)
          Sets the selected component.
 void setSelected(int index)
          Sets the selected component.
 void setSpacing(int spacing)
          Sets the vertical spacing between components.
 void setTitle(java.lang.String title)
          Sets the title of this screen.
 int size()
          Returns the number of components on this form.
 
Methods inherited from class org.j4me.ui.DeviceScreen
acceptNotify, declineNotify, getCanvas, getHeight, getLeftMenuText, getRightMenuText, getScreenHeight, getScreenWidth, getTitle, hasMenuBar, hasTitleBar, intersects, isFullScreenMode, isShown, paintBackground, paintMenuBar, paintTitleBar, repaint, repaint, serviceRepaints, show, showNotify, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Dialog

public Dialog()
Implicitly called by derived classes to setup a new J4ME form.

Method Detail

hideNotify

public void hideNotify()
Called immediately before this screen is replaced by another screen.

Notifies all the components they are hidden. Classes that override this method should be sure to call super.onDeselection.

Overrides:
hideNotify in class DeviceScreen
See Also:
DeviceScreen.hideNotify()

append

public void append(Component component)
Adds the component to the end of this form.

Parameters:
component - is the UI component to add to the bottom of the form.

insert

public void insert(Component component,
                   int index)
Inserts the component in this form at the specified index. Each component on this form with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

Parameters:
component - is the UI component to insert.
index - is where to insert component on the form. It must greater than or equal to 0 and less than or equal to the number of components already on the form.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

set

public void set(Component component,
                int index)
Sets the component in this form at the specified index. The previous component at that position is discarded.

Parameters:
component - is the UI component to set to.
index - is where to set component on the form. It must greater than or equal to 0 and less than the number of components already on the form.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

delete

public void delete(Component component)
Removes the first occurrence of the component from this form. If component is found on this form, each component on the form with an index greater or equal to the component's index is shifted downward to have an index one smaller than the value it had previously.

Parameters:
component - is the UI component to remove.

delete

public void delete(int index)
Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously.

Parameters:
index - is the index of the component to remove. It must be a value greater than or equal to 0 and less than the current number of components on the form.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

deleteAll

public void deleteAll()
Removes all of the components from this form.


components

public java.util.Enumeration components()
Returns an enumeration of the components on this form.

Returns:
An enumeration of the components on this form.

size

public int size()
Returns the number of components on this form.

Returns:
The number of components on this form.

get

public Component get(int index)
Returns the component at the specified index.

Parameters:
index - is the value into the component list to get.
Returns:
The component at index or null if the index is invalid.

getSelected

public int getSelected()
Returns the index of the currently selected component. It is the one the user can currently enter data into.

Returns:
The index of the component on the form that is currently selected.

setSelected

public void setSelected(int index)
Sets the selected component. It is the one the user can input data into and that the screen is scrolled to.

Parameters:
index - is the new selected component.

setSelected

public void setSelected(Component component)
Sets the selected component. It is the one the user can input data into and that the screen is scrolled to.

Parameters:
component - is the new selected component. If it is not on the form this has no effect.

paint

protected void paint(javax.microedition.lcdui.Graphics g)
Paints the form and its components. The layout is calculated from the components and their order.

Specified by:
paint in class DeviceScreen
Parameters:
g - is the Graphics object to paint with.
See Also:
DeviceScreen.paintBackground(Graphics)

paintVerticalScrollbar

protected void paintVerticalScrollbar(javax.microedition.lcdui.Graphics g,
                                      int x,
                                      int y,
                                      int width,
                                      int height,
                                      int offset,
                                      int formHeight)
Paints the vertical scrollbar. The scrollbar must go on the right side of the form and span from the top to the bottom. Its width is returned from this method and used to calculate the width of the remaining form area to draw components in.

Parameters:
g - is the Graphics object to paint with.
x - is the top-left X-coordinate pixel of the form area.
y - is the top-left Y-coordinate pixel of the form area.
width - is the width of the form area in pixels.
height - is the height of the form area in pixels.
offset - is the vertical scrolling position of the top pixel to show on the form area.
formHeight - is the total height of all the components on the form. This is bigger than height.

getMargin

public int getMargin()
Returns the margin for the left and right of the screen. This also pads the top and bottom of the form; however, scrolling can make the text appear at the very top and bottom of the screen.

Returns:
The number of pixels between components and the edges of the screen.

setMargin

public void setMargin(int margin)
Sets the margin for the left and right of the screen. This also pads the top and bottom of the form; however, scrolling can make the text appear at the very top and bottom of the screen.

Parameters:
margin - is the number of pixels between components and the edges of the screen. Values less than 0 are ignored.

getSpacing

public int getSpacing()
Returns the vertical spacing between components.

Returns:
The number of pixels that vertically separate components.

setSpacing

public void setSpacing(int spacing)
Sets the vertical spacing between components.

Parameters:
spacing - is the number of pixels that vertically separates components. Values less than 0 are be ignored.

getWidth

public int getWidth()
Returns the width of the usuable portion of this form. The usable portion excludes the vertical scrollbar on the right of the screen (if it exists).

Overrides:
getWidth in class DeviceScreen
Returns:
The number of pixels wide the usable portion of the form is.

hasVerticalScrollbar

public boolean hasVerticalScrollbar()
Determines if the height of all the components is greater than the height of the screen. If so a veritical scrollbar will be drawn on the form.

Returns:
true if the form has a vertical scrollbar and false if it does not.

invalidate

public void invalidate()
Forces the layout of all components to be recalculated. This should be called whenever this screen is altered.


setFullScreenMode

public void setFullScreenMode(boolean mode)
Shows or hides the menu bar at the bottom of the screen.

Overrides:
setFullScreenMode in class DeviceScreen
Parameters:
mode - is true if the DeviceScreen is to be in full screen mode, false otherwise.

setMenuText

public void setMenuText(java.lang.String left,
                        java.lang.String right)
Sets the menu bar text.

For the menu to be visible full screen mode must be off. This can be done with the setFullScreenMode method.

Overrides:
setMenuText in class DeviceScreen
Parameters:
left - is the text for the negative menu option or null to remove the button. Negative menu options are things like canceling a form and moving back to a previous screen.
right - is the text for the positive menu option or null to remove the button. Positive menu options are things like accepting a form, advancing to the next screen, or displaying a menu.
See Also:
DeviceScreen.declineNotify(), DeviceScreen.acceptNotify()

setTitle

public void setTitle(java.lang.String title)
Sets the title of this screen. The default is null meaning no title.

For the title to be visible full screen mode must be off. This can be done with the setFullScreenMode method.

Overrides:
setTitle in class DeviceScreen
Parameters:
title - is the new title for the screen.

keyPressed

protected void keyPressed(int keyCode)
Called when a key is pressed. It can be identified using the constants defined in this class.

Overrides:
keyPressed in class DeviceScreen
Parameters:
keyCode - is the key code of the key that was pressed.

keyRepeated

protected void keyRepeated(int keyCode)
Called when a key is repeated (held down). It can be identified using the constants defined in this class.

Overrides:
keyRepeated in class DeviceScreen
Parameters:
keyCode - is the key code of the key that was held down.

keyReleased

protected void keyReleased(int keyCode)
Called when a key is released. It can be identified using the constants defined in this class.

Overrides:
keyReleased in class DeviceScreen
Parameters:
keyCode - is the key code of the key that was released.

pointerPressed

protected void pointerPressed(int x,
                              int y)
Called when the pointer is pressed.

Overrides:
pointerPressed in class DeviceScreen
Parameters:
x - is the horizontal location where the pointer was pressed.
y - is the vertical location where the pointer was pressed.

pointerDragged

protected void pointerDragged(int x,
                              int y)
Called when the pointer is dragged.

Overrides:
pointerDragged in class DeviceScreen
Parameters:
x - is the horizontal location where the pointer was dragged.
y - is the vertical location where the pointer was dragged.

pointerReleased

protected void pointerReleased(int x,
                               int y)
Called when the pointer is released.

Overrides:
pointerReleased in class DeviceScreen
Parameters:
x - is the horizontal location where the pointer was released.
y - is the vertical location where the pointer was released.