jcontrol.ui.wombat
Class Component

java.lang.Object
  jcontrol.ui.wombat.Component

Direct Known Subclasses:

AbstractFocusComponent, Border, Container, DigitalMeter, FastLabel, Frame, Label

public abstract class Component
extends Object

A Component is an object having a graphical representation that can be displayed on the screen and that can interact with the user. Examples of components are the buttons, labels and checkboxes etc of a typical graphical user interface.

The Component class is the abstract superclass of all components in this library. Class Component may also be extended directly to create your own components.

To work properly, components must be part of a container-tree (see Container), with a Frame instance as top-level element.
There are two different types of components. Some components, such as labels or borders don't have any interactive behaviour. Their only purpose is displaying text, images, measuring values or whatever. They can neither be selected by any user action nor they can fire events.
Interactive components, such as buttons, combo boxes, list boxes, radio buttons etc, are controllable by the user via keyboard and/or touch screen and they can even fire action events.

Note: It is not recommended to access components using multiple threads at the same time. This may cause synchronization problems resulting in unexpected behaviour.

Get more information and demo applications at www.jcontrol.org.

(c) Copyright 2005-2007 DOMOLOGIC GmbH

Field Summary

Color	backgroundColor
static Color	COLOR_COMPONENT_BACKGROUND
static Color	COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED
static Color	COLOR_COMPONENT_DARK_SHADOW
static Color	COLOR_COMPONENT_FOREGROUND
static Color	COLOR_COMPONENT_FOREGROUND_INACTIVE
static Color	COLOR_COMPONENT_HIGHLIGHT_SHADOW
static Color	COLOR_COMPONENT_LIGHT_SHADOW
static Color	COLOR_COMPONENT_LIST_BACKGROUND
static Color	COLOR_COMPONENT_NORMAL_SHADOW
static Color	COLOR_COMPONENT_SELECTION_TEXT
static Color	COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND
static Color	COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE
static Color	COLOR_COMPONENT_SELECTION_TEXT_INACTIVE
protected static Queue	eventQueue Static event queue for all components.
protected Resource	font A font resource for drawing text.
Color	foregroundColor
IFrame	frame
int	height The component's height.
IContainer	parent The parent container of the component.
protected static int	RESERVED1
protected static int	RESERVED2
protected static int	RESERVED3
protected static int	RESERVED4
protected static int	RESERVED5
protected static int	RESERVED6
int	state The state control flag.
protected static int	STATE_ABORT_UPDATE
protected static int	STATE_ANIMATED
protected static int	STATE_BG_COLOR_SET
protected static int	STATE_COVERED
protected static int	STATE_DIRTY_MASK
protected static int	STATE_DIRTY_PAINTALL
protected static int	STATE_DIRTY_REPAINT
protected static int	STATE_DIRTY_UPDATE
protected static int	STATE_DISABLED
protected static int	STATE_DISPOSED
protected static int	STATE_FG_COLOR_SET
protected static int	STATE_FOCUS
protected static int	STATE_HEIGHT_FIXED
protected static int	STATE_NO_REDRAW
protected static int	STATE_REVALIDATE
protected static int	STATE_SELECTED Selected state for buttons, comboboxes etc,
protected static int	STATE_SIZE_FIXED
protected static int	STATE_UPDATED If set, the last update has been accomplished successfully.
protected static int	STATE_VISIBLE
protected static int	STATE_WIDTH_FIXED
Color	transparentColor
int	width The component's width.
int	x The component's x location.
int	y The component's y location.

Constructor Summary

Component()

Method Summary

protected void	drawDisabledImage(XGraphics g, Resource image, int x, int y, int w, int h)
IFrame	getFrame() Returns the applications root IFrame object.
boolean	isEnabled()
boolean	isVisible() Returns true if this component is set visible, and false otherwise.
protected boolean	isVisibleInternal()
void	paint(XGraphics g) This method should not be called from the application.
protected void	redrawInternalAndParent() Sets the repaint dirty flag for this component and all parent components.
void	repaint() Causes the entire component to be marked as needing to be redrawn.
void	repaintAll() Causes the entire component to be marked as needing to be redrawn.
static void	safeExec(Runnable runnable) Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
void	setBackgroundColor(Color background) Sets the background color for this component.
protected void	setBackgroundColorInternal(Color background)
void	setBounds(int x, int y, int width, int height) Set the dimensions of this component.
void	setDirty(int state, boolean onoff) This method should not be called from the application.
void	setEnabled(boolean enabled) Sets the enabled state of this component.
void	setFont(Resource font) Sets the font for this component.
void	setForegroundColor(Color foreground) Sets the foreground color for this component.
protected void	setForegroundColorInternal(Color foreground)
protected void	setParametersInternal(Resource font, Color foregroundColor, Color backgroundColor, Color transparentColor)
void	setRedraw(boolean onoff) Disables/enables drawing for this component.
void	setTransparentColor(Color transparentColor) Sets the transparent color for this component.
void	setVisible(boolean visible) Turns the component visible or invisible.
static void	unsafeExec(Runnable runnable) Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
void	update(XGraphics g) This method should not be called from the application.

Methods inherited from class java.lang.Object

clone, equals, getClass, notifyAll, toString, wait

Field Detail

COLOR_COMPONENT_FOREGROUND

public static final Color COLOR_COMPONENT_FOREGROUND

COLOR_COMPONENT_FOREGROUND_INACTIVE

public static final Color COLOR_COMPONENT_FOREGROUND_INACTIVE

COLOR_COMPONENT_BACKGROUND

public static final Color COLOR_COMPONENT_BACKGROUND

COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED

public static final Color COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED

COLOR_COMPONENT_DARK_SHADOW

public static final Color COLOR_COMPONENT_DARK_SHADOW

COLOR_COMPONENT_NORMAL_SHADOW

public static final Color COLOR_COMPONENT_NORMAL_SHADOW

COLOR_COMPONENT_LIGHT_SHADOW

public static final Color COLOR_COMPONENT_LIGHT_SHADOW

COLOR_COMPONENT_HIGHLIGHT_SHADOW

public static final Color COLOR_COMPONENT_HIGHLIGHT_SHADOW

COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND

public static final Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND

COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE

public static final Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE

COLOR_COMPONENT_SELECTION_TEXT

public static final Color COLOR_COMPONENT_SELECTION_TEXT

COLOR_COMPONENT_SELECTION_TEXT_INACTIVE

public static final Color COLOR_COMPONENT_SELECTION_TEXT_INACTIVE

COLOR_COMPONENT_LIST_BACKGROUND

public static final Color COLOR_COMPONENT_LIST_BACKGROUND

STATE_VISIBLE

protected static final int STATE_VISIBLE

See Also:

Constant Field Values

STATE_DIRTY_UPDATE

protected static final int STATE_DIRTY_UPDATE

See Also:

Constant Field Values

STATE_DIRTY_REPAINT

protected static final int STATE_DIRTY_REPAINT

See Also:

Constant Field Values

STATE_DIRTY_PAINTALL

protected static final int STATE_DIRTY_PAINTALL

See Also:

Constant Field Values

STATE_DIRTY_MASK

protected static final int STATE_DIRTY_MASK

See Also:

Constant Field Values

STATE_ABORT_UPDATE

protected static final int STATE_ABORT_UPDATE

See Also:

Constant Field Values

STATE_ANIMATED

protected static final int STATE_ANIMATED

See Also:

Constant Field Values

STATE_UPDATED

protected static final int STATE_UPDATED

If set, the last update has been accomplished successfully. Otherwise, the update method has returned without calling paint, for any reason.

See Also:

Constant Field Values

STATE_REVALIDATE

protected static final int STATE_REVALIDATE

See Also:

Constant Field Values

STATE_WIDTH_FIXED

protected static final int STATE_WIDTH_FIXED

See Also:

Constant Field Values

STATE_HEIGHT_FIXED

protected static final int STATE_HEIGHT_FIXED

See Also:

Constant Field Values

STATE_SIZE_FIXED

protected static final int STATE_SIZE_FIXED

See Also:

Constant Field Values

STATE_COVERED

protected static final int STATE_COVERED

See Also:

Constant Field Values

STATE_DISPOSED

protected static final int STATE_DISPOSED

See Also:

Constant Field Values

STATE_FOCUS

protected static final int STATE_FOCUS

See Also:

Constant Field Values

RESERVED1

protected static final int RESERVED1

See Also:

Constant Field Values

RESERVED2

protected static final int RESERVED2

See Also:

Constant Field Values

RESERVED3

protected static final int RESERVED3

See Also:

Constant Field Values

RESERVED4

protected static final int RESERVED4

See Also:

Constant Field Values

RESERVED5

protected static final int RESERVED5

See Also:

Constant Field Values

RESERVED6

protected static final int RESERVED6

See Also:

Constant Field Values

STATE_DISABLED

protected static final int STATE_DISABLED

See Also:

Constant Field Values

STATE_NO_REDRAW

protected static final int STATE_NO_REDRAW

See Also:

Constant Field Values

STATE_FG_COLOR_SET

protected static final int STATE_FG_COLOR_SET

See Also:

Constant Field Values

STATE_BG_COLOR_SET

protected static final int STATE_BG_COLOR_SET

See Also:

Constant Field Values

STATE_SELECTED

protected static final int STATE_SELECTED

Selected state for buttons, comboboxes etc,

See Also:

Constant Field Values

x

public int x

The component's x location. This variable should not be modified directly!

See Also:

setBounds(int, int, int, int)

y

public int y

The component's y location. This variable should not be modified directly!

See Also:

setBounds(int, int, int, int)

width

public int width

The component's width. This variable should not be modified directly!

See Also:

setBounds(int, int, int, int)

height

public int height

The component's height. This variable should not be modified directly!

See Also:

setBounds(int, int, int, int)

parent

public IContainer parent

The parent container of the component. This variable should not be modified!

frame

public IFrame frame

state

public int state

The state control flag. This should only be modified directly if you know exactly what you're doing.

font

protected Resource font

A font resource for drawing text. Components are self-responsible for making use of this resource.

foregroundColor

public Color foregroundColor

backgroundColor

public Color backgroundColor

transparentColor

public Color transparentColor

eventQueue

protected static Queue eventQueue

Static event queue for all components.

Constructor Detail

Component

public Component()

Method Detail

setRedraw

public void setRedraw(boolean onoff)

Disables/enables drawing for this component. If drawing has been disabled the component will not be (re-)painted until drawing is enabled again. This method can be used to avoid flickering or undesired repainting effects. Use this method sparely if you are not really sure what you are doing.

Parameters:

onoff - true - drawing on (default), false - drawing off

safeExec

public static void safeExec(Runnable runnable)

Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity. The thread calling this method is blocked until the runnable has been completed.

This method should be used every time when the ui framework is modified from a thread that is NOT the user interface thread. Please use this method only after the method setVisible(true) of the main frame has been called (because this mthod is starting the user-interface thread).
When an application adds or removes components or when it changes the content of the main frame, it is strongly recommended to use safeExec(). Otherwise, the ui framework might behave unexpectedly.

Use the method safeExec() as shown by the following code snipped:

// The run method of any thread
public void run() {
...
// here, the content of the main frame should be changed
// call the safeExec method
Component.safeExec(new Runnable() {
public void run() {
// place your code here to be executed by the ui-thread
// example:
frame.setContent(new MyContent());
}
});
// here, the content of the frame has already been changed because
// this thread was blocked until the runnable has been executed
...
}


Parameters:

runnable - the runnable to execute

See Also:

unsafeExec(Runnable)

unsafeExec

public static void unsafeExec(Runnable runnable)

Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity. The caller of this method continues to run in parallel, and is not notified when the runnable has been completed.

This method should be used every time when the ui framework is modified from a thread that is NOT the user interface thread. Please use this method only after the method setVisible(true) of the main frame has been called (because this mthod is starting the user-interface thread).
When an application adds or removes components or when it changes the content of the main frame, it is strongly recommended to use safeExec(). Otherwise, the ui framework might behave unexpectedly.

Use the method unsafeExec() as shown by the following code snipped:

// The run method of any thread
public void run() {
...
// here, the content of the main frame should be changed
// call the unsafeExec method
Component.unsafeExec(new Runnable() {
public void run() {
// place your code here to be executed by the ui-thread
// example:
frame.setContent(new MyContent());
}
});
// here, the content of the frame has NOT been changed yet and
// this thread continues to run BEFORE the runnable has been executed
...
}


Parameters:

runnable - the runnable to execute

See Also:

safeExec(Runnable)

getFrame

public IFrame getFrame()

Returns the applications root IFrame object.

Returns:

the applications root IFrame.

update

public void update(XGraphics g)

This method should not be called from the application. Repaints the component if the dirty flag is set. This method must not be overwritten by extending classes.

Parameters:

g - the application's graphics object.

setForegroundColorInternal

protected void setForegroundColorInternal(Color foreground)

setBackgroundColorInternal

protected void setBackgroundColorInternal(Color background)

setParametersInternal

protected void setParametersInternal(Resource font,
                                     Color foregroundColor,
                                     Color backgroundColor,
                                     Color transparentColor)

setTransparentColor

public void setTransparentColor(Color transparentColor)

Sets the transparent color for this component. Transparent color is optional and will be used in components that have "transparent" areas. E.g. the round corners of buttons and borders or radio buttons where the main background shines through. If a transparent color for those components is set it will be used instead of the component's background color in the "transparent" areas.

Parameters:

transparentColor - the transparent color to set

setForegroundColor

public void setForegroundColor(Color foreground)

Sets the foreground color for this component.

Parameters:

foreground - the foreground color to set

setBackgroundColor

public void setBackgroundColor(Color background)

Sets the background color for this component.

Parameters:

background - the background color to set

redrawInternalAndParent

protected void redrawInternalAndParent()

Sets the repaint dirty flag for this component and all parent components. For internal use only.

paint

public void paint(XGraphics g)

This method should not be called from the application. Paints this component. Here, all drawing action will occur by using the graphics parameter. This method must be overwritten by any extending class. It must not be used by any application.

Parameters:

g - the application's graphics object.

setDirty

public void setDirty(int state,
                     boolean onoff)

This method should not be called from the application. Sets/unsets the state flag of this component to the state specified by the state-parameter. All parent containers are set/unset dirty.

Parameters:

state - the state to set

onoff - set or unset the state

repaint

public void repaint()

Causes the entire component to be marked as needing to be redrawn. The next time a paint request is processed, the component will be painted completely.
Note that this method will have no effect if the component is already marked to be redrawn. Thus, e.g. after adding, changing, etc., components are marked dirty anyway. An additional repaint-call will make no sense in this case.

repaintAll

public void repaintAll()

Causes the entire component to be marked as needing to be redrawn. The next time a paint request is processed, the background is cleared and the component will be completely painted.
Note that this method will have no effect if the component is already marked to be redrawn. Thus, e.g. after adding, changing, etc., components are marked dirty anyway. An additional repaint-call will make no sense in this case.

setVisible

public void setVisible(boolean visible)

Turns the component visible or invisible.

Parameters:

visible - the visible state to set.

setEnabled

public void setEnabled(boolean enabled)

Sets the enabled state of this component. Disabled components are no longer able to receive user (keyboard or touch) input. Some components get a "grayed" look in disabled state.

Parameters:

enabled - the enabled state.

isEnabled

public boolean isEnabled()

isVisible

public boolean isVisible()

Returns true if this component is set visible, and false otherwise.

If one of the component's ancestors is not visible or some other condition makes the component not visible, e.g. it is covered by another component or whatever, this method may still indicate that it is considered visible even though it may not actually be showing.

Returns:

boolean the visible state of this component.

isVisibleInternal

protected boolean isVisibleInternal()

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Set the dimensions of this component. The component is repainted automatically.

Parameters:

x - The x-coordinate of the upper left corner

y - The y-coordinate of the upper left corner

width - The width of this component

height - The height of this component

setFont

public void setFont(Resource font)

Sets the font for this component.

Parameters:

font - the new font.

drawDisabledImage

protected void drawDisabledImage(XGraphics g,
                                 Resource image,
                                 int x,
                                 int y,
                                 int w,
                                 int h)