==============
Tree (hwx.gui)
==============

Hierarchical list of items.

Inherits:
  - :ref:`Widget (hwx.gui)`

----------
Properties
----------

  +----------------+----------------+----------------+
  | header_        | numCols_       | selectionMode_ |
  +----------------+----------------+----------------+

--------------
Public Methods
--------------

  +--------------------------------------------------------+
  | add_ (self, parent=None, text=None, icon=None, **kwds) |
  +--------------------------------------------------------+
  | addColumn_ (self, label, width=-1)                     |
  +--------------------------------------------------------+
  | clear_ (self)                                          |
  +--------------------------------------------------------+
  | collapseAll_ (self)                                    |
  +--------------------------------------------------------+
  | enableEdit_ (self, col=None, edit=True)                |
  +--------------------------------------------------------+
  | ensureItemVisible_ (self, item)                        |
  +--------------------------------------------------------+
  | expandAll_ (self, expanded=True)                       |
  +--------------------------------------------------------+
  | get_ (self)                                            |
  +--------------------------------------------------------+
  | getChildren_ (self, parent=None)                       |
  +--------------------------------------------------------+
  | getSelected_ (self)                                    |
  +--------------------------------------------------------+
  | remove_ (self, item)                                   |
  +--------------------------------------------------------+
  | removeColumn_ (self, indices)                          |
  +--------------------------------------------------------+
  | setSelected_ (self, items, selected=True, clear=True)  |
  +--------------------------------------------------------+

----------------
Property Details
----------------

.. _header:
.. property:: header

Column labels of the tree.

.. _numCols:
.. property:: numCols

The number of columns in the tree.

.. _selectionMode:
.. property:: selectionMode

The selection mode. Valid choices are:
  
- "single"
- "extended"
- "multi"
- "contiguous"
- "none"

--------------
Method Details
--------------

.. _add:
.. method:: add(self, parent=None, text=None, icon=None, **kwds)

Adds a TreeItem to the Tree.

:param parent: A TreeItem to define hierarchy.
:type parent: TreeItem
:param text: Text or List of text that gets displayed in column.
:type text: str|list[str]
:param icon: Absolute path of the icon or a list of icons.
:type icon: str|list[str]

:returns: the added TreeItem.
:rtype: TreeItem


.. _addColumn:
.. method:: addColumn(self, label, width=-1)

Adds one or more columns to the tree, width pixes wide.

All columns apart from the first one are inserted to the right of the
existing ones.
If width is negative, the new column's width is set to maximum.

:param label: Name of the column.
:type label: str|list[str]
:param width: How wide each column is in pixels.
:type width: int|list[int]

:returns: The indices of the new columns.
:rtype: list[int]


.. _clear:
.. method:: clear(self)

Removes all items from the tree.

.. _collapseAll:
.. method:: collapseAll(self)

Collapses all items.

.. _enableEdit:
.. method:: enableEdit(self, col=None, edit=True)

Makes all tree items or specific tree column to be editable.

:param col: Column index needs to be make editable.
:type col: int
:param edit: If True, column is editable else not.
:type edit: bool


.. _ensureItemVisible:
.. method:: ensureItemVisible(self, item)

Scrolls view so this item is visible.

:param item: TreeItem to make visible.
:type item: TreeItem


.. _expandAll:
.. method:: expandAll(self, expanded=True)

Expands (or collapses) all items.

:param expanded: Determines whether to expand or not.
:type expanded: bool


.. _get:
.. method:: get(self)

Returns the current selected item.


.. _getChildren:
.. method:: getChildren(self, parent=None)

Overloaded Widget method for 'children' property.

.. _getSelected:
.. method:: getSelected(self)

Returns a list of the selected items.

.. _remove:
.. method:: remove(self, item)

Removes the specified item from the tree.

:param item: Item to be removed.
:type item: TreeItem


.. _removeColumn:
.. method:: removeColumn(self, indices)

Removes columns based on their initial indices.

:param indices:
:type indices: int|list[int]


.. _setSelected:
.. method:: setSelected(self, items, selected=True, clear=True)

Selects the specified items.

:param items: list of TreeItems to be selected.
:type items: list[TreeItem]
:param selected: Determines if items will be selected or not.
:type selected: bool
:param clear: Determines if al previously selected items will be cleared or not.
:type clear: bool