4.26. Table widget class

The Table class inherits QTableView Qt class.

Widget's input value

The input value of the Table widget is an XML string in the form :

<table>

    <header>
        <column>Label</column>
        <column>Label</column>
        ...
    </header>

    <row>
        <column>Value</column>
        <column>Value</column>
        ...
    </row>
    <row></row>
    ...

    <template>
        <column>Value</column>
        <column>Value</column>
        ...
    </template>

</table>

[Warning]Warning
Unlike the example, the XML input value must not contain spaces between tags.

The template tag is used to specify the content of new rows. You should have only one template tag. The content of the template tag is the same as row tag.

The following attributes can be specified in the different tags, see Table 4.2, “Table widget XML attributes” to know where you can put each attribute.

icon
Icon's file path.
color
Decoration's color.
bg
Background's color.
font
Font family name.
size
Font size.
decoration
Font decoration. Possible values are : bold, italic, underline, overline, strikeout. You can specify more than one value separated with commas or spaces.
txt_color
Text's color.
align
Text alignment. Possible values are : left, right, top, bottom, center, hcenter, vcenter, justify.
ro
Set cell(s) read only.
editor
Cell's editor widget. Possible values are :
default
A line edit. This is the default.
text
A text edit.
spin
A spin box. The value is in the form : min,max.
check
A check box. The value can be set to 1 or 0 which is the checked state.
combo
A combo box. The value is an XML string in the form : <item id='id01' selected='1'>Item 1</item><item id='id02' selected='0'>Item 2</item>....
id
Item's ID.
data
Item's data.
width
Column's width.
height
Row's height.
label
Row's label displayed in the row's header section.
tooltip
Cell's tooltip text.
whatsthis
Cell's what's this text.
disabled
If set to 1, the cell cannot be selected.
row_span
This attribute sets the row span of the cell.
col_span
This attribute sets the column span of the cell.

This table defines in which tag attributes can be specified :

Attribute<table> tag<header> tagheader's <column> tag<row> tagrow's <column> tag
iconXXXXX
colorXXXXX
bgXXXXX
fontXXXXX
sizeXXXXX
decorationXXXXX
txt_colorXXXXX
alignXXXXX
roX  XX
editorX  XX
id  XXX
data   X 
width  X  
height   X 
label   X 
tooltip    X
whatsthis    X
disabled    X
row_span    X
col_span    X

Table 4.2. Table widget XML attributes


Widget's attributes

sort
This attribute holds the sorting mode. Possible values are : asc or desc. If the attribute is set to False, sorting is disabled. The default is asc.
numeric_sort
If this attribute is True (which is the default), numbers are sorted like numbers not strings.
dynamic_sort
This attribute holds whether the Table is dynamically sorted whenever the contents change. The default is True.
case_sort
This attribute holds the case sensitivity setting used for comparing strings when sorting. If set to True sorting is case sensitive. The default is False.
buttons
This attribute holds a list of Button widgets which will be disabled when no items are selected. The buttons are enabled when selection contains items.
ro
If set to True, the Table is set to read only mode.
verbose
If this attribute is set to True, the getValue function returns all items values. If set to False (which is the default), only selected items are returned.
return
This attribute holds the format of the return value of the getValue function. dict (which is the default) returns a dict with keys formed from rows id, it is usefull to access rows directly without a loop. list returns a list in the same order as the screen.
headers
This attribute holds which headers are displayed. none means that no headers are displayed. top means that only columns headers are displayed. side means that only rows headers are displayed. both (which is the default) means that both rows and columns headers are displayed.
rows_resize
This attribute sets the constraint on how the rows can be resized. Possible values are :
none
The user cannot resize the rows.
free
The user can resize the rows.
fit
Rows are automatically resized to an optimal size based on the contents. The size cannot be changed by the user. This is the default.
stretch
Rows are automatically resized to fill the available space. The size cannot be changed by the user.
stretch_last
The last row is automatically resized to fill the available space.
stretch_N
The row N is automatically resized to fill the available space.
cols_resize
This attribute sets the constraint on how the columns can be resized. Possible values are the same as the rows_resize attribute. This attribute default is stretch.
adjust_size
This attribute holds whether rows and/or columns are automatically resized to fit the content. none (which is the default) means that no automatic resize occurs. rows means that only rows are automatically resized. cols means that only columns are automatically resized. both means that both rows and columns are automatically resized.
cascading_resize
This attribute holds if interactive resizing will be cascaded to the following rows/columns once the row/column being resized by the user has reached its minimum size. Possible values are : none (which is the default), rows, cols, both.
movable
This attribute holds whether rows and/or columns can be moved by the user. Possible values are : none (which is the default), rows, cols, both.
grid
This attribute holds the pen style used to draw the grid. Possible values are : none, solid (which is the default), dash, dot, dashdot, dashdotdot.
selection
This attribute holds which selection mode the view operates in. Possible values are :
none
Cells cannot be selected.
row
Only one row at a time can be selected.
rows
Multiple rows can be selected.
col
Only one column at a time can be selected.
cols
Multiple columns can be selected.
cell
Only one cell at a time can be selected.
cells
Multiple cells can be selected. This is the default.
elide
This attribute holds the the position of the "..." in elided text. Possible values are : none, left, right, middle. The default is right.
ignore_span
If this attribute is set to True, the span attributes are ignored. This can speed up layout for large tables.
ignore_size
If this attribute is set to True, the size attributes are ignored. This can speed up layout for large tables.
duplicates
If this attribute is set to False, duplicate items are not permitted. The default is True.
duplicates_msg
This attribute holds the message shown to the user when he tries to add a duplicate item. The default is "Item '@ITEM@' already exists" where @ITEM@ is replaced with the duplicate item.
validators
Validator type of input text. Possible values are : int, date, time. Validators are specified by column index, ex : 0:int,1:int,2:date.
invalid_msg
This attribute holds the message shown to the user when he tries to add an invalid item. The default is "Item '@ITEM@' is invalid" where @ITEM@ is replaced with the invalid item.
confirm_del
If this attribute is True (which is the default) a confirmation message is shown to the user before deleting items.
del_item_msg
This attribute holds the message shown to the user before deleting one item. The default is "Delete Item '@ITEM@' ?" where @ITEM@ is replaced with the item to delete.
del_items_msg
This attribute holds the message shown to the user before deleting multiple items. The default is "Delete these @COUNT@ Items ?" where @COUNT@ is replaced with the number of items to delete.
clear_msg
This attribute holds the message shown to the user before deleting all items. The default is "Delete all items ?".

Widget's functions

getRowValue(row)
This function returns a row's value. row can be the id, the value or the index of the row.
getCurrentValue(single_value=False)
This function returns the current selected items. if single_value is set to True, the return value is assumed to be a single row.
setSingleSelection()
This function ensures that only one row is selected. If multiple rows are selected, only the last selected row remains selected.
addRows(data=None, position=-1)
Add rows represented by data in the given position, -1 means at the bottom. data can be :
  • An XML string containing any number of row tags.
  • A tuple that represent one row in the form : (column0, column1, ..., columnN) where column can be a string or a dict. If column is a dict, column's attributes can be passed as the dict's keys, the value of the column is passed in the value key.
  • A list that contains any of the previous formats. You can use different formats in the same list.
  • If data is left to None, the template tag is used as a model for the new row. If template tag is missed, an empty row is added.
addRequest()
This function triggers a row add action. An empty row is added and set in edit mode immediately, the cursor is positioned so the user can begin editing the first cell.
editRow(row, data)
Edit row. row can be the id, the text or the index of the row. data can be :
  • A list or tuple that contains column values.
  • A value that will be assigned to all columns in the edited row.
In both cases, a column value can be a string representing the cell's value. It can be a boolean representing the cell's checked state (for the check editor). It can also be a dict that contains cell's attributes that will be modified, cell's value can be modified with the value key.
editRequest(row=None)
This function triggers a row edit action, the row is selected and put into edit mode. if row is left to None, the current row is edited.
editCurrentRow(data)
Edit the current row. data holds the row's data and follow the same rules as the editRow function.
editCell(row, col, data)
This function edits the cell referenced by row and col, row and col can be an id, a value or an index. data is the cell's value and can be a string or a dict like in the editRow function.
editCurrentCell(data)
This function sets the value of the current cell to data.
delRows(rows)
This function deletes rows. rows can be a list of rows (id, value or index) or a single row.
delCurrentRows()
This function deletes the current selected rows.
clear(clear_header=True)
This function deletes all rows. if clear_header is set to False, the headers are not deleted.
select(rows, flag='clearandselect')
This function selects rows. rows can be a list of rows (id, value or index) or a single row. flag can be one of the following :
none
No selection will be made.
clear
The complete selection will be cleared.
select
All specified rows will be selected.
deselect
All specified rows will be deselected.
toggle
All specified rows will be selected or deselected depending on their current state.
current
The current selection will be updated.
selectcurrent
A combination of select and current, provided for convenience.
togglecurrent
A combination of toggle and current, provided for convenience.
clearandselect
A combination of clear and select, provided for convenience.
scrollToRow(row)
This function scrolls the view to ensure that row is visible.
moveRow(row, position)
This function moves row to position. position can be an absolute index position or an offset in the form +n or -n. Moving rows is disabled when sorting is enabled.
moveRowUp(row)
This function moves row up. Moving rows is disabled when sorting is enabled.
moveRowDown(row)
This function moves row down. Moving rows is disabled when sorting is enabled.
moveCurrentRow(position)
This function moves the current row to position. position can be an absolute index position or an offset in the form +n or -n. Moving rows is disabled when sorting is enabled.
moveCurrentRowUp()
This function moves the current row up. Moving rows is disabled when sorting is enabled.
moveCurrentRowDown()
This function moves the current row down. Moving rows is disabled when sorting is enabled.

Widget's signals

clicked(row)
This signal is emitted when the user clicks on a row. row is the value of the clicked row as returned with the getRowValue function.
doubleClicked(row)
This signal is emitted when the user double clicks on a row. row is the value of the double clicked row as returned with the getRowValue function.
rowAdded(row)
This signal is emitted when a row is added after calling the addRequest function.
cellChanged(row, col, cell)
This signal is emitted when the content of the cell referenced by row and col change. cell is the new value of the cell.
rowsDeleted(rows)
This signal is emitted when one or more rows are deleted. rows is a dict or list (depending on return attribute) that contains the deleted rows values.

Widget's output value

The output value of a Table widget depends on two attributes : verbose and return.

If return is dict, the output value is a bi-dimensional dict where each cell's value can be accessed like this : output_value[row_id][column_id]. cell's value is a dict in the form : {'column':INDEX, 'editor':EDITOR, 'selected':BOOL, 'value':VALUE, 'checked':BOOL, 'combo_id':ID}. the checked key is available only for check editor. the combo_id key is available only for combo editor. The row's index is available at output_value[row_id]['__row__'] and the row's embedded data is available at output_value[row_id]['__data__'].

If return is list, the output value is a list of rows values. Each row's value is a dict in the form : {'id':ID, 'row':INDEX, 'columns':COLUMNS, 'data':DATA} where COLUMNS is a list of cells values. All those elements follows the screen order.

If verbose is True all rows are returned otherwise only selected rows are returned.