wxPython: Learning About TreeCtrls

the wxpython gui toolkit comes with many widgets. a common control is a tree widget. wxpython has several different tree widgets, including the regular wx.treectrl , the newer dvc_treectrl , and the pure python variants, customtreectrl and hypertreelist . in this article, we will focus on the regular wx.treectrl and learn the basics of how to create and use one.

creating a simple tree

creating a treectrl is actually quite easy. the wxpython demo has a fairly complex example, so i wasn’t able to use it here. instead, i ended up taking the demo example and stripping it down as much as i could. here’s the result:

import wx
 
class mytree(wx.treectrl):
 
    def __init__(self, parent, id, pos, size, style):
        wx.treectrl.__init__(self, parent, id, pos, size, style)
 
 
class treepanel(wx.panel):
 
    def __init__(self, parent):
        wx.panel.__init__(self, parent)
 
        self.tree = mytree(self, wx.id_any, wx.defaultposition, wx.defaultsize,
                           wx.tr_has_buttons)    
 
        self.root = self.tree.addroot('something goes here')
        self.tree.setpydata(self.root, ('key', 'value'))
        os = self.tree.appenditem(self.root, 'operating systems')
        self.tree.expand(self.root)
 
        sizer = wx.boxsizer(wx.vertical)
        sizer.add(self.tree, 0, wx.expand)
        self.setsizer(sizer)
 
 
class mainframe(wx.frame):
 
    def __init__(self):
        wx.frame.__init__(self, parent=none, title='treectrl demo')
        panel = treepanel(self)
        self.show()
 
 
if __name__ == '__main__':
    app = wx.app(redirect=false)
    frame = mainframe()
    app.mainloop()

in this example, we create a subclass of wx.treectrl that doesn’t do anything. then, we create a panel subclass where we instantiate the tree and add a root and sub-item. finally, we create the frame that holds the panel and we run the application. you should end up with something that looks similar to the following:

this is a pretty boring example, so let’s make something a bit more interesting.

creating an xml viewer

something that i’ve wanted to do for some time now is to create an xml editor with python. to get started, i wrote some code a couple of weekends ago that could read xml into a treectrl for viewing the tag elements. for this example, i will be using some sample xml i found on microsoft’s msdn website :

<?xml version="1.0"?>
<catalog>
    <book id="bk101">
        <author>gambardella, matthew</author>
        <title>xml developer's guide</title>
        <genre>computer</genre>
        <price>44.95</price>
        <publish_date>2000-10-01</publish_date>
        <description>an in-depth look at creating applications 
        with xml.</description>
    </book>
    <book id="bk102">
        <author>ralls, kim</author>
        <title>midnight rain</title>
        <genre>fantasy</genre>
        <price>5.95</price>
        <publish_date>2000-12-16</publish_date>
        <description>a former architect battles corporate zombies, 
        an evil sorceress, and her own childhood to become queen 
        of the world.</description>
    </book>
    <book id="bk103">
        <author>corets, eva</author>
        <title>maeve ascendant</title>
        <genre>fantasy</genre>
        <price>5.95</price>
        <publish_date>2000-11-17</publish_date>
        <description>after the collapse of a nanotechnology 
        society in england, the young survivors lay the 
        foundation for a new society.</description>
    </book>
    <book id="bk104">
        <author>corets, eva</author>
        <title>oberon's legacy</title>
        <genre>fantasy</genre>
        <price>5.95</price>
        <publish_date>2001-03-10</publish_date>
        <description>in post-apocalypse england, the mysterious 
        agent known only as oberon helps to create a new life 
        for the inhabitants of london. sequel to maeve 
        ascendant.</description>
    </book>
    <book id="bk105">
        <author>corets, eva</author>
        <title>the sundered grail</title>
        <genre>fantasy</genre>
        <price>5.95</price>
        <publish_date>2001-09-10</publish_date>
        <description>the two daughters of maeve, half-sisters, 
        battle one another for control of england. sequel to 
        oberon's legacy.</description>
    </book>
    <book id="bk106">
        <author>randall, cynthia</author>
        <title>lover birds</title>
        <genre>romance</genre>
        <price>4.95</price>
        <publish_date>2000-09-02</publish_date>
        <description>when carla meets paul at an ornithology 
        conference, tempers fly as feathers get ruffled.</description>
    </book>
    <book id="bk107">
        <author>thurman, paula</author>
        <title>splish splash</title>
        <genre>romance</genre>
        <price>4.95</price>
        <publish_date>2000-11-02</publish_date>
        <description>a deep sea diver finds true love twenty 
        thousand leagues beneath the sea.</description>
    </book>
    <book id="bk108">
        <author>knorr, stefan</author>
        <title>creepy crawlies</title>
        <genre>horror</genre>
        <price>4.95</price>
        <publish_date>2000-12-06</publish_date>
        <description>an anthology of horror stories about roaches,
        centipedes, scorpions  and other insects.</description>
    </book>
    <book id="bk109">
        <author>kress, peter</author>
        <title>paradox lost</title>
        <genre>science fiction</genre>
        <price>6.95</price>
        <publish_date>2000-11-02</publish_date>
        <description>after an inadvertant trip through a heisenberg
        uncertainty device, james salway discovers the problems 
        of being quantum.</description>
    </book>
    <book id="bk110">
        <author>o'brien, tim</author>
        <title>microsoft .net: the programming bible</title>
        <genre>computer</genre>
        <price>36.95</price>
        <publish_date>2000-12-09</publish_date>
        <description>microsoft's .net initiative is explored in 
        detail in this deep programmer's reference.</description>
    </book>
    <book id="bk111">
        <author>o'brien, tim</author>
        <title>msxml3: a comprehensive guide</title>
        <genre>computer</genre>
        <price>36.95</price>
        <publish_date>2000-12-01</publish_date>
        <description>the microsoft msxml3 parser is covered in 
        detail, with attention to xml dom interfaces, xslt processing, 
        sax and more.</description>
    </book>
    <book id="bk112">
        <author>galos, mike</author>
        <title>visual studio 7: a comprehensive guide</title>
        <genre>computer</genre>
        <price>49.95</price>
        <publish_date>2001-04-16</publish_date>
        <description>microsoft visual studio 7 is explored in depth,
        looking at how visual basic, visual c++, c#, and asp+ are 
        integrated into a comprehensive development 
        environment.</description>
    </book>
</catalog>

the first thing we need to decide is what python xml parser we want to use. i personally like lxml the best, but python’s own elementtree is certainly a viable option and actually quite easy to switch too if you start out with lxml . but for this example, we will be using lxml . let’s take a look:

import wx
 
from lxml import etree, objectify
 
 
class xmltree(wx.treectrl):
 
    def __init__(self, parent, id, pos, size, style):
        wx.treectrl.__init__(self, parent, id, pos, size, style)
 
        try:
            with open(parent.xml_path) as f:
                xml = f.read()
        except ioerror:
            print('bad file')
            return
        except exception as e:
            print('really bad error')
            print(e)
            return
 
        self.xml_root = objectify.fromstring(xml)
 
        root = self.addroot(self.xml_root.tag)
        self.setpydata(root, ('key', 'value'))        
 
        for top_level_item in self.xml_root.getchildren():
            child = self.appenditem(root, top_level_item.tag)
            self.setitemhaschildren(child)
            if top_level_item.attrib:
                self.setpydata(child, top_level_item.attrib)
 
        self.expand(root)
        self.bind(wx.evt_tree_item_expanding, self.onitemexpanding)
 
    def onitemexpanding(self, event):
        item = event.getitem()
        book_id = self.getpydata(item)
 
        for top_level_item in self.xml_root.getchildren():
            if top_level_item.attrib == book_id:
                book = top_level_item
                self.setpydata(item, top_level_item)                                
                self.add_book_elements(item, book)
                break
 
    def add_book_elements(self, item, book):
        for element in book.getchildren():
            child = self.appenditem(item, element.tag)
            if element.getchildren():
                self.setitemhaschildren(child)
 
            if element.attrib:
                self.setpydata(child, element.attrib)  
 
 
class treepanel(wx.panel):
 
    def __init__(self, parent, xml_path):
        wx.panel.__init__(self, parent)
        self.xml_path = xml_path
 
        self.tree = xmltree(self, wx.id_any, wx.defaultposition, wx.defaultsize,
                            wx.tr_has_buttons)    
 
        sizer = wx.boxsizer(wx.vertical)
        sizer.add(self.tree, 0, wx.expand)
        self.setsizer(sizer)
 
 
class mainframe(wx.frame):
 
    def __init__(self, xml_path):
        wx.frame.__init__(self, parent=none, title='xml editor')
        panel = treepanel(self, xml_path)
        self.show()
 
 
if __name__ == '__main__':
    xml_path = 'books.xml'
    app = wx.app(redirect=false)
    frame = mainframe(xml_path)
    app.mainloop()

the main change here is in the treectrl subclass, although we had to make some small modifications in the other classes to pass in the xml file path. let’s focus on the treectrl class though. first, we read the xml from the file and load it into lxml ’s objectify module. at this point, we have an xml object that we can use to populate the treectrl with data. so we add the root and then loop over the top-level children in the xml. for each top level element, we add an item to the root of the treectrl . this is extremely basic as we should also be checking each element to see if it has children too. we don’t. instead, we just assume that it does and call the treectrl ’s setitemhaschildren() method. this adds an arrow to the element to allow expanding of the element.

lastly we expand the root and bind an event to evt_tree_item_expanding which will allow us to update the sub-elements when they get expanded. you can see how this is done in the onitemexpanding event handler and the add_book_elements() which is called by the event handler. here we actually do check the element to see if it has children using lxml ’s getchildren() . if it does, then we call setitemhaschildren() . the other thing i want to point out is all the calls to setpydata() . the setpydata() method is for saving data into the tree item. in this case, we are saving the xml element into the tree item itself, which we can get access to again via getpydata() . this will be important if we want to add editing functionality to the gui.

other odds and ends

the wxpython demo also demonstrates some interesting tidbits. for example, it shows that you can add a wx.imagelist to your treectrl . it also shows some of the other tree specific events you can bind to. such as:

• evt_tree_item_collapsed
  
• evt_tree_sel_changed
  
• evt_tree_begin_label_edit
  
• evt_tree_end_label_edit
  
• evt_tree_item_activated
  

of course, you can also bind to mouse events like evt_left_dclick and evt_right_down too.

if you’d like to make the tree elements editable, then you’ll need to pass the wx.tr_edit_labels style flag in when you instantiate the tree. since my example is just a viewer, i didn’t feel the need to do that. there are some other style flags mentioned in the demo and in the documentation that you may also want to check out.

wrapping up

at this point, i think you should be able to get started using wxpython’s handy wx.treectrl . it is quite powerful and easy to utilize. should you find yourself needing to do something more custom, then i highly recommend checking out one of wxpython’s alternate tree controls, such as the customtreectrl or hypertreelist .