In this example we will step through the code of the Tree List example. The source code of the entire example is available as leafs of the tree. Note that Wt offers a Tree List widget as part of the library (see WTreeNode), of which this example is a down-stripped version.
The example in particular demonstrates the use of stateless slot learning to simultaneously implement client-side and server-side event handling in C++.
The tree constructed as hierarchy of tree nodes. A single tree node is implemented in the class TreeNode. TreeNode uses the helper class IconPair for rendering icons that have a state (such as the expand/collapse icons). We start with a walk-over of this class.
For the implementation of the tree list expand/collapse icons, as well as the label icons (such as the folder icon), we use class IconPair. It takes a pair of icons and shows only one at a time. Passing clickIsSwitch = true to the constructor will make the icon react to click events to switch the current icon.
This is the class definition of IconPair:
IconPair is a composite widget, implemented as a WContainerWidget which contains two WImage objects. The class defines two slots: IconPair::showIcon1() and IconPair::showIcon2(), which show the respective icon, while hiding the other icon.
The key concept behind Wt's capability to implement things at the client-side is stateless slot implementations. A stateless slot is, besides a normal C++ function that may be connected to a signal, a C++ function that promises to always have the same behaviour (until it is reset, as we will see later).
This applies to the two functions showIcon1() and showIcon2(), as they simply set the corresponding icon, irrespective of any application state. The library offers two methods for stateless slot implementations: AutoLearned and PreLearned. An AutoLearned stateless slot will only "become client-side" after the first invocation. Applied to our tree widget, this would mean that the first click on any icon would require a round-trip to the server the first time only. An AutoLearned stateless slot simply requires an indication that the particular slot confirms to the contract of being stateless. A PreLearned stateless slot, on the other hand, is "client-side" from the first invocation. To implement a PreLearned stateless however, we need to do some extra work by providing methods that exactly undo the effect of the slot. We provide here two such undo methods: undoShowIcon1() and undoShowIcon2().
Enough talk! Let's look at the implementation, starting with the constructor.
IconPair inherits from WCompositeWidget. A composite widget is a widget which is composed from other widgets, in a way not exposed in its API. In this way, you may later change the implementation without any problem.
Notice how we constructed three widgets that are used in the implementation: two images (icon1_ and icon2_), and a container (impl_) to hold them. The images are added to the container by passing the container as the last argument in their constructor.
We declare the slots showIcon1() and showIcon2() as stateless slots, allowing for client-side optimisation, and offer an undo function which facilitates a PreLearned client-side implementation.
The calls to WObject::implementStateless() state that the slots showIcon1() and showIcon2() are stateless slots, and their visual effect may be learned in advance. The effect of these statements is merely an optimization. Any non-visual effects of these slots are still propagated and executed, as expected.
Next, we declare the widget to be an inline widget. An inline widget will be layed out following the natural flow of text (left to right). This does not really matter for our example, since TreeNode will do the layout with a WTable, but we do so to provide consistency with a WImage which is also inline by default.
The initial state is to show the first icon:
To react to click events, we connect signals with slots:
We change the cursor to a pointer to hint that clicking these icons may do something useful.
We also change the cursor to a pointer to hint that clicking these icons will in fact perform an action.
The rest of the class definition is:
Note the implementations of undoShowIcon1() and undoShowIcon2(): they simply, but accurately, reset the state to what it was before the respective showIcon1() and showIcon2() calls.
TreeNode contains the implementation of the tree, as a hierarchy of tree nodes. The layout of a single node is done using a 2x2 WTable:
|-----------------------| | +/- | label | |------------------------ | | child1 | | | child2 | | | child3 | | | ... | |-----------------------|
The TreeNode manages a list of child nodes in a WContainerWidget which will be hidden and shown when the node is expanded or collapsed, and children are collapsed when the node is expanded.
This is the TreeNode class definition:
The public interface of the TreeNode provides methods to manage its children, and two public slots to expand or collapse the node. Remember, a slot is nothing more than a method (and the public slots: does not actually mean anything, except providing a hint to the user of this class that these methods are made to be connected to signals).
We start with the implementation of the constructor:
We start with declaring stateless implementations for the slots. It is good practice to do this first, since it must be done before any connections are made to the slots.
We will implement the treenode as 2 by 2 table.
We create all icons. Since currently the node is empty, we only show the no-expand version (which is simply a horizontal line).
The expanded content is a WContainerWidget.
We create the label and child count text widgets:
Now we add all widgets in the proper table cell, and set the correct alignment.
Finally, we connect the click events of the expandIcon to the expand and collapse slots.
WTable::elementAt(int row, int column) is used repeatedly to add or modify contents of the table cells, expanding the table geometry as needed. Finally, we make connections from the expand and collapse icons to the slots we define in the TreeNode class.
The "business logic" of the TreeNode is simply to manage its children. Whenever a child is added or removed, adjustments to its look are updated by calling childNodesChanged().
The expand icon of the last child is rendered differently, as it needs to terminate the vertical guide line. To keep the implementation simple, we simply let every child reset its proper look by calling adjustExpandIcon().
When getting a first child, or losing the last child, the expand icon changes too.
We also update the childCount label.
Finally, we call WObject::resetLearnedSlots(). Because the expand() slot depends on the number of children, because it needs to collapse all children – this slot is not entirely stateless, breaking the contract for a stateless slot. However, we can get away with still implementing as a stateless slot, by indicating when the state has changed.
The implementation of the collapse slot is as follows:
First we record the current state, so the undo method can exactly undo what happened.
Next, we implement the actual collapse logic:
Similarly, the implementation of the expand slot. However, in this case we need to collapse all children as well.
Since we implement these slots as prelearned stateless slots, we also need to define the undo functions. Note that Because expand() also collapses all child nodes, the undo function of expand() is not simply collapse() and vice-versa.
Finally, the adjustExpandIcon() function sets the correct images, which depends on how the node relates to its siblings. The last node looks a bit different.
We set the expand icon images:
Then, we set the vertical guide line if not the last child, and nothing if the last child:
Finally, we select the correct icon, depending on whether the node has children: