14. CellRenderers

Gtk.CellRenderer widgets are used to display information within widgets such as the Gtk.TreeView or Gtk.ComboBox. They work closely with the associated widgets and are very powerful, with lots of configuration options for displaying a large amount of data in different ways. There are seven Gtk.CellRenderer widgets which can be used for different purposes:

14.1. CellRendererText

A Gtk.CellRendererText renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the "ellipsize" property allows it.

By default, text in Gtk.CellRendererText widgets is not editable. This can be changed by setting the value of the "editable" property to True:

cell.set_property("editable", True)

You can then connect to the "edited" signal and update your Gtk.TreeModel accordingly.

14.1.1. Example

_images/cellrenderertext_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk
 5
 6
 7classCellRendererTextWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererText Example")
10
11 self.set_default_size(200, 200)
12
13 self.liststore = Gtk.ListStore(str, str)
14 self.liststore.append(["Fedora", "https://fedoraproject.org/"])
15 self.liststore.append(["Slackware", "http://www.slackware.com/"])
16 self.liststore.append(["Sidux", "http://sidux.com/"])
17
18 treeview = Gtk.TreeView(model=self.liststore)
19
20 renderer_text = Gtk.CellRendererText()
21 column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0)
22 treeview.append_column(column_text)
23
24 renderer_editabletext = Gtk.CellRendererText()
25 renderer_editabletext.set_property("editable", True)
26
27 column_editabletext = Gtk.TreeViewColumn(
28 "Editable Text", renderer_editabletext, text=1
29 )
30 treeview.append_column(column_editabletext)
31
32 renderer_editabletext.connect("edited", self.text_edited)
33
34 self.add(treeview)
35
36 deftext_edited(self, widget, path, text):
37 self.liststore[path][1] = text
38
39
40win = CellRendererTextWindow()
41win.connect("destroy", Gtk.main_quit)
42win.show_all()
43Gtk.main()

14.2. CellRendererToggle

Gtk.CellRendererToggle renders a toggle button in a cell. The button is drawn as a radio- or checkbutton, depending on the "radio" property. When activated, it emits the "toggled" signal.

As a Gtk.CellRendererToggle can have two states, active and not active, you most likely want to bind the "active" property on the cell renderer to a boolean value in the model, thus causing the check button to reflect the state of the model.

14.2.1. Example

_images/cellrenderertoggle_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk
 5
 6
 7classCellRendererToggleWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererToggle Example")
10
11 self.set_default_size(200, 200)
12
13 self.liststore = Gtk.ListStore(str, bool, bool)
14 self.liststore.append(["Debian", False, True])
15 self.liststore.append(["OpenSuse", True, False])
16 self.liststore.append(["Fedora", False, False])
17
18 treeview = Gtk.TreeView(model=self.liststore)
19
20 renderer_text = Gtk.CellRendererText()
21 column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0)
22 treeview.append_column(column_text)
23
24 renderer_toggle = Gtk.CellRendererToggle()
25 renderer_toggle.connect("toggled", self.on_cell_toggled)
26
27 column_toggle = Gtk.TreeViewColumn("Toggle", renderer_toggle, active=1)
28 treeview.append_column(column_toggle)
29
30 renderer_radio = Gtk.CellRendererToggle()
31 renderer_radio.set_radio(True)
32 renderer_radio.connect("toggled", self.on_cell_radio_toggled)
33
34 column_radio = Gtk.TreeViewColumn("Radio", renderer_radio, active=2)
35 treeview.append_column(column_radio)
36
37 self.add(treeview)
38
39 defon_cell_toggled(self, widget, path):
40 self.liststore[path][1] = not self.liststore[path][1]
41
42 defon_cell_radio_toggled(self, widget, path):
43 selected_path = Gtk.TreePath(path)
44 for row in self.liststore:
45 row[2] = row.path == selected_path
46
47
48win = CellRendererToggleWindow()
49win.connect("destroy", Gtk.main_quit)
50win.show_all()
51Gtk.main()

14.3. CellRendererPixbuf

A Gtk.CellRendererPixbuf can be used to render an image in a cell. It allows to render either a given Gdk.Pixbuf (set via the "pixbuf" property) or a named icon (set via the "icon-name" property).

14.3.1. Example

_images/cellrendererpixbuf_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk
 5
 6
 7classCellRendererPixbufWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererPixbuf Example")
10
11 self.set_default_size(200, 200)
12
13 self.liststore = Gtk.ListStore(str, str)
14 self.liststore.append(["New", "document-new"])
15 self.liststore.append(["Open", "document-open"])
16 self.liststore.append(["Save", "document-save"])
17
18 treeview = Gtk.TreeView(model=self.liststore)
19
20 renderer_text = Gtk.CellRendererText()
21 column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0)
22 treeview.append_column(column_text)
23
24 renderer_pixbuf = Gtk.CellRendererPixbuf()
25
26 column_pixbuf = Gtk.TreeViewColumn("Image", renderer_pixbuf, icon_name=1)
27 treeview.append_column(column_pixbuf)
28
29 self.add(treeview)
30
31
32win = CellRendererPixbufWindow()
33win.connect("destroy", Gtk.main_quit)
34win.show_all()
35Gtk.main()

14.4. CellRendererCombo

Gtk.CellRendererCombo renders text in a cell like Gtk.CellRendererText from which it is derived. But while the latter offers a simple entry to edit the text, Gtk.CellRendererCombo offers a Gtk.ComboBox widget to edit the text. The values to display in the combo box are taken from the Gtk.TreeModel specified in the "model" property.

The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its "text-column" property.

A Gtk.CellRendererCombo can operate in two modes. It can be used with and without an associated Gtk.Entry widget, depending on the value of the "has-entry" property.

14.4.1. Example

_images/cellrenderercombo_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk
 5
 6
 7classCellRendererComboWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererCombo Example")
10
11 self.set_default_size(200, 200)
12
13 liststore_manufacturers = Gtk.ListStore(str)
14 manufacturers = ["Sony", "LG", "Panasonic", "Toshiba", "Nokia", "Samsung"]
15 for item in manufacturers:
16 liststore_manufacturers.append([item])
17
18 self.liststore_hardware = Gtk.ListStore(str, str)
19 self.liststore_hardware.append(["Television", "Samsung"])
20 self.liststore_hardware.append(["Mobile Phone", "LG"])
21 self.liststore_hardware.append(["DVD Player", "Sony"])
22
23 treeview = Gtk.TreeView(model=self.liststore_hardware)
24
25 renderer_text = Gtk.CellRendererText()
26 column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0)
27 treeview.append_column(column_text)
28
29 renderer_combo = Gtk.CellRendererCombo()
30 renderer_combo.set_property("editable", True)
31 renderer_combo.set_property("model", liststore_manufacturers)
32 renderer_combo.set_property("text-column", 0)
33 renderer_combo.set_property("has-entry", False)
34 renderer_combo.connect("edited", self.on_combo_changed)
35
36 column_combo = Gtk.TreeViewColumn("Combo", renderer_combo, text=1)
37 treeview.append_column(column_combo)
38
39 self.add(treeview)
40
41 defon_combo_changed(self, widget, path, text):
42 self.liststore_hardware[path][1] = text
43
44
45win = CellRendererComboWindow()
46win.connect("destroy", Gtk.main_quit)
47win.show_all()
48Gtk.main()

14.5. CellRendererProgress

Gtk.CellRendererProgress renders a numeric value as a progress bar in a cell. Additionally, it can display a text on top of the progress bar.

The percentage value of the progress bar can be modified by changing the "value" property. Similar to Gtk.ProgressBar, you can enable the activity mode by incrementing the "pulse" property instead of the "value" property.

14.5.1. Example

_images/cellrendererprogress_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk, GLib
 5
 6
 7classCellRendererProgressWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererProgress Example")
10
11 self.set_default_size(200, 200)
12
13 self.liststore = Gtk.ListStore(str, int, bool)
14 self.current_iter = self.liststore.append(["Sabayon", 0, False])
15 self.liststore.append(["Zenwalk", 0, False])
16 self.liststore.append(["SimplyMepis", 0, False])
17
18 treeview = Gtk.TreeView(model=self.liststore)
19
20 renderer_text = Gtk.CellRendererText()
21 column_text = Gtk.TreeViewColumn("Text", renderer_text, text=0)
22 treeview.append_column(column_text)
23
24 renderer_progress = Gtk.CellRendererProgress()
25 column_progress = Gtk.TreeViewColumn(
26 "Progress", renderer_progress, value=1, inverted=2
27 )
28 treeview.append_column(column_progress)
29
30 renderer_toggle = Gtk.CellRendererToggle()
31 renderer_toggle.connect("toggled", self.on_inverted_toggled)
32 column_toggle = Gtk.TreeViewColumn("Inverted", renderer_toggle, active=2)
33 treeview.append_column(column_toggle)
34
35 self.add(treeview)
36
37 self.timeout_id = GLib.timeout_add(100, self.on_timeout, None)
38
39 defon_inverted_toggled(self, widget, path):
40 self.liststore[path][2] = not self.liststore[path][2]
41
42 defon_timeout(self, user_data):
43 new_value = self.liststore[self.current_iter][1] + 1
44 if new_value > 100:
45 self.current_iter = self.liststore.iter_next(self.current_iter)
46 if self.current_iter is None:
47 self.reset_model()
48 new_value = self.liststore[self.current_iter][1] + 1
49
50 self.liststore[self.current_iter][1] = new_value
51 return True
52
53 defreset_model(self):
54 for row in self.liststore:
55 row[1] = 0
56 self.current_iter = self.liststore.get_iter_first()
57
58
59win = CellRendererProgressWindow()
60win.connect("destroy", Gtk.main_quit)
61win.show_all()
62Gtk.main()

14.6. CellRendererSpin

Gtk.CellRendererSpin renders text in a cell like Gtk.CellRendererText from which it is derived. But while the latter offers a simple entry to edit the text, Gtk.CellRendererSpin offers a Gtk.SpinButton widget. Of course, that means that the text has to be parseable as a floating point number.

The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. Gtk.CellRendererSpin also has properties for the climb rate and the number of digits to display.

14.6.1. Example

_images/cellrendererspin_example.png 
 1importgi
 2
 3gi.require_version("Gtk", "3.0")
 4fromgi.repositoryimport Gtk
 5
 6
 7classCellRendererSpinWindow(Gtk.Window):
 8 def__init__(self):
 9 super().__init__(title="CellRendererSpin Example")
10
11 self.set_default_size(200, 200)
12
13 self.liststore = Gtk.ListStore(str, int)
14 self.liststore.append(["Oranges", 5])
15 self.liststore.append(["Apples", 4])
16 self.liststore.append(["Bananas", 2])
17
18 treeview = Gtk.TreeView(model=self.liststore)
19
20 renderer_text = Gtk.CellRendererText()
21 column_text = Gtk.TreeViewColumn("Fruit", renderer_text, text=0)
22 treeview.append_column(column_text)
23
24 renderer_spin = Gtk.CellRendererSpin()
25 renderer_spin.connect("edited", self.on_amount_edited)
26 renderer_spin.set_property("editable", True)
27
28 adjustment = Gtk.Adjustment(
29 value=0,
30 lower=0,
31 upper=100,
32 step_increment=1,
33 page_increment=10,
34 page_size=0,
35 )
36 renderer_spin.set_property("adjustment", adjustment)
37
38 column_spin = Gtk.TreeViewColumn("Amount", renderer_spin, text=1)
39 treeview.append_column(column_spin)
40
41 self.add(treeview)
42
43 defon_amount_edited(self, widget, path, value):
44 self.liststore[path][1] = int(value)
45
46
47win = CellRendererSpinWindow()
48win.connect("destroy", Gtk.main_quit)
49win.show_all()
50Gtk.main()