public class SurfaceImage

Object
SurfaceNode
SurfaceImage

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.

Fields

`public static final int SCALE_FIT = 0`	Scales the image to fit inside the node bounds, preserving aspect ratio.
`public static final int SCALE_FILL = 1`	Scales the image to fill the node bounds, preserving aspect ratio and cropping overflow.
`public static final int SCALE_CENTER = 2`	Centers the image without scaling.

Constructors

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

Methods

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

Inherited methods

From SurfaceNode

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

From Object

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

Field details

SCALE_FIT

public static final int SCALE_FIT = 0

Scales the image to fit inside the node bounds, preserving aspect ratio.

SCALE_FILL

public static final int SCALE_FILL = 1

Scales the image to fill the node bounds, preserving aspect ratio and cropping overflow.

SCALE_CENTER

public static final int SCALE_CENTER = 2

Centers the image without scaling.

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 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 String: the previously registered image name

Method details

setScaleMode

public SurfaceImage setScaleMode(int scaleMode)

Sets how the image scales within the node bounds.

Parameters

scaleMode int: 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 SurfaceColor: 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)

Sets the same padding on all four sides.

Parameters

all int: padding in dips

Returns

this node, for chaining

setPadding

public SurfaceImage setPadding(int top, int right, int bottom, int left)

Sets the padding of each side individually.

Parameters

top int: top padding in dips
right int: right padding in dips
bottom int: bottom padding in dips
left int: left padding in dips

Returns

this node, for chaining

setBackground

public SurfaceImage setBackground(SurfaceColor background)

Sets the background color of this node.

Parameters

background SurfaceColor: the background color

Returns

this node, for chaining

setCornerRadius

public SurfaceImage setCornerRadius(int radius)

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

Parameters

radius int: the corner radius in dips

Returns

this node, for chaining

setAlignment

public SurfaceImage setAlignment(SurfaceAlignment alignment)

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 SurfaceAlignment: the alignment

Returns

this node, for chaining

setWeight

public SurfaceImage setWeight(int weight)

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 int: the relative weight, 0 for natural sizing

Returns

this node, for chaining

setSize

public SurfaceImage setSize(int widthDips, int heightDips)

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

Parameters

widthDips int: fixed width in dips, 0 for natural width
heightDips int: fixed height in dips, 0 for natural height

Returns

this node, for chaining

setAction

public SurfaceImage setAction(String actionId)

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 String: the app-defined action identifier

Returns

this node, for chaining

setAction

public SurfaceImage setAction(String actionId, Map<String, Object> params)

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 String: the app-defined action identifier
params Map<String, Object>: parameters delivered with the action, may be null

Returns

this node, for chaining