Skip to main content

widget.listbox

local listbox = require "widget.listbox"

COLEND​

(field) COLEND: integer

Indicates on a widget.listbox.row that the end of a column was reached.

NEWLINE​

(field) NEWLINE: integer

Indicates on a widget.listbox.row that a new line follows while still rendering the same column.

__index​

(field) __index: core.object

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

animations​

(field) animations: widget.animation[]

background_color​

(field) background_color: renderer.color

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

border​

(field) border: widget.border

Represents the border of a widget.

captured_widget​

(field) captured_widget: widget

Widget that captured mouse events

child_active​

(field) child_active: widget|nil

A base widget

childs​

(field) childs: table<integer, widget>

clickable​

(field) clickable: boolean

columns​

(field) columns: widget.listbox.column[]

context​

(field) context: 'application'|'session'

current_scale​

(field) current_scale: number

cursor​

(field) cursor: 'arrow'|'hand'|'ibeam'|'sizeh'|'sizev'

defer_draw​

(field) defer_draw: boolean

draggable​

(field) draggable: boolean

dragged​

(field) dragged: boolean

expand​

(field) expand: boolean

explicit_update​

(field) explicit_update: boolean

font​

(field) font: string|renderer.font|widget.fontreference

Represents a reference to a font stored elsewhere.

force_events​

(field) force_events: table

foreground_color​

(field) foreground_color: renderer.color

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

h_scrollbar​

(field) h_scrollbar: widget.scrollbar

has_focus​

(field) has_focus: boolean

hovered_row​

(field) hovered_row: integer

hovered_scrollbar​

(field) hovered_scrollbar: boolean

input_text​

(field) input_text: boolean

is_scrolling​

(field) is_scrolling: boolean

label​

(field) label: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>

largest_row​

(field) largest_row: integer

last_offset​

(field) last_offset: integer

mouse​

(field) mouse: widget.position

Represents the position of a widget.

mouse_is_hovering​

(field) mouse_is_hovering: boolean

mouse_is_pressed​

(field) mouse_is_pressed: boolean

mouse_pressed_outside​

(field) mouse_pressed_outside: boolean

name​

(field) name: string

next_zindex​

(field) next_zindex: integer

parent​

(field) parent: widget|nil

A base widget

perform_update_size_position​

(field) perform_update_size_position: boolean

position​

(field) position: widget.position

Represents the position of a widget.

positions​

(field) positions: table<integer, integer>[]

prev_height​

(field) prev_height: number?

prev_size​

(field) prev_size: widget.position

Represents the position of a widget.

prev_view​

(field) prev_view: unknown

prev_width​

(field) prev_width: number?

render_background​

(field) render_background: boolean

row_data​

(field) row_data: any

row_data_original​

(field) row_data_original: any

rows​

(field) rows: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>[]

rows_idx_original​

(field) rows_idx_original: table

rows_original​

(field) rows_original: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>[]

scroll​

(field) scroll: core.view.scroll

scrollable​

(field) scrollable: boolean

selected_row​

(field) selected_row: integer

set_focus​

(field) set_focus: any

size​

(field) size: widget.position

Modifying this property directly is not advised, use set_size() instead.

skip_scroll_ctrl​

(field) skip_scroll_ctrl: boolean

By default is set to true to allow ctrl+wheel or cmd+wheel on mac to scale the interface, you can set it to false on your parent widget to allow manually intercepting ctrl+wheel.

super​

(field) super: widget

A base widget

textview​

(field) textview: widget

A base widget

tooltip​

(field) tooltip: (string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>)?

tooltip_command​

(field) tooltip_command: string?

type_name​

(field) type_name: string

updated​

(field) updated: boolean

v_scrollbar​

(field) v_scrollbar: widget.scrollbar

visible​

(field) visible: boolean

visible_rendered​

(field) visible_rendered: boolean

visible_rows​

(field) visible_rows: table<integer, integer>

zindex​

(field) zindex: integer

widget.listbox.colpos​

widget.listbox.column​

expand​

(field) expand: boolean

longest​

(field) longest: integer

name​

(field) name: string

width​

(field) width: string

widget.listbox.drawcol​

widget.listbox.filtercb​

widget.listbox.row​

from_state​

function core.view.from_state(state: table)
  -> view: (core.view)?

Create and initialize a new view instance from a previously saved state.

This function is called when restoring workspace/session state. Implementations are responsible for:

  • creating the view instance
  • applying any persisted state

If loading the instance failed nil will be returned.

override_rootview​

function widget.override_rootview()

Called when initializing a floating widget to generate RootView overrides, this function will only override the events once.

__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) widget:__tostring()
  -> string

Useful for debugging.

activate​

(method) widget:activate()

Emitted to input_text widgets when clicked.

add_child​

(method) widget:add_child(child: widget)

Add a child widget, automatically assign a zindex if non set and sorts them in reverse order for better events matching.

add_column​

(method) widget.listbox:add_column(name: string, width?: number, expand?: boolean)

If no width is given column will be set to automatically expand depending on the longest element

add_row​

(method) widget.listbox:add_row(row: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>, data: any)

You can give it a table a la statusview style where you pass elements like fonts, colors, ListBox.COLEND, ListBox.NEWLINE and multiline strings.

@param data — Associated with the row and given to on_row_click()

animate​

(method) widget:animate(target?: table, properties: table<string, number>, options?: widget.animation.options)

Registers a new animation to be ran on the update cycle.

@param target — If nil assumes properties belong to widget it self.

calc_row_size_pos​

(method) widget.listbox:calc_row_size_pos(ridx: integer)

Calculate a row position and size and store it on the row it self on the fields x, y, w, h

capture_mouse​

(method) widget:capture_mouse(scrolling?: boolean)

All mouse events will be directly sent to the widget even if mouse moves outside the widget region.

@param scrolling — Capture for scrolling

centered​

(method) widget:centered()

Center the widget horizontally and vertically to the screen or parent widget.

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.

clear​

(method) widget.listbox:clear()

Remove all the rows from the listbox.

deactivate​

(method) widget:deactivate()

Emitted to input_text widgets on lost focus.

destroy​

(method) widget:destroy()

If floating, remove the widget from the floating widgets list to allow proper garbage collection.

destroy_childs​

(method) widget:destroy_childs()

Recursively destroy all childs from the widget.

drag​

(method) widget:drag(x: number, y: number)

Used internally when dragging is activated.

draw​

(method) widget.listbox:draw()
  -> boolean

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_border​

(method) widget:draw_border(x?: number, y?: number, w?: number, h?: number)

Draw the widget configured border or custom one.

draw_header​

(method) widget.listbox:draw_header(w: integer, h: integer, ox: number)

Draw the column headers of the list if available

@param ox — Horizontal offset

draw_row​

(method) widget.listbox:draw_row(row: integer, x: integer, y: integer, only_calc?: boolean)
  -> width: integer
  2. height: integer

Draw or calculate the dimensions of the given row position and stores the size and position on the row it self.

draw_row_range​

(method) widget.listbox:draw_row_range(ridx: integer, row: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>, start_idx: integer, end_idx: integer, x: integer, y: integer, only_calc: boolean)
  -> width: integer
  2. height: integer

Render or calculate the size of the specified range of elements in a row.

draw_scrollbar​

(method) widget:draw_scrollbar()

draw_styled_text​

(method) widget:draw_styled_text(text: table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>, x: integer, y: integer, only_calc?: boolean, start_idx?: integer, end_idx?: integer)
  -> width: integer
  2. height: integer

Render or calculate the size of the specified range of elements in a styled text elemet.

draw_text_multiline​

(method) widget:draw_text_multiline(font: string|renderer.font|widget.fontreference, text: string, x: integer, y: integer, color: renderer.color, only_calc: boolean)
  -> resx: integer
  2. resy: integer
  3. width: integer
  4. height: integer

Taken from the logview and modified it a tiny bit. TODO: something similar should be on pragtical core.

enable_expand​

(method) widget.listbox:enable_expand(expand: any)

Enables expanding the element to total size of parent on content updates.

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

filter​

(method) widget.listbox:filter(match?: string|fun(self: widget.listbox, idx: integer, row: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>, data: any):number?)

Set which rows to show using the specified match string or callback, if nil all rows are restored.

force_event​

(method) widget:force_event(name: "mouse_released", force: boolean)

Toggle the forced interception of given event even if all the conditions for emitting it are not met.

Note: only "mouse_released" is implemented for the moment on floating views for use in the SelectBox, maybe a better system can be implemented on the future.

@param force — If omitted is set to true by default

name:
    | "mouse_released"

get_bottom​

(method) widget:get_bottom()
  -> number

Get the bottom y coordinate relative to parent

get_col_positions​

(method) widget.listbox:get_col_positions(row: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>)
  -> table<integer, integer>

Get the starting and ending position of columns in a row table.

get_col_width​

(method) widget.listbox:get_col_width(col: integer)
  -> number

Calculate the overall width of a column.

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_font​

(method) widget:get_font(font?: string|renderer.font|widget.fontreference)
  -> renderer.font

Get the real renderer.font associated with a widget.font.

get_h_scrollable_size​

(method) widget.listbox:get_h_scrollable_size()
  -> number

get_height​

(method) widget:get_height()
  -> number

Get height including borders.

get_module​

(method) core.view:get_module()
  -> path: string?

Returns the module path of this view.

This method resolves the Lua module name that loaded the concrete view class (for example "core.view").

If the view class cannot be associated with any loaded module, nil is returned.

get_name​

(method) widget:get_name()
  -> string

The name that is displayed on pragtical tabs.

get_position​

(method) widget:get_position()
  -> widget.position

Get the relative position in relation to parent

get_real_height​

(method) widget:get_real_height()
  -> number

Overall height of the widget accounting all visible child widgets.

get_real_width​

(method) widget:get_real_width()
  -> number

Overall width of the widget accounting all visible child widgets.

get_right​

(method) widget:get_right()
  -> number

Get the right x coordinate relative to parent

get_row_at_position​

(method) widget.listbox:get_row_at_position(x: number, y: number)
  -> integer?

Get the row at a screen position.

get_row_data​

(method) widget.listbox:get_row_data(idx: integer)
  -> any

Get the data associated with a row.

get_row_text​

(method) widget.listbox:get_row_text(row: integer|table)
  -> string

Get the text only of a styled row.

get_scrollable_size​

(method) widget.listbox:get_scrollable_size()
  -> number

Calculates the scrollable size based on the last row of the list.

get_selected​

(method) widget.listbox:get_selected()
  -> integer|nil

Get the row that is currently active/selected.

get_size​

(method) widget:get_size()
  -> widget.position

get_state​

(method) core.view:get_state()
  -> state: table?

Serialize this view into a persistable state table.

This method is called when the editor is saving workspace/session state. The returned table must contain only plain Lua data (no functions, userdata, metatables, or cyclic references).

Returning nil indicates that this view should NOT be restored when reloading the workspace.

get_width​

(method) widget:get_width()
  -> number

Get width including borders.

hide​

(method) widget:hide()

Hide the widget.

hide_animated​

(method) widget:hide_animated(lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Perform an animated hide.

@param lock_x — Do not resize width while animating

@param lock_y — Do not resize height while animating

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

is_visible​

(method) widget:is_visible()
  -> boolean

Check if the widget is visible also recursing to the parent visibility.

mouse_on_top​

(method) widget:mouse_on_top(x: number, y: number)
  -> boolean

Check if the given mouse coordinate is hovering the widget

move_row_down​

(method) widget.listbox:move_row_down(idx: integer)
  -> moved: boolean

Move a row one position down if possible.

move_row_to​

(method) widget.listbox:move_row_to(idx: integer, pos: integer)
  -> moved: boolean

Move a row to the desired position if possible.

move_row_up​

(method) widget.listbox:move_row_up(idx: integer)
  -> moved: boolean

Move a row one position up if possible.

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) widget.listbox:new(parent: widget)

Constructor

on_change​

(method) widget:on_change(value: any)

Event emitted when the value of the widget changes. If applicable, child widgets should call this method when its value changes.

on_click​

(method) widget.listbox:on_click(button: "left"|"right", x: number, y: number)

on_file_dropped​

(method) widget:on_file_dropped(filename: string, x: number, y: number)
  -> processed: boolean

Send file drop event to hovered child.

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_enter​

(method) widget:on_mouse_enter(x: any, y: any, dx: any, dy: any)

Emitted once when the mouse hovers the widget.

on_mouse_leave​

(method) widget.listbox:on_mouse_leave(x: any, y: any, dx: any, dy: any)

on_mouse_left​

(method) widget:on_mouse_left()

on_mouse_moved​

(method) widget.listbox:on_mouse_moved(x: number, y: number, dx: number, dy: number)

on_mouse_pressed​

(method) widget.listbox:on_mouse_pressed(button: "left"|"right", x: number, y: number, clicks: integer)
  -> boolean

on_mouse_released​

(method) widget:on_mouse_released(button: "left"|"right", x: number, y: number)
  -> processed: boolean

Send mouse released events to hovered child, ends dragging if enabled and emits on click events if applicable.

button:
    | "left"
    | "right"

on_mouse_wheel​

(method) widget:on_mouse_wheel(y: number, x: number)
  -> boolean

on_row_click​

(method) widget.listbox:on_row_click(idx: integer, data: any)

You can overwrite this to listen to item clicks

@param data — Data associated with the row

on_scale_change​

(method) widget.listbox:on_scale_change(new_scale: number, prev_scale: number)

on_text_input​

(method) widget:on_text_input(text: string)
  -> processed: boolean

Redirects any text input to active child with the input_text flag.

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

recalc_all_rows​

(method) widget.listbox:recalc_all_rows()

Recalculate all row sizes and positions which should be only required when pragtical ui scale changes or a row is removed from the list

release_mouse​

(method) widget:release_mouse()

Undo capture_mouse()

remove_child​

(method) widget:remove_child(child: widget)

Remove a child widget.

remove_row​

(method) widget.listbox:remove_row(ridx: integer)

Remove a given row index from the list.

resize_to_parent​

(method) widget.listbox:resize_to_parent()

Resizes the listbox to match the parent size

run_animations​

(method) widget:run_animations()

Runs all registered animations removing duplicated and finished ones.

schedule_update​

(method) widget:schedule_update(delayed: any)

Schedule a core update and redraw. Since widgets try to not fire updates and draws to child widgets to reduce cpu consumption this function can be used when a re-update and re-draw is strictly needed.

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

set_border_width​

(method) widget:set_border_width(width: integer)

Set the widget border size and appropriately re-set the widget size.

set_label​

(method) widget:set_label(text: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>)

A text label for the widget, not all widgets support this.

set_position​

(method) widget:set_position(x?: integer, y?: integer)

Set the position of the widget and updates the child absolute coordinates

set_row​

(method) widget.listbox:set_row(idx: integer, row: table<integer, string|integer|fun(self: any, row: any, x: any, y: any, font: any, color: any, only_calc: any)|renderer.color|renderer.font...(+2)>)

Change the content assigned to a row.

set_row_data​

(method) widget.listbox:set_row_data(idx: integer, data: any)

Change the data assigned to a row.

set_selected​

(method) widget.listbox:set_selected(idx?: integer)

Set the row that is currently active/selected.

set_size​

(method) widget:set_size(width?: integer, height?: integer)

set_target_size​

(method) widget:set_target_size(axis: string|'x'|'y', value: number)
  -> boolean

Called by pragtical node system to properly resize the widget.

axis:
    | 'x'
    | 'y'

set_tooltip​

(method) widget:set_tooltip(tooltip?: string|table<integer, string|integer|renderer.color|renderer.font|widget.colorreference...(+1)>, command?: string)

Text displayed when the widget is hovered. If a command name is also given its associated binding will be displayed as part of the tooltip.

set_visible_rows​

(method) widget.listbox:set_visible_rows()

Detects the rows that are visible each time the content is scrolled, this way the draw function will only process the visible rows.

show​

(method) widget:show()

Show the widget.

show_animated​

(method) widget:show_animated(lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Perform an animated show.

@param lock_x — Do not resize width while animating

@param lock_y — Do not resize height while animating

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.

swap_active_child​

(method) widget:swap_active_child(child?: widget)

Replaces current active child with a new one and calls the activate/deactivate events of the child. This is especially used to send text input events to widgets with input_text support.

@param child — If nil deactivates current child

toggle_background​

(method) widget:toggle_background(enable?: boolean)

When set to false the background rendering is disabled.

toggle_visible​

(method) widget:toggle_visible(animated?: boolean, lock_x?: boolean, lock_y?: boolean, options?: widget.animation.options)

Toggle visibility of widget.

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) widget.listbox:update()
  -> boolean

update_if_scaled​

(method) widget:update_if_scaled()

Explicitly call the widget update procedure when the scale change even if the widget is not visible.

update_position​

(method) widget:update_position()

Called on the update function to be able to scroll the child widgets.

update_scrollbar​

(method) core.view:update_scrollbar()

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

update_size_position​

(method) widget:update_size_position()

Similar to update, but here you should perform expensive calculations that will get executed for a predefined period of time when a widget is initialized, scale has changed or a widget switched from hidden to visible.