Actually I did not, neither did Google and the API documentation seems to miss out one crucial point – which took me some time to figure out. So I decided to be a nice boy scout and share my findings as my good deed of the day .

According to the JavaDoc the method Tree#select(TreeItem) ‘Selects an item in the receiver’ while Tree#setSelection(TreeItem) ‘Sets the receiver’s selection to the given item’. The difference is made clear by the subsequent remark on setSelection : ‘The current selection is cleared before the new item is selected’. The latter does not happen if you choose to go with select which is perfectly alright if think about it – even if it is not explicitly mentioned in the documentation. And consequently there are a couple of other methods like Tree.deselect(TreeItem) or Tree.deselectAll() .

On first sight Tree.setSelection(TreeItem) and its overloaded sister Tree.setSelection(TreeItem[]) seem to be some kind of convenience methods replacing subsequent calls to deselect , select by a single statement. However there is more than meets the eye and I had to learn it the hard way, because I decided to go with select and its companions .

Tree#select(TreeItem) does not influence which tree item has the focus while Tree#setSelection(TreeItem) does. This is quite important and – again, if you think about it – makes perfect sense as manipulation of the selection without changing the focus item is a valid use case. But as it was not obvious to me I thought it would not have been wrong to mention it in the documentation .

As a picture is worth a thousand words have look at image below that illustrates the situation:

In the example the selection has been set to the fourth node by subsequent calls to deselect and select . But as you can see, the focus stays on the first node. If the user now uses the arrow-down key for example the second node would be selected. Which is not how it what was intended. Using setSelection instead does the trick and the focus item is the same as the selected item:

The attentive reader might wonder: As there is a method to manipulate the selection without changing the focus item, is there also a method to change the focus item without changing the selection? Well, I could not find one. But there is an understandable explanation why. It seems that changing the tree’s focus item alone is not supported on all operating systems . Therefore it was omitted from the API providing the lowest common denominator.