Package limn.components

Class Surface

java.lang.Object
limn.scene.Widget<Surface>
limn.components.Surface
public final class Surface extends Widget<Surface>
A surface lifted above what is around it: a fill, the shadow its Elevation has in the theme, and one child inside. For a panel that slides in over content, a card with no edge, a bar that floats; the toolkit's own menus, lists, calendars and dialogs draw theirs themselves.

The surface is as large as its child and lays it out over its whole box; put a Padding inside for a margin. The shadow is painted outside the box, so whatever holds the surface must leave it room: a parent that clips to the surface's own box clips the shadow away.

  • Constructor Details

    • Surface

      public Surface(Widget<?> content)
      Parameters:
      content - what the surface holds

  • Method Details

    • setElevation

      public Surface setElevation(Elevation level)
      Sets how far the surface is lifted (default Elevation.RAISED). UI thread only.
      Parameters:
      level - the level
      Returns:
      this surface

    • elevation

      public Elevation elevation()
      Returns:
      how far the surface is lifted

    • setFill

      public Surface setFill(@Nullable Color color)
      Sets the surface's colour, or null (the default) for the theme's: surface when raised or flat, surfaceRaised when it covers. UI thread only.
      Parameters:
      color - the fill, or null to follow the theme
      Returns:
      this surface

    • setCornerRadius

      public Surface setCornerRadius(float radius)
      Sets the corner radius in points, or a negative number (the default) for the theme's medium radius at this widget's size step; zero for a surface that meets an edge of the window. UI thread only.
      Parameters:
      radius - the radius
      Returns:
      this surface

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

    • onLayout

      protected void onLayout()
      Description copied from class: Widget
      Containers position children here (measure + Widget.layoutBox(float, float, float, float) per child).
      Overrides:
      onLayout in class Widget<Surface>

    • paintsDecoration

      protected boolean paintsDecoration()
      The surface's fill and shadow are background to its child, which is what a reader is told: the surface itself is not in the accessible tree.
      Overrides:
      paintsDecoration in class Widget<Surface>
      Returns:
      true, always

    • paintOutset

      protected float paintOutset()
      Description copied from class: Widget
      How far beyond this widget's bounds its painting may reach, in logical points: its own painting and any descendant no ancestor clips (a drop shadow, a glow, a child positioned outside the parent's box). Partial rendering uses it both ways: Widget.invalidate() damage grows by it, and a repaint pass skips this subtree only when bounds + outset miss the pass region; painting farther than declared leaves stale pixels.

      The work is divided by who knows the number. A widget declares what it paints itself outside its box: Label's icon overhang, the focus ring Button, Checkbox and RadioButton draw outside theirs. A widget that lays out children and does not clip them declares how far they may paint past it, because a ring on a child at its edge hangs past it too, and a pass landing only in that band would otherwise skip it and never reach the child. Every layout the toolkit ships does that by default with the reach the theme gives a focus ring, and takes another number through its public paintOverflow, which sets what this hook answers; a layout an application writes inherits both by extending limn.scene.layout.Container, and one that extends this class directly overrides this hook itself. A widget that clips its children declares only its own painting, since the clip bounds theirs.

      Asked of every widget a repaint pass considers, and on every invalidate(), so an override answers in constant time without allocating: a number held or looked up, never a walk over the children. Default 0: everything stays inside the bounds, which is true for most leaves.

      Overrides:
      paintOutset in class Widget<Surface>

    • onPaint

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