The qtgrid Reference Manual

Taken for granted, the primary source is the API documentation. The qtgrid tutorial gives an in deep explanation, and this reference manual is intended to give an overview for the everyday module usage.

Instantiation and Usage

The following two instantiations are equivalent:

grid = Grid()

grid = Grid(
    layout          = QGridLayout(),
    content_columns = 1,
    expand_left     = False,
    expand_right    = False,
    column_gaps     = [],
    list_names      = [],
    work_up         = False
)

layout: Optional QGridLayout object whose items will be cleared.
If left out, it will be instantiated within the Grid constructor.
content_columns: The maximum number of content columns.
Optional integer n with n >= 1 and n > max number of column_gaps (see below). Default 1.
expand_left: Set whether or not a far left expanding column will be added, thus influencing the grid alignment.
Optional boolean value. Default False.
expand_right: Set whether or not a far right expanding column will be added, thus influencing the grid alignment.
Optional boolean value. Default False.
column_gaps: Define gap cells for complete columns.
Optional list of tuples. Default [ ].
See also the set_column_gaps() method.
list_names: Prepare internal lists with given names.
Optional list of strings naming internal lists to create. Default [ ].
The lists purpose is to hold added widgets for later disposal.
See also the set_list_names() method.
work_up: Set whether or not to activate the work up mode.
Optional boolean value. Default is False.
In work-up mode a visual feed back is given for otherwise invisible cells.
See also the set_work_up() method for a list of used colors and their meanings.

In most cases the best place for the Grid instantiation is within class constructors while the dynamic build process is delegated to another method. You may apply settings for the wrapped QGridLayout object directly after the instantiation.

class Example():
    def __init__(self):

    self.grid = Grid(
        layout       = QGridLayout(), # Optional QGridLayout object
        max_x        = 8,             # Maximum number of content columns
        expand_left  = False,
        expand_right = True,

        column_gaps  = [
            # Define gaps for complete columns
            (0, 0),        # (column_index, width) / "width" can be ...
            (2, None),     #   - 0 or None := leave cells explicitly empty
            (4, "expand"), #   - "expand"  := add horizontal expander
            (6, 20),       #   - number    := add fixed sized column gaps
        ],

        # Prepare internal lists to hold widgets for my disposal
        list_names = ["headers", "labels"],

        # Show visual help
        work_up = True
    )
    # QGridLayout settings
    self.grid.layout.setSpacing(1)

In your methods where the grid is build up you often call the clear() method, otherwise the widgets would be added repeatedly. At the end you need to call the finish() method to actually apply all added widgets, gaps, and expander.

    def build_grid(self):
        grid = self.grid
        grid.clear()

        #############
        # Add widgets

        ########
        # Finish
        grid.finish()

Set Instantiation Options

Use the following methods in case you did not set at construction time.
Note: You can do that only before any widget is added or after calling the clear() method.

grid.clear()
grid.set_content_columns( 8 )
grid.set_expand_left( False )
grid.set_expand_right( True )
grid.set_column_gaps(
    [ (0, 0), (2, None), (4, "expand"), (6, 20) ]
)
grid.set_list_names(
    [ "headers", "labels" ]
)
grid.set_work_up( True )

set_column_gaps()

Define gap cells for complete columns. If called without argument, all column gaps will be removed. Can only be used before any widget is added or after calling the clear() method.

grid.set_column_gaps( column_gaps=[ <tuple>, <tuple>, ... ] )

grid.set_column_gaps( column_gaps=[ (0,20), (2,None), (4,"expand"), (6,20) ] )
grid.set_column_gaps([
    (0, 0),        # (column_index, width) / "width" can be ...
    (2, None),     #   - 0 or None := leave cells explicitly empty
    (4, "expand"), #   - "expand"  := add horizontal expander
    (6, 20),       #   - number    := add fixed sized column gap
])
grid.set_column_gaps()

column_gaps

Optional column_gaps argument is a list of tuples.
Each tuple has the form: (column_index, width).

column_index
integer n with 0 <= n < content_columns number
width
keyword None, or string "expand", or int >= 0

The overall used tuples, thus the number of column gaps, must be less than content_columns number. The width value can be None, int >= 0, or the string "expand". Here, value 0 and None are equivalent.

set_expand_left()

Set whether or not a far left expanding column is added, thus influencing the grid alignment. Can only be used before any widget is added or after calling the clear() method.

grid.set_expand_left( flag=<bool> )

grid.set_expand_left( flag=False )
grid.set_expand_left( False )
grid.set_expand_left()

flag: Optional boolean value. Default False.

set_expand_right()

Set whether or not a far right expanding column is added, thus influencing the grid alignment. Can only be used before any widget is added or after calling the clear() method.

grid.set_expand_right( flag=<bool> )

grid.set_expand_right( flag=False )
grid.set_expand_right( False )
grid.set_expand_right()

flag: Optional boolean value. Default False.

set_list_names()

Prepare internal lists with given names. If called without the argument, all internal lists will be removed. Can only be used before any widget is added or after calling the clear() method.

grid.set_list_names( names=[ <str>, <str>, ... ] )

grid.set_list_names( names=[ "list1", "list2" ] )
grid.set_list_names( ["list1", "list2"] )
grid.set_list_names()

names: Optional list with string names identifying the internal lists to be created.

You can add widgets to those prepared lists with the to_list argument along with the add() or add_label() methods. After all, use the get_list_names(), or get_list() methods to access the lists in turn.

set_content_columns()

Set the maximum number of content columns. Can only be used before any widget is added or after calling the clear() method.

grid.set_content_columns( content_columns=<int> )

grid.set_content_columns( content_columns=1 )
grid.set_content_columns( 1 )

content_columns: Optional integer n with n >= 1 and n > number of column_gaps. Default is 1.

set_work_up()

Set whether or not to activate the work up mode. Can only be used before any widget is added or after calling the clear() method.

grid.set_work_up( flag=<bool> )

grid.set_work_up( flag=False )
grid.set_work_up( False )
grid.set_work_up()

flag: Optional boolean value. Default is False.

In work up mode otherwise invisible cells are colored indicating the following meaning:

Magenta: unused cell
Blue: horizontal expander
Cyan: vertical expander
Yellow: fixed sized horizontal gap
Orange: fixed sized vertical gap
Grey: explicit empty cell

Methods

add()

Add arbitrary widgets to the grid.

grid.add( widget=<QWidget>, y_span=<int>, x_span=<int|"all">, to_list=<str> )

grid.add( widget=WIDGET, y_span=1, x_span=1, to_list="list_name" )
grid.add( WIDGET, y_span=2, x_span=2 )
grid.add( WIDGET, x_span="all" )
grid.add( WIDGET )

widget: Required QWidget object to add.
y_span: Optional int >= 1. Default 1.
x_span: Optional int >= 1, or string "all". Default 1.
to_list: Optional string identifying an internal prepared list, or the None keyword. Default None.

The to_list argument can be used to not only add the widget to the grid, but also to a prepared internal list for later use. See also the set_list_names() method.

The y_span and x_span integer arguments spans the cell over the given number of rows and columns. If x_span value is "all" the cell spans over the remaining row.

add_empty_row()

grid.add_empty_row( height=<int|"expand"> )

grid.add_empty_row()     # same as None
grid.add_empty_row(0)    # same as None
grid.add_empty_row(None) # explicitly empty
grid.add_empty_row(20)
grid.add_empty_row("expand")

Add a row gap.

height: Optional keyword None, int >= 0, or string "expand". Default None.

If not in the first column: fill the remaining row with explicit empty cells (colored grey), then ...
In the first column of a row: apply a vertical gap by adding a single cell spawning the complete row.

Above, the first three calls are all equivalent. When given a integer number, the row gets a fixed height in pixels. If the string "expand" is used, the row expands in vertical direction.

See the set_work_up() method for a list of displayed colors in work_up mode.

add_gap()

Add a cell gap.

grid.add_gap( direction=<str>, length=<int|"expand">, y_span=<int>, x_span=<int> )

# horizontal direction
grid.add_gap("H")           # same as None
grid.add_gap("H", 0)        # same as None
grid.add_gap("H", None)     # explicitly empty
grid.add_gap("H", 20)
grid.add_gap("H", "expand")

# horizontal direction is default
grid.add_gap()         # same as None
grid.add_gap(0)        # same as None
grid.add_gap(None)     # explicitly empty
grid.add_gap(20)
grid.add_gap("expand")

# vertical direction
grid.add_gap("V")           # same as None
grid.add_gap("V", 0)        # same as None
grid.add_gap("V", None)     # explicitly empty
grid.add_gap("V", 20)
grid.add_gap("V", "expand")

direction: None, "H" (default) , "V", "horizontal", or "vertical"
length: None, int >= 0, or "expand", default None
y_span: Optional int >= 1. Default is 1.
x_span: Optional int >= 1. Default is 1.

The direction argument comes into account when the gap has a fixed size or should be an expander. It defaults to the horizontal direction. Thus, to add a gap horizontally, you may left out the direction argument :

grid.add_gap(20)         # add horizontal fixed size gap
grid.add_gap("expander") # add horizontal expander

In order to orient vertically use the "V" or "vertical" value for the direction argument :

grid.add_gap("V", 20)
grid.add_gap("V", "expander")

See the set_work_up() method for a list of displayed colors in work_up mode.

add_label()

Add a new label to the grid. Copy the label configuration from a previously stored label.

grid.add_label( name_id=<str>, text=<str>, y_span=<int>, x_span=<int|"all">, to_list=<str> )

grid.add_label(
    name_id = "foo",
    text    = "lorem ipsum",
    y_span  = 2,
    x_span  = 2,
    to_list = "list1"
)
grid.add_label("foo", "lorem ipsum")
grid.add_label("foo", "lorem ipsum", x_span="all")

name_id: Required string identifying an internally stored label widget.
See also the set_label_source().
That label serves as a copy source for its attributes.
text: Optional text for the new label. Default is ''.
y_span: Optional integer n with n >= 1. Default is 1.
x_span: Optional integer n with n >= 1, or string "all". Default is 1.
to_list: Optional string identifying an internally stored list, or the None keyword. Default is None.
x_span_remain: Optional boolean value. Default is False.

The name_id argument references to a label preset. If the x_span value is "all" the added label spans over the remaining row. For your disposla, you may also add the label to an internal list with the to_list argument, or use the get_label() method.

There are predefined defaults:

grid.add_label("default", "lorem ipsum")
grid.add_label("default-header", "Some Header")

clear()

Clear all cells and the underlying QGridLayout object. You likely want to call this in your method where the grid is build-up dynamically. Otherwise, all widgets are added repeatedly. See Instantiation and Usage.

grid.clear()

This removes each grid cell, resets internal indices, removes all spans and reinitialize all prepared lists. See also the set_list_names method.

finish()

Always call this method after you added all your widgets.

grid.finish()

It applies all gaps, expander and marks unused cells (colored magenta). See the set_work_up() method for a list of displayed colors in work_up mode.

get_list()

Get name list of widgets as it was prepared with set_list_names.

<list of QWidget objects> = grid.get_list( name=<str> )

for widget in grid.get_list("list1"):
    pass

The returned list contains QWidget objects added with the add() or add_label() methods.

name: Required string identifying a stored internal list.

get_list_names()

Get all custom list names as they were prepared with set_list_names().

<list of str> = grid.get_list_names()

for name in grid.get_list_names():
    for widget in grid.get_list( name ):
        pass

get_content_columns()

Get the maximum number of content columns.

<int> = grid.get_content_columns()

get_label()

Get stored QLabel object by name_id.

<QLabel> = grid.get_label( name_id=<str> )

label = grid.get_label( name_id="foo" )
label = grid.get_label( "foo" )

Labels are stored with set_label_source.

name_id: Required string identifying a stored QLabel object.

set_label_source()

Store a given QLabel object as a copy source for its attributes.

grid.set_label_source( name_id="foo", label=myLabel )

grid.set_label_source("foo", myLabel)

The name_id is the key to access the label with the add_label(), or get_label() methods.

name_id: Required string id for the given label to be stored.
label: Required QLabel object with proper configuration.