Package totalcross.ui

Class 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);
    }

    • 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)

      • 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

    • 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