Package limn.components

Class Button

java.lang.Object
limn.scene.Widget
limn.components.Button
public class Button extends Widget
Push button with the full state set (normal, hover, pressed, disabled, focused) and an onAction(Runnable) fired by click or by Enter/Space while focused. All visuals come from the Theme. Keep actions short (the slow-handler instrumentation will flag violations); heavy work goes through Ui.async.

Sizes follow the ControlSize resolved on this widget: every metric comes from the SizeTokens row, every weight from Strokes. Tokens are resolved once per pass into a local and threaded down; resolving twice inside one pass is how measure and paint end up disagreeing about where the label sits.

The icon-and-caption block is centred, so a text-only button draws the same coordinates whichever way its subtree reads. What the direction decides is the order of the two things inside that block: the icon is leading, which is the block's left end reading left to right and its right end reading right to left. Whether the glyph drawn inside that square turns around as well is the caller's to say — see Icon.Mirroring.

  • Constructor Details

    • Button

      public Button(String text)
      A button with a fixed caption; see the I18nString constructor for localized text.

    • Button

      public Button(I18nString text)
      A button whose caption follows the UI language; see I18nString.

  • Method Details

    • setIcon

      public Button setIcon(Icon newIcon)
      Sets a leading icon, drawn tinted to the label color. null clears it. Leading is the end of the caption block reading starts from, so the square trades ends with the caption when the button reads right to left; the glyph inside it is drawn as authored. Use setIcon(Icon, Icon.Mirroring) for an icon that means a direction.

    • setIcon

      public Button setIcon(Icon newIcon, Icon.Mirroring mirroring)
      A leading icon that says whether its glyph turns around when the interface does. Only the code that placed an icon knows whether its arrow means "back" or "download", which is why this is a flag here and never a classification inside the toolkit.
      Parameters:
      mirroring - Icon.Mirroring.NEVER unless this glyph is directional; the square's own end of the block moves either way

    • setSecondary

      public Button setSecondary(boolean value)
      Secondary style: a surface-filled, outlined button instead of the filled primary.

    • withControlSize

      public Button withControlSize(ControlSize size)
      Chaining form of Widget.setControlSize(limn.scene.ControlSize); setControlSize is void.

    • onAction

      public Button onAction(Runnable newAction)
      Called on click, or on Space/Enter while focused. Not called while disabled.

    • text

      public String text()
      The caption as it currently reads; see textSource() for the key behind it.

    • textSource

      public I18nString textSource()
      The localizable value this button holds, which a language change re-resolves.

    • setText

      public Button setText(String newText)
      Replaces the caption with a fixed string. UI thread only.

    • setText

      public Button setText(I18nString newText)
      Replaces the caption with a value that follows the UI language. UI thread only.

    • 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

    • baselineOffset

      protected float baselineOffset()
      The baseline BASELINE rows align on, the very expression onPaint(limn.graphics.Canvas) draws with.
      Overrides:
      baselineOffset in class Widget

    • paintOutset

      protected float paintOutset()
      The focus ring is drawn OUTSIDE the box: centred Strokes.FOCUS_GAP_BUTTON out with a Strokes.FOCUS_RING pen, so its outer ink reaches Strokes.FOCUS_RING_OUTSET, and damage has to know that. Scene inflates a widget's damage rect by 1 + paintOutset(), so without this override the fade-out of a ring on the toolkit's most-used widget sheds stale pixels under partial rendering.

      Declares reach only; it moves no ink. Checkbox, RadioButton and Label carry the same kind of override for the same reason.

      Overrides:
      paintOutset in class Widget

    • onPaint

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

    • onMouseEvent

      protected void onMouseEvent(MouseEvent event)
      Description copied from class: Widget
      Mouse events (bubbling); call event.consume() when handled.
      Overrides:
      onMouseEvent in class Widget

    • onKeyEvent

      protected void onKeyEvent(KeyEvent event)
      Description copied from class: Widget
      Key events (focused widget first, then ancestors).
      Overrides:
      onKeyEvent in class Widget

    • onFocusGained

      protected void onFocusGained()
      Description copied from class: Widget
      Called when this widget takes keyboard focus. Default: nothing.
      Overrides:
      onFocusGained in class Widget

    • onFocusLost

      protected void onFocusLost()
      Description copied from class: Widget
      Called when this widget loses keyboard focus. Default: nothing.
      Overrides:
      onFocusLost in class Widget