Class Component

  Object
      Component

Direct Known Subclasses:

Banner, Camera, Canvas, Flow, HyperText, Label, Picture, Progress, Scrollable, Shell, System, Text, Widget

public class Component
extends Object

Component is base class for user interface elements. Most of the access methods are available through this class even if the actual instance might not support them. Rationale for this is to improve the usability of API so that need for explicit casting is minimized.

Every component has flags that define some basic properties of it and the way other components are positioned inside it. The existing flags are:

• VISIBLE - visible or not
• FOCUSABLE - can the user or UI focus to the element.
• LINEFEED - no more components will appear on the same horizontal height on the right side
• WRAP - When components are set horizontally one after another any component that won't fit on that line will be placed on the next line.

Constructor Summary

Component(Style style)
Creates a new component with the specified style.

Method Summary

Component	add(Component child) Adds the given component to end of this container.
Component	appendText(String text) Sets the more text into Text or Input component.
void	clear() Clears all children from container.
Component	find(Object data) Searches for component with matching data attachment.
Component	first() Returns the first component on container.
Component	get(int index) Returns the component at the specified index.
int	getAction() Gets the explicit "fire" action associated with this component.
Object	getData() Gets the data attachment associated with this component.
Component	getElement(String name) Returns named component from View.
int	getFlags() Return the current flags of this component
Image	getImage() Return the current image of Label or Picture component.
int, int	getLocation() Returns the coordinate of component.
Component	getParent() Return the parent component.
Shell	getShell() Returns the root Shell of component tree.
int, int	getSize() Returns the realized width and height of this Component.
Style	getStyle() Returns the current style of this component.
String	getText() Return the current text of Label, Text or Input component.
Scrollable	getViewPort() Searches for Scrollable among the parents of this Component.
boolean	hasLinefeed() Return the current state of LINEFEED flag.
int	indexOf(Component child) Returns the index of specified child in container.
Component	insert(int index, Component child) Inserts the given component to specified index in this container.
boolean	isFocusable() Return the current state of FOCUSABLE flag.
boolean	isShown() Checks if the given component is shown on screen.
boolean	isVisible() Return the current state of VISIBLE flag.
boolean	isWrapping() Return the current state of WRAP flag.
Component	last() Returns the last component on container.
Component	operator_get(int index) Returns the component at the specified index.
Component	operator_set(int index, Component child) Sets the component at the specified index.
Component	remove(Component child) Removes the given component.
Component	remove(int index) Removes the component at specified index.
void	repaint(boolean refreshLayout) Adds this component is repaint queue.
Component	set(int index, Component child) Sets the given component at specified index in this container.
Component	setAction(int action) Sets the explicit "fire" action.
Component	setData(Object data) Sets the data attachment to this component.
Component	setElement(String name, Component element) Sets named component in this View.
Component	setFlags(int flags) Sets the flags of this component.
Component	setImage(Image image) Sets the image of Label and Picture component.
Component	setLocation(int x, int y) Sets the location of this component.
Component	setPreferredHeight(int height) Sets the preferred height of this Component.
Component	setPreferredSize(int width, int height) Sets preferred width and height for this Component.
Component	setPreferredWidth(int width) Sets the preferred width of this Component.
Component	setStyle(Style style) Sets the style of this Component.
Component	setText(String text) Sets the text of Label, Text or Input component.
int	size() Returns the number of children in container.

Methods inherited from class Object

toString, equals, hashCode

Methods inherited from

equals, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Component

public Component(Style style)

Creates a new component with the specified style. Even though plain Component does not paint any content the style is nevertheless painted and hence it can be used for decorative purposes.

Parameters:

style - Component style

Method Detail

getStyle

public Style getStyle()

Returns the current style of this component.

Returns:

style

See Also:

setStyle(Style)

getData

public Object getData()

Gets the data attachment associated with this component. Data attachment can be used to store state/context information.

Returns:

data attachment

See Also:

setData(Object)

getAction

public int getAction()

Gets the explicit "fire" action associated with this component. This action is never invoked if the component does not have FOCUSABLE flag set, since the user can't focus on it.

Returns:

fire action

See Also:

setAction(int), FOCUSABLE

getParent

public Component getParent()

Return the parent component. A Component instance can only be placed once on Component tree. However, it is legal to re-use components after they are no longer part of any component tree on the shell stack.

Returns:

parent component

See Also:

add(Component), insert(int, Component), set(int, Component), remove(int)

getViewPort

public Scrollable getViewPort()

Searches for Scrollable among the parents of this Component. If this component is Scrollable, returns this

Returns:

Parent scrollable or null if there is no scrollable on component tree

getShell

public Shell getShell()

Returns the root Shell of component tree.

Returns:

root of tree

hasLinefeed

public boolean hasLinefeed()

Return the current state of LINEFEED flag.

See Also:

LINEFEED

isVisible

public boolean isVisible()

Return the current state of VISIBLE flag.

See Also:

VISIBLE

isFocusable

public boolean isFocusable()

Return the current state of FOCUSABLE flag.

See Also:

FOCUSABLE

isWrapping

public boolean isWrapping()

Return the current state of WRAP flag.

See Also:

WRAP

getFlags

public int getFlags()

Return the current flags of this component

Returns:

flags

See Also:

VISIBLE, FOCUSABLE, LINEFEED, WRAP

getText

public String getText()

Return the current text of Label, Text or Input component. Returns null for all other components.

Returns:

Current text or null

See Also:

Label, Text, Input

getImage

public Image getImage()

Return the current image of Label or Picture component. Returns null for all other components.

Returns:

Current image or null

See Also:

Label, Picture

setStyle

public Component setStyle(Style style)

Sets the style of this Component. Changing the style does not automatically repaint Component.

Parameters:

style - New style

See Also:

getStyle(), repaint(boolean), flushScreen(boolean)

setData

public Component setData(Object data)

Sets the data attachment to this component. Data attachment can be used to store state/context information.

Parameters:

data - data attachment

Returns:

this Component instance

See Also:

getData()

setAction

public Component setAction(int action)

Sets the explicit "fire" action. Only meaningful if component has FOCUSABLE flag set.

Parameters:

action - Fire action

See Also:

getAction(), FOCUSABLE

setFlags

public Component setFlags(int flags)

Sets the flags of this component. This method will override current flags with new one.

Parameters:

flags - Flags to set

Returns:

this component

See Also:

VISIBLE, FOCUSABLE, LINEFEED, WRAP

setPreferredWidth

public Component setPreferredWidth(int width)

Sets the preferred width of this Component. Width can be:

• 1.. : Absolute width
• 0 : Optimal width, calculated automatically
• -100..-1: Relative width (1%..100%), calculated from available space

Parameters:

width - desired width

Returns:

this Component

See Also:

setPreferredHeight(int), setPreferredSize(int, int), getSize()

setPreferredHeight

public Component setPreferredHeight(int height)

Sets the preferred height of this Component. Width can be:

• 1.. : Absolute height
• 0 : Optimal height, calculated automatically
• -100..-1: Relative height (1%..100%), calculated from available space

Parameters:

height - desired height

Returns:

this Component

See Also:

setPreferredWidth(int), setPreferredSize(int, int), getSize()

setPreferredSize

public Component setPreferredSize(int width,
                                  int height)

Sets preferred width and height for this Component.

Parameters:

width - desired width

height - desired height

See Also:

setPreferredWidth(int), setPreferredHeight(int)

getSize

public   int, int getSize()

Returns the realized width and height of this Component. The values are available only after the layout has been computed.

Returns:

(int width, int height) tuple.

getLocation

public   int, int getLocation()

Returns the coordinate of component. Values returned might not represent actual screen coordinates if the Component is placed inside scrollable container.

Returns:

(int x, int y) tuple.

setLocation

public Component setLocation(int x,
                             int y)

Sets the location of this component. This method can only be used on components placed inside Surface, all other usages will be ignored.

Parameters:

x - Absolute X position of component

y - Absolute Y position of component

Returns:

This component

Since:

3.0.0

size

public int size()

Returns the number of children in container. Containers are Flow, Scrollable and Shell.

Returns:

Number of children.

See Also:

Flow, Scrollable, Shell

indexOf

public int indexOf(Component child)

Returns the index of specified child in container. This method uses pointer check to determine the equality.

Returns:

Index, or -1 if child was not found

clear

public void clear()

Clears all children from container. Only applicable to Flow component.

repaint

public void repaint(boolean refreshLayout)

Adds this component is repaint queue. Repaint queue is handled automatically if this method called inside handling of following callbacks:

• Script.keyAction(Component, int, int)
• Script.actionPerformed(Shell, Component, int)
• Script.getMenu(Shell, Component)
• Script.getSoftKey(Shell, Component, int)
• Script.openWidget()
• Script.paint(Component, Graphics, Style, int, int)

Otherwise handling is requested with flushScreen(boolean) method. Queue is optimized so that no Component is repainted twice.

Parameters:

refreshLayout - Flag to indicate if the layout of component should be re-computed. Computation occurs prior painting. It is highly recommended to optimize code so that true is supplied only if component tree contents or styles have changed.

first

public Component first()

Returns the first component on container.

This method is equal to call component.get(0).

Returns:

first component

See Also:

first(), size(), get(int)

last

public Component last()

Returns the last component on container.

This method is equal to call component.get(component.size()-1).

Returns:

last component

See Also:

last(), size(), get(int)

get

public Component get(int index)

Returns the component at the specified index.

Parameters:

index - Index to container, must be on range [0..size()-1].

Returns:

Component at specified index

See Also:

size()

find

public Component find(Object data)

Searches for component with matching data attachment. This method will descend into component hierarchy. Match is determined by comparing the pointers.

Parameters:

data - Data attachment to search for

Returns:

Matching component or null null if no match was found

getElement

public Component getElement(String name)

Returns named component from View. View is a special case of Flow container created using createView(String, Object).

Parameters:

name - Name of element to return

Returns:

element or null if there is no such element on View.

setElement

public Component setElement(String name,
                            Component element)

Sets named component in this View. View is a special case of Flow container created using createView(String, Object).

Parameters:

name - Name of element to override

element - Component to set

Returns:

this Component

remove

public Component remove(int index)

Removes the component at specified index. Only applicable to Flow component.

Parameters:

index - Index of component to remove, must be on range [0..size()-1].

Returns:

this Component

remove

public Component remove(Component child)

Removes the given component. Only applicable to Flow component.

Parameters:

child - Component to remove

Returns:

this Component

add

public Component add(Component child)

Adds the given component to end of this container. Only applicable to Flow component.

Parameters:

child - Component to add

Returns:

this Component

set

public Component set(int index,
                     Component child)

Sets the given component at specified index in this container. Only applicable to Flow component.

Parameters:

index - Index to container, must be on range [0..size()-1].

child - Component to set

Returns:

this Component

insert

public Component insert(int index,
                        Component child)

Inserts the given component to specified index in this container. Existing components at given index and higher will be shifted to the next index. Only applicable to Flow component.

Parameters:

index - Index to container, must be on range [0..size()].

child - Component to add

Returns:

this Component

setText

public Component setText(String text)

Sets the text of Label, Text or Input component.

Parameters:

text - Text to set

Returns:

this Component

appendText

public Component appendText(String text)

Sets the more text into Text or Input component.

Parameters:

text - Text to append

Returns:

this Component

setImage

public Component setImage(Image image)

Sets the image of Label and Picture component.

Parameters:

image - Image to set

Returns:

this Component

operator_get

public Component operator_get(int index)

Returns the component at the specified index.

Parameters:

index - Index to container

Returns:

Component at specified index

See Also:

size()

operator_set

public Component operator_set(int index,
                              Component child)

Sets the component at the specified index. Note that Component may appear only once on active component trees.

Parameters:

index - Index to container, must be on range [0..size()-1].

child - Child component

Returns:

child parameter

See Also:

size()

isShown

public boolean isShown()

Checks if the given component is shown on screen. Component is considered to be shown if:

• It's either Shell or is part of some Shell's component tree
• Its Shell is placed on screen stack
• Its Shell is either top most or stack, or the shells on top of it are partially visible.

Since:

3.0.0