hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-28 01:07:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

[site] Lists and Trees: cleanup

Browse Source
This commit is contained in:
Anna Bulenkova 2015-03-25 10:22:15 +01:00
parent d774b2ae99
commit db1b5fade0
1 changed files with 58 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
lists_and_trees.md
View File

@ -10,34 +10,77 @@ INITIAL_SOURCE https://confluence.jetbrains.com/display/IDEADEV/IntelliJ+IDEA+Li
### JBList and Tree
Whenever you would normally use a standard Swing JList component, it's recommended to use the ```JBList``` class as drop-in replacement.
JBList supports the following additional features on top of JList:
Whenever you would normally use a standard
[Swing JList](http://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html)
component, it's recommended to use the
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java)
class as drop-in replacement.
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java)
supports the following additional features on top of
[JList]((http://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html)):
* Drawing a tooltip with complete text of an item if the item doesn't fit into the list box width
* Drawing a tooltip with complete text of an item if the item doesn't fit into the list box width.
* Drawing a gray text message in the middle of the list box when it contains no items (the text can be customized by calling ```getEmptyText().setText()```)
* Drawing a gray text message in the middle of the list box when it contains no items.
The text can be customized by calling ```getEmptyText().setText()```.
* Drawing a busy icon in the top right corner of the list box to indicate that a background operation is being performed (enabled by calling ```setPaintBusy()```)
* Drawing a busy icon in the top right corner of the list box to indicate that a background operation is being performed.
This can be enabled by calling ```setPaintBusy()```.
Similarly, the ```com.intellij.ui.treeStructure.Tree``` class provides a replacement for the standard JTree class. In addition to the features of JBList, it supports wide selection painting (Mac style) and auto-scroll on drag & drop.
Similarly, the
[Tree](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/treeStructure/Tree.java)
class provides a replacement for the standard
[JTree](http://docs.oracle.com/javase/8/docs/api/javax/swing/JTree.html)
class.
In addition to the features of
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java),
it supports wide selection painting (Mac style) and auto-scroll on drag & drop.
### ColoredListCellRenderer and ColoredTreeCellRenderer
When you need to customize the presentation of items in a list box or a tree, it's recommended to use the ```ColoredListCellRenderer``` or ```ColoredTreeCellRenderer``` classes as the cell renderer. These classes allow you to compose the presentation out of multiple text fragments with different attributes (by calling ```append()```) and to set an optional icon for the item (by calling ```setIcon```). The renderer automatically takes care of setting the correct text color for selected items and of many other platform-specific rendering details.
When you need to customize the presentation of items in a list box or a tree, it's recommended to use the
[ColoredListCellRenderer](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ColoredListCellRenderer.java)
or
[ColoredTreeCellRenderer](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ColoredTreeCellRenderer.java)
classes as the cell renderer.
These classes allow you to compose the presentation out of multiple text fragments with different attributes by calling ```append()``` and to set an optional icon for the item by calling ```setIcon```.
The renderer automatically takes care of setting the correct text color for selected items and of many other platform-specific rendering details.
### ListSpeedSearch and TreeSpeedSearch
To facilitate keyboard-based selection of items in a list box or a tree, you can install a speed search handler on it. This can be done simply by calling ```new ListSpeedSeach(list)``` or ```new TreeSpeedSearch(tree)```. If you need to customize the text which is used to locate the element, you can override the ```getElementText()``` method. Alternatively, you can pass a function to convert items to strings (as ```elementTextDelegate``` to the ListSpeedSearch constructor or as ```toString``` to the TreeSpeedSearch constructor).
To facilitate keyboard-based selection of items in a list box or a tree, you can install a speed search handler on it using the
[ListSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
and
[TreeSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java).
This can be done simply by calling ```new ListSpeedSeach(list)``` or ```new TreeSpeedSearch(tree)```.
If you need to customize the text which is used to locate the element, you can override the ```getElementText()``` method.
Alternatively, you can pass a function to convert items to strings.
A function needs to be passed as ```elementTextDelegate``` to the
[ListSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
constructor or as ```toString``` to the
[TreeSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java)
constructor.
### ToolbarDecorator
A very common task in plugin development is showing a list or a tree where the user is allowed to add, remove, edit or reorder the items. The implementation of this task is greatly facilitated by the ```ToolbarDecorator``` class. This class provides a toolbar with actions on items and automatically enables drag & drop reordering of items in list boxes if supported by the underlying list model. The position of the toolbar (above or below the list) depends on the platform under which IntelliJ IDEA is running.
A very common task in plugin development is showing a list or a tree where the user is allowed to add, remove, edit or reorder the items.
The implementation of this task is greatly facilitated by the
[ToolbarDecorator](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
class.
This class provides a toolbar with actions on items and automatically enables drag & drop reordering of items in list boxes if supported by the underlying list model.
The position of the toolbar above or below the list depends on the platform under which *IntelliJ IDEA* is running.
To use a toolbar decorator:
* If you need to support removing and reordering of items in a list box, make sure the model of your list implements the ```EditableModel``` interface. ```CollectionListModel``` is a handy model class that implements this interface.
* If you need to support removing and reordering of items in a list box, make sure the model of your list implements the
[EditableModel](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/util/ui/EditableModel.java)
interface.
[CollectionListModel](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/CollectionListModel.java)
is a handy model class that implements this interface.
* Call ```ToolbarDecorator.createDecorator``` to create a decorator instance.
* Call
[ToolbarDecorator.createDecorator](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
to create a decorator instance.
* If you need to support adding and/or removing items, call ```setAddAction()``` and/or ```setRemoveAction()```.
@ -45,7 +88,10 @@ To use a toolbar decorator:
* Call ```createPanel()``` and add the component it returns to your panel.
<!--
### AbstractTreeBuilder and AbstractTreeStructure
TODO link to tutorial
-->
TBD