Used for a scrolling lists of items. Replaces the list control. More...

Classes
class	XBMCAddon::xbmcgui::ControlList

Functions
	XBMCAddon::xbmcgui::ControlList::addItem (...)
	`Function: addItem(item)` Add a new item to this list control.

	XBMCAddon::xbmcgui::ControlList::addItems (...)
	`Function: addItems(items)` Adds a list of listitems or strings to this list control.

	XBMCAddon::xbmcgui::ControlList::selectItem (...)
	`Function: selectItem(item)` Select an item by index number.

	XBMCAddon::xbmcgui::ControlList::removeItem (...)
	`Function: removeItem(index)` Remove an item by index number.

	XBMCAddon::xbmcgui::ControlList::reset ()
	`Function: reset()` Clear all ListItems in this control list.

	XBMCAddon::xbmcgui::ControlList::getSpinControl ()
	`Function: getSpinControl()` Returns the associated ControlSpin object.

	XBMCAddon::xbmcgui::ControlList::getSelectedPosition ()
	`Function: getSelectedPosition()` Returns the position of the selected item as an integer.

	XBMCAddon::xbmcgui::ControlList::getSelectedItem ()
	`Function: getSelectedItem()` Returns the selected item as a ListItem object.

	XBMCAddon::xbmcgui::ControlList::setImageDimensions (...)
	`Function: setImageDimensions(imageWidth, imageHeight)` Sets the width/height of items icon or thumbnail.

	XBMCAddon::xbmcgui::ControlList::setSpace (...)
	`Function: setSpace(space)` Sets the space between items.

	XBMCAddon::xbmcgui::ControlList::setPageControlVisible (...)
	`Function: setPageControlVisible(visible)` Sets the spin control's visible/hidden state.

	XBMCAddon::xbmcgui::ControlList::size ()
	`Function: size()` Returns the total number of items in this list control as an integer.

	XBMCAddon::xbmcgui::ControlList::getItemHeight ()
	`Function: getItemHeight()` Returns the control's current item height as an integer.

	XBMCAddon::xbmcgui::ControlList::getSpace ()
	`Function: getSpace()` Returns the control's space between items as an integer.

	XBMCAddon::xbmcgui::ControlList::getListItem (...)
	`Function: getListItem(index)` Returns a given ListItem in this List.

	XBMCAddon::xbmcgui::ControlList::setStaticContent (...)
	`Function: setStaticContent(items)` Fills a static list with a list of listitems.

Detailed Description

Used for a scrolling lists of items. Replaces the list control.

`Class: ControlList(x, y, width, height[, font, textColor, buttonTexture, buttonFocusTexture, /// selectedColor, imageWidth, imageHeight, itemTextXOffset, itemTextYOffset, /// itemHeight, space, alignmentY, shadowColor])`

    The list container is one of several containers used to display items
    from file lists in various ways. The list container is very
    flexible - it's only restriction is that it is a list - i.e. a single
    column or row of items. The layout of the items is very flexible and
    is up to the skinner.

    @note This class include also all calls from \ref python_xbmcgui_control "Control"

    @param x                        integer - x coordinate of control.
    @param y                        integer - y coordinate of control.
    @param width                    integer - width of control.
    @param height                   integer - height of control.
    @param font                     [opt] string - font used for items label. (e.g. 'font13')
    @param textColor                [opt] hexstring - color of items label. (e.g. '0xFFFFFFFF')
    @param buttonTexture            [opt] string - filename for focus texture.
    @param buttonFocusTexture       [opt] string - filename for no focus texture.
    @param selectedColor            [opt] integer - x offset of label.
    @param imageWidth               [opt] integer - width of items icon or thumbnail.
    @param imageHeight              [opt] integer - height of items icon or thumbnail.
    @param itemTextXOffset          [opt] integer - x offset of items label.
    @param itemTextYOffset          [opt] integer - y offset of items label.
    @param itemHeight               [opt] integer - height of items.
    @param space                    [opt] integer - space between items.
    @param alignmentY               [opt] integer - Y-axis alignment of items label
    - \ref kodi_gui_font_alignment "Flags for alignment" used as bits to have several together:
    | Definition name   |   Bitflag  | Description                         |
    |-------------------|:----------:|:------------------------------------|
    | XBFONT_LEFT       | 0x00000000 | Align X left
    | XBFONT_RIGHT      | 0x00000001 | Align X right
    | XBFONT_CENTER_X   | 0x00000002 | Align X center
    | XBFONT_CENTER_Y   | 0x00000004 | Align Y center
    | XBFONT_TRUNCATED  | 0x00000008 | Truncated text
    | XBFONT_JUSTIFIED  | 0x00000010 | Justify text
    | XBFONT_TRUNCATED_LEFT | 0x00000020 | Truncated text from left
    @param shadowColor              [opt] hexstring - color of items
                                        label's shadow. (e.g. '0xFF000000')

    @note You can use the above as keywords for arguments and skip certain
          optional arguments.\n
          Once you use a keyword, all following arguments require the
          keyword.\n
          After you create the control, you need to add it to the window
          with addControl().


   --------------------------------------------------------------------------

    **Example:**
    ~~~~~~~~~~~~~{.py}
    ...
    self.cList = xbmcgui.ControlList(100, 250, 200, 250, 'font14', space=5)
    ...
    ~~~~~~~~~~~~~

Function Documentation

◆ addItem()

void XBMCAddon::xbmcgui::ControlList::addItem ( ... )

`Function: addItem(item)`

Add a new item to this list control.

Parameters

item	string, unicode or ListItem - item to add.

Example:

...
cList.addItem('Reboot Kodi')
...

◆ addItems()

void XBMCAddon::xbmcgui::ControlList::addItems ( ... )

`Function: addItems(items)`

Adds a list of listitems or strings to this list control.

Parameters

items List - list of strings, unicode objects or ListItems to add.

Note: You can use the above as keywords for arguments.

Large lists benefit considerably, than using the standard addItem()

Example:

...
cList.addItems(items=listitems)
...

◆ getItemHeight()

long XBMCAddon::xbmcgui::ControlList::getItemHeight ( )

`Function: getItemHeight()`

Returns the control's current item height as an integer.

Returns: Current item heigh

Example:

..
item_height = self.cList.getItemHeight()
...

◆ getListItem()

XBMCAddon::xbmcgui::ListItem * XBMCAddon::xbmcgui::ControlList::getListItem ( ... )

`Function: getListItem(index)`

Returns a given ListItem in this List.

Parameters

index integer - index number of item to return.

Returns: List item

Exceptions

ValueError if index is out of range.

Example:

...
listitem = cList.getListItem(6)
...

◆ getSelectedItem()

XBMCAddon::xbmcgui::ListItem * XBMCAddon::xbmcgui::ControlList::getSelectedItem ( )

`Function: getSelectedItem()`

Returns the selected item as a ListItem object.

Returns: The selected item

Note: Same as getSelectedPosition(), but instead of an integer a ListItem object is returned. Returns None for empty lists.
See windowexample.py on how to use this.

Example:

...
item = cList.getSelectedItem()
...

◆ getSelectedPosition()

long XBMCAddon::xbmcgui::ControlList::getSelectedPosition ( )

`Function: getSelectedPosition()`

Returns the position of the selected item as an integer.

Note: Returns -1 for empty lists.

Example:

...
pos = cList.getSelectedPosition()
...

◆ getSpace()

long XBMCAddon::xbmcgui::ControlList::getSpace ( )

`Function: getSpace()`

Returns the control's space between items as an integer.

Returns: Space between items

Example:

...
gap = self.cList.getSpace()
...

◆ getSpinControl()

Control * XBMCAddon::xbmcgui::ControlList::getSpinControl ( )

`Function: getSpinControl()`

Returns the associated ControlSpin object.

Warning: Not working completely yet
After adding this control list to a window it is not possible to change the settings of this spin control.

Example:

...
ctl = cList.getSpinControl()
...

◆ removeItem()

void XBMCAddon::xbmcgui::ControlList::removeItem ( ... )

`Function: removeItem(index)`

Remove an item by index number.

Parameters

index integer - index number of the item to remove.

v13 Python API changes: New function added.

Example:

...
cList.removeItem(12)
...

◆ reset()

void XBMCAddon::xbmcgui::ControlList::reset ( )

`Function: reset()`

Clear all ListItems in this control list.

Warning: Calling reset() will destroy any ListItem objects in the ControlList if not hold by any other class. Make sure you you don't call addItems() with the previous ListItem references after calling reset(). If you need to preserve the ListItem objects after reset() make sure you store them as members of your WindowXML class (see examples).

Examples:

...
cList.reset()
...

The below example shows you how you can reset the ControlList but this time avoiding ListItem object destruction. The example assumes self as a WindowXMLDialog instance containing a ControlList with id = 800. The class preserves the ListItem objects in a class member variable.

...
# Get all the ListItem objects in the control
self.list_control = self.getControl(800) # ControlList object
self.listitems = [self.list_control.getListItem(item) for item in range(0, self.list_control.size())]
# Reset the ControlList control
self.list_control.reset()
#
# do something with your ListItem objects here (e.g. sorting.)
# ...
#
# Add them again to the ControlList
self.list_control.addItems(self.listitems)
...

◆ selectItem()

void XBMCAddon::xbmcgui::ControlList::selectItem ( ... )

`Function: selectItem(item)`

Select an item by index number.

Parameters

item	integer - index number of the item to select.

Example:

...
cList.selectItem(12)
...

◆ setImageDimensions()

void XBMCAddon::xbmcgui::ControlList::setImageDimensions ( ... )

`Function: setImageDimensions(imageWidth, imageHeight)`

Sets the width/height of items icon or thumbnail.

Parameters

imageWidth	[opt] integer - width of items icon or thumbnail.
imageHeight	[opt] integer - height of items icon or thumbnail.

Example:

...
cList.setImageDimensions(18, 18)
...

◆ setPageControlVisible()

void XBMCAddon::xbmcgui::ControlList::setPageControlVisible ( ... )

`Function: setPageControlVisible(visible)`

Sets the spin control's visible/hidden state.

Parameters

visible boolean - True=visible / False=hidden.

Example:

...
cList.setPageControlVisible(True)
...

◆ setSpace()

void XBMCAddon::xbmcgui::ControlList::setSpace ( ... )

`Function: setSpace(space)`

Sets the space between items.

Parameters

space [opt] integer - space between items.

Example:

...
cList.setSpace(5)
...

◆ setStaticContent()

void XBMCAddon::xbmcgui::ControlList::setStaticContent ( ... )

`Function: setStaticContent(items)`

Fills a static list with a list of listitems.

Parameters

items List - list of listitems to add.

Note: You can use the above as keywords for arguments.

Example:

...
cList.setStaticContent(items=listitems)
...

◆ size()

long XBMCAddon::xbmcgui::ControlList::size ( )

`Function: size()`

Returns the total number of items in this list control as an integer.

Returns: Total number of items

Example:

...
cnt = cList.size()
...

Classes

Functions

Function: addItem(item)

Function: addItems(items)

Function: selectItem(item)

Function: removeItem(index)

Function: reset()

Function: getSpinControl()

Function: getSelectedPosition()

Function: getSelectedItem()

Function: setImageDimensions(imageWidth, imageHeight)

Function: setSpace(space)

Function: setPageControlVisible(visible)

Function: size()

Function: getItemHeight()

Function: getSpace()

Function: getListItem(index)

Function: setStaticContent(items)

Detailed Description

Class: ControlList(x, y, width, height[, font, textColor, buttonTexture, buttonFocusTexture, /// selectedColor, imageWidth, imageHeight, itemTextXOffset, itemTextYOffset, /// itemHeight, space, alignmentY, shadowColor])

Function Documentation

◆ addItem()

Function: addItem(item)

◆ addItems()

Function: addItems(items)

◆ getItemHeight()

Function: getItemHeight()

◆ getListItem()

Function: getListItem(index)

◆ getSelectedItem()

Function: getSelectedItem()

◆ getSelectedPosition()

Function: getSelectedPosition()

◆ getSpace()

Function: getSpace()

◆ getSpinControl()

Function: getSpinControl()

◆ removeItem()

Function: removeItem(index)

◆ reset()

Function: reset()

◆ selectItem()

Function: selectItem(item)

◆ setImageDimensions()

Function: setImageDimensions(imageWidth, imageHeight)

◆ setPageControlVisible()

Function: setPageControlVisible(visible)

◆ setSpace()

Function: setSpace(space)

◆ setStaticContent()

Function: setStaticContent(items)

◆ size()

Function: size()

`Function: addItem(item)`

`Function: addItems(items)`

`Function: selectItem(item)`

`Function: removeItem(index)`

`Function: reset()`

`Function: getSpinControl()`

`Function: getSelectedPosition()`

`Function: getSelectedItem()`

`Function: setImageDimensions(imageWidth, imageHeight)`

`Function: setSpace(space)`

`Function: setPageControlVisible(visible)`

`Function: size()`

`Function: getItemHeight()`

`Function: getSpace()`

`Function: getListItem(index)`

`Function: setStaticContent(items)`

`Class: ControlList(x, y, width, height[, font, textColor, buttonTexture, buttonFocusTexture, /// selectedColor, imageWidth, imageHeight, itemTextXOffset, itemTextYOffset, /// itemHeight, space, alignmentY, shadowColor])`

`Function: addItem(item)`

`Function: addItems(items)`

`Function: getItemHeight()`

`Function: getListItem(index)`

`Function: getSelectedItem()`

`Function: getSelectedPosition()`

`Function: getSpace()`

`Function: getSpinControl()`

`Function: removeItem(index)`

`Function: reset()`

`Function: selectItem(item)`

`Function: setImageDimensions(imageWidth, imageHeight)`

`Function: setPageControlVisible(visible)`

`Function: setSpace(space)`

`Function: setStaticContent(items)`

`Function: size()`