jcontrol.ui.wombat
Class Component

java.lang.Object
  extended by jcontrol.ui.wombat.Component
Direct Known Subclasses:
AbstractFocusComponent, Border, Container, DigitalMeter, FastLabel, Frame, Label

public abstract class Component
extends java.lang.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 DOMOLOGIC GmbH

Author:
Marcus Timmermann

Field Summary
 jcontrol.graphics.Color backgroundColor
           
static jcontrol.graphics.Color COLOR_COMPONENT_BACKGROUND
           
static jcontrol.graphics.Color COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED
           
static jcontrol.graphics.Color COLOR_COMPONENT_DARK_SHADOW
           
static jcontrol.graphics.Color COLOR_COMPONENT_FOREGROUND
           
static jcontrol.graphics.Color COLOR_COMPONENT_FOREGROUND_INACTIVE
           
static jcontrol.graphics.Color COLOR_COMPONENT_HIGHLIGHT_SHADOW
           
static jcontrol.graphics.Color COLOR_COMPONENT_LIGHT_SHADOW
           
static jcontrol.graphics.Color COLOR_COMPONENT_LIST_BACKGROUND
           
static jcontrol.graphics.Color COLOR_COMPONENT_NORMAL_SHADOW
           
static jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT
           
static jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND
           
static jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE
           
static jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_INACTIVE
           
 jcontrol.graphics.Color foregroundColor
           
 IFrame frame
           
 int height
          The component's height.
 IContainer parent
          The parent container of the component.
 int state
          The state control flag.
 jcontrol.graphics.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
 IFrame getFrame()
          Returns the applications root IFrame object.
 boolean isEnabled()
           
 boolean isVisible()
           Returns true if this component is set visible, and false otherwise.
 void paint(jcontrol.graphics.XGraphics g)
          This method should not be called from the application.
 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(java.lang.Runnable runnable)
          Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
 void setBackgroundColor(jcontrol.graphics.Color background)
          Sets the background color for this component.
 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(jcontrol.io.Resource font)
          Sets the font for this component.
 void setForegroundColor(jcontrol.graphics.Color foreground)
          Sets the foreground color for this component.
 void setRedraw(boolean onoff)
          Disables/enables drawing for this component.
 void setTransparentColor(jcontrol.graphics.Color transparentColor)
          Sets the transparent color for this component.
 void setVisible(boolean visible)
          Turns the component visible or invisible.
static void unsafeExec(java.lang.Runnable runnable)
          Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
 void update(jcontrol.graphics.XGraphics g)
          This method should not be called from the application.
 
Methods inherited from class java.lang.Object
equals, getClass, notifyAll, toString, wait
 

Field Detail

backgroundColor

public jcontrol.graphics.Color backgroundColor

COLOR_COMPONENT_BACKGROUND

public static final jcontrol.graphics.Color COLOR_COMPONENT_BACKGROUND

COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED

public static final jcontrol.graphics.Color COLOR_COMPONENT_BACKGROUND_HIGHLIGHTED

COLOR_COMPONENT_DARK_SHADOW

public static final jcontrol.graphics.Color COLOR_COMPONENT_DARK_SHADOW

COLOR_COMPONENT_FOREGROUND

public static final jcontrol.graphics.Color COLOR_COMPONENT_FOREGROUND

COLOR_COMPONENT_FOREGROUND_INACTIVE

public static final jcontrol.graphics.Color COLOR_COMPONENT_FOREGROUND_INACTIVE

COLOR_COMPONENT_HIGHLIGHT_SHADOW

public static final jcontrol.graphics.Color COLOR_COMPONENT_HIGHLIGHT_SHADOW

COLOR_COMPONENT_LIGHT_SHADOW

public static final jcontrol.graphics.Color COLOR_COMPONENT_LIGHT_SHADOW

COLOR_COMPONENT_LIST_BACKGROUND

public static final jcontrol.graphics.Color COLOR_COMPONENT_LIST_BACKGROUND

COLOR_COMPONENT_NORMAL_SHADOW

public static final jcontrol.graphics.Color COLOR_COMPONENT_NORMAL_SHADOW

COLOR_COMPONENT_SELECTION_TEXT

public static final jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT

COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND

public static final jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND

COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE

public static final jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_BACKGROUND_INACTIVE

COLOR_COMPONENT_SELECTION_TEXT_INACTIVE

public static final jcontrol.graphics.Color COLOR_COMPONENT_SELECTION_TEXT_INACTIVE

foregroundColor

public jcontrol.graphics.Color foregroundColor

frame

public IFrame frame

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!


state

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


transparentColor

public jcontrol.graphics.Color transparentColor

width

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

See Also:
setBounds(int, int, int, int)

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)
Constructor Detail

Component

public Component()
Method Detail

getFrame

public IFrame getFrame()
Returns the applications root IFrame object.

Returns:
the applications root IFrame.

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.

paint

public void paint(jcontrol.graphics.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.

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.


safeExec

public static void safeExec(java.lang.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)

setBackgroundColor

public void setBackgroundColor(jcontrol.graphics.Color background)
Sets the background color for this component.

Parameters:
background - the background color to set

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

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

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.

setFont

public void setFont(jcontrol.io.Resource font)
Sets the font for this component.

Parameters:
font - the new font.

setForegroundColor

public void setForegroundColor(jcontrol.graphics.Color foreground)
Sets the foreground color for this component.

Parameters:
foreground - the foreground color to set

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

setTransparentColor

public void setTransparentColor(jcontrol.graphics.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

setVisible

public void setVisible(boolean visible)
Turns the component visible or invisible.

Parameters:
visible - the visible state to set.

unsafeExec

public static void unsafeExec(java.lang.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)

update

public void update(jcontrol.graphics.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.