win.listWindow - WIN

Class listWindow
Inherits from window.

The listWindow class provides a single selection vertical list of strings. Its colors are initialized from the theme but may be customized after creation. The list's vertical scrolling is automatically handled but any strings exceeding the width are clipped. The scroll width of the control may be manually set, ensuring the scroll height is preserved.

The following events are sent to the parent with a first parameter of the list window object:
selection_change When the current selection changes, by any means.
list_click When a list item is left clicked/touched/enter key pressed while active.
list_double_click When a list item is left clicked/touched/enter key pressed within the theme's double_click time of os.clock () on the same character.
A list_click is not sent if list_double_click is, but the list_double_click will be preceded with a list_click.

To create a listWindow use it's new method:
local lst = win.listWindow:new (parent, id, x, y, width, height)


Properties

list__click_time number Records click time for double click.
list__click_x number Records x coordinate for double click.
list__click_y number Records y coordinate for double click.
list__colors table Color table.
list__colors.back number Blurred background color.
list__colors.focus number Focused background color.
list__colors.selected_back number Background color of selected item.
list__colors.selected_text number Text color of selected item.
list__colors.text number Text color.
list__items table Table of items.
list__sel_index number Holds the last selected item's index.

Methods

See also API Reference, WIN.

local list_sorter_ascending

result list_sorter_ascending (string1, string2)

Helper function to sort the list of strings.

Parameters
string1 string
First string to test.
string2 string Second string to test.

Returns
result boolean
True if string1 is before string2.

Remarks
Used internally.


top


local list_sorter_descending

result list_sorter_descending (string1, string2)

Helper function to sort the list of strings.

Parameters
string1 string First string to test.
string2 string

Returns
result boolean True if string1 is before string2.

Remarks
Used internally.


top


win.listWindow:add_string

listWindow:add_string (str, data, index)

Inserts an item (string) into the list.

Parameters
str string The string to display in the list.
data any Any custom object/value associated with the list entry.
index number/nil 1 based index to insert the item. If nil or out of range the item is added to the end of the list.

Returns
none


Remarks
Scroll sizing and invalidation is handled.

See listWindow:remove_string.


top


win.listWindow:constructor

list listWindow:constructor (parent, id, x, y, width, height)

Constructs and returns the instantiated list window.

Parameters
parent window Parent window, typically a frame.
id number Numeric id value for list window.
x number Parent relative x position.
y number Parent relative y position.
width number List window's width.
height number List window's height.

Returns
list listWindow The instantiated list window.

Remarks


top


win.listWindow:count

count listWindow:count ()

Returns the count of items (strings) in the list.

Parameters
none


Returns
count number The count of items in the list control.

Remarks


top


win.listWindow:draw

listWindow:draw (gdi, bounds)

Draws the list control.

Parameters
gdi GDI GDI object to use for drawing.
bounds rect Invalidated area of the window.

Returns
none


Remarks
See window:draw.


top


win.listWindow:ensure_visible

listWindow:ensure_visible (index)

Adjusts the scrolling to bring the item at the given index into view, if needed.

Parameters
index number 1 based item index to ensure is visible. If nil the currently selected item is used.

Returns
none


Remarks
Invalidation is handled.


top


win.listWindow:find

index listWindow:find (str, from, exact)

Finds the next item in the list which matches the string.

Parameters
str string The string to search for.
from number/nil The 1 based index to search after. Zero or nil searches from the beginning.
exact boolean If true the string must match exactly, otherwise a match if the start of the string is the same.

Returns
index number The 1 based index of the item found, or zero if none.

Remarks


top


win.listWindow:get_cur_sel

index listWindow:get_cur_sel ()

Returns the index of the currently selected list item.

Parameters
none


Returns
index number The 1 based index of the currently selected list item, or zero if none.

Remarks
See listWindow:set_cur_sel.


top


win.listWindow:get_data

data listWindow:get_data (index)

Returns the data of the item at the given index.

Parameters
index number/nil The 1 based index of the item. If nil or omitted the currently selected item is used, if any.

Returns
data any The item's data, or nil if index is out of range.

Remarks
See listWindow:set_data, listWindow:get_string.


top


win.listWindow:get_string

str listWindow:get_string (index)

Returns the string of the item at the given index.

Parameters
index number/nil The 1 based index of the item. If nil or omitted the currently selected item is used, if any.

Returns
str string/nil The item's string, or nil if index is out of range.

Remarks
See listWindow:set_string, listWindow:get_data.


top


win.listWindow:on_blur

result listWindow:on_blur (focused)

Sets blurred background color.

Parameters
focused window The window gaining focus, it may be nil.

Returns
result boolean Always false.

Remarks
See window:on_blur.


top


win.listWindow:on_focus

result listWindow:on_focus (blurred)

Sets focused background color.

Parameters
blurred window The window losing focus, it may be nil.

Returns
result boolean Always false.

Remarks
See window:on_focus.


top


win.listWindow:on_key

result listWindow:on_key (key, ctrl, alt, shift)

Handles key events; up, down, page up, page down, home, end, ctrl+up, ctrl+down, ctrl+left, ctrl+right, ctrl+page up, ctrl+page down, ctrl+home, ctrl+end and sends a list_click or list_double_click event to the parent window on enter.

Parameters
key number Key code.
ctrl boolean True if control key is depressed.
alt boolean True if alternate key is depressed.
shift boolean True if shift key is depressed.

Returns
result boolean True if key was handled, false if not.

Remarks
See window:on_key.


top


win.listWindow:on_left_click

result listWindow:on_left_click (x, y, count)

Calls the base implementation, sets the selected item at the click point, and sends list_click and list_double_click events to parent.

Parameters
x number Window relative x position.
y number Window relative y position.
count number The number of times this same position was repeatedly clicked, with each successive click within the double_click_time.

Returns
result boolean Always true.

Remarks
See window:on_left_click.


top


win.listWindow:on_touch

result listWindow:on_touch (x, y)

Calls the base implementation, sets the selected item at the touch point, and sends list_click and list_double_click events to parent.

Parameters
x number Window relative x position.
y number Window relative y position.

Returns
result boolean Always true.

Remarks

See window:on_touch.

top


win.listWindow:remove_string

result listWindow:remove_string (index)

Removes the item at the given index from the list.

Parameters
index number 1 based index of the item to remove.

Returns
result boolean True if successfully removed, or false otherwise (index is out of range).

Remarks
Scroll sizing and invalidation is handled.

See listWindow:add_string.


top


win.listWindow:reset_content

listWindow:reset_content ()

Removes all items from the list.

Parameters
none


Returns
none


Remarks
Scroll sizing and invalidation is handled.


top


win.listWindow:set_colors

listWindow:set_colors (text, background, focus, selected_text, selected_back)

Sets the colors for the list control.

Parameters
text number Text color.
background number Blurred background color.
focus number Focused background color.
selected_text number Text color of selected item.
selected_back number Background color of selected item.

Returns
none


Remarks
The window is invalidated.


top


win.listWindow:set_cur_sel

changed listWindow:set_cur_sel (index, make_visible)

Sets the currently selected item in the list to the index given (1 based).

Parameters
index number 1 based index of the item to select. Zero or nil for no selection.
make_visible boolean If true or nil scrolling is adjusted to bring the selected item into view if needed.

Returns
changed boolean True if the current selection changed, false if not.

Remarks
If index is greater than the number of items in the list the last one is selected.

If the selection changed a selection_change event is sent to the parent.

Invalidation is handled.

See listWindow:get_cur_sel.


top


win.listWindow:set_data

result listWindow:set_data (data, index)

Sets the data value for the item.

Parameters
data any The data value to set.
index number/nil The 1 based index of the item to set. If nil the currently selected item is used, if any.

Returns
result boolean True if the item was successfully set, false if not.

Remarks
See listWindow:get_data, listWindow:set_string.


top


win.listWindow:set_string

result listWindow:set_string (str, index)

Sets the string for the item.

Parameters
str string The string value to set.
index number/nil The 1 based index of the item to set. If nil the currently selected item is used, if any.

Returns
result boolean True if the item was successfully set, false if not.

Remarks
See listWindow:get_string, listWindow:set_data.


top


win.listWindow:sort

listWindow:sort (descending)

Sorts the items (strings) in the list.

Parameters
descending boolean If true the sort is descending, otherwise ascending.

Returns
none


Remarks
Invalidation is handled.

See list_sorter_ascending, list_sorter_descending.


top


See also API Reference, WIN.