DataTables¶

Warnings¶

Warning

Data tables are still far from perfect. The class is in constant change, because of optimizations and bug fixes.

If you find a bug or have an improvement you want to share, take some time and share your discoveries with us over the main git repo.

Any help is well appreciated.

Warning

In versions prior to Kivy 2.1-dev0 exists an error in which is the table has only one row in the current page, the table will only render one column instead of the whole row.

Note

MDDataTable allows developers to sort the data provided by column. This happens thanks to the use of an external function that you can bind while you’re defining the table columns.

Be aware that the sorting function must return a 2 value list in the format of:

[Index, Sorted_Row_Data]

This is because the index list is needed to allow MDDataTable to keep track of the selected rows. and, after the data is sorted, update the row checkboxes.

API - `kivymd.uix.datatables`¶

class kivymd.uix.datatables.MDDataTable(**kwargs)¶

Events

on_row_press: Called when a table row is clicked.
on_check_press: Called when the check box in the table row is checked.

Use events as follows

from kivy.metrics import dp
from kivy.uix.anchorlayout import AnchorLayout
from kivy.lang import Builder
from kivy.logger import Logger

from kivymd.app import MDApp
from kivymd.uix.datatables import MDDataTable

kv = '''
BoxLayout:
    orientation: "vertical"
    BoxLayout:
        id:button_tab
        size_hint_y:None
        height: dp(48)

        MDFlatButton:
            text: "Hello <3"
            on_release:
                app.update_row_data()

    BoxLayout:
        id:body

'''

class Example(MDApp):
    def build(self):
        self.data_tables = MDDataTable(
            # MDDataTable allows the use of size_hint
            size_hint=(0.8, 0.7),
            use_pagination=True,
            check=True,
            column_data=[
                ("No.", dp(30)),
                ("Status", dp(30)),
                ("Signal Name", dp(60), self.sort_on_signal),
                ("Severity", dp(30)),
                ("Stage", dp(30)),
                ("Schedule", dp(30), self.sort_on_schedule),
                ("Team Lead", dp(30), self.sort_on_team)
            ],
            row_data=[
                ("1", ("alert", [255 / 256, 165 / 256, 0, 1], "No Signal"),
                 "Astrid: NE shared managed", "Medium", "Triaged", "0:33",
                 "Chase Nguyen"),
                ("2", ("alert-circle", [1, 0, 0, 1], "Offline"),
                 "Cosmo: prod shared ares", "Huge", "Triaged", "0:39",
                 "Brie Furman"),
                ("3", (
                    "checkbox-marked-circle",
                    [39 / 256, 174 / 256, 96 / 256, 1],
                    "Online"), "Phoenix: prod shared lyra-lists", "Minor",
                 "Not Triaged", "3:12", "Jeremy lake"),
                ("4", (
                    "checkbox-marked-circle",
                    [39 / 256, 174 / 256, 96 / 256, 1],
                    "Online"), "Sirius: NW prod shared locations",
                 "Negligible",
                 "Triaged", "13:18", "Angelica Howards"),
                ("5", (
                    "checkbox-marked-circle",
                    [39 / 256, 174 / 256, 96 / 256, 1],
                    "Online"), "Sirius: prod independent account",
                 "Negligible",
                 "Triaged", "22:06", "Diane Okuma"),

            ],
            sorted_on="Schedule",
            sorted_order="ASC",
            elevation=2
        )
        self.data_tables.bind(on_row_press=self.on_row_press)
        self.data_tables.bind(on_check_press=self.on_check_press)
        root = Builder.load_string(kv)
        root.ids.body.add_widget(self.data_tables)
        return root

    def update_row_data(self, *dt):
        self.data_tables.row_data = [
        (
            "21",
            ("alert", [255 / 256, 165 / 256, 0, 1], "No Signal"),
            "Astrid: NE shared managed",
            "Medium",
            "Triaged",
            "0:33",
            "Chase Nguyen"
        ),
        ("32", ("alert-circle", [1, 0, 0, 1], "Offline"),
        "Cosmo: prod shared ares", "Huge", "Triaged", "0:39",
        "Brie Furman"),
        ("43", (
        "checkbox-marked-circle",
        [39 / 256, 174 / 256, 96 / 256, 1],
        "Online"), "Phoenix: prod shared lyra-lists", "Minor",
        "Not Triaged", "3:12", "Jeremy lake"),
        ("54", (
        "checkbox-marked-circle",
        [39 / 256, 174 / 256, 96 / 256, 1],
        "Online"), "Sirius: NW prod shared locations",
        "Negligible",
        "Triaged", "13:18", "Angelica Howards"),
        ("85", (
        "checkbox-marked-circle",
        [39 / 256, 174 / 256, 96 / 256, 1],
        "Online"), "Sirius: prod independent account",
        "Negligible",
        "Triaged", "22:06", "Diane Okuma"),
        ("85", (
        "checkbox-marked-circle",
        [39 / 256, 174 / 256, 96 / 256, 1],
        "Online"), "Sirius: prod independent account",
        "Negligible",
        "Triaged", "22:06", "John Sakura"),
        ]


    def on_row_press(self, instance_table, instance_row):
        '''Called when a table row is clicked.'''

        print(instance_table, instance_row)

    def on_check_press(self, instance_table, current_row):
        '''Called when the check box in the table row is checked.'''

        print(instance_table, current_row)

    # Sorting Methods:
    # Since the # 914 Pull request, the sorting method requires you to sort
    # out the indexes of each data value for the support of selections

    # The most common method to do this is with the use of the bult-in function
    # zip and enimerate, see the example below for more info.

    # the result given by these funcitons must be a list in the format of
    # [Indexes, Sorted_Row_Data]


    def sort_on_signal(self, data):
        return zip(
            *sorted(
                enumerate(data),
                key=lambda l: l[1][2]
            )
        )

    def sort_on_schedule(self, data):
        return zip(
            *sorted(
                enumerate(data),
                key=lambda l: sum(
                    [int(l[1][-2].split(":")[0])*60,
                    int(l[1][-2].split(":")[1])]
                )
            )
        )

    def sort_on_team(self, data):
        return zip(
            *sorted(
                enumerate(data),
                key=lambda l: l[1][-1]
            )
        )

Example().run()

column_data¶

Data for header columns.

from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.datatables import MDDataTable
from kivy.uix.anchorlayout import AnchorLayout


class Example(MDApp):
    def build(self):
        layout = AnchorLayout()
        self.data_tables = MDDataTable(
            size_hint=(0.7, 0.6),
            use_pagination=True,
            check=True,

            # name column, width column, sorting function column(optional)
            column_data=[
                ("No.", dp(30)),
                ("Status", dp(30)),
                ("Signal Name", dp(60)),
                ("Severity", dp(30)),
                ("Stage", dp(30)),
                ("Schedule", dp(30), lambda *args: print("Sorted using Schedule")),
                ("Team Lead", dp(30)),
            ],
        )
        layout.add_widget(self.data_tables)
        return layout


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-column-data.png

column_data is an ListProperty and defaults to [].

Note

The functions which will be called for sorting must accept a data argument and return the sorted data.

Incoming data format will be similar to the provided row_data except that it’ll be all list instead of tuple like below. Any icon provided initially will also be there in this data so handle accordingly.

[
    ['1', ['icon', 'No Signal'], 'Astrid: NE shared managed', 'Medium', 'Triaged', '0:33', 'Chase Nguyen'],
    ['2', 'Offline', 'Cosmo: prod shared ares', 'Huge', 'Triaged', '0:39', 'Brie Furman'],
    ['3', 'Online', 'Phoenix: prod shared lyra-lists', 'Minor', 'Not Triaged', '3:12', 'Jeremy lake'],
    ['4', 'Online', 'Sirius: NW prod shared locations', 'Negligible', 'Triaged', '13:18', 'Angelica Howards'],
    ['5', 'Online', 'Sirius: prod independent account', 'Negligible', 'Triaged', '22:06', 'Diane Okuma']
]

You must sort inner lists in ascending order and return the sorted data in the same format.

row_data¶

Data for rows. To add icon in addition to a row data, include a tuple with This property stores the row data used to display each row in the DataTable To show an icon inside a column in a row, use the folowing format in the row’s columns.

Format:

(“MDicon-name”, [icon color in rgba], “Column Value”)

Example:

For a more complex example see below.

from kivy.metrics import dp
from kivy.uix.anchorlayout import AnchorLayout

from kivymd.app import MDApp
from kivymd.uix.datatables import MDDataTable


class Example(MDApp):
    def build(self):
        layout = AnchorLayout()
        data_tables = MDDataTable(
            size_hint=(0.9, 0.6),
            column_data=[
                ("Column 1", dp(20)),
                ("Column 2", dp(30)),
                ("Column 3", dp(50), self.sort_on_col_3),
                ("Column 4", dp(30)),
                ("Column 5", dp(30)),
                ("Column 6", dp(30)),
                ("Column 7", dp(30), self.sort_on_col_2),
            ],
            row_data=[
                # The number of elements must match the length
                # of the `column_data` list.
                (
                    "1",
                    ("alert", [255 / 256, 165 / 256, 0, 1], "No Signal"),
                    "Astrid: NE shared managed",
                    "Medium",
                    "Triaged",
                    "0:33",
                    "Chase Nguyen",
                ),
                (
                    "2",
                    ("alert-circle", [1, 0, 0, 1], "Offline"),
                    "Cosmo: prod shared ares",
                    "Huge",
                    "Triaged",
                    "0:39",
                    "Brie Furman",
                ),
                (
                    "3",
                    (
                        "checkbox-marked-circle",
                        [39 / 256, 174 / 256, 96 / 256, 1],
                        "Online",
                    ),
                    "Phoenix: prod shared lyra-lists",
                    "Minor",
                    "Not Triaged",
                    "3:12",
                    "Jeremy lake",
                ),
                (
                    "4",
                    (
                        "checkbox-marked-circle",
                        [39 / 256, 174 / 256, 96 / 256, 1],
                        "Online",
                    ),
                    "Sirius: NW prod shared locations",
                    "Negligible",
                    "Triaged",
                    "13:18",
                    "Angelica Howards",
                ),
                (
                    "5",
                    (
                        "checkbox-marked-circle",
                        [39 / 256, 174 / 256, 96 / 256, 1],
                        "Online",
                    ),
                    "Sirius: prod independent account",
                    "Negligible",
                    "Triaged",
                    "22:06",
                    "Diane Okuma",
                ),
            ],
        )
        layout.add_widget(data_tables)
        return layout

    def sort_on_col_3(self, data):
        return zip(
            *sorted(
                enumerate(data),
                key=lambda l: l[1][3]
            )
        )

    def sort_on_col_2(self, data):
        return zip(
            *sorted(
                enumerate(data),
                key=lambda l: l[1][-1]
            )
        )

Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-row-data.png

row_data is an ListProperty and defaults to [].

sorted_on¶

Column name upon which the data is already sorted.

If the table data is showing an already sorted data then this can be used to indicate upon which column the data is sorted.

sorted_on is an StringProperty and defaults to ‘’.

sorted_order¶

Order of already sorted data. Must be one of ‘ASC’ for ascending or ‘DSC’ for descending order.

sorted_order is an OptionProperty and defaults to ‘ASC’.

check¶

Use or not use checkboxes for rows.

check is an BooleanProperty and defaults to False.

use_pagination¶

Use page pagination for table or not.

from kivy.metrics import dp
from kivy.uix.anchorlayout import AnchorLayout

from kivymd.app import MDApp
from kivymd.uix.datatables import MDDataTable


class Example(MDApp):
    def build(self):
        layout = AnchorLayout()
        data_tables = MDDataTable(
            size_hint=(0.9, 0.6),
            use_pagination=True,
            column_data=[
                ("No.", dp(30)),
                ("Column 1", dp(30)),
                ("Column 2", dp(30)),
                ("Column 3", dp(30)),
                ("Column 4", dp(30)),
                ("Column 5", dp(30)),
            ],
            row_data=[
                (f"{i + 1}", "1", "2", "3", "4", "5") for i in range(50)
            ],
        )
        layout.add_widget(data_tables)
        return layout


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-use-pagination.png

use_pagination is an BooleanProperty and defaults to False.

elevation¶

Table elevation.

elevation is an NumericProperty and defaults to 8.

rows_num¶

The number of rows displayed on one page of the table.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-use-pagination.gif

rows_num is an NumericProperty and defaults to 10.

pagination_menu_pos¶

Menu position for selecting the number of displayed rows. Available options are ‘center’, ‘auto’.

Center

Auto

pagination_menu_pos is an OptionProperty and defaults to ‘center’.

pagination_menu_height¶

Menu height for selecting the number of displayed rows.

140dp

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-menu-height-140.png

240dp

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/data-tables-menu-height-240.png

pagination_menu_height is an NumericProperty and defaults to ‘140dp’.

background_color¶

Background color in the format (r, g, b, a). See background_color.

from kivy.metrics import dp
from kivy.uix.anchorlayout import AnchorLayout

from kivymd.app import MDApp
from kivymd.uix.datatables import MDDataTable


class Example(MDApp):
    def build(self):
        layout = AnchorLayout()
        data_tables = MDDataTable(
            size_hint=(0.9, 0.6),
            use_pagination=True,
            column_data=[
                ("No.", dp(30)),
                ("Column 1", dp(30)),
                ("[color=#52251B]Column 2[/color]", dp(30)),
                ("Column 3", dp(30)),
                ("[size=24][color=#C042B8]Column 4[/color][/size]", dp(30)),
                ("Column 5", dp(30)),
            ],
            row_data=[
                (
                    f"{i + 1}",
                    "[color=#297B50]1[/color]",
                    "[color=#C552A1]2[/color]",
                    "[color=#6C9331]3[/color]",
                    "4",
                    "5",
                )
                for i in range(50)
            ],
        )
        layout.add_widget(data_tables)
        return layout


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/datatables-use-markup-strings.png

background_color is a ColorProperty and defaults to [0, 0, 0, 0].

update_row_data(self, instance, value)¶

Called when a the widget data must be updated.

Remember that this is a heavy function. since the whole data set must be updated. you can get better results calling this metod with in a coroutine.

on_row_press(self, *args)¶: Called when a table row is clicked.

on_check_press(self, *args)¶: Called when the check box in the table row is checked.

get_row_checks(self)¶: Returns all rows that are checked.

create_pagination_menu(self, interval)¶

DataTables¶

Warnings¶

API - kivymd.uix.datatables¶

API - `kivymd.uix.datatables`¶