qtgrid.qtgrid.Grid

class documentation

class Grid(QObject):

View In Hierarchy

Interface class for this qtgrid module
Method __init__ Examples
Instance Variable layout Composed QGridLayout object. Will be cleared
Instance Variable wh Composed _WriteHead object
Instance Variable colgaps Composed _ColumnGaps object
Instance Variable spans Composed _Spans object
Instance Variable cells Composed _Cells object
Instance Variable expand_left Boolean. If True, a far left column with expanders are applied
Instance Variable expand_right Boolean. If True, a far right column with expanders are applied
Instance Variable content_columns Integer >= 1. Max number of content columns
Instance Variable work_up Boolean. If True, visual help is applied
Instance Variable label_sources Dictionary = { "name_id1": qlabel1, "name_id2": qlabel2, ... }
Instance Variable custom_lists Dictionary = { "list_name1": [ ], "list_name2": [ ], ... }
Method set_list_names Prepare internal lists with given names
Method set_expand_left Set whether or not to add a far left expanding column, influencing the grid alignment
Method set_expand_right Set whether or not to add a far right expanding column, influencing the grid alignment
Method set_content_columns Set maximum number of content columns
Method set_column_gaps Interface method to _ColumnGaps.set
Method set_work_up Set whether or not to activate the work-up mode
Method set_label_source Store a given QLabel object as a copy source
Method get_list Get name list of widgets as it was prepared with set_list_names
Method get_list_names Get all custom list names as they were prepared with set_list_names
Method get_content_columns Get max number of content columns
Method get_label Get stored QLabel object by name_id
Method add Add a widget to the current _WriteHead position into the grid
Method add_gap Add a _Cell object with a _Gap object to the _WriteHead position into the grid
Method add_empty_row Add a row gap
Method add_label Add a _Cell object with a QLabel object at _WriteHead position into the grid
Method clear Delete all _Cell objects and corresponding items in QGridLayout recursively
Method finish Always call this after you added all your cells
Method _set_default_label_sources Set label sources for "default" and "default-header"
Method _get_remaining_x_span Get the number of remaining cells in row
Method _copy_label Get a copy of a given label
def __init__(self, layout=None, content_columns=1, expand_left=False, expand_right=False, work_up=False, column_gaps=[], list_names=[]):

Examples

grid = Grid()

grid = Grid(
    layout          = QGridLayout(),
    content_columns = 5,
    expand_left     = False,
    expand_right    = True,
    work_up         = True,

    column_gaps = [ (1, 20), (3, None) ],

    list_names = ["list1", "list2"],
)
ParameterslayoutNone (default) or QGridLayout object
content_columnsMax int number of content columns, default 1
expand_leftboolean, default False
expand_rightboolean, default False
work_upboolean, default False
column_gapslist of tuples, default [ ]
list_nameslist of string names pointing to lists, default [ ]
layout =
Composed QGridLayout object. Will be cleared
wh =
Composed _WriteHead object
colgaps =
Composed _ColumnGaps object
spans =
Composed _Spans object
cells =
Composed _Cells object
expand_left =
Boolean. If True, a far left column with expanders are applied
expand_right =
Boolean. If True, a far right column with expanders are applied
content_columns =
Integer >= 1. Max number of content columns
work_up =
Boolean. If True, visual help is applied
label_sources =
Dictionary = { "name_id1": qlabel1, "name_id2": qlabel2, ... }
(type: dict)
custom_lists =
Dictionary = { "list_name1": [ ], "list_name2": [ ], ... }
(type: dict)
def set_list_names(self, names=[]):

Prepare internal lists with given names

grid.set_list_names("list1", "list2")
grid.set_list_names()
Can only be used before any widget is added or after calling the clear method.
The internal lists are intended to hold users widgets for later disposal.
Add widgets to the lists with add, or add_label methods.
After all, use the get_list_names, or get_list methods to access the lists in turn.
If called without argument, all internal lists will be removed.
Parametersnameslist of strings, default [ ]
def set_expand_left(self, flag=False):

Set whether or not to add a far left expanding column, influencing the grid alignment

Can only be used before any widget is added or after calling the clear method.

Parametersflagboolean, default False
def set_expand_right(self, flag=False):

Set whether or not to add a far right expanding column, influencing the grid alignment

Can only be used before any widget is added or after calling the clear method.

Parametersflagboolean, default False
def set_content_columns(self, content_columns=1):

Set maximum number of content columns

grid.set_content_columns( content_columns=1 )
grid.set_content_columns( 1 )
Can only be used before any widget is added or after calling the clear method.
The possibly far left or right expanding columns are not considered.
See also the set_column_gaps method.
Parameterscontent_columnsint n with n >= 1 and n > number of _ColumnGaps.count, default 1
def set_column_gaps(self, column_gaps=[]):
Interface method to _ColumnGaps.set
def set_work_up(self, flag=False):

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.

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
Parametersflagboolean, default False
def set_label_source(self, name_id=None, label=None):

Store a given QLabel object as a copy source

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.

Parametersname_idrequired str name for the label
labelrequired QLabel object to store
def get_list(self, name=None):

Get name list of widgets as it was prepared with set_list_names

The returned list contains QWidgets object added with the add or add_label methods.

for widget in grid.get_list("list1"):
    pass
Parametersnamerequired str name of an internal list
Returnslist of widgets (type: list)
def get_list_names(self):

Get all custom list names as they were prepared with set_list_names

names = grid.get_list_names()
for name in names:
    for widget in grid.get_list( name ):
        pass
Returnslist of list names (type: list)
def get_content_columns(self):
Get max number of content columns
Returnsint (type: int)
def get_label(self, name_id=None):

Get stored QLabel object by name_id

Labels are stored with set_label_source.

Parametersname_idrequired str id for a stored label
ReturnsQLabel object (type: object)
def add(self, widget=None, y_span=1, x_span=1, to_list=None):

Add a widget to the current _WriteHead position into the grid

cell = grid.add( widget=WIDGET, y_span=1, x_span=1, to_list="list_name" )
cell = grid.add( WIDGET, y_span=2, x_span=2 )
cell = grid.add( WIDGET, x_span="all" )
cell = grid.add( WIDGET )
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.
Parameterswidgetrequired QWidget object to be added
y_spanint >= 1, default 1
x_spanint >= 1, or string "all", default 1
to_listoptional str name of an internal list
Returns_Cell object with QWidget object (type: object)
def add_gap(self, direction=None, length=None, y_span=1, x_span=1):

Add a _Cell object with a _Gap object to the _WriteHead position into the grid

cell = add_gap(direction="H", length="20", y_span=2, x_span=2)
# horizontal direction
cell = add_gap("H")           # same as None
cell = add_gap("H", 0)        # same as None
cell = add_gap("H", None)     # explicitly empty
cell = add_gap("H", 20)
cell = add_gap("H", "expand")

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

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

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

ParametersdirectionNone, "H" (default) , "V", "horizontal", or "vertical"
lengthNone, int >= 0, or "expand", default None
y_spanint >= 1, default 1
x_spanint >= 1, default 1
Returns_Cell object with a _Gap object (type: object)
def add_empty_row(self, height=None):

Add a row gap

cell = grid.add_empty_row()     # same as None
cell = grid.add_empty_row(0)    # same as None
cell = grid.add_empty_row(None) # explicitly empty
cell = grid.add_empty_row(20)
cell = grid.add_empty_row("expand")
If not in first column: fill the remaining row with explicit empty cells (colored grey), then …
In the first column of a row: apply vertical gap by adding a single cell spawning the complete row.

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.
ParametersheightNone (default), int >= 0, or "expand"
Returns_Cell object with _Gap object (type: object)
def add_label(self, name_id=None, text='', y_span=1, x_span=1, to_list=None):

Add a _Cell object with a QLabel object at _WriteHead position into the grid

The name_id argument references to a label preset.
If x_span value is "all", the added label spans over the remaining row.
See also the set_label_source method.
cell = grid.add_label( name_id="foo", text="lorem ipsum", y_span=2, x_span=2, to_list="list1" )
cell = grid.add_label("foo", "lorem ipsum", y_span=2, x_span=2, to_list="list1")
cell = grid.add_label("foo", "lorem ipsum", x_span="all")
cell = grid.add_label("foo", "lorem ipsum")

There are predefined defaults:

cell = grid.add_label("default", "lorem ipsum")
cell = grid.add_label("default-header", "Some Header")
For your disposla, you may also add the label to an internal list with the to_list
argument, or use the get_label method.
In most cases the user don't need the returned _Cell object, since the added label
can also be added to an internal list with the to_list argument. But you may also
access the new label directly:
cell  = grid.add_label("default", "lorem ipsum")
label = cell.item
Parametersname_idrequired string
textrequired string
y_spanint >= 1, default 1
x_spanint >= 1, or string "all", default 1
to_listoptional str name of an internal list
Returns_Cell object with QLabel object (type: object)
def clear(self, _layout=None):

Delete all _Cell objects and corresponding items in QGridLayout recursively

grid.clear()
The _layout argument is used for the recursive call only.
The _WriteHead coordinates are reset.
All custom_lists and the private list _Spans._list are reset.
Parameters_layoutNone or QGridLayout object
def finish(self):

Always call this after you added all your cells

Apply from all _Cell objects their holding QWidget objects to the resulting QGridLayout.
Also add the expander and gaps and mark unused cells in work_up mode.
def _set_default_label_sources(self):

Set label sources for "default" and "default-header"

After calling this method at init time the user can do :

grid.add_label("default", "my text")
grid.add_label("default-header", "Some Header")
def _get_remaining_x_span(self, from_x=None):

Get the number of remaining cells in row

If from_x is None, the current x value from _WriteHead is taken.
The return value is the range from_x to the end of all content columns.
It is appropiate for layout span values counting from 1.
Parametersfrom_xNone (default), or int >= 0
Returnsint >= 0 (type: int)
def _copy_label(self, label):

Get a copy of a given label

label2 = grid._copy_label( label1 )
Parameterslabelrequired QLabel object
ReturnsQLabel object (type: object)
API Documentation for gtgrid, generated by pydoctor 21.2.2 at 2021-06-12 11:12:41.