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 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 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 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 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 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 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
Tree
whose item should be selected ↩ - Actually this decision was made by chance, as I first stumbled across
select
and did not recognize that there is such a thing assetSelection
. 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… ↩
- Xmas Clean Sheet Update (0.9) - 21. December 2021
- Clean Sheet Service Update (0.8) - 23. May 2020
- Clean Sheet Service Update (0.7) - 24. April 2020
I’m waiting for your patch improving the documentation :).
Well, good point – maybe that will be my good deed of tomorrow ;-)
Interesting! I didn’t know that either.
BTW, the term “receiver” is used throughout the SWT API documentation to denote the object that a method has been called on (i.e. “this”). I understand it as a reference to message passing style – thinking about a method invocation as sending a (synchronous) message to the object, I guess old SmallTalkers prefer to see it this way ;-).