SWT: Do You Know the Difference between Tree#select and Tree#setSelection?

Home  >>  Eclipse  >>  SWT: Do You Know the Difference between Tree#select and Tree#setSelection?

SWT: Do You Know the Difference between Tree#select and Tree#setSelection?

On March 5, 2014, Posted by , In Eclipse, By ,,,,,, , With 3 Comments

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:

See also  A JUnit Rule to Ease SWT Test Setup

tree-selection

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:

tree-set-selection

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.


  1. If you came here using Google search, maybe Google knows now… ;-)
  2. I guess ‘receiver’ refers to the native instance of Tree whose item should be selected
  3. Actually this decision was made by chance, as I first stumbled across select and did not recognize that there is such a thing as setSelection. At that point it seemed to be what I was looking for
  4. Always ready and willing to blame others for my failure :-)
  5. Unfortunately, I have lost the reference, so you will have to take my word for it – which is not much, I know…
Frank Appel
Follow me

3 Comments so far:

  1. Alexander Kurtakov says:

    I’m waiting for your patch improving the documentation :).

    • Frank Appel says:

      Well, good point – maybe that will be my good deed of tomorrow ;-)

  2. Ralf Sternberg says:

    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 ;-).