NAME

UI::Various::Listbox - general listbox widget of UI::Various

SYNOPSIS

    use UI::Various;
    my $main = UI::Various::main();
    my @variable = ('1st', '2nd', '3rd');
    $main->window(...
                  UI::Various::Listbox->new(height => 5,
                                            selection => 2,
                                            texts => \@variable),
                  ...);
    $main->mainloop();

ABSTRACT

This module defines the general listbox widget of an application using UI::Various.

DESCRIPTION

Besides the common attributes inherited from UI::Various::widget the Listbox widget knows the following additional attributes:

Attributes

first [ro]

the index of the first element to be shown

The last element shown will have the index first + height - 1, if texts is long enough.

height [rw, fixed]

the height of the listbox is the maximum number of elements shown

Other then in other UI elements it is a mandatory parameter. Note the the *Term UIs use one additional line for the position information at the top of the listbox.

on_select [rw, optional]

an optional callback called after changing the selection

Note that the callback routine is called without parameters. If you need to access the current selection, use the method selected. Also note that when a user drags a selection in Tk the callback is called for each and every change, not only for the final one after releasing the mouse button.

selection [rw, fixed, recommended]

the selection type of the listbox, a number between 0 and 2, defaults to 2:

0 - the elements are not selectable

1 - only single selection

2 - multiple selection is possible

Note that changing the value after displaying the listbox will not work without recreating its container.

texts [rw, fixed, recommended]

the texts of the elements of the listbox as strings

The default is an empty list.

Note that the content of the list may only be modified with the methods provided by Listbox (add and remove). The only exception is when the listbox did not yet contain any element.

METHODS

Besides the accessors (attributes) described above and by UI::Various::widget and the methods inherited from UI::Various::widget only the constructor is provided by the Listbox class itself:

new - constructor

see UI::Various::core::construct

add - add new element

    $listbox->add($text, ...);

example:

    $self->add('one more');
    $self->add('one more', 'still one more');

parameters:

    $text               another text to be added to the end of the listbox

description:

This method adds one or more new elements at the end of the listbox.

modify - modify element

    $listbox->modify($index, $value);

example:

    $self->modify(2, 'new value');

parameters:

    $index              the index of the element to be modified
    $value              the new value for the element

description:

This method modifies an element in the listbox by replacing its value. The element is identified by its index. Indices start with 0.

remove - remove element

    $listbox->remove($index);

example:

    $self->remove(2);

parameters:

    $index              the index of the element to be removed from the listbox

description:

This method removes an element from the listbox. The element to be removed is identified by its index. Indices start with 0.

replace - replace all elements

    $listbox->replace(@new_elements);

example:

    $self->replace('one new entry', 'another new entry');

parameters:

    $text               list of texts to replace original entries

description:

This method replaces all elements in the listbox and removes all selections.

selected - get current selection of listbox

    $selection = $listbox->selected();  # C<selection =E<gt> 1>
    @selection = $listbox->selected();  # C<selection =E<gt> 2>

description:

This method returns the sorted indices of the currently selected element(s) of the listbox. Indices start with 0. If there is nothing selected at all, the method returns undef for selection => 1 and an empty list for selection => 2.

returns:

selected element(s) (or undef for selection => 0)

SEE ALSO

UI::Various

LICENSE

Copyright (C) Thomas Dorner.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See LICENSE file for more details.

AUTHOR

Thomas Dorner <dorner (at) cpan (dot) org>

cpanm UI::Various

perl -MCPAN -e shell
install UI::Various