Table of Contents

image

`image()` displays an image file, an `image_data` object, or an `image_stream` object.

It can also draw on a loaded static image through an `image_pen` object returned by `pen()`.

Constructor

image()

Creates an image control. Default size is `160 x 120`.

Item Description
Syntax `image()`
Arguments none
Returns image object 
view = image().load('preview.png');

Properties

Properties are read-only. Use methods to change values.

Property Type Description
`position_x` number X position.
`position_y` number Y position.
`size_width` number Width.
`size_height` number Height.
`visible` boolean Visibility state.
`enabled` boolean Enabled state.
`file` string Current file path, or empty when image data or stream is used.
`scale` number Current manual scale. `-1` means automatic scale.
`placement` string One of `fit`, `fill`, `center`, `stretch`, `top_left`.
`animated` boolean `true` for animated images or streams.
`playing` boolean `true` when animation or stream playback is active.
`frame_width` number Current frame width.
`frame_height` number Current frame height.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `image`.

Common GUI Methods

Most visible GUI controls support these methods.

position(x, y)

Sets the component position in pixels.

Item Description
Syntax `component.position(x, y)`
Arguments `x`: x position; `y`: y position
Returns component object

Example: 

label().position(20, 10);

size(width, height)

Sets the component size in pixels. Width and height are clamped to at least `1`.

Some container objects, such as `panel()` and `group()`, use `size(-1, -1)` as a special fit-parent mode.

Item Description
Syntax `component.size(width, height)`
Arguments `width`: width in pixels; `height`: height in pixels
Returns component object

Example: 

textinput().size(220, 26);

visible(enabled)

Shows or hides the component.

Item Description
Syntax `component.visible(enabled)`
Arguments `enabled`: boolean
Returns component object

Example: 

status.visible(false);

enabled(enabled)

Enables or disables user interaction with the component.

Item Description
Syntax `component.enabled(enabled)`
Arguments `enabled`: boolean
Returns component object

Example: 

run_button.enabled(false);

Methods

info(enabled)

Shows or hides image debug information.

Item Description
Syntax `image.info(enabled)`
Arguments `enabled`: boolean value
Returns image object 
view = image().info(true);

load(source)

Loads an image source.

`source` can be a file path, an `image_data` object, or an `image_stream` object.

Item Description
Syntax `image.load(source)`
Arguments `source`: file path, `image_data`, or `image_stream`
Returns image object 
view = image().load('preview.png');

pen(color, thickness)

Creates an `image_pen` object for a loaded static image.

The image must already be loaded. `pen()` is not supported for animated images or image streams.

Item Description
Syntax `image.pen(color, thickness)`
Arguments `color`: numeric RGBA color; `thickness`: line thickness
Returns `image_pen` object 
view = image().load('drawing.png');
pen = view.pen(0xff0000ff, 2);

scale(value)

Sets manual image scale.

Use `-1` for automatic scale.

Item Description
Syntax `image.scale(value)`
Arguments `value`: scale value, or `-1` for automatic scale
Returns image object 
view = image().load('preview.png').scale(-1);

placement_fit()

Fits the image inside the control.

Item Description
Syntax `image.placement_fit()`
Arguments none
Returns image object 
view = image().load('preview.png').placement_fit();

placement_fill()

Fills the control and crops the image if needed.

Item Description
Syntax `image.placement_fill()`
Arguments none
Returns image object 
view = image().load('preview.png').placement_fill();

placement_center()

Centers the image without scaling.

Item Description
Syntax `image.placement_center()`
Arguments none
Returns image object 
view = image().load('preview.png').placement_center();

placement_stretch()

Stretches the image to the control size.

Item Description
Syntax `image.placement_stretch()`
Arguments none
Returns image object 
view = image().load('preview.png').placement_stretch();

placement_top_left()

Draws the image at the top-left corner without centering.

Item Description
Syntax `image.placement_top_left()`
Arguments none
Returns image object 
view = image().load('preview.png').placement_top_left();

play()

Starts animated image or stream playback.

Item Description
Syntax `image.play()`
Arguments none
Returns image object 
stream = image_stream().load_folder('frames', '*.jpg');
view = image().load(stream).play();

stop()

Stops animated image or stream playback.

Item Description
Syntax `image.stop()`
Arguments none
Returns image object 
view.stop();

image_pen

`image_pen` records drawing commands on the owning image.

`image_pen()` is not a public constructor. Create an `image_pen` object with `image.pen(color, thickness)`.

Colors are numeric RGBA values used by the host color type.

Constructor

`image_pen` objects are not created with a public constructor.

Item Description
Syntax created by `image.pen(color, thickness)`
Arguments not applicable
Returns `image_pen` object 
view = image().load('drawing.png');
pen = view.pen(0xff0000ff, 2);

Properties

`image_pen` currently exposes no public properties.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `image_pen`.

Methods

move_to(x, y)

Moves the current drawing point.

Item Description
Syntax `image_pen.move_to(x, y)`
Arguments `x`: x coordinate; `y`: y coordinate
Returns `image_pen` object 
pen.move_to(10, 10);

line_to(x, y)

Draws a line from the current point to the new point.

Item Description
Syntax `image_pen.line_to(x, y)`
Arguments `x`: end x coordinate; `y`: end y coordinate
Returns `image_pen` object 
pen.move_to(10, 10).line_to(120, 10);

draw_line(x0, y0, x1, y1)

Draws a line between two points.

Item Description
Syntax `image_pen.draw_line(x0, y0, x1, y1)`
Arguments `x0`: start x; `y0`: start y; `x1`: end x; `y1`: end y
Returns `image_pen` object 
pen.draw_line(10, 10, 120, 10);

draw_rect(x, y, width, height)

Draws a rectangle outline.

Item Description
Syntax `image_pen.draw_rect(x, y, width, height)`
Arguments `x`: left position; `y`: top position; `width`: rectangle width; `height`: rectangle height
Returns `image_pen` object 
pen.draw_rect(10, 10, 120, 80);

fill_rect(x, y, width, height)

Draws a filled rectangle.

Item Description
Syntax `image_pen.fill_rect(x, y, width, height)`
Arguments `x`: left position; `y`: top position; `width`: rectangle width; `height`: rectangle height
Returns `image_pen` object 
pen.fill_rect(10, 10, 120, 80);

draw_circle(cx, cy, diameter)

Draws a circle outline.

Item Description
Syntax `image_pen.draw_circle(cx, cy, diameter)`
Arguments `cx`: center x; `cy`: center y; `diameter`: circle diameter
Returns `image_pen` object 
pen.draw_circle(80, 60, 40);

fill_circle(cx, cy, diameter)

Draws a filled circle.

Item Description
Syntax `image_pen.fill_circle(cx, cy, diameter)`
Arguments `cx`: center x; `cy`: center y; `diameter`: circle diameter
Returns `image_pen` object 
pen.fill_circle(80, 60, 40);

draw_text(x, y, text)

Draws text with default size and weight.

Item Description
Syntax `image_pen.draw_text(x, y, text)`
Arguments `x`: x position; `y`: y position; `text`: text to draw
Returns `image_pen` object 
pen.draw_text(20, 40, 'OK');

draw_text(x, y, text, size)

Draws text with a font size.

Item Description
Syntax `image_pen.draw_text(x, y, text, size)`
Arguments `x`: x position; `y`: y position; `text`: text to draw; `size`: font size
Returns `image_pen` object 
pen.draw_text(20, 40, 'OK', 18);

draw_text(x, y, text, size, bold)

Draws text with a font size and bold flag.

Item Description
Syntax `image_pen.draw_text(x, y, text, size, bold)`
Arguments `x`: x position; `y`: y position; `text`: text to draw; `size`: font size; `bold`: boolean value
Returns `image_pen` object 
pen.draw_text(20, 40, 'OK', 18, true);

draw_image(x, y, path)

Draws another image at position.

Item Description
Syntax `image_pen.draw_image(x, y, path)`
Arguments `x`: x position; `y`: y position; `path`: image file path
Returns `image_pen` object 
pen.draw_image(10, 10, 'logo.png');

draw_image(x, y, path, width, height)

Draws another image scaled to size.

Item Description
Syntax `image_pen.draw_image(x, y, path, width, height)`
Arguments `x`: x position; `y`: y position; `path`: image file path; `width`: target width; `height`: target height
Returns `image_pen` object 
pen.draw_image(10, 10, 'logo.png', 80, 40);

color(color)

Sets pen and fill color to the same color.

Item Description
Syntax `image_pen.color(color)`
Arguments `color`: numeric RGBA color
Returns `image_pen` object 
pen.color(0xff0000ff);

color(penColor, fillColor)

Sets pen color and fill color separately.

Item Description
Syntax `image_pen.color(penColor, fillColor)`
Arguments `penColor`: numeric RGBA outline color; `fillColor`: numeric RGBA fill color
Returns `image_pen` object 
pen.color(0xff0000ff, 0x00ff00ff);

color_fill(color)

Sets fill color.

Item Description
Syntax `image_pen.color_fill(color)`
Arguments `color`: numeric RGBA fill color
Returns `image_pen` object 
pen.color_fill(0x00ff00ff);

thickness(value)

Sets line thickness.

Item Description
Syntax `image_pen.thickness(value)`
Arguments `value`: line thickness
Returns `image_pen` object 
pen.thickness(3);

Examples

view = image()
    .position(10, 10)
    .size(320, 200)
    .load('preview.png')
    .placement_fit();
 
window().title('Preview').size(360, 260).add(view).show();
stream = image_stream().load_folder('frames', '*.jpg');
view = image().position(10, 10).size(320, 240).load(stream).play();
window().title('Stream').size(360, 300).add(view).show();
view = image().position(10, 10).size(300, 200).load('drawing.png');
pen = view.pen(0xff0000ff, 2);
pen.draw_rect(10, 10, 120, 80)
   .draw_text(20, 40, 'OK', 18, true);
 
window().title('Drawing').size(340, 260).add(view).show();

Previous: menu

Next: snake