Label (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.ui.gfx.GfxSurface
- - totalcross.ui.Control
  - - totalcross.ui.Label

All Implemented Interfaces:

TextControl

Direct Known Subclasses:

ToolTip
```
public class Label
extends Control
implements TextControl
```
Label is a text label control. It supports multiline, but you need to separate the text with \n. A Label never receives focus neither dispatches events.
Note: this class does not do automatic parse of the text. However, you can use a handy method to parse the text that you want to display: see the totalcross.sys.Convert.insertLineBreak method.
Here is an example showing a label being used:
```
 public class MyProgram extends MainWindow
 {
    public void initUI()
    {
       add(new Label("Value:"), LEFT, TOP);
    }
 
```

Nested Class Summary
- Nested classes/interfaces inherited from class totalcross.ui.Control
  Control.TranslucentShape

Field Summary

Fields
Modifier and Type	Field and Description
`int`	`align` The text alignment; possible values are LEFT, RIGHT, CENTER, FILL (justifies the text).
`protected int`	`alpha`
`boolean`	`autoSplit` Set to true to let the label split its text based on the width every time its width changes.
`int`	`backgroundType` The type of background of this Label (defaults to SOLID_BACKGROUND).
`int`	`borderColor` Set to a color to let this Label have a border with that color.
`int`	`firstGradientColor` The first color used in GRADIENT backgrounds.
`static byte`	`HORIZONTAL_GRADIENT_BACKGROUND` Specifies a horizontal 3d-gradient background for this Label.
`protected java.lang.String[]`	`lines`
`boolean`	`pageScroll` Set to false if you want to scroll the text a line at a time instead of a page at a time.
`java.lang.String`	`preferredWidthText` By default, the getPreferredWidth uses the current text to compute the width.
`int`	`secondGradientColor` The second color used in GRADIENT backgrounds.
`static byte`	`SOLID_BACKGROUND` Specifies a solid background for this button (the default).
`protected java.lang.String`	`text` The String with the full text (not splitted)
`boolean`	`useFillAsPreferred` Set automatically to true when an empty string is passed in the constructor.
`int`	`vAlign` The vertical alignment.
`static byte`	`VERTICAL_GRADIENT_BACKGROUND` Specifies a vertical gradient background for this Label.

Fields inherited from class totalcross.ui.Control
AFTER, alphaValue, appId, appObj, asContainer, asWindow, backColor, BEFORE, BOTTOM, BOTTOM_OF, BRIGHTER_BACKGROUND, callListenersOnAllTargets, CENTER, CENTER_OF, clearValueInt, clearValueStr, DARKER_BACKGROUND, DP, effect, enableUpdateScreen, esce, eventsEnabled, FILL, fillColor, FIT, floating, fm, fmH, focusHandler, focusLess, focusOnPenDown, focusTraversable, font, FONTSIZE, foreColor, height, ignoreInsets, isHighlighting, isTablet, KEEP, keepDisabled, keepEnabled, LEFT, next, nextTabControl, npParts, offscreen, offscreen0, onEventFirst, parent, PARENTSIZE, PARENTSIZEMAX, PARENTSIZEMIN, PREFERRED, prev, RANGE, repositionAllowed, RIGHT, RIGHT_OF, SAME, SCREENSIZE, SCREENSIZEMAX, SCREENSIZEMIN, setFont, setH, setRel, setW, setX, SETX_NOT_SET, setY, tempW, textShadowColor, TOP, translucentShape, transparentBackground, uiAdjustmentsBasedOnFontHeightIsSupported, uiAndroid, UICONST, uiFlat, uiHolo, uiMaterial, uiVista, visible, width, WILL_RESIZE, x, y

Constructor Summary

Constructors
Constructor and Description
`Label()` Creates an empty label, using FILL as the preferred width.
`Label(java.lang.String text)` Creates a label displaying the given text.
`Label(java.lang.String text, int align)` Creates a label displaying the given text with the given alignment. Supports inverted text, multiple lines and is scrollable by default.
`Label(java.lang.String text, int align, int fore, boolean bold)` Creates a label with the given text, alignment, foreground color, and if the font is bold or not.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canScroll(boolean down)` Returns if the label can scroll in the given direction.
`void`	`clear()` This method does nothing: clear a label is usually not a desired action.
`int`	`getAlpha()` Gets the alpha applied to the text color of this object
`int`	`getLineCount()` Return the number of lines of this label.
`int`	`getLinesPerPage()` Return the number of lines per page of this label.
`int`	`getMaxTextWidth()` Returns the maximum text width for the lines of this Label.
`int`	`getPreferredHeight()` Returns the preffered height of this control.
`int`	`getPreferredWidth()` Returns the preffered width of this control.
`java.lang.String`	`getText()` Gets the text that is displayed in the label.
`boolean`	`isMarqueeRunning()` Returns true if the marquee is running.
`protected void`	`onBoundsChanged(boolean screenChanged)` Called after a setRect.
`protected void`	`onColorsChanged(boolean colorsChanged)` Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container.
`void`	`onEvent(Event e)` Called to process key, pen, control and other posted events.
`protected void`	`onFontChanged()` Called after a setFont
`void`	`onPaint(Graphics g)` Called by the system to draw the button.
`boolean`	`scroll(boolean down)` Scroll one page.
`void`	`scrollTo(int line)` Scroll to the given line.
`void`	`scrollToBegin()` Scrolls the text to the begining.
`void`	`scrollToEnd()` Scroll the text to the end.
`void`	`set3d(boolean on)` Draws the label with a 3d effect.
`void`	`setAlpha(int alpha)` Set the alpha value to be used with the text of this object (0 to 255)
`void`	`setHighlighted(boolean on)` Highlights the text, i.e., paints the text in all directions with a brighter color, then centered, with the foreground color.
`void`	`setHighlightedColor(int c)` The color used when highlighting is on.
`void`	`setInsets(int left, int right, int top, int bottom)` Defines a space to be placed around the text of this label.
`void`	`setInvert(boolean on)` Inverts the back and fore colors.
`void`	`setMarqueeText(java.lang.String text, int delay, int loopCount, int step)` Shows this label as a horizontal marquee.
`void`	`setText(java.lang.String text)` Sets the text that is displayed in the label.
`void`	`split(int maxWidth)` Splits the text to the given width.
`void`	`stopMarquee()` Stops the marquee, but does not change the current text.

Methods inherited from class totalcross.ui.Control
_onEvent, addEnabledStateListener, addFocusListener, addFontChangeHandler, addGridListener, addHandler, addHighlightListener, addKeyListener, addListContainerListener, addMouseListener, addMultiTouchListener, addPenListener, addPressListener, addPushNotificationListener, addSizeChangeHandler, addTimer, addTimer, addTimerListener, addValueChangeHandler, addWindowListener, bringToFront, changeHighlighted, contains, drawTranslucentBackground, getAbsoluteRect, getBackColor, getDoEffect, getEffectH, getEffectW, getEffectX, getEffectY, getEventListeners, getFont, getForeColor, getGap, getGraphics, getHeight, getNext, getParent, getParentWindow, getPos, getPressedEvent, getPrev, getRect, getSize, getTextShadowColor, getWidth, getX, getX2, getY, getY2, hadParentScrolled, handleGeographicalFocusChangeKeys, hasFocus, internalSetEnabled, intXYWH, isActionEvent, isChildOf, isDisplayed, isEnabled, isFloating, isInsideOrNear, isObscured, isTopMost, isVisible, isVisibleAndInside, onWindowPaintFinished, post, postEvent, postPressedEvent, releaseScreenShot, removeEnabledStateListener, removeFocusListener, removeGridListener, removeHandler, removeHighlightListener, removeKeyListener, removeListContainerListener, removeMouseListener, removeMultiTouchListener, removePenListener, removePressListener, removePushNotificationListener, removeTimer, removeTimerListener, removeWindowListener, repaint, repaintNow, reposition, reposition, repositionChildren, requestFocus, resetSetPositions, resetStyle, safeRepaintNow, safeUpdateScreen, sendToBack, setBackColor, setBackForeColors, setDoEffect, setEnabled, setFloating, setFocusLess, setFont, setForeColor, setNinePatch, setNinePatch, setRect, setRect, setRect, setRect, setSet, setTextShadowColor, setTranslucent, setVisible, showTip, takeInitialScreenShot, takeScreenShot, translateFromOrigin, uiStyleChanged, updateScreen, updateTemporary, willOpenKeyboard

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - text
```
protected java.lang.String text
```
    The String with the full text (not splitted)
  - alpha
```
protected int alpha
```
  - align
```
public int align
```
    The text alignment; possible values are LEFT, RIGHT, CENTER, FILL (justifies the text). If align is CENTER and the text is wider than the Label, only the right portion will be lost.
  - pageScroll
```
public boolean pageScroll
```
    Set to false if you want to scroll the text a line at a time instead of a page at a time.
  - lines
```
protected java.lang.String[] lines
```
  - useFillAsPreferred
```
public boolean useFillAsPreferred
```
    Set automatically to true when an empty string is passed in the constructor.
  - preferredWidthText
```
public java.lang.String preferredWidthText
```
    By default, the getPreferredWidth uses the current text to compute the width. However, if you create a Label with a predefined text that will be changed later, in the advent of a reposition, the preferred width will be recomputed again using the current text and not the predefined one. For example, if you do:
```
 Label l = new Label("99");
 l.setText("0");
 
```
    ... then the preferred width will be computed based on "0", not in "99". To change this behaviour, assign to this field the text that you want to be used to compute the preferred width.
    Since:
    
    TotalCross 1.3
  - borderColor
```
public int borderColor
```
    Set to a color to let this Label have a border with that color. Defaults to -1, which means no border. Note that the border affects the Label's size (width and height are increased by 4), so you must set it this field before setting the rect. If you want a bigger gap between border and text, you can use setInsets.
    
    Since:
    
    TotalCross 1.27
    
    See Also:
    
    setInsets(int, int, int, int)
  - SOLID_BACKGROUND
```
public static final byte SOLID_BACKGROUND
```
    Specifies a solid background for this button (the default).
    
    Since:
    
    TotalCross 1.15
    
    See Also:
    
    VERTICAL_GRADIENT_BACKGROUND, HORIZONTAL_GRADIENT_BACKGROUND, Constant Field Values
  - VERTICAL_GRADIENT_BACKGROUND
```
public static final byte VERTICAL_GRADIENT_BACKGROUND
```
    Specifies a vertical gradient background for this Label.
    
    Since:
    
    TotalCross 1.15
    
    See Also:
    
    SOLID_BACKGROUND, HORIZONTAL_GRADIENT_BACKGROUND, Constant Field Values
  - HORIZONTAL_GRADIENT_BACKGROUND
```
public static final byte HORIZONTAL_GRADIENT_BACKGROUND
```
    Specifies a horizontal 3d-gradient background for this Label. Used in the setBorder method.
    
    Since:
    
    TotalCross 1.15
    
    See Also:
    
    VERTICAL_GRADIENT_BACKGROUND, SOLID_BACKGROUND, Constant Field Values
  - backgroundType
```
public int backgroundType
```
    The type of background of this Label (defaults to SOLID_BACKGROUND). One color is the background color, and the other color is defined by firstGradientColor and secondGradientColor.
    
    Since:
    
    TotalCross 1.15
    
    See Also:
    
    HORIZONTAL_GRADIENT_BACKGROUND, VERTICAL_GRADIENT_BACKGROUND, SOLID_BACKGROUND, firstGradientColor, secondGradientColor
  - firstGradientColor
```
public int firstGradientColor
```
    The first color used in GRADIENT backgrounds. Defaults to Color.WHITE.
    
    Since:
    
    TotalCross 1.15
  - secondGradientColor
```
public int secondGradientColor
```
    The second color used in GRADIENT backgrounds. Defaults to Color.BLACK.
    
    Since:
    
    TotalCross 1.15
  - autoSplit
```
public boolean autoSplit
```
    Set to true to let the label split its text based on the width every time its width changes. If the height is PREFERRED, the Label will change its size accordingly. You may change the height again calling setRect.
    
    Since:
    
    TotalCross 1.14
  - vAlign
```
public int vAlign
```
    The vertical alignment. Defaults to CENTER
    
    Since:
    
    TotalCross 1.14
    
    See Also:
    
    Control.TOP, Control.CENTER, Control.BOTTOM
- Constructor Detail
  - Label
```
public Label()
```
    Creates an empty label, using FILL as the preferred width.
  - Label
```
public Label(java.lang.String text)
```
    Creates a label displaying the given text. Alignment is set to LEFT by default.
    Supports inverted text, multiple lines and is scrollable by default.
    
    Parameters:
    
    text - the to be text displayed
    
    Throws:
    
    java.lang.NullPointerException - if text is null.
  - Label
```
public Label(java.lang.String text,
             int align,
             int fore,
             boolean bold)
```
    Creates a label with the given text, alignment, foreground color, and if the font is bold or not.
  - Label
```
public Label(java.lang.String text,
             int align)
```
    Creates a label displaying the given text with the given alignment.
    Supports inverted text, multiple lines and is scrollable by default.
    
    Parameters:
    
    text - the text displayed; cannot be null, but can be an empty string.
    
    align - the alignment
    
    Throws:
    
    java.lang.NullPointerException - if text is null.
    
    java.lang.IllegalArgumentException - if align value is not either LEFT, RIGHT, CENTER or FILL.
    
    See Also:
    
    align
- Method Detail
  - setInsets
```
public void setInsets(int left,
                      int right,
                      int top,
                      int bottom)
```
    Defines a space to be placed around the text of this label.
    
    Since:
    
    TotalCross 1.14
  - setMarqueeText
```
public void setMarqueeText(java.lang.String text,
                           int delay,
                           int loopCount,
                           int step)
```
    Shows this label as a horizontal marquee. The text must have a single line. To stop the marquee, just call setText. When a window covers the marquee, it is halted, and resumed when the window closes.
    
    Parameters:
    
    text - the text to be displayed
    
    delay - the timer delay in ms used to scroll the marquee. 100 is a good value.
    
    loopCount - the number of times the text will loop. Set to -1 to loop forever. When the loop count is reached, the text is cleared.
    
    step - the step in pixels in which the text will be scrolled. If > 0, will scroll from left to right; if < 0, will scroll from right to left.
    
    Since:
    
    TotalCross 1.0 beta 4
  - isMarqueeRunning
```
public boolean isMarqueeRunning()
```
    Returns true if the marquee is running.
    
    Since:
    
    TotalCross 1.0 beta 4
  - onEvent
```
public void onEvent(Event e)
```
    Description copied from class: Control
    
    Called to process key, pen, control and other posted events.
    
    Overrides:
    
    onEvent in class Control
    
    Parameters:
    
    e - the event to process
    
    See Also:
    
    Event, KeyEvent, PenEvent
  - set3d
```
public void set3d(boolean on)
```
    Draws the label with a 3d effect. Automatically turns off invert.
  - setInvert
```
public void setInvert(boolean on)
```
    Inverts the back and fore colors. Automatically turns off 3d.
  - setHighlighted
```
public void setHighlighted(boolean on)
```
    Highlights the text, i.e., paints the text in all directions with a brighter color, then centered, with the foreground color.
    
    Since:
    
    TotalCross 1.01
    
    See Also:
    
    setHighlightedColor(int)
  - setHighlightedColor
```
public void setHighlightedColor(int c)
```
    The color used when highlighting is on. Defaults to a brighter foreground color.
    
    Parameters:
    
    c - The color to be used as highlighted color. Pass -1 to use the default one.
    
    Since:
    
    TotalCross 1.01
    
    See Also:
    
    setHighlighted(boolean)
  - split
```
public void split(int maxWidth)
```
    Splits the text to the given width. Remember to set the font (or add the Label to its parent) before calling this method.
    
    Since:
    
    TotalCross 1.14
    
    See Also:
    
    autoSplit
  - setText
```
public void setText(java.lang.String text)
```
    Sets the text that is displayed in the label. Newline is represented as \n.
    
    Specified by:
    
    setText in interface TextControl
  - stopMarquee
```
public void stopMarquee()
```
    Stops the marquee, but does not change the current text.
  - getText
```
public java.lang.String getText()
```
    Gets the text that is displayed in the label.
    
    Specified by:
    
    getText in interface TextControl
  - getPreferredWidth
```
public int getPreferredWidth()
```
    Returns the preffered width of this control.
    
    Overrides:
    
    getPreferredWidth in class Control
  - getMaxTextWidth
```
public int getMaxTextWidth()
```
    Returns the maximum text width for the lines of this Label.
  - getPreferredHeight
```
public int getPreferredHeight()
```
    Returns the preffered height of this control.
    
    Overrides:
    
    getPreferredHeight in class Control
  - getAlpha
```
public int getAlpha()
```
    Gets the alpha applied to the text color of this object
  - setAlpha
```
public void setAlpha(int alpha)
```
    Set the alpha value to be used with the text of this object (0 to 255)
  - onColorsChanged
```
protected void onColorsChanged(boolean colorsChanged)
```
    Description copied from class: Control
    
    Called after a setEnabled, setForeColor and setBackColor and when a control has been added to a Container. If colorsChanged is true, it was called from setForeColor/setBackColor/Container.add; otherwise, it was called from setEnabled
    
    Overrides:
    
    onColorsChanged in class Control
  - onFontChanged
```
protected void onFontChanged()
```
    Description copied from class: Control
    
    Called after a setFont
    
    Overrides:
    
    onFontChanged in class Control
  - onBoundsChanged
```
protected void onBoundsChanged(boolean screenChanged)
```
    Description copied from class: Control
    
    Called after a setRect.
    
    Overrides:
    
    onBoundsChanged in class Control
    
    Parameters:
    
    screenChanged - If the bounds were changed due to a screen change (rotation, collapse)
  - canScroll
```
public boolean canScroll(boolean down)
```
    Returns if the label can scroll in the given direction. A Label can scroll if the number of text lines is greater than the actual height.
  - scrollToBegin
```
public void scrollToBegin()
```
    Scrolls the text to the begining.
  - scrollToEnd
```
public void scrollToEnd()
```
    Scroll the text to the end.
  - scrollTo
```
public void scrollTo(int line)
```
    Scroll to the given line. Can be used to scroll the Label using a ScrollBar. Here's a sample, assuming that sbVert has been added to the container:
```
 sbVert.setMaximum(lab.getLineCount());
 sbVert.setVisibleItems(lab.getLinesPerPage());
 sbVert.setUnitIncrement(1);
 sbVert.setLiveScrolling(true);
 
```
    At the onEvent:
```
 if (event.type == ControlEvent.PRESSED && event.target == sbVert)
    lab.scrollTo(sbVert.getValue());
 
```
    Since:
    
    TotalCross 1.2
  - getLinesPerPage
```
public int getLinesPerPage()
```
    Return the number of lines per page of this label.
    
    Since:
    
    TotalCross 1.2
  - getLineCount
```
public int getLineCount()
```
    Return the number of lines of this label.
    
    Since:
    
    TotalCross 1.2
  - scroll
```
public boolean scroll(boolean down)
```
    Scroll one page. returns true if success, false if no scroll possible
    
    See Also:
    
    pageScroll
  - onPaint
```
public void onPaint(Graphics g)
```
    Called by the system to draw the button.
    
    Overrides:
    
    onPaint in class Control
    
    Parameters:
    
    g - the graphics object for drawing
    
    See Also:
    
    Graphics
  - clear
```
public void clear()
```
    This method does nothing: clear a label is usually not a desired action. However, if you really want to clear it, set its clearValueStr property.
    
    Overrides:
    
    clear in class Control

Class Label

Nested Class Summary

Nested classes/interfaces inherited from class totalcross.ui.Control

Field Summary

Fields inherited from class totalcross.ui.Control

Constructor Summary

Method Summary

Methods inherited from class totalcross.ui.Control

Methods inherited from class java.lang.Object

Field Detail

text

alpha

align

pageScroll

lines

useFillAsPreferred

preferredWidthText

borderColor

SOLID_BACKGROUND

VERTICAL_GRADIENT_BACKGROUND

HORIZONTAL_GRADIENT_BACKGROUND

backgroundType

firstGradientColor

secondGradientColor

autoSplit

vAlign

Constructor Detail

Label

Label

Label

Label

Method Detail

setInsets

setMarqueeText

isMarqueeRunning

onEvent

set3d

setInvert

setHighlighted

setHighlightedColor

split

setText

stopMarquee

getText

getPreferredWidth

getMaxTextWidth

getPreferredHeight

getAlpha

setAlpha

onColorsChanged

onFontChanged

onBoundsChanged

canScroll

scrollToBegin

scrollToEnd

scrollTo

getLinesPerPage

getLineCount

scroll

onPaint

clear