SWT: Do You Know the Difference between Tree#select and Tree#setSelection?
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 1.
According to the JavaDoc the method
Tree#select(TreeItem) ‘Selects an item in the receiver’2 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
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
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 companions3.
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 perfectly 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 documentation4.
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
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 systems5. Therefore it was omitted from the API providing the lowest common denominator.
- If you came here using google search, maybe google knows now… ↩
- I guess ‘receiver’ refers to the native instance of
Treewhose item should be selected ↩
- Actually this decision was made by chance, as I first stumbled across
selectand did not recognize that there is such a thing as
setSelection. At that point it seemed to be what I was looking for ↩
- Always ready and willing to blame others for my failure ↩
- Unfortunately I have lost the reference, so you will have to take my word for it – which is not much, I know… ↩