Kodi Documentation 18.0
Kodi is an open source media player and entertainment hub.
Classes | Functions
Subclass - ControlList
Python » Library - xbmcgui » Control

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

Classes

class  XBMCAddon::xbmcgui::ControlList
 

Functions

 XBMCAddon::xbmcgui::ControlList::addItem (...)
 
 XBMCAddon::xbmcgui::ControlList::addItems (...)
 
 XBMCAddon::xbmcgui::ControlList::selectItem (...)
 
 XBMCAddon::xbmcgui::ControlList::removeItem (...)
 
 XBMCAddon::xbmcgui::ControlList::reset ()
 
 XBMCAddon::xbmcgui::ControlList::getSpinControl ()
 Returns the associated ControlSpin object. More...
 
 XBMCAddon::xbmcgui::ControlList::getSelectedPosition ()
 Returns the position of the selected item as an integer. More...
 
 XBMCAddon::xbmcgui::ControlList::getSelectedItem ()
 
 XBMCAddon::xbmcgui::ControlList::setImageDimensions (...)
 
 XBMCAddon::xbmcgui::ControlList::setSpace (...)
 
 XBMCAddon::xbmcgui::ControlList::setPageControlVisible (...)
 
 XBMCAddon::xbmcgui::ControlList::size ()
 Returns the total number of items in this list control as an integer. More...
 
 XBMCAddon::xbmcgui::ControlList::getItemHeight ()
 
 XBMCAddon::xbmcgui::ControlList::getSpace ()
 
 XBMCAddon::xbmcgui::ControlList::getListItem (...)
 
 XBMCAddon::xbmcgui::ControlList::setStaticContent (...)
 

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 Control
Parameters
xinteger - x coordinate of control.
yinteger - y coordinate of control.
widthinteger - width of control.
heightinteger - height of control.
font[opt] string - font used for items label. (e.g. 'font13')
textColor[opt] hexstring - color of items label. (e.g. '0xFFFFFFFF')
buttonTexture[opt] string - filename for focus texture.
buttonFocusTexture[opt] string - filename for no focus texture.
selectedColor[opt] integer - x offset of label.
imageWidth[opt] integer - width of items icon or thumbnail.
imageHeight[opt] integer - height of items icon or thumbnail.
itemTextXOffset[opt] integer - x offset of items label.
itemTextYOffset[opt] integer - y offset of items label.
itemHeight[opt] integer - height of items.
space[opt] integer - space between items.
alignmentY[opt] integer - Y-axis alignment of items label
  • Flags for alignment used as bits to have several together:
    Defination 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
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.
Once you use a keyword, all following arguments require the keyword.
After you create the control, you need to add it to the window with addControl().

Example:

...
self.cList = xbmcgui.ControlList(100, 250, 200, 250, 'font14', space=5)
...

Function Documentation

◆ addItem()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> addItem(item) </big></font></span></code></h4> \endhtmlonly

Add a new item to this list control.

Parameters
itemstring, unicode or ListItem - item to add.

Example:

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

◆ addItems()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> addItems(items) </big></font></span></code></h4> \endhtmlonly

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

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getItemHeight() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getListItem(index) </big></font></span></code></h4> \endhtmlonly

Returns a given ListItem in this List.

Parameters
indexinteger - index number of item to return.
Returns
List item
Exceptions
ValueErrorif index is out of range.

Example:

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

◆ getSelectedItem()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getSelectedItem() </big></font></span></code></h4> \endhtmlonly

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

Returns the position of the selected item as an integer.

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getSelectedPosition() </big></font></span></code></h4> \endhtmlonly

Note
Returns -1 for empty lists.

Example:

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

◆ getSpace()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getSpace() </big></font></span></code></h4> \endhtmlonly

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

Returns the associated ControlSpin object.

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> getSpinControl() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> removeItem(index) </big></font></span></code></h4> \endhtmlonly

Remove an item by index number.

Parameters
indexinteger - index number of the item to remove.
v13 Python API changes:
New function added.

Example:

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

◆ reset()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> reset() </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> selectItem(item) </big></font></span></code></h4> \endhtmlonly

Select an item by index number.

Parameters
iteminteger - index number of the item to select.

Example:

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

◆ setImageDimensions()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setImageDimensions(imageWidth, imageHeight) </big></font></span></code></h4> \endhtmlonly

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setPageControlVisible(visible) </big></font></span></code></h4> \endhtmlonly

Sets the spin control's visible/hidden state.

Parameters
visibleboolean - True=visible / False=hidden.

Example:

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

◆ setSpace()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setSpace(space) </big></font></span></code></h4> \endhtmlonly

Set's the space between items.

Parameters
space[opt] integer - space between items.

Example:

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

◆ setStaticContent()

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> setStaticContent(items) </big></font></span></code></h4> \endhtmlonly

Fills a static list with a list of listitems.

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

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

@brief \htmlonly <h4><code><span style="font-style: italic;">Function: </span><span style="font-style: bold;"><font color=31363b><big> size() </big></font></span></code></h4> \endhtmlonly

Returns
Total number of items

Example:

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