Skip to main content

widget.treelist

local treelist = require "widget.treelist"

NEWLINE

(field) NEWLINE: integer

Indicates on a widget.styledtext that a new line follows.


__index

(field) __index: core.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

context

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

count_lines

(field) count_lines: integer

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

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_item

(field) hovered_item: (widget.treelist.item)?

hovered_scrollbar

(field) hovered_scrollbar: boolean

icon_font

(field) icon_font: (renderer.font)?

init_size

(field) init_size: boolean

input_text

(field) input_text: boolean

is_scrolling

(field) is_scrolling: boolean

item_icon_width

(field) item_icon_width: number

item_text_spacing

(field) item_text_spacing: number

items

(field) items: widget.treelist.item[]

label

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

last_scroll_y

(field) last_scroll_y: number

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.


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

scroll

(field) scroll: core.view.scroll

scroll_width

(field) scroll_width: integer

scrollable

(field) scrollable: boolean

selected_item

(field) selected_item: (widget.treelist.item)?

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: table

tooltip_command

(field) tooltip_command: string?

type_name

(field) type_name: string

v_scrollbar

(field) v_scrollbar: widget.scrollbar

visible

(field) visible: boolean

zindex

(field) zindex: integer

widget.treelist.item

childs

(field) childs: widget.treelist.item[]?

data

(field) data: any

depth

(field) depth: integer?

expanded

(field) expanded: boolean?

icon

(field) icon: string?

label

(field) label: string

name

(field) name: string

parent

(field) parent: widget.treelist.item[]?

tooltip

(field) tooltip: string?

visible

(field) visible: boolean?

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)
-> core.object

Metamethod to allow using the object call as a constructor.


__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_item

(method) widget.treelist:add_item(item: widget.treelist.item)

Add new item to to tree list


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.


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()

clear

(method) widget.treelist:clear()

Remove all items from the tree


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.treelist:draw()

draw_background

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

draw_border

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

Draw the widget configured border or custom one.


draw_item

(method) widget.treelist:draw_item(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)
-> number
2. number
3. number
4. number

draw_item_background

(method) widget.treelist:draw_item_background(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)

draw_item_body

(method) widget.treelist:draw_item_body(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)
-> number
2. number
3. number
4. number

draw_item_chevron

(method) widget.treelist:draw_item_chevron(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)
-> number

draw_item_icon

(method) widget.treelist:draw_item_icon(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)
-> number

draw_item_text

(method) widget.treelist:draw_item_text(item: widget.treelist.item, active: boolean, hovered: boolean, x: number, y: number, w: number, h: number)
-> number
2. number
3. number
4. number

draw_scrollbar

(method) widget:draw_scrollbar()

draw_styled_text

(method) widget:draw_styled_text(text: table<integer, string|integer|renderer.color|renderer.font|widget.fontreference>, 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.


draw_tooltip

(method) widget.treelist:draw_tooltip()

each_item

(method) widget.treelist:each_item()
-> fun():widget.treelist.item, number, number, number, number

Allows iterating the currently visible items only.


extend

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

extends

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

Check if the object inherits from the given type.


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_chevron_position

(method) widget.treelist:get_chevron_position(item: any)
-> x1: number
2. x2: number

Get an item chevron starting and ending positions.


get_content_bounds

(method) core.view:get_content_bounds()
-> number
2. number
3. number
4. number

get_content_offset

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

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.treelist:get_h_scrollable_size()
-> number

get_height

(method) widget:get_height()
-> number

Get height including borders.


get_item

(method) widget.treelist:get_item(item?: widget.treelist.item, where: integer)
-> item: widget.treelist.item
2. x: number
3. y: number
4. w: number
5. h: number

get_item_height

(method) widget.treelist:get_item_height()
-> h: number

Get the height of a single item.


get_item_icon

(method) widget.treelist:get_item_icon(item: widget.treelist.item, active: boolean, hovered: boolean)
-> string
2. renderer.font
3. unknown

get_item_text

(method) widget.treelist:get_item_text(item: widget.treelist.item, active: boolean, hovered: boolean)
-> string
2. renderer.font
3. unknown

get_items

(method) widget.treelist:get_items(item: widget.treelist.item, x: number, y: number, w: number, h: number, depth?: number)
-> items_count: integer

Retrieve the amount of visible items and also yield them.


get_name

(method) widget:get_name()
-> string

The name that is displayed on pragtical tabs.


get_next

(method) widget.treelist:get_next(item?: widget.treelist.item)
-> item: widget.treelist.item
2. x: number
3. y: number
4. w: number
5. h: number

get_position

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

Get the relative position in relation to parent


get_previous

(method) widget.treelist:get_previous(item?: widget.treelist.item)
-> item: widget.treelist.item
2. x: number
3. y: number
4. w: number
5. h: number

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_scrollable_size

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

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)
-> boolean

Check if the object is strictly of the given type.


is_class_of

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

Check if the parameter is strictly of the object type.


is_extended_by

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

Check if the parameter inherits from the object.


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_towards

(method) core.view:move_towards(t: any, k: any, dest: any, rate: any, name: any)

new

(method) widget.treelist: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:on_click(button: "left"|"right", x: number, y: number)

Click event emitted on a succesful on_mouse_pressed and on_mouse_released events combo.

button:
| "left"
| "right"

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: any, start: any, length: any)

on_item_click

(method) widget.treelist:on_item_click(item: widget.treelist.item, button: string, x: any, y: any, clicks: integer)

Override to listen for item click events.


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:on_mouse_leave(x: any, y: any, dx: any, dy: any)

Emitted once when the mouse leaves the widget.


on_mouse_left

(method) widget.treelist:on_mouse_left()

on_mouse_moved

(method) widget.treelist:on_mouse_moved(px: number, py: number, ...any)
-> boolean

on_mouse_pressed

(method) widget.treelist: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_scale_change

(method) widget.treelist:on_scale_change()

Keep the icon font size updated to match current scale.


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)

query_item

(method) widget.treelist:query_item(query: string, items?: widget.treelist.item[], separator?: string)
-> (widget.treelist.item)?

Retrieve an item by name using the query format: "parent_name>child_name_2>child_name_2>etc..."

@param separator — Use a different separator (default: >)


release_mouse

(method) widget:release_mouse()

Undo capture_mouse()


remove_child

(method) widget:remove_child(child: widget)

Remove a child widget.


run_animations

(method) widget:run_animations()

Runs all registered animations removing duplicated and finished ones.


schedule_update

(method) widget:schedule_update()

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()
-> boolean

scrollbar_hovering

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

scrollbar_overlaps_point

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

select_next

(method) widget.treelist:select_next()

select_prev

(method) widget.treelist:select_prev()

set_border_width

(method) widget:set_border_width(width: integer)

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


set_icon_font

(method) widget.treelist:set_icon_font(font: renderer.font)

Set the icon font used to render the items icon.


set_label

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

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_selection

(method) widget.treelist:set_selection(selection: widget.treelist.item, selection_y?: number, center?: boolean, instant?: boolean)

Set the active item.


set_selection_from_path

(method) widget.treelist:set_selection_from_path(path: string, expand: boolean, scroll_to: boolean, instant: boolean)
-> table?

Sets the selection to the file with the specified path. TODO: Not tested, idea is to allow query like selections using item names by introducing a get_item/set_item methods that accepts a string query, For the moment we leave this inherited TreeView function here.

@param path — Absolute path of item to select

@param expand — Expand dirs leading to the item

@param scroll_to — Scroll to make the item visible

@param instant — Don't animate the scroll

@return — The selected item


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.fontreference>, 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.


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

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_expand

(method) widget.treelist:toggle_expand(toggle?: boolean, item?: widget.treelist.item)

Expand or collapse the currently selected or given item.


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: any)

update

(method) widget.treelist:update()

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_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.