Class Label

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Label
All Implemented Interfaces:
Animation, Editable, StyleListener, IconHolder, TextHolder
Direct Known Subclasses:
Button, DefaultListCellRenderer, ScaleImageLabel, Slider
public class Label extends Component implements IconHolder, TextHolder

Allows displaying a single line of text and icon (both optional) with different alignment options. This class is a base class for several components allowing them to declare alignment/icon appearance universally.

Label text can be positioned in one of 4 locations as such:

Label left = new Label("Left", icon);
left.setTextPosition(Component.LEFT);
Label right = new Label("Right", icon);
right.setTextPosition(Component.RIGHT);
Label bottom = new Label("Bottom", icon);
bottom.setTextPosition(Component.BOTTOM);
Label top = new Label("Top", icon);
top.setTextPosition(Component.TOP);
hi.add(left).add(right).add(bottom).add(top);

  • Constructor Details

    • Label

      public Label(String text)

      Constructs a new label with the specified string of text, left justified.

      Parameters
      • text: the string that the label presents.

    • Label

      public Label(String text, String uiid)

      Constructs a new label with the specified string of text and uiid

      Parameters

      • text: the string that the label presents.

      • uiid: the uiid for the label

    • Label

      public Label()
      Construct an empty label

    • Label

      public Label(Image icon)

      Constructs a new label with the specified icon

      Parameters
      • icon: the image that the label presents.

    • Label

      public Label(Image icon, String uiid)

      Constructs a new label with the specified icon and UIID

      Parameters

      • icon: the image that the label presents.

      • uiid: the uiid for the label

    • Label

      public Label(String text, Image icon, String uiid)

      Constructs a new label with the specified icon text and UIID

      Parameters

      • text: the text of the label

      • icon: the image that the label presents.

      • uiid: the uiid for the label

    • Label

      public Label(String text, Image icon)

      Constructs a new label with the specified icon and text

      Parameters

      • text: the text of the label

      • icon: the image that the label presents.

  • Method Details

    • getDefaultGap

      public static int getDefaultGap()

      Returns the default gap in pixels between the icon/text to the Label boundaries

      Returns

      the gap in pixels between the icon/text to the Label boundaries

    • setDefaultGap

      public static void setDefaultGap(int gap)

      Set the default gap in pixels between the icon/text to the Label boundaries

      Parameters
      • gap: the gap in pixels

    • isDefaultTickerEnabled

      public static boolean isDefaultTickerEnabled()

      Allows disabling/enabling tickers globally

      Returns

      the defaultTickerEnabled

    • setDefaultTickerEnabled

      public static void setDefaultTickerEnabled(boolean aDefaultTickerEnabled)

      Allows disabling/enabling tickers globally

      Parameters
      • aDefaultTickerEnabled: the defaultTickerEnabled to set

    • laidOut

      protected void laidOut()
      This is a callback method to inform the Component when it's been laidout on the parent Container This is overriden for auto size mode
      Overrides:
      laidOut in class Component

    • getBadgeText

      public String getBadgeText()

      Gets the text to be used in a badge on this label.

      Returns

      the badge text to be used on this label. May return if no text is set.

      Since

      7.0

      See also

      • #setBadgeText(java.lang.String)

      • #setBadgeUIID(java.lang.String)

      • #getBadgeStyleComponent()

    • setBadgeText

      public void setBadgeText(String badgeText)

      Sets the badge text to be used on this label. Badges are rendered in the upper right corner of the label inside round border. The style of the badge can be configured using #setBadgeUIID(java.lang.String), but the default style uses the "Badge" UIID, which, by default, uses white text on a red round border background.

      Parameters
      • badgeText: @param badgeText The text to include in the badge. null or empty strings will result in the badge not being rendered.
      Since

      7.0

      See also

      • #getBadgeText()

      • #getBadgeStyleComponent()

      • #setBadgeUIID(java.lang.String)

    • setBadgeUIID

      public void setBadgeUIID(String badgeUIID)

      Sets the style that should be used for rendering badges. By default it will use the "Badge" UIID, which rendered 1.5mm white text on a red round border.

      Parameters
      • badgeUIID: The UIID to use for the badge.
      Since

      7.0

      See also

      • #setBadgeText(java.lang.String)

      • #getBadgeStyleComponent()

    • getBadgeStyleComponent

      public Component getBadgeStyleComponent()

      Gets a component that can be used for the style of the badge.

      Returns

      The component whose style can be used to style the badge. May return null if none set.

      Since

      7.0

      See also

      • #setBadgeText(java.lang.String)

      • #setBadgeUIID(java.lang.String)

      • #getBadgeText()

    • getIconStyleComponent

      public Component getIconStyleComponent()

      Gets the component that should be used for styling material the material icon. If #setIconUIID(java.lang.String) has been used to set a custom UIID for the icon, then this will return a component with that UIID. Otherwise this will just return this component itself.

      Returns

      The component to use for styling the material icon.

      Since

      7.0

      Specified by:
      getIconStyleComponent in interface IconHolder

    • setFontIcon

      public void setFontIcon(Font font, char c)

      This method is shorthand for Font, char, float)

      Parameters
      • c: one of the constants from the font

    • setMaterialIcon

      public void setMaterialIcon(char c, float size)

      This method is shorthand for char, float)

      Parameters

      • c: one of the constants from com.codename1.ui.FontImage

      • size: the size of the icon in millimeters

      Specified by:
      setMaterialIcon in interface IconHolder

    • setFontIcon

      public void setFontIcon(Font font, char c, float size)

      This method is shorthand for com.codename1.ui.Font, char, float)

      Parameters

      • c: one of the constants from the font

      • size: the size of the icon in millimeters

      Specified by:
      setFontIcon in interface IconHolder

    • getMaterialIcon

      public char getMaterialIcon()

      Returns the material icon assigned to this component or 0 if not applicable

      Returns

      the material icon

    • setMaterialIcon

      public void setMaterialIcon(char c)

      This method is shorthand for char)

      Parameters
      • c: one of the constants from com.codename1.ui.FontImage

    • getFontIcon

      public char getFontIcon()

      Returns the font icon assigned to this component or 0 if not applicable

      Returns

      the material icon

    • setFontIcon

      public void setFontIcon(char c)

      Sets an icon font using either the same icon font that was used to set the icon font last, or using the font from the icon UIID.

      Parameters
      • c: The character to render in the font.
      Since

      8.0

    • getMaterialIconSize

      public float getMaterialIconSize()

      Returns the material icon size assigned to this component or 0/-1 if not applicable

      Returns

      the material icon size

    • getFontIconSize

      public float getFontIconSize()

      Returns the icon size assigned to this component or 0/-1 if not applicable

      Returns

      the icon size

    • getIconFont

      public Font getIconFont()

      Returns the font for the icon font or null if not font set

      Returns

      the material icon size

    • getBaselineResizeBehavior

      public int getBaselineResizeBehavior()

      Returns a constant indicating how the baseline varies with the size of the component.

      Returns
      Overrides:
      getBaselineResizeBehavior in class Component
      Returns:
      one of BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_CENTER_OFFSET or BRB_OTHER

    • getBaseline

      public int getBaseline(int width, int height)
      Description copied from class: Component

      The baseline for the component text according to which it should be aligned with other components for best visual look.

      Parameters

      • width: the component width

      • height: the component height

      Returns

      baseline value from the top of the component

      Overrides:
      getBaseline in class Component

    • setUIID

      public void setUIID(String id)

      This method sets the Component the Unique identifier. This method should be used before a component has been initialized

      Parameters
      • id: UIID unique identifier for component type
      Overrides:
      setUIID in class Component

    • refreshTheme

      public void refreshTheme(boolean merge)

      Makes sure the component is up to date with the current theme, ONLY INVOKE THIS METHOD IF YOU CHANGED THE THEME!

      Parameters
      • merge: indicates if the current styles should be merged with the new styles
      Overrides:
      refreshTheme in class Component

    • initLaf

      protected void initLaf(UIManager uim)
      Description copied from class: Component
      This method initializes the Component defaults constants
      Overrides:
      initLaf in class Component

    • getText

      public String getText()

      Returns the label text

      Returns

      the label text

      Specified by:
      getText in interface TextHolder

    • setText

      public void setText(String text)

      Sets the Label text

      Parameters
      • text: the string that the label presents.
      Specified by:
      setText in interface TextHolder

    • getIcon

      public Image getIcon()

      Returns the labels icon

      Returns

      the labels icon

      Specified by:
      getIcon in interface IconHolder

    • setIcon

      public void setIcon(Image icon)

      Sets the Label icon, if the icon is unmodified a repaint would not be triggered

      Parameters
      • icon: the image that the label presents.
      Specified by:
      setIcon in interface IconHolder

    • getVerticalAlignment

      public int getVerticalAlignment()

      Returns the vertical alignment of the Label, this will only work when the icon is in the side of the text and not above or below it. The valign property is only relevant relatively to the icon and not the entire label, this will only work when there is an icon

      Returns

      the vertical alignment of the Label one of: CENTER, TOP, BOTTOM, BASELINE

      See also

      • #CENTER

      • #TOP

      • #BOTTOM

      • #BASELINE

    • setVerticalAlignment

      public void setVerticalAlignment(int valign)

      Sets the vertical alignment of the Label to one of: CENTER, TOP, BOTTOM, BASELINE The valign property is only relevant relatively to the icon and not the entire label, this will only work when there is an icon

      Parameters
      • valign: alignment value
      See also

      • #CENTER

      • #TOP

      • #BOTTOM

      • #BASELINE

    • getAlignment

      public int getAlignment()

      Returns the alignment of the Label

      Returns

      the alignment of the Label one of: CENTER, LEFT, RIGHT

      Deprecated

      use Style.getAlignment instead

      See also

      • #CENTER

      • #LEFT

      • #RIGHT

    • setAlignment

      public void setAlignment(int align)

      Sets the Alignment of the Label to one of: CENTER, LEFT, RIGHT

      Parameters
      • align: alignment value
      Deprecated

      use Style.setAlignment instead

      See also

      • #CENTER

      • #LEFT

      • #RIGHT

    • getTextPosition

      public int getTextPosition()

      Returns The position of the text relative to the icon

      Returns

      The position of the text relative to the icon, one of: LEFT, RIGHT, BOTTOM, TOP

      See also

      • #LEFT

      • #RIGHT

      • #BOTTOM

      • #TOP

      Specified by:
      getTextPosition in interface IconHolder

    • setTextPosition

      public void setTextPosition(int textPosition)

      Sets the position of the text relative to the icon if exists

      Parameters
      • textPosition: alignment value (LEFT, RIGHT, BOTTOM or TOP)
      See also

      • #LEFT

      • #RIGHT

      • #BOTTOM

      • #TOP

      Specified by:
      setTextPosition in interface IconHolder

    • getGap

      public int getGap()

      Returns the gap in pixels between the icon/text to the Label boundaries

      Returns

      the gap in pixels between the icon/text to the Label boundaries

      Specified by:
      getGap in interface IconHolder

    • setGap

      public void setGap(int gap)

      Set the gap in pixels between the icon/text to the Label boundaries

      Parameters
      • gap: the gap in pixels
      Specified by:
      setGap in interface IconHolder

    • paramString

      protected String paramString()

      Returns a string representing the state of this component. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

      Returns

      a string representation of this component's state

      Overrides:
      paramString in class Component

    • paint

      public void paint(Graphics g)

      This method paints the Component on the screen, it should be overriden by subclasses to perform custom drawing or invoke the UI API's to let the PLAF perform the rendering.

      Parameters
      • g: the component graphics
      Specified by:
      paint in interface Animation
      Overrides:
      paint in class Component

    • getMaxAutoSize

      public float getMaxAutoSize()

      Allows us to limit the maximum size for the autosize mode

      Returns

      the maximum font size in millimeters

    • setMaxAutoSize

      public void setMaxAutoSize(float maxSize)

      Allows us to limit the maximum size for the autosize mode

      Parameters
      • maxSize: the maximum font size in millimeters

    • getMinAutoSize

      public float getMinAutoSize()

      Allows us to limit the minimum size for the autosize mode

      Returns

      the minimum font size in millimeters

    • setMinAutoSize

      public void setMinAutoSize(float minSize)

      Allows us to limit the minimum size for the autosize mode

      Parameters
      • minSize: the minimum font size in millimeters

    • calcPreferredSize

      protected Dimension calcPreferredSize()

      Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

      Returns

      the calculated preferred size based on component content

      Overrides:
      calcPreferredSize in class Component

    • getShiftText

      public int getShiftText()

      Simple getter to return how many pixels to shift the text inside the Label

      Returns

      number of pixels to shift

    • setShiftText

      public void setShiftText(int shiftText)

      This method shifts the text from it's position in pixels. The value can be positive/negative to move the text to the right/left

      Parameters
      • shiftText: The number of pixels to move the text

    • shouldTickerStart

      public boolean shouldTickerStart()

      Returns true if a ticker should be started since there is no room to show the text in the label.

      Returns

      true if a ticker should start running

    • startTicker

      public void startTicker()
      This method will start the text ticker

    • startTicker

      public void startTicker(long delay, boolean rightToLeft)

      This method will start the text ticker

      Parameters

      • delay: the delay in millisecods between animation intervals

      • rightToLeft: if true move the text to the left

    • stopTicker

      public void stopTicker()
      Stops the text ticker

    • isTickerRunning

      public boolean isTickerRunning()

      Returns true if the ticker is running

      Returns

      true if the ticker is running

    • isTickerEnabled

      public boolean isTickerEnabled()

      This method return true if the ticker is enabled on this Label

      Returns

      tickerEnabled

    • setTickerEnabled

      public void setTickerEnabled(boolean tickerEnabled)

      Sets the Label to allow ticking of the text. By default is true

      Parameters
      • tickerEnabled

    • isEndsWith3Points

      public boolean isEndsWith3Points()

      If the Label text is too long fit the text to the widget and adds "..." points at the end. By default this is set to false for faster performance.

      Returns

      true if this Label adds "..." when the text is too long

    • setEndsWith3Points

      public void setEndsWith3Points(boolean endsWith3Points)

      If the Label text is too long fit the text to the widget and adds "..." points at the end. By default this is set to false for faster performance.

      Parameters
      • endsWith3Points: true if text should add "..." at the end

    • animate

      public boolean animate()

      Allows the animation to reduce "repaint" calls when it returns false. It is called once for every frame. Frames are defined by the com.codename1.ui.Display class.

      Returns

      true if a repaint is desired or false if no repaint is necessary

      Specified by:
      animate in interface Animation
      Overrides:
      animate in class Component

    • getMask

      public Object getMask()

      Returns the mask matching the given image

      Returns

      the mask for the given label

    • setMask

      public void setMask(Object mask)

      A mask image can be applied to the label (see the image mask method for details) which allows for things like rounded image appearance etc.

      Parameters
      • mask: the mask returned from the image object

    • getMaskName

      public String getMaskName()

      Determines the name of the mask from the image constants thus allowing the mask to be applied from the theme

      Returns

      the maskName

    • setMaskName

      public void setMaskName(String maskName)

      Determines the name of the mask from the image constants thus allowing the mask to be applied from the theme

      Parameters
      • maskName: the maskName to set

    • getPropertyNames

      public String[] getPropertyNames()

      A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code

      Returns

      the property names allowing mutation

      Overrides:
      getPropertyNames in class Component

    • getPropertyTypes

      public Class[] getPropertyTypes()

      Matches the property names method (see that method for further details).

      Returns

      the types of the properties

      Overrides:
      getPropertyTypes in class Component

    • getPropertyTypeNames

      public String[] getPropertyTypeNames()

      This method is here to workaround an XMLVM array type bug where property types aren't identified properly, it returns the names of the types using the following type names: String,int,double,long,byte,short,char,String[],String[][],byte[],Image,Image[],Object[],ListModel,ListCellRenderer

      Returns

      Array of type names

      Overrides:
      getPropertyTypeNames in class Component

    • getPropertyValue

      public Object getPropertyValue(String name)

      Returns the current value of the property name, this method is used by the GUI builder

      Parameters
      • name: the name of the property
      Returns

      the value of said property

      Overrides:
      getPropertyValue in class Component

    • setPropertyValue

      public String setPropertyValue(String name, Object value)

      Sets a new value to the given property, returns an error message if failed and null if successful. Notice that some builtin properties such as "$designMode" might be sent to components to indicate application state.

      Parameters

      • name: the name of the property

      • value: new value for the property

      Returns

      error message or null

      Overrides:
      setPropertyValue in class Component

    • getMaskedIcon

      public Image getMaskedIcon()

      If a mask is applied returns the icon with a mask, otherwise returns the icon

      Returns

      the icon masked or otherwise

    • getBindablePropertyNames

      public String[] getBindablePropertyNames()

      Returns the names of the properties within this component that can be bound for persistence, the order of these names mean that the first one will be the first bound

      Returns

      a string array of property names or null

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Overrides:
      getBindablePropertyNames in class Component

    • getBindablePropertyTypes

      public Class[] getBindablePropertyTypes()

      Returns the types of the properties that are bindable within this component

      Returns

      the class for binding

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Overrides:
      getBindablePropertyTypes in class Component

    • bindProperty

      public void bindProperty(String prop, BindTarget target)

      Binds the given property name to the given bind target

      Parameters

      • prop: the property name

      • target: the target binder

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Deprecated

      uses the deprecated BindTarget interface

      Overrides:
      bindProperty in class Component

    • unbindProperty

      public void unbindProperty(String prop, BindTarget target)

      Removes a bind target from the given property name

      Parameters

      • prop: the property names

      • target: the target binder

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Deprecated

      uses the deprecated BindTarget interface

      Overrides:
      unbindProperty in class Component

    • getBoundPropertyValue

      public Object getBoundPropertyValue(String prop)

      Allows the binding code to extract the value of the property

      Parameters
      • prop: the property
      Returns

      the value for the property

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Overrides:
      getBoundPropertyValue in class Component

    • setBoundPropertyValue

      public void setBoundPropertyValue(String prop, Object value)

      Sets the value of a bound property within this component, notice that this method MUST NOT fire the property change event when invoked to prevent recursion!

      Parameters

      • prop: the property whose value should be set

      • value: the value

      Deprecated

      this mapped to an older iteration of properties that is no longer used

      Overrides:
      setBoundPropertyValue in class Component

    • isShouldLocalize

      public boolean isShouldLocalize()

      Indicates if text should be localized when set to the label, by default all text is localized so this allows disabling automatic localization for a specific label.

      Returns

      the shouldLocalize value

    • setShouldLocalize

      public void setShouldLocalize(boolean shouldLocalize)

      Indicates if text should be localized when set to the label, by default all text is localized so this allows disabling automatic localization for a specific label.

      Parameters
      • shouldLocalize: the shouldLocalize to set

    • getShiftMillimeters

      public int getShiftMillimeters()

      Returns the number of millimeters that should be shifted in tickering rounded to nearest int.

      Returns

      the shiftMillimeters

      Deprecated

      Use #getShiftMillimetersF()

    • setShiftMillimeters

      public void setShiftMillimeters(int shiftMillimeters)

      Sets the millimeters that should be shifted in tickering

      Parameters
      • shiftMillimeters: the shiftMillimeters to set

    • setShiftMillimeters

      public void setShiftMillimeters(float shiftMillimeters)

      Sets the millimeters that should be shifted in tickering as a float.

      Parameters
      • shiftMillimeters: the shiftMillimeters to set
      Since

      7.0

    • getShiftMillimetersF

      public float getShiftMillimetersF()

      Returns the number of millimeters that should be shifted in tickering as a float.

      Since

      7.0

    • isShowEvenIfBlank

      public boolean isShowEvenIfBlank()

      By default labels and subclasses become 0 sized when they are blank even ignoring their padding setting this to true makes the padding take effect even in a blank field.

      Returns

      the showEvenIfBlank

    • setShowEvenIfBlank

      public final void setShowEvenIfBlank(boolean showEvenIfBlank)

      By default labels and subclasses become 0 sized when they are blank even ignoring their padding setting this to true makes the padding take effect even in a blank field.

      Parameters
      • showEvenIfBlank: the showEvenIfBlank to set

    • getStringWidth

      public int getStringWidth(Font fnt)

      This method is equivalent to label.getStyle().getFont().stringWidth(label.getText()) but its faster

      Parameters
      • fnt: the font is passed as an optimization to save a call to getStyle
      Returns

      the string width

    • isLegacyRenderer

      public boolean isLegacyRenderer()

      Fallback to the old default look and feel renderer for cases where compatibility is essential

      Returns

      the legacyRenderer

    • setLegacyRenderer

      public void setLegacyRenderer(boolean legacyRenderer)

      Fallback to the old default look and feel renderer for cases where compatibility is essential

      Parameters
      • legacyRenderer: the legacyRenderer to set

    • styleChanged

      public void styleChanged(String propertyName, Style source)
      Description copied from class: Component

      Invoked to indicate a change in a propertyName of a Style

      NOTE By default this will trigger a call to Container#revalidate() on the parent container, which is expensive. You can disable this behavior by calling CN.setProperty("Component.revalidateOnStyleChange", "false"). The intention is to change this behavior so that the default is to "not" revalidate on style change, so we encourage you to set this to "false" to ensure for future compatibility.

      Parameters

      • propertyName: the property name that was changed

      • source: The changed Style object

      Specified by:
      styleChanged in interface StyleListener
      Overrides:
      styleChanged in class Component

    • initUnselectedStyle

      protected void initUnselectedStyle(Style unselectedStyle)
      Description copied from class: Component

      Can be overridden by subclasses to perform initialization when the unselected style is set to a new value.

      Parameters
      • unselectedStyle: The unselected style.
      Since

      8.0

      Overrides:
      initUnselectedStyle in class Component

    • isAutoSizeMode

      public boolean isAutoSizeMode()

      Autosize mode automatically shrinks/grows the font of the label to fit in the available width, it carries a noticeable performance penalty and we recommend you avoid using it unless absolutely necessary

      Returns

      the autoSizeMode

    • setAutoSizeMode

      public void setAutoSizeMode(boolean autoSizeMode)

      Autosize mode automatically shrinks/grows the font of the label to fit in the available width, it carries a noticeable performance penalty and we recommend you avoid using it unless absolutely necessary

      Parameters
      • autoSizeMode: the autoSizeMode to set

    • isTextSelectionEnabled

      public boolean isTextSelectionEnabled()

      Returns true if text selection is enabled on this label. Default is false. To enable text selection, you must enable text selection on the Form with Form#getTextSelection() and TextSelection#setEnabled(boolean), and also ensure that the label's text selection is enabled via #setTextSelectionEnabled(boolean).

      Since

      7.0

      See also
      • #setTextSelectionEnabled(boolean)

    • setTextSelectionEnabled

      public void setTextSelectionEnabled(boolean enabled)

      Enables text selection on this label. Text selection must also be enabled on the Form in order to text selection to be activated.

      Parameters
      • enabled
      Since

      7.0

      See also

      • #setTextSelectionEnabled(boolean)

      • Form#getTextSelection()

      • TextSelection#setEnabled(boolean)

    • getTextSelectionSupport

      public TextSelection.TextSelectionSupport getTextSelectionSupport()
      Description copied from class: Component

      Returns text selection support object for this component. Only used by components that support text selection (e.g. Labels, un-editable text fields, etc..).

      Returns

      text selection support object

      Since

      7.0

      Overrides:
      getTextSelectionSupport in class Component

    • getIconUIID

      public String getIconUIID()
      Description copied from interface: IconHolder
      Gets the UIID used for styling material icons on this component.
      Specified by:
      getIconUIID in interface IconHolder

    • setIconUIID

      public void setIconUIID(String uiid)

      Sets a UIID to be used for the material icon style.

      Parameters
      • uiid: The uiid to use for the material icon style.
      Since

      7.0

      Specified by:
      setIconUIID in interface IconHolder