# ListBox

    __init__(
        self,
        master,
        items=None,
        selected=None,
        command=None,
        grid=None,
        align=None,
        visible=True,
        enabled=None,
        multiselect=False,
        scrollbar=False,
        width=None,
        height=None)

### What is it?

The `ListBox` object displays a list of items from which either single or multiple items can be selected.

### How do I make one?

Create a `ListBox` object like this:

    from guizero import App, ListBox
    app = App()
    listbox = ListBox(app, items=["Beef", "Chicken", "Fish", "Vegetarian"])
    app.display()

### Starting parameters

When you create a `ListBox` object you must specify `master` and you can specify any of the optional parameters. Specify parameters in the brackets, like this: `listbox = ListBox(app, items=["Beef", "Chicken", "Fish", "Vegetarian"])`

If you want the `ListBox` to allow multiple items to be selected you must set the `multiselect` optional parameter to `True`: `listbox = ListBox(app, multiselect=True)`

Parameter | Takes | Default | Compulsory | Description
--- | --- | --- | --- | ---
master | App, Window or Box | - | Yes | The container to which this widget belongs
selected | string or List | None | No | The item or items to select by default
items | List | - | Yes | A list of items to display
align | string | None | - | Alignment of this widget within its container. Possible values: `"top"`, `"bottom"`, `"left"`, `"right"`.
command | function name | None | - | The name of a function to call when a different option is selected. This function MUST take either zero or one argument, if the function takes one argument the current value of the ListBox will be given.
grid | List [int, int] | None | - | `[x,y]` coordinates of this widget. This parameter is only required if the `master` object has a grid layout.
visible | boolean | True | No | If the widget should be visible.
enabled | boolean | None | No | If the widget should be enabled. If `None` (the default) the enabled property will be inherited from the master
multiselect | boolean | False | No | If the widget should allow multiple items to be selected.
scrollbar | boolean | False | No | If the widget should have a verticle scrollbar.
width | size | None | No | Set the width of the widget in pixels or to `"fill"`
height | size | None | No | Set the height of the widget in pixels or to `"fill"`

### Methods

You can call the following methods on a `ListBox` object.

Method | Takes | Returns | Description
--- | --- | --- | ---
after(time, command, args=None) | time (int), command (function name), args (list of arguments) | - | Schedules a single call to `command` after `time` milliseconds. (To repeatedly call the same command, use `repeat()`)
append(item) | item (string) | - | Appends a new `item` to the end of the ListBox.
cancel(command) | command (function name) | - | Cancels a scheduled call to `command`
clear() | - | - | Clears all the items in a ListBox
destroy() | - | - | Destroys the widget
disable() | - | - | Disables the widget so that it is "greyed out" and cannot be interacted with
enable() | - | - | Enables the widget
focus() | - | - | Gives focus to the widget
hide() | - | - | Hides the widget from view. This method will unpack the widget from the layout manager.
insert(index, item) | index (int), item (string) | - | Insert a new `item` in the ListBox at `index`
remove(item) | item (string) | Boolean | Removes the first `item` from the ListBox. Returns `True` if an item was removed.
repeat(time, command, args=None) | time (int), command (function name), args (list of arguments) | - | Repeats `command` every `time` milliseconds. This is useful for scheduling a function to be regularly called, for example updating a value read from a sensor.
resize(width, height) | width (int), height (int) | - | Sets the width and height of the widget
show() | - | - | Displays the widget if it was previously hidden
update_command(command) | command (function name) | - | Updates the function to call when a different option is selected.

### Properties

You can set and get the following properties:

Method | Data type | Description
--- | --- | ---
align | string | The alignment of this widget within its container
bg | color | The background colour of the widget
children | List | A list of the widgets in this container. `[ListBoxWidget, ListBoxScrollbar]`
enabled | boolean | `True` if the widget is enabled
font | string | The font of the text
grid | List | `[x,y]` coordinates of this widget. This parameter is only required if the `master` object has a grid
height | size | Set the height of the widget in pixels or to `"fill"`
items | List | Returns a list of items in the ListBox
master | App or Box | The container to which this widget belongs
value | string | Sets or returns the items selected in a ListBox. Returns `None` if 0 items are selected. If the ListBox is a not `multiselect`, `value` is the item selected, if the ListBox is a `multiselect`, `value` is a list of items selected.
visible | boolean | If this widget is visible
width | size | Set the width of the widget in pixels or to `"fill"`
text_size | int | The size of the text
text_color | color | The colour of the text
tk | tkinter.Frame | The internal tkinter object, see Using tkinter

Refer to a property as `<name of widget>.property`. For example, if your `ListBox` object is called `listbox` you would write `listbox.value`.

You can set the property (for example `listbox.value = "Chicken"`) or get the value of the property to use (for example `print(listbox.value)`).

### Examples

** Select a text color from a ListBox **

When an item in the ListBox is selected a function will be called to change the color of the text.

    from guizero import App, ListBox, Text

    def change_color(value):
        t.text_color = value

    a = App()

    t = Text(a, text="Its a ListBox", color="black")

    listbox = ListBox(
        a,
        items=["red", "green", "blue", "yellow", "purple", "turquoise", "pink", "orange", "black", "brown", "cyan"],
        selected="black",
        command=change_color,
        scrollbar=True)

    a.display()

### Using ListBox tk widgets

Advanced users can gain internal access to the internal tkinter widgets used by `ListBox`. For more information on using tkinter in combination with guizero see Using tkinter.

The `ListBox` widget contains a `tkinter.Frame` object, which frames 2 other child guizero widgets containing `tkinter.Listbox` and `tkinter.Scrollbar` objects.

The `.children` property returns a list of these widgets:

.children index | guizero class | tk class | notes
--- | --- | --- | ---
0 | `ListBoxWidget` | `tkinter.Listbox` |
1 | `ListBoxScrollbar` | `tkinter.Scrollbar` | A `ListBoxScrollbar` widget will only be present if `ListBox.scrollbar` is set to `True`.

To access the internal tk object for these child guizero widgets you would use its `tk` property e.g.

    listbox = listBox(app)

    tk_listbox = listbox.children[0].tk
    tk_scrollbar = listbox.children[1].tk