core.imageview

An image view that allows zooming in and out an image.

local imageview = require "core.imageview"

__index​

(field) __index: core.object

Base class providing OOP functionality for Lua. All classes in Pragtical inherit from Object.

background​

(field) background: canvas?

Core functionality that allows rendering into a separate surface.

bg_color​

(field) bg_color: renderer.color

Array of bytes that represents a color used by the rendering functions.

bg_mode​

(field) bg_mode: "grid"|"none"|"solid"

context​

(field) context: string

current_scale​

(field) current_scale: number

cursor​

(field) cursor: string

errmsg​

(field) errmsg: string?

h_scrollbar​

(field) h_scrollbar: core.scrollbar

Scrollable viewport indicator with draggable thumb. Supports both vertical and horizontal orientation with configurable alignment. Uses a "normal" coordinate system internally that treats all scrollbars as vertical-end-aligned, then transforms to the actual orientation/alignment.

height​

(field) height: number

hovered_scrollbar​

(field) hovered_scrollbar: boolean

image​

(field) image: canvas?

Core functionality that allows rendering into a separate surface.

image_scaled​

(field) image_scaled: canvas?

Core functionality that allows rendering into a separate surface.

mouse_pressed​

(field) mouse_pressed: boolean

path​

(field) path: string?

position​

(field) position: core.view.position

prev_size​

(field) prev_size: table

scroll​

(field) scroll: core.view.scroll

scrollable​

(field) scrollable: boolean

size​

(field) size: core.view.position

super​

(field) super: core.view

Base view.

type​

(field) type: string

v_scrollbar​

(field) v_scrollbar: core.scrollbar

Scrollable viewport indicator with draggable thumb. Supports both vertical and horizontal orientation with configurable alignment. Uses a "normal" coordinate system internally that treats all scrollbars as vertical-end-aligned, then transforms to the actual orientation/alignment.

width​

(field) width: number

zoom_mode​

(field) zoom_mode: "fit"|"fixed"

zoom_scale​

(field) zoom_scale: number

is_supported​

function core.imageview.is_supported(path: string)
  -> supported: boolean
  2. file_extension: string

Check if an image type is supported by its filename extension.

__call​

(method) core.object:__call(...any)
  -> obj: core.object

Metamethod allowing class to be called like a constructor. Enables syntax: local obj = MyClass(args) instead of MyClass:new(args) Automatically creates instance and calls new() with provided arguments.

@return obj — The new instance of the class

__tostring​

(method) core.imageview:__tostring()
  -> string

clamp_scroll_position​

(method) core.view:clamp_scroll_position()

Clamp scroll position to valid range (0 to max scrollable size). Called automatically by update(). Override get_scrollable_size() to customize.

draw​

(method) core.imageview:draw()

draw_background​

(method) core.view:draw_background(color: renderer.color)

Draw a solid background color for the entire view. Commonly called at the start of draw() methods.

draw_image​

(method) core.imageview:draw_image()

draw_scrollbar​

(method) core.view:draw_scrollbar()

Draw the view's scrollbars. Commonly called at the end of draw() methods.

extend​

(method) core.object:extend()
  -> cls: core.object

Create a new class that inherits from this one. Returns a new class with this class as its parent. Example: local MyClass = Object:extend()

@return cls — The new class table

extends​

(method) core.object:extends(T: any)
  -> extends: boolean

Check if object inherits from the given type (inheritance-aware). Use this to check class hierarchy. Example: view:extends(View) returns true for View and all subclasses

@param T — Class to check inheritance from

@return extends — True if object is T or inherits from T

get_content_bounds​

(method) core.view:get_content_bounds()
  -> x1: number
  2. y1: number
  3. x2: number
  4. y2: number

Get the content bounds in content coordinates (accounting for scroll).

@return x1 — Left edge

@return y1 — Top edge

@return x2 — Right edge

@return y2 — Bottom edge

get_content_offset​

(method) core.view:get_content_offset()
  -> x: number
  2. y: number

Get the top-left corner of content area in screen coordinates. Accounts for scroll offset. Use for drawing content at correct position.

@return x — Screen x coordinate

@return y — Screen y coordinate

get_h_scrollable_size​

(method) core.imageview:get_h_scrollable_size()
  -> number

get_name​

(method) core.imageview:get_name()
  -> string

get_scrollable_size​

(method) core.imageview:get_scrollable_size()
  -> number

is​

(method) core.object:is(T: any)
  -> is_exact: boolean

Check if object is exactly of the given type (no inheritance check). Use this for strict type matching. Example: view:is(DocView) returns true only if view is a DocView, not a subclass

@param T — Class to check against

@return is_exact — True if object is exactly type T

is_class_of​

(method) core.object:is_class_of(T: any)
  -> is_instance: boolean

Check if the given object is exactly an instance of this class. Inverse of is() - checks if T is an instance of self. Example: DocView:is_class_of(obj) checks if obj is exactly a DocView

@param T — Object to check

@return is_instance — True if T is exactly an instance of this class

is_extended_by​

(method) core.object:is_extended_by(T: any)
  -> is_extended: boolean

Check if the given object/class inherits from this class. Inverse of extends() - checks if T is a subclass of self. Example: View:is_extended_by(DocView) checks if DocView inherits from View

@param T — Object or class to check

@return is_extended — True if T inherits from this class

load​

(method) core.imageview:load(path?: string)
  -> loaded: boolean
  2. errmsg: string?

Loads the given image into the view.

move_towards​

(method) core.view:move_towards(t: table, k: string|number, dest: number, rate?: number, name?: string)

Smoothly animate a value towards a destination. Use this for animations instead of direct assignment.

@param t — Table containing the value

@param k — Key in table

@param dest — Target value

@param rate — Animation speed (0-1, default 0.5, higher = faster)

@param name — Transition name (for config.disabled_transitions)

new​

(method) core.imageview:new(path?: string)

Constructor

on_file_dropped​

(method) core.view:on_file_dropped(filename: string, x: number, y: number)
  -> consumed: boolean

Handle file drop events (drag and drop from OS). Override to handle dropped files. Return true to consume event.

@param filename — Absolute path to dropped file

@param x — Screen x where file was dropped

@param y — Screen y where file was dropped

@return consumed — True to consume event, false to propagate

on_ime_text_editing​

(method) core.view:on_ime_text_editing(text: string, start: number, length: number)

Handle IME (Input Method Editor) text composition events. Override for IME support in text editors. Called during composition.

@param text — Composition text being edited

@param start — Start position of selection within composition

@param length — Length of selection within composition

on_mouse_left​

(method) core.view:on_mouse_left()

Called when mouse leaves the view's area. Override to clear hover states. Base implementation notifies scrollbars.

on_mouse_moved​

(method) core.imageview:on_mouse_moved(x: number, y: number, dx: number, dy: number)
  -> boolean

on_mouse_pressed​

(method) core.imageview:on_mouse_pressed(button: 'left'|'right', x: number, y: number, clicks: integer)
  -> boolean

on_mouse_released​

(method) core.imageview:on_mouse_released(button: 'left'|'right', x: number, y: number)

on_mouse_wheel​

(method) core.imageview:on_mouse_wheel(d: number)
  -> boolean

on_scale_change​

(method) core.view:on_scale_change(new_scale: number, prev_scale: number)

Called when DPI scale changes (display moved, zoom changed, etc.). Override to adjust sizes, padding, or other scale-dependent values.

@param new_scale — New scale factor (e.g., 1.0, 1.5, 2.0)

@param prev_scale — Previous scale factor

on_text_input​

(method) core.view:on_text_input(text: string)

Handle text input events (typing, IME composition). Override for text editing. Called after IME composition completes.

@param text — Input text (may be multiple characters)

on_touch_moved​

(method) core.view:on_touch_moved(x: number, y: number, dx: number, dy: number, i: number)

Handle touch move events (touchscreen/trackpad gestures). Override for touch-specific behavior. Base implementation handles scrolling.

@param x — Current touch x coordinate

@param y — Current touch y coordinate

@param dx — Delta x since last position

@param dy — Delta y since last position

@param i — Touch finger/pointer index

scale_image​

(method) core.imageview:scale_image()

Scale the currently loaded image depending on the current zoom mode and scale factor.

scrollbar_dragging​

(method) core.view:scrollbar_dragging()
  -> dragging: boolean

Check if user is currently dragging either scrollbar.

@return dragging — True if scrollbar drag is in progress

scrollbar_hovering​

(method) core.view:scrollbar_hovering()
  -> hovering: boolean

Check if mouse is hovering over either scrollbar track.

@return hovering — True if mouse is over scrollbar

scrollbar_overlaps_point​

(method) core.view:scrollbar_overlaps_point(x: number, y: number)
  -> overlaps: boolean

Check if a screen point overlaps either scrollbar. Useful for determining cursor style or handling clicks.

@param x — Screen x coordinate

@param y — Screen y coordinate

@return overlaps — True if point is over vertical or horizontal scrollbar

supports_text_input​

(method) core.view:supports_text_input()
  -> boolean

Whether this view accepts text input (enables IME). Override and return true for text editors and input fields.

try_close​

(method) core.view:try_close(do_close: function)

Called when view is requested to close (e.g., tab close button). Override to show confirmation dialogs for unsaved changes. Example: core.command_view:enter("Save?", \{submit = do_close\})

@param do_close — Call this function to actually close the view

update​

(method) core.imageview:update()

update_scrollbar​

(method) core.view:update_scrollbar()

Update scrollbar positions and sizes. Called automatically by update(). Rarely needs to be called manually.

zoom_in​

(method) core.imageview:zoom_in()

Increases the image scale.

zoom_out​

(method) core.imageview:zoom_out()

Decreases the image scale.

zoom_reset​

(method) core.imageview:zoom_reset()

Sets image size to original.