# 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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `SCALE_CENTER`
  Centers the image without scaling.
  `static final int`
  `SCALE_FILL`
  Scales the image to fill the node bounds, preserving aspect ratio and cropping overflow.
  `static final int`
  `SCALE_FIT`
  Scales the image to fit inside the node bounds, preserving aspect ratio.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SurfaceImage(Image image)`
  Creates an image node from an image.
  `SurfaceImage(String registeredName)`
  Creates an image node referencing an image name shipped with an earlier publish to the same surface.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Image`
  `getImage()`
  Returns the source image, or null when this node references a registered name.
  `String`
  `getRegisteredName()`
  Returns the referenced registered name, or null when this node ships its own image.
  `int`
  `getScaleMode()`
  Returns the scale mode, one of `SCALE_FIT`, `SCALE_FILL`, `SCALE_CENTER`.
  `SurfaceColor`
  `getTint()`
  Returns the tint color, or null.
  `SurfaceImage`
  `setAction(String actionId)`
  Assigns a tap action to this node.
  `SurfaceImage`
  `setAction(String actionId, Map<String,Object> params)`
  Assigns a tap action with parameters to this node.
  `SurfaceImage`
  `setAlignment(SurfaceAlignment alignment)`
  Sets this node's alignment within its parent.
  `SurfaceImage`
  `setBackground(SurfaceColor background)`
  Sets the background color of this node.
  `SurfaceImage`
  `setCornerRadius(int radius)`
  Sets the corner radius applied to the node's background.
  `SurfaceImage`
  `setPadding(int all)`
  Sets the same padding on all four sides.
  `SurfaceImage`
  `setPadding(int top, int right, int bottom, int left)`
  Sets the padding of each side individually.
  `SurfaceImage`
  `setScaleMode(int scaleMode)`
  Sets how the image scales within the node bounds.
  `SurfaceImage`
  `setSize(int widthDips, int heightDips)`
  Sets a fixed size for this node.
  `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.
  `SurfaceImage`
  `setWeight(int weight)`
  Sets the flexible-space weight of this node within a row or column.

  ### Methods inherited from class SurfaceNode

  `getActionId, getActionParams, getAlignment, getBackground, getCornerRadius, getHeightDips, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getWeight, getWidthDips`

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### SCALE_FIT

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

  - ### SCALE_FILL

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

  - ### SCALE_CENTER

    public static final int SCALE_CENTER
    Centers the image without scaling.
    See Also:
      - Constant Field Values

- ## 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`