org.j4me.ui.components
Class Component

java.lang.Object
  extended by org.j4me.ui.components.Component
Direct Known Subclasses:
CheckBox, HorizontalRule, Label, MenuOption, Picture, ProgressBar, RadioButton, TextBox, Whitespace

public abstract class Component
extends java.lang.Object

Components are UI widgets that appear on forms. Examples of components include labels, text boxes, and check boxes. The Dialog class calls methods on this interface to layout, paint, and manage components.


Field Summary
protected  Component container
          A component this one is embedded within.
protected static int HIGHLIGHTED_BORDER_WIDTH
          Components that highlight entry boxes should use this value as a width for their borders.
 
Constructor Summary
Component()
          Constructs a component and attaches it to a screen.
 
Method Summary
 boolean acceptsInput()
          Tells if this component accepts user input or not.
 int getHeight()
           
 int getHorizontalAlignment()
           
protected abstract  int[] getPreferredComponentSize(Theme theme, int viewportWidth, int viewportHeight)
          Returns the desired width and height of this component in pixels.
 int[] getPreferredSize(Theme theme, int viewportWidth, int viewportHeight)
          Returns the desired width and height of this component in pixels.
 DeviceScreen getScreen()
           
 int getWidth()
           
 int getX()
           
 int getY()
           
protected  void hideNotify()
          An event raised whenever the component is removed from the screen.
protected  void invalidate()
          Signals that the Component's size needs to be updated.
 boolean isShown()
          Returns if this component is shown on the screen now.
 void keyPressed(int keyCode)
          Called when a key is pressed.
 void keyReleased(int keyCode)
          Called when a key is released.
 void keyRepeated(int keyCode)
          Called when a key is repeated (held down).
 void paint(javax.microedition.lcdui.Graphics g, Theme theme, DeviceScreen screen, int x, int y, int width, int height, boolean selected)
          Paints the component using g.
protected abstract  void paintComponent(javax.microedition.lcdui.Graphics g, Theme theme, int width, int height, boolean selected)
          Implemented by the subclass to render the item within its container.
protected static int paintRect(javax.microedition.lcdui.Graphics g, Theme theme, int x, int y, int width, int height, boolean selected)
          Paints a rectangle used within a component.
 void pointerDragged(int x, int y)
          Called when the pointer is dragged.
 void pointerPressed(int x, int y)
          Called when the pointer is pressed.
 void pointerReleased(int x, int y)
          Called when the pointer is released.
 void repaint()
          Forces this component to repaint itself.
 void setHorizontalAlignment(int alignment)
           
protected  void showNotify()
          An event raised whenever the component is made visible on the screen.
 void visible(boolean visible)
          Sets if the component is currently shown on the screen or not.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HIGHLIGHTED_BORDER_WIDTH

protected static final int HIGHLIGHTED_BORDER_WIDTH
Components that highlight entry boxes should use this value as a width for their borders. For example an unselected text box appears as a rectangle but a selected text box has a border around it that is this thick and has rounded edges.

See Also:
Constant Field Values

container

protected Component container
A component this one is embedded within. Typically components are not embedded within each other so this will be null.

Constructor Detail

Component

public Component()
Constructs a component and attaches it to a screen.

Method Detail

paint

public final void paint(javax.microedition.lcdui.Graphics g,
                        Theme theme,
                        DeviceScreen screen,
                        int x,
                        int y,
                        int width,
                        int height,
                        boolean selected)
Paints the component using g. The top-left corner is at (0,0) and the component fills the rectangle bounded by width and height.

Parameters:
g - is the Graphics object to be used for rendering the item.
theme - is the application's theme. Use it to get fonts and colors.
screen - is the screen object displaying this component.
x - is the left corner pixel of the component.
y - is the top corner pixel of the component.
width - is the width, in pixels, to paint the component.
height - is the height, in pixels, to paint the component.
selected - is true when this components is currently selected and false when it is not.

paintComponent

protected abstract void paintComponent(javax.microedition.lcdui.Graphics g,
                                       Theme theme,
                                       int width,
                                       int height,
                                       boolean selected)
Implemented by the subclass to render the item within its container. At the time of the call, the Graphics context's destination is the content area of this Component (or back buffer for it). The translation is set so that the upper left corner of the content area is at (0,0), and the clip is set to the area to be painted. The application must paint every pixel within the given clip area. The item is allowed to modify the clip area, but the system must not allow any modification to result in drawing outside the bounds of the item's content area. The w and h passed in are the width and height of the content area of the item. These values will always be set to the clip width and height and are passed here for convenience.

Other values of the Graphics object are as follows:

The paint() method will be called only when at least a portion of the item is actually visible on the display.

Parameters:
g - is the Graphics object to be used for rendering the item.
theme - is the application's theme. Use it to get fonts and colors.
width - is the width, in pixels, to paint the component.
height - is the height, in pixels, to paint the component.
selected - is true when this components is currently selected and false when it is not.

getPreferredSize

public final int[] getPreferredSize(Theme theme,
                                    int viewportWidth,
                                    int viewportHeight)
Returns the desired width and height of this component in pixels.

Parameters:
theme - is the application's Theme.
viewportWidth - is the width of the screen in pixels.
viewportHeight - is the height of the screen in pixels.
Returns:
A array with two elements where the first is the width of the component in pixels and the second is the height.

getPreferredComponentSize

protected abstract int[] getPreferredComponentSize(Theme theme,
                                                   int viewportWidth,
                                                   int viewportHeight)
Returns the desired width and height of this component in pixels. It cannot be wider than the screen or it will be cropped. However, it can be taller than the screen, in which case a scroll bar will be added to the form this component resides on.

Parameters:
theme - is the application's Theme.
viewportWidth - is the width of the viewable area, in pixels, the component can use.
viewportHeight - is the height of the viewable area, in pixels, the component can use.
Returns:
A array with two elements where the first is the width of the component in pixels and the second is the height.

acceptsInput

public boolean acceptsInput()
Tells if this component accepts user input or not. If it does then it can be scrolled to by the user. If it does not, it will be displayed, but can be skipped over by scrolling.

The default implementation returns false. Override this method to return true if the component accepts input.

Returns:
true if the component accepts user input; false if it does not.

getScreen

public DeviceScreen getScreen()
Returns:
The screen displaying this component.

getX

public int getX()
Returns:
The pixel for the left side of this component.

getY

public int getY()
Returns:
The pixel for the top of this component.

getWidth

public int getWidth()
Returns:
The width, in pixels, for this component.

getHeight

public int getHeight()
Returns:
The height, in pixels, for this component.

getHorizontalAlignment

public int getHorizontalAlignment()
Returns:
The horizontalAlignment of the text in the label. It is one of Graphics.LEFT, Graphics.HCENTER, and Graphics.RIGHT.

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Parameters:
alignment - is how the text in the label is justified. It is one of Graphics.LEFT, Graphics.HCENTER, and Graphics.RIGHT.

visible

public void visible(boolean visible)
Sets if the component is currently shown on the screen or not. A call to show(true) must be made before paint. When the component is no longer visible call show(false) so that the component may clean up any resources.

Parameters:
visible - when true indicates the component is painted (or about to be) on the screen.

isShown

public boolean isShown()
Returns if this component is shown on the screen now.

Returns:
true if this component is currently visible on the screen; false if not.

showNotify

protected void showNotify()
An event raised whenever the component is made visible on the screen. This is called before the paintComponent method.

The default implementation does nothing. Override it to initialize any resources required by the component.


hideNotify

protected void hideNotify()
An event raised whenever the component is removed from the screen.

The default implementation does nothing. Override it to clean up any resources required by the component.


invalidate

protected void invalidate()
Signals that the Component's size needs to be updated. This method is intended to be called by subclassed components to force layout of the component to change. A call to this method will return immediately, and it will cause the container's layout algorithm to run at some point in the future.

See Also:
Dialog.invalidate()

repaint

public void repaint()
Forces this component to repaint itself.


keyPressed

public void keyPressed(int keyCode)
Called when a key is pressed. It can be identified using the constants defined in the DeviceScreen class. Note to receive key events the component must override acceptsInput to return true.

The default implementation does nothing. If a component requires keypad interaction, such as to enter text, it should override this method.

Parameters:
keyCode - is the key code of the key that was pressed.

keyRepeated

public void keyRepeated(int keyCode)
Called when a key is repeated (held down). It can be identified using the constants defined in the DeviceScreen class. Note to receive key events the component must override acceptsInput to return true.

The default implementation does nothing. If a component requires keypad interaction, such as to enter text, it should override this method.

Parameters:
keyCode - is the key code of the key that was held down.

keyReleased

public void keyReleased(int keyCode)
Called when a key is released. It can be identified using the constants defined in the DeviceScreen class. Note to receive key events the component must override acceptsInput to return true.

The default implementation does nothing. If a component requires keypad interaction, such as to enter text, it should override this method.

Parameters:
keyCode - is the key code of the key that was released.

pointerPressed

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

Parameters:
x - is the horizontal location where the pointer was pressed relative to the top-left corner of the component.
y - is the vertical location where the pointer was pressed relative to the top-left corner of the component.

pointerReleased

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

Parameters:
x - is the horizontal location where the pointer was released relative to the top-left corner of the component.
y - is the vertical location where the pointer was released relative to the top-left corner of the component.

pointerDragged

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

Parameters:
x - is the horizontal location where the pointer was dragged relative to the top-left corner of the component.
y - is the vertical location where the pointer was dragged relative to the top-left corner of the component.

paintRect

protected static int paintRect(javax.microedition.lcdui.Graphics g,
                               Theme theme,
                               int x,
                               int y,
                               int width,
                               int height,
                               boolean selected)
Paints a rectangle used within a component. If the rectangle is selected it will have rounded edges and be highlighted. If it is not it will have square edges and be slightly inset from (x, y). The border color, highlight color, and inner part of the rectangle (background color) all come from the theme.

Parameters:
g - is the Graphics object to be used for rendering the item.
theme - is the application's theme. Use it to get fonts and colors.
x - is the left side of the box.
y - is the top of the box.
width - is the width, in pixels, to paint the component.
height - is the height, in pixels, to paint the component.
selected - is true when this components is currently selected and false when it is not.
Returns:
The offset, in pixels, of the interior of the box. This is the usuable area by a component: (x + offset, y + offset, width - 2 * offset, height - 2 * offset).