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​

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_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_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_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:on_mouse_pressed(button: "left"|"right", x: number, y: number, clicks: integer)
  -> processed: boolean

Send mouse pressed events to hovered child or starts dragging if enabled.

button:
    | "left"
    | "right"

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.