Class SurfaceImage

java.lang.Object
com.codename1.surfaces.SurfaceNode
com.codename1.surfaces.SurfaceImage
public class SurfaceImage extends SurfaceNode

An image node. Because surfaces render while the app process may be dead, images are shipped as named PNG blobs beside the descriptor rather than passed by reference: constructing the node from a com.codename1.ui.Image encodes it to PNG at publish time and names it by content hash (identical art re-published later ships no new bytes). A node can also reference a name that was already shipped with a previous publish.

Keep surface art small -- widget renderers run under tight memory budgets (about 30mb for the whole iOS widget extension) and Android parcels the rendered widget over a 1mb binder transaction.

  • Field Details

    • SCALE_FIT

      public static final int SCALE_FIT
      Scales the image to fit inside the node bounds, preserving aspect ratio.
      See Also:

    • SCALE_FILL

      public static final int SCALE_FILL
      Scales the image to fill the node bounds, preserving aspect ratio and cropping overflow.
      See Also:

    • SCALE_CENTER

      public static final int SCALE_CENTER
      Centers the image without scaling.
      See Also:

  • Constructor Details

    • SurfaceImage

      public SurfaceImage(Image image)

      Creates an image node from an image. The image is encoded to PNG when the descriptor is published.

      Parameters
      • image: the image to ship with the descriptor

    • SurfaceImage

      public SurfaceImage(String registeredName)

      Creates an image node referencing an image name shipped with an earlier publish to the same surface.

      Parameters
      • registeredName: the previously registered image name

  • Method Details

    • setScaleMode

      public SurfaceImage setScaleMode(int scaleMode)

      Sets how the image scales within the node bounds.

      Parameters
      • scaleMode: one of SCALE_FIT, SCALE_FILL, SCALE_CENTER
      Returns

      this image node, for chaining

    • setTint

      public SurfaceImage setTint(SurfaceColor tint)

      Tints the image with the supplied color, template-image style: the image's alpha channel is kept and its color replaced.

      Parameters
      • tint: the tint color
      Returns

      this image node, for chaining

    • getImage

      public Image getImage()
      Returns the source image, or null when this node references a registered name.

    • getRegisteredName

      public String getRegisteredName()
      Returns the referenced registered name, or null when this node ships its own image.

    • getScaleMode

      public int getScaleMode()
      Returns the scale mode, one of SCALE_FIT, SCALE_FILL, SCALE_CENTER.

    • getTint

      public SurfaceColor getTint()
      Returns the tint color, or null.

    • setPadding

      public SurfaceImage setPadding(int all)
      Description copied from class: SurfaceNode

      Sets the same padding on all four sides.

      Parameters
      • all: padding in dips
      Returns

      this node, for chaining

      Overrides:
      setPadding in class SurfaceNode

    • setPadding

      public SurfaceImage setPadding(int top, int right, int bottom, int left)
      Description copied from class: SurfaceNode

      Sets the padding of each side individually.

      Parameters
      • top: top padding in dips
      • right: right padding in dips
      • bottom: bottom padding in dips
      • left: left padding in dips
      Returns

      this node, for chaining

      Overrides:
      setPadding in class SurfaceNode

    • setBackground

      public SurfaceImage setBackground(SurfaceColor background)
      Description copied from class: SurfaceNode

      Sets the background color of this node.

      Parameters
      • color: the background color
      Returns

      this node, for chaining

      Overrides:
      setBackground in class SurfaceNode

    • setCornerRadius

      public SurfaceImage setCornerRadius(int radius)
      Description copied from class: SurfaceNode

      Sets the corner radius applied to the node's background. May render square on Android versions below 12.

      Parameters
      • radius: the corner radius in dips
      Returns

      this node, for chaining

      Overrides:
      setCornerRadius in class SurfaceNode

    • setAlignment

      public SurfaceImage setAlignment(SurfaceAlignment alignment)
      Description copied from class: SurfaceNode

      Sets this node's alignment within its parent. In a SurfaceBox all nine positions apply; in rows and columns only the cross-axis component is used.

      Parameters
      • alignment: the alignment
      Returns

      this node, for chaining

      Overrides:
      setAlignment in class SurfaceNode

    • setWeight

      public SurfaceImage setWeight(int weight)
      Description copied from class: SurfaceNode

      Sets the flexible-space weight of this node within a row or column. Nodes with a weight share the leftover space of the parent proportionally; a weight of 0 (the default) sizes the node to its natural size.

      Parameters
      • weight: the relative weight, 0 for natural sizing
      Returns

      this node, for chaining

      Overrides:
      setWeight in class SurfaceNode

    • setSize

      public SurfaceImage setSize(int widthDips, int heightDips)
      Description copied from class: SurfaceNode

      Sets a fixed size for this node. A value of 0 (the default) keeps the natural size of the respective axis.

      Parameters
      • widthDips: fixed width in dips, 0 for natural width
      • heightDips: fixed height in dips, 0 for natural height
      Returns

      this node, for chaining

      Overrides:
      setSize in class SurfaceNode

    • setAction

      public SurfaceImage setAction(String actionId)
      Description copied from class: SurfaceNode

      Assigns a tap action to this node. Tapping the node opens (or foregrounds) the app and delivers the action id to the handler registered with Surfaces.setActionHandler(...). Note that small iOS home-screen widgets only honor the action of the root node.

      Parameters
      • actionId: the app-defined action identifier
      Returns

      this node, for chaining

      Overrides:
      setAction in class SurfaceNode

    • setAction

      public SurfaceImage setAction(String actionId, Map<String,Object> params)
      Description copied from class: SurfaceNode

      Assigns a tap action with parameters to this node. The parameter map may contain String, Number and Boolean values and is delivered verbatim with the SurfaceActionEvent.

      Parameters
      • actionId: the app-defined action identifier
      • params: parameters delivered with the action, may be null
      Returns

      this node, for chaining

      Overrides:
      setAction in class SurfaceNode