Class CT_Tbl

src/docx/oxml/table.py:146–256

`` `` element.

class CT_Tbl(BaseOxmlElement):
    """``<w:tbl>`` element."""

    add_tr: Callable[[], CT_Row]
    tr_lst: list[CT_Row]

    tblPr: CT_TblPr = OneAndOnlyOne("w:tblPr")  # pyright: ignore[reportAssignmentType]
    tblGrid: CT_TblGrid = OneAndOnlyOne("w:tblGrid")  # pyright: ignore[reportAssignmentType]
    tr = ZeroOrMore("w:tr")

    @property
    def bidiVisual_val(self) -> bool | None:
        """Value of `./w:tblPr/w:bidiVisual/@w:val` or |None| if not present.

        Controls whether table cells are displayed right-to-left or left-to-right.
        """
        bidiVisual = self.tblPr.bidiVisual
        if bidiVisual is None:
            return None
        return bidiVisual.val

    @bidiVisual_val.setter
    def bidiVisual_val(self, value: WD_TABLE_DIRECTION | None):
        tblPr = self.tblPr
        if value is None:
            tblPr._remove_bidiVisual()  # pyright: ignore[reportPrivateUsage]
        else:
            tblPr.get_or_add_bidiVisual().val = bool(value)

    @property
    def col_count(self):
        """The number of grid columns in this table."""
        return len(self.tblGrid.gridCol_lst)

    def iter_tcs(self):
        """Generate each of the `w:tc` elements in this table, left to right and top to
        bottom.

        Each cell in the first row is generated, followed by each cell in the second
        row, etc.
        """
        for tr in self.tr_lst:
            for tc in tr.tc_lst:
                yield tc

    @classmethod
    def new_tbl(cls, rows: int, cols: int, width: Length) -> CT_Tbl:
        """Return a new `w:tbl` element having `rows` rows and `cols` columns.

        `width` is distributed evenly between the columns.
        """
        return cast(CT_Tbl, parse_xml(cls._tbl_xml(rows, cols, width)))

    @property
    def tblStyle_val(self) -> str | None:
        """`w:tblPr/w:tblStyle/@w:val` (a table style id) or |None| if not present."""
        tblStyle = self.tblPr.tblStyle
        if tblStyle is None: