===============
Table (hwx.gui)
===============

A Table widget used to display/edit a list of list of values.

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

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

  +-----------------------+-----------------------+-----------------------+
  | columnLabels_         | columnStretchability_ | columnWidth_          |
  +-----------------------+-----------------------+-----------------------+
  | hResizeMode_          | hTooltips_            | numCols_              |
  +-----------------------+-----------------------+-----------------------+
  | numRows_              | readOnly_             | rowHeight_            |
  +-----------------------+-----------------------+-----------------------+
  | rowLabels_            | rowStretchability_    | selectionBehavior_    |
  +-----------------------+-----------------------+-----------------------+
  | selectionMode_        | shape_                | vResizeMode_          |
  +-----------------------+-----------------------+-----------------------+

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

  +--------------------------------------------------------------------+
  | HideRow_ (self, row)                                               |
  +--------------------------------------------------------------------+
  | addColumn_ (self, *values)                                         |
  +--------------------------------------------------------------------+
  | addRow_ (self, *values)                                            |
  +--------------------------------------------------------------------+
  | clearSelection_ (self)                                             |
  +--------------------------------------------------------------------+
  | getCellTooltip_ (self, row, col)                                   |
  +--------------------------------------------------------------------+
  | getColumnWidth_ (self, col='all')                                  |
  +--------------------------------------------------------------------+
  | getRowHeight_ (self, row='all')                                    |
  +--------------------------------------------------------------------+
  | getSelectedRows_ (self, full=False)                                |
  +--------------------------------------------------------------------+
  | getValue_ (self, row, col)                                         |
  +--------------------------------------------------------------------+
  | hideColumn_ (self, col)                                            |
  +--------------------------------------------------------------------+
  | isSelected_ (self, row, col)                                       |
  +--------------------------------------------------------------------+
  | removeColumn_ (self, indices)                                      |
  +--------------------------------------------------------------------+
  | removeRow_ (self, indices)                                         |
  +--------------------------------------------------------------------+
  | selectCells_ (self, row='all', col='all', select=True, clear=True) |
  +--------------------------------------------------------------------+
  | selectRow_ (self, row, clear=True)                                 |
  +--------------------------------------------------------------------+
  | selectRows_ (self, rows=[], clear=True)                            |
  +--------------------------------------------------------------------+
  | setCellImage_ (self, row, col, file)                               |
  +--------------------------------------------------------------------+
  | setCellTooltip_ (self, row, col, value)                            |
  +--------------------------------------------------------------------+
  | setColumnWidth_ (self, width, col='all')                           |
  +--------------------------------------------------------------------+
  | setHResizeMode_ (self, mode, col='all')                            |
  +--------------------------------------------------------------------+
  | setRowHeight_ (self, height=20, row='all')                         |
  +--------------------------------------------------------------------+
  | setVResizeMode_ (self, mode, row='all')                            |
  +--------------------------------------------------------------------+
  | setValue_ (self, row, col, value)                                  |
  +--------------------------------------------------------------------+
  | setValues_ (self, values, rowOrder=False)                          |
  +--------------------------------------------------------------------+
  | showColumn_ (self, col)                                            |
  +--------------------------------------------------------------------+
  | showRow_ (self, row)                                               |
  +--------------------------------------------------------------------+
  | unselectCells_ (self, row='all', col='all')                        |
  +--------------------------------------------------------------------+

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

.. _columnLabels:
.. property:: columnLabels

Column labels to use for resulting table.

.. _columnStretchability:
.. property:: columnStretchability

A list describing whether each column is stretchable or not.
If the table widget's width decreases or increases stretchable columns will
grow narrower or wider to fit the space available as completely as possible.
The user cannot manually resize stretchable columns.

Returns:
  list[bool]: A list describing whether each column is stretchable or not.

.. _columnWidth:
.. property:: columnWidth

The width of each column of the table.

.. _hResizeMode:
.. property:: hResizeMode

(Table.ResizeMode) The resize mode that applies to the horizontal header.

.. _hTooltips:
.. property:: hTooltips

Get or set the current tooltips of the horizontal header elements of the table.

Args:
  value (list[str]): A list that specifies the tooltips.

.. _numCols:
.. property:: numCols

The number of columns in the table.

.. _numRows:
.. property:: numRows

The number of rows in the table.

.. _readOnly:
.. property:: readOnly

Determines whether the cells are readonly or not.

.. _rowHeight:
.. property:: rowHeight

The height of each row of the table.

.. _rowLabels:
.. property:: rowLabels

Row labels to use for resulting table. 
By default, this label is just the row number, starting from 1.

.. _rowStretchability:
.. property:: rowStretchability

A list describing whether each row is stretchable or not.
If the table widget's width decreases or increases stretchable rows will
grow narrower or wider to fit the space available as completely as possible.
The user cannot manually resize stretchable rows.

Returns:
  list[bool]: A list describing whether each column is stretchable or not.

.. _selectionBehavior:
.. property:: selectionBehavior

Determines the way the items of the table can be selected.

Args:
  value (Table.selectionBehaviorType): The type of selection to allow.

.. _selectionMode:
.. property:: selectionMode

Determines the way the items of the table can be selected.

Args:
  value (Table.selectionModeType): The type of selection to allow.

.. _shape:
.. property:: shape

The dimensionality of the table.

.. _vResizeMode:
.. property:: vResizeMode

(Table.ResizeMode) The resize mode that applies to the vertical header.

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

.. _HideRow:
.. method:: HideRow(self, row)

Hide specified row of the table.

:param row: The column index of the table.
:type row: int


.. _addColumn:
.. method:: addColumn(self, *values)

Appends a column of values.

:param values: The values to be set in column of the table
:type values: list[list[str]]


.. _addRow:
.. method:: addRow(self, *values)

Appends a row of values.

:param values: The values to be set in row of the table
:type values: list[list[str]]


.. _clearSelection:
.. method:: clearSelection(self)

Unselects all cells.

.. _getCellTooltip:
.. method:: getCellTooltip(self, row, col)

Gets the tooltip for specified row and column.

:param row: The row index of the table.
:type row: int
:param col: The column index of the table.
:type col: int

:returns: The tooltip at the specified row and column.
:rtype: str


.. _getColumnWidth:
.. method:: getColumnWidth(self, col='all')

Gets the width of the column.

:param col: The indices of columns.
:type col: str | list[int]

:returns: The width of the column.
:rtype: int


.. _getRowHeight:
.. method:: getRowHeight(self, row='all')

Gets the row height.

:param row: A list of indices of rows.
:type row: str | list[int]


.. _getSelectedRows:
.. method:: getSelectedRows(self, full=False)

Returns a list of row indices that are selected.

:param full: If full is False, then if at least one cell in the row has to
          selected to return the row index. If full is True, then every cell in the row
          must be selected to return the row index.
:type full: bool


.. _getValue:
.. method:: getValue(self, row, col)

Gets the value from the specified row and column.

:param row: The row index of the table.
:type row: int
:param col: The column index of the table.
:type col: int

:returns: The text at the specified row and column.
:rtype: str


.. _hideColumn:
.. method:: hideColumn(self, col)

Hide specified column of the table.

:param col: The column index of the table.
:type col: int


.. _isSelected:
.. method:: isSelected(self, row, col)

Returns True if the specified cell is selected, False otherwise.

:param row: The index of row.
:type row: int
:param col: The index of col.
:type col: int


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

Removes a column or columns based on their indices.

:param indices: The indices of columns to be removed from the table.
:type indices: list[int]


.. _removeRow:
.. method:: removeRow(self, indices)

Removes a row or rows based on their indices.

:param indices: The indices of rows to be removed from the table.
             If none removes the last row of the table.
:type indices: list[int], None


.. _selectCells:
.. method:: selectCells(self, row='all', col='all', select=True, clear=True)

Selects the specified cells.

:param row: The indices of rows.
:type row: str | list[int]
:param col: The indices of columns.
:type col: str | list[int]
:param select: Determines whether the specified cells will be selected.
:type select: bool
:param clear: Determines whether the previously selected will be cleared.
:type clear: bool


.. _selectRow:
.. method:: selectRow(self, row, clear=True)

Selects all cells of a row and ensures the row is visible.

:param row: The row to be selected.
:type row: int
:param clear: Determines whether the previously selected will be cleared.
:type clear: bool


.. _selectRows:
.. method:: selectRows(self, rows=[], clear=True)

Selects all specified rows.

:param row: The rows to be selected.
:type row: list
:param clear: Determines whether the previously selected will be cleared.
:type clear: bool


.. _setCellImage:
.. method:: setCellImage(self, row, col, file)

Set image to specified cell of the table.

:param row: The row index of the table.
:type row: int
:param col: The column index of the table.
:type col: int
:param file: Image file name.
:type file: str


.. _setCellTooltip:
.. method:: setCellTooltip(self, row, col, value)

Sets the tooltip for specified row and column.

:param row: The row index of the table.
:type row: int
:param col: The column index of the table.
:type col: int
:param value: The tool tip to be set.
:type value: str


.. _setColumnWidth:
.. method:: setColumnWidth(self, width, col='all')

Sets the column width.

:param width: The width the column.
:type width: int
:param col: The indices of columns.
:type col: str | list[int]


.. _setHResizeMode:
.. method:: setHResizeMode(self, mode, col='all')

Controls resize behavior of horizontal header.

:param mode:
:type mode: Table.ResizeMode
:param col:
:type col: int | 'all'


.. _setRowHeight:
.. method:: setRowHeight(self, height=20, row='all')

Sets specific row height.

:param height: height to set the rows.
:type height: int
:param row: A list of indices of rows.
:type row: str | list[int]


.. _setVResizeMode:
.. method:: setVResizeMode(self, mode, row='all')

Controls resize behavior of vertical header.

:param mode:
:type mode: Table.ResizeMode
:param row:
:type row: int | 'all'


.. _setValue:
.. method:: setValue(self, row, col, value)

Sets the value from the specified row and column.

:param row: The row index of the table.
:type row: int
:param col: The column index of the table.
:type col: int
:param value: The value to be set.
:type value: str


.. _setValues:
.. method:: setValues(self, values, rowOrder=False)

Sets the cell text from the list of list of values.

:param values: The values to be set in cell of the table
:type values: list[list[str]]
:param rowOrder: Determines if values will be transposed.
:type rowOrder: bool


.. _showColumn:
.. method:: showColumn(self, col)

Show specified column of the table if hidden.

:param col: The column index of the table.
:type col: int


.. _showRow:
.. method:: showRow(self, row)

Show specified row of the table if hidden.

:param row: The column index of the table.
:type row: int


.. _unselectCells:
.. method:: unselectCells(self, row='all', col='all')

Deselects the specified cells.

:param row: The indices of rows.
:type row: str | list[int]
:param col: The indices of columns.
:type col: str | list[int]