fsleyes_widgets.widgetgrid

This module provides the WidgetGrid class, which can display a tabular grid of arbitrary widgets.

class fsleyes_widgets.widgetgrid.WidgetGrid(parent, style=None)

Bases: wx._core.ScrolledWindow

A scrollable panel which displays a tabular grid of widgets. A WidgetGrid looks something like this:

_images/widgetgrid.png

The most important methods are:

GetGridSize Returns the current grid size as a tuple containing (rows, cols).
SetGridSize Set the size of the widdget grid.
Refresh Redraws the contents of this WidgetGrid.
DeleteRow Removes the specified row from the grid, destroying all widgets on that row.
InsertRow Inserts a new row into the WidgetGrid at the specified row index.
SetColours Set the colours used in this WidgetGrid.
SetWidget Adds the given widget to the grid.
SetText Convenience method which creates a wx.StaticText widget with the given text, and passes it to the SetWidget() method.
ClearGrid Removes and destroys all widgets from the grid, and sets the grid size to (0, 0).

Labels

ShowRowLabels Shows/hides the grid row labels.
ShowColLabels Shows/hides the grid column labels.
SetRowLabel Sets a label for the specified row.
SetColLabel Sets a label for the specified column.

Selections

GetSelection Returns the currently selected item, as a tuple of (row, col) indices.
SetSelection Select the given item.

Styles

The WidgetGrid supports the following styles:

wx.HSCROLL Use a horizontal scrollbar.
wx.VSCROLL Use a vertical scrollbar.
WG_SELECTABLE_CELLS Individual cells are selectable.
WG_SELECTABLE_ROWS Rows are selectable.
WG_SELECTABLE_COLUMN Columns are selectable.
WG_KEY_NAVIGATION The keyboard can be used for navigation.
WG_DRAGGABLE_COLUMNS Columns can be dragged to re-order them (see also the ReorderColumns() method)

The *_SELECTABLE_* styles are mutualliy exclusive; their precedence is equivalent to their order in the above table. By default, the arrow keys are used for keyboard navigation, but these are customisable via the SetNavKeys() method.

Events

The following events may be emitted by a WidgetGrid:

Create a WidgetGrid.

Parameters:
_defaultBorderColour = '#000000'

The colour of border a border which is shown around every cell in the grid.

_defaultOddColour = '#ffffff'

Background colour for cells on odd rows.

_defaultEvenColour = '#eeeeee'

Background colour for cells on even rows.

_defaultLabelColour = '#dddddd'

Background colour for row and column labels.

_defaultSelectedColour = '#cdcdff'

Background colour for selected cells.

_defaultDragColour = '#ffcdcd'

Background colour for columns being dragged.

__init__(parent, style=None)

Create a WidgetGrid.

Parameters:
rowLabels

Returns the wx.StaticText objects used for the row labels.

colLabels

Returns the wx.StaticText objects used for the column labels.

widgets

Returns a list of lists, containing all widgets in the grid.

Refresh()

Redraws the contents of this WidgetGrid. This method must be called after the contents of the grid are changed.

Disable()

Disables this WidgetGrid.

Enable(enable=True)

Enables/disable this WidgetGrid, and recursively does the same to all of its children.

Hide()

Hides this WidgetGrid.

Show(show=True)

Shows/hides this WidgetGrid, and recursively does the same to all of its children.

SetEvtHandlerEnabled(enable=True)

Enables/disables events on this WidgetGrid, and recursively does the same to all of its children.

SetColours(**kwargs)

Set the colours used in this WidgetGrid. The Refresh() method must be called afterwards for this method to take effect.

Parameters:
  • border – The cell border colour.
  • label – Background colour for row and column labels.
  • odd – Background colour for cells on odd rows.
  • even – Background colour for cells on even rows.
  • selected – Background colour for selected cells.
  • drag – Background colour for columns being dragged.
SetNavKeys(**kwargs)

Set the keys used for keyboard navigation (if the WG_KEY_NAVIGATION style is enabled). Setting an argument to None will disable navigation in that direction.

Parameters:
  • up – Key to use for up navigation.
  • down – Key to use for down navigation.
  • left – Key to use for left navigation.
  • right – Key to use for right navigation.
SetDragLimit(limit)

Set the index of the highest column that can be dragged. Only columns before this limit can be dragged, and they can only be dropped onto a location before the limit. Only relevant if WG_DRAGGABLE_COLUMNS is enabled.

GetGridSize()

Returns the current grid size as a tuple containing (rows, cols).

SetGridSize(nrows, ncols, growCols=None)

Set the size of the widdget grid. The Refresh() method must be called afterwards for this method to take effect.

Parameters:
  • nrows – Number of rows
  • ncols – Number of columns
  • growCols – A sequence specifying which columns should be stretched to fit.
GetRow(widget)

Returns the index of the row in which the given widget is located, or -1 if it is not in the WidgetGrid.

GetColumn(widget)

Returns the index of the column in which the given widget is located, or -1 if it is not in the WidgetGrid.

DeleteRow(row)

Removes the specified row from the grid, destroying all widgets on that row. This method does not need to be followed by a call to Refresh(), but a call to Layout may be required.

Note

Make sure you reparent any widgets that you do not want destroyed before calling this method.

InsertRow(row)

Inserts a new row into the WidgetGrid at the specified row index. This method must be followed by a call to Refresh().

ClearGrid()

Removes and destroys all widgets from the grid, and sets the grid size to (0, 0). The Refresh() method must be called afterwards for this method to take effect.

SetText(row, col, text)

Convenience method which creates a wx.StaticText widget with the given text, and passes it to the SetWidget() method.

If there is already a wx.StaticText widget at the given row/col, it is re-used, and its label simply updated.

Parameters:
  • row – Row index.
  • col – Column index.
  • text – Text to display.
GetWidget(row, col)

Returns the widget located at the specified row/column.

SetWidget(row, col, widget)

Adds the given widget to the grid. The Refresh() method must be called afterwards for this method to take effect.

The parent of the widget is changed to this WidgetGrid.

Note

The provided widget may alternately be a wx.Sizer. However, nested sizers, i.e. sizers which contain other sizers, are not supported.

Parameters:
  • row – Row index.
  • col – Column index.
  • widget – The widget or sizer to add to the grid.

Raises an IndexError if the specified grid location (row, col) is invalid.

GetSelection()

Returns the currently selected item, as a tuple of (row, col) indices. If an entire row has been selected, the col index will be -1, and vice-versa. If nothing is selected, None is returned.

SetSelection(row, col)

Select the given item. A ValueError is raised if the selection is invalid.

Parameters:
  • row – Row index of item to select. Pass in -1 to select a whole column.
  • col – Column index of item to select. Pass in -1 to select a whole row.
Returns:

True if the selected item was changed, False otherwise.

ShowRowLabels(show=True)

Shows/hides the grid row labels. The Refresh() method must be called afterwards for this method to take effect.

ShowColLabels(show=True)

Shows/hides the grid column labels. The Refresh() method must be called afterwards for this method to take effect.

SetRowLabel(row, label)

Sets a label for the specified row.

Raises an IndexError if the row is invalid.

SetColLabel(col, label)

Sets a label for the specified column.

Raises an IndexError if the column is invalid.

SetRowLabels(labels)

Sets the label for every row.

SetColLabels(labels)

Sets the label for every column.

GetRowLabel(row)

Return the label of the specified row.

GetColLabel(col)

Return the label of the specified column.

GetRowLabels()

Return all row labels.

GetColLabels()

Return all column labels.

ReorderColumns(order)

Re-orders the grid columns according to the given sequence of column indices.

A call to this method must be followed by a call to Refresh().

Parameters:order – Sequence of column indices (starting from 0) specifying the new column ordering.
_WidgetGrid__dragPanelPaint(ev)

Paints the current column drop location on the drag panel.

_WidgetGrid__getCellPanel(widget)

Returns the parent wx.Panel for the given widget, or None if the widget is not in the grid.

_WidgetGrid__getColumnDragPosition()

Called during a column drag/drop.

Returns the current insert index of the dragged column, if it were to be dropped now.

_WidgetGrid__initCell(row, col)

Called by SetGridSize() and InsertRow(). Creates a placeholder wx.Panel at the specified cell.

_WidgetGrid__initColLabel(col)

Called by SetGridSize(). Creates a label widget at the specified column

_WidgetGrid__initRowLabel(row)

Called by SetGridSize() and InsertRow(). Creates a label widget at the specified row.

_WidgetGrid__initWidget(widget, row, col)

Called by the AddWidget() method.

Performs some initialisation on a widget which has just been added to the grid.

Parameters:
  • widget – The widget to initialise
  • row – Row index of the widget in the grid.
  • col – Column index of the widget in the grid.
_WidgetGrid__onChildFocus(ev)

If this WidgetGrid is selectable, this method is called when a widget in the grid gains focus. Ensures that the containing cell is selected.

_WidgetGrid__onColumnLabelMouseDown(ev)

Called on mouse down events on a column label.

_WidgetGrid__onColumnLabelMouseDrag(ev)

Called during a column drag. Updates the marker location on the drag panel.

_WidgetGrid__onColumnLabelMouseUp(ev)

Called on the mouse up event at the end of a column drag.

Re-orders the grid columns.

_WidgetGrid__onKeyboard(ev)

If the WG_KEY_NAVIGATION style is enabled, this method is called when the user pushes a key while this WidgetGrid has focus. It changes the currently selected cell, row, or column.

_WidgetGrid__onLeftMouseDown(ev)

If this WidgetGrid is selectable, this method is called whenever an left mouse down event occurs on an item in the grid.

_WidgetGrid__onResize(ev)

Called when this WidgetGrid is resized. Makes sure the scrollbars are up to date.

_WidgetGrid__recurse(obj, funcname, *args, **kwargs)

Recursively call funcname on obj and all its children.

This really is something which wxwidgets should be able to do for me (e.g. enable/disable a window and all of its children).

_WidgetGrid__refresh()

Lays out and re-sizes the entire widget grid.

_WidgetGrid__reparent(widget, parent)

Convenience method which re-parents the given widget. If widget is a wx.Sizer the sizer children are re-parented.

_WidgetGrid__scrollTo(row, col)

If scrolling is enabled, this method makes sure that the specified row/column is visible.

_WidgetGrid__select(row, col, selectType, select=True)

Called by the SetSelection() method. Sets the background colour of the specified row/column to the selection colour, or the default colour.

Parameters:
  • row – Row index. If -1, the colour of the entire column is toggled.
  • col – Column index. If -1, the colour of the entire row is toggled.
  • selectType – Either 'rows', 'columns', or 'cells'.
  • select – If True, the item background colour is set to the selected colour, otherwise it is set to its default colour.
_WidgetGrid__selectCell(row, col)

Called by the __onChildFocus() and __onLeftMouseDown() methods. Selects the specified row/column, and generates an EVT_WG_SELECT event.

_WidgetGrid__setBackgroundColour(widget, colour)

Convenience method which changes the background colour of the given widget. If widget is a wx.Sizer the background colours of the sizer children is updated.

__module__ = 'fsleyes_widgets.widgetgrid'
fsleyes_widgets.widgetgrid.WG_SELECTABLE_CELLS = 1

If this style is enabled, individual cells can be selected.

fsleyes_widgets.widgetgrid.WG_SELECTABLE_ROWS = 2

If this style is enabled, whole rows can be selected.

fsleyes_widgets.widgetgrid.WG_SELECTABLE_COLUMNS = 4

If this style is enabled, whole columns can be selected.

fsleyes_widgets.widgetgrid.WG_KEY_NAVIGATION = 8

If this style is enabled along with one of the *_SELECTABLE_* styles, the user may use the keyboard to navigate between cells, rows, or columns.

fsleyes_widgets.widgetgrid.WG_DRAGGABLE_COLUMNS = 16

If this style is enabled, column names can be dragged with the mouse to re-order them.

fsleyes_widgets.widgetgrid.EVT_WG_SELECT = <wx.core.PyEventBinder object>

Identifier for the WidgetGridSelectEvent.

fsleyes_widgets.widgetgrid.EVT_WG_REORDER = <wx.core.PyEventBinder object>

Identifier for the WidgetGridReorderEvent.

fsleyes_widgets.widgetgrid.WidgetGridSelectEvent

alias of wx.lib.newevent.NewEvent.<locals>._Event

fsleyes_widgets.widgetgrid.WidgetGridReorderEvent

alias of wx.lib.newevent.NewEvent.<locals>._Event

fsleyes_widgets.widgetgrid.TRIANGLE_ICON = b'iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4wIFDQoeGSImZAAAACZpVFh0Q29tbWVudAAAAAAAQ3JlYXRlZCB3aXRoIEdJTVAgb24gYSBNYWOV5F9bAAAAZklEQVQY053PwQmEUAyE4U8Ftw5L8KAlbksetgIrsBLRy8O9RBDxCTowhyTDH4YH+iFhyzhFRn8T2t3v1DFDTXEDJdobWouyimHBig51AGZ8MWAtTsW201xctf+gObxsYpfVFH6nP5vqKwqbBq3zAAAAAElFTkSuQmCC'

Icon used as the drop marker when columns are being re-ordered by mouse drag.