Package limn.components

Class Badge

java.lang.Object
limn.scene.Widget<Badge>
limn.components.Badge
public final class Badge extends Widget<Badge>
A short status beside or inside something else: "Overdue" in a table's cell, "3" beside an inbox, a dot beside a row's name that says it is unread.

One look, whatever the tone. A pill tinted in the Tone, and at its leading end either the icon drawn in the tone or, with no icon, a dot of it; the word is in the palette's text colour. The colour says the state at a glance and the word says it to everyone, a person who does not tell red from green and a screen reader included, and the word's contrast is the palette's own text on its surface, which every built-in palette is tested for, at every tone.

Three kinds, by how the badge is made:

  • a text badge, Badge(I18nString), with a dot or an icon before the word;
  • a count, ofCount(int): the number alone in the pill, in the digits the language is shown in, and "99+" past 99 so a badge does not grow with its count;
  • a dot, dot(I18nString): the dot alone, twice as wide as a text badge's, and a name a reader hears in its place.

To an assistive technology a badge is a static text, a Accessible.Role.LABEL, named by the word it shows, the number as shown, or a dot's name. It takes no focus and has no verb. An application that wants a count read as "3 unread" names it with Widget.setAccessibleName(limn.i18n.I18nString); a badge inside a table's row or an activatable Card is read through the row's or the card's own name, as anything inside them is. 


 new Badge("Overdue").setTone(Tone.DANGER);
 Badge.ofCount(unread).setTone(Tone.ACCENT).setAccessibleName(unread + " unread");

  • Constructor Details

    • Badge

      public Badge(String text)
      A badge with a fixed word.
      Parameters:
      text - the word; never null

    • Badge

      public Badge(I18nString text)
      A badge whose word follows the UI language.
      Parameters:
      text - the word; never null

    • Badge

      public Badge(Icon icon, I18nString text)
      A badge whose icon leads its word, drawn in the badge's tone in place of the dot.
      Parameters:
      icon - the icon; never null
      text - the word, which also names the badge; never null

  • Method Details

    • ofCount

      public static Badge ofCount(int n)
      A badge that shows a number: in the digits the language is shown in, and "99+" past 99.
      Parameters:
      n - the count; at least zero
      Returns:
      the badge
      Throws:
      IllegalArgumentException - if n is negative

    • dot

      public static Badge dot(I18nString name)
      A dot alone, for an "unread" or "changed" mark beside a row's name: twice as wide as a text badge's dot, with no pill and no word. The name is what a reader hears in its place.
      Parameters:
      name - what the dot means; never null
      Returns:
      the badge

    • setText

      public Badge setText(String newText)
      Replaces the word, or a dot's name, with a fixed string.
      Parameters:
      newText - the word; never null
      Returns:
      this badge
      Throws:
      IllegalStateException - on a count badge, which shows its count

    • setText

      public Badge setText(I18nString newText)
      Replaces the word, or a dot's name, with one that follows the UI language. A layout runs only when the badge's width changes.
      Parameters:
      newText - the word; never null
      Returns:
      this badge
      Throws:
      IllegalStateException - on a count badge, which shows its count

    • text

      public String text()
      Returns:
      the word, a dot's name, or for a count the number as shown

    • setIcon

      public Badge setIcon(@Nullable Icon newIcon)
      Sets the icon drawn before the word in place of the dot, in the badge's tone; null brings the dot back. Not drawn by a count or a dot badge.
      Parameters:
      newIcon - the icon, or null
      Returns:
      this badge

    • icon

      public @Nullable Icon icon()
      Returns:
      the icon drawn before the word, or null for the dot

    • setTone

      public Badge setTone(Tone newTone)
      Sets the tone the pill, the dot and the icon are drawn in; Tone.NEUTRAL by default. Resolved against the palette on every paint, so a change of palette re-colours the badge.
      Parameters:
      newTone - the tone; never null
      Returns:
      this badge

    • tone

      public Tone tone()
      Returns:
      the tone the badge is drawn in

    • setCount

      public Badge setCount(int n)
      Changes a count badge's number. A layout runs only when the shown width changes, which is when the number of digits does.
      Parameters:
      n - the count; at least zero
      Returns:
      this badge
      Throws:
      IllegalArgumentException - if n is negative
      IllegalStateException - on a badge that is not a count

    • count

      public int count()
      Returns:
      a count badge's number, or zero for any other

    • onMeasure

      protected Size onMeasure(Constraints constraints)
      Description copied from class: Widget
      Reports the size this widget wants within constraints. Called once per layout pass, and the result is cached against the constraints and the resolved axes (size step, layout direction, locale), so it must be a pure function of them and of this widget's own state.

      Resolve the ControlSize and the LayoutDirection once each here and thread them down; never read either in a constructor. The locale needs no threading: it is in scope, and I18n.locale() answers it wherever text is resolved.

      Specified by:
      onMeasure in class Widget<Badge>

    • baselineOffset

      protected float baselineOffset()
      The baseline a BASELINE row aligns on: the very expression the paint draws with.
      Overrides:
      baselineOffset in class Widget<Badge>

    • onPaint

      protected void onPaint(Canvas canvas)
      Description copied from class: Widget
      Widget's own background/content, in local coordinates.
      Overrides:
      onPaint in class Widget<Badge>

    • onAccessibility

      protected void onAccessibility(Accessibility a)
      A static text named by what it shows: the word, the number as drawn, or a dot's name. The count's name is the held string with the counter that moves when it does, so a quiet frame compares a number and allocates nothing.
      Overrides:
      onAccessibility in class Widget<Badge>
      Parameters:
      a - the node being described