Custom Drawing Table and Tree Items

Summary Populating a table or tree widget involves creating items and setting their attributes (eg.- texts, images, etc.), after which the table or tree takes responsibility for displaying the items. This approach makes item creation straightforward and visually consistent. As of Eclipse 3.2, clients of Table and Tree can now custom draw their items, enabling a wide range of potential visual appearances. This article explores the custom draw mechanism for Table and Tree.
By Grant Gayed, IBM Ottawa Lab September 15th, 2006 (updated to include SWT.HOT style on June 8, 2007)
Tables and trees are powerful tools for presenting data in a structured manner. Data is displayed as a collection of items which have attributes like text(s), image(s), and sometimes interactive controls such as checkboxes. Typically, clients create the items and set their attributes, after which the table or tree takes responsibility for displaying them. This approach makes item creation straightforward and visually consistent, but is inflexible. For example, an item in a table or tree can only contain one image, and it must appear before its text. Given the range of visual appearances that a client may want an item to have, the best way to ensure that clients can create items with custom appearances is to allow items to be drawn.
The ability to partially or fully custom draw TableItems and TreeItems has been added as of Eclipse 3.2, and will be described in this article. It should be noted that all references made throughout the article to tables can be equally applied to trees, and vice versa.
Custom drawing is done on a per-cell basis, where a cell is the portion of an item that resides within some row and column of the parent table, or the full item if the table has no columns. For example, if a table has two columns and three items then it has six cells.
The following Table events have been defined to provide hooks into the drawing process:
To minimize the amount of work required to draw cells, these events are configured to reflect how the cell would be drawn by default. This makes it easy to augment a cell’s default appearance without having to draw the whole cell. If a client does not hook one of these listeners then the default cell drawing process will occur. The following sections will examine each of these events in detail along with some example code snippets.
SWT.MeasureItem is the first custom draw event that is sent. This event gives a client the opportunity to specify the width and/or height of a cell’s content. It is important to note that content size is not necessarily equivalent to cell size, since the latter may include additional decorations such as checkboxes or tree indentation. Contexts where this event is typically sent include drawing a cell and packing a table column. This event comes pre-configured with the following fields:
An application that wishes to specify a different content width and/or height for the cell can do so by changing the event’s width and height fields. A listener may choose to not change one or both of these values.
Listing 1 (snippet) demonstrates the use of SWT.MeasureItem to specify custom content dimensions in a table with no columns.
Listing 1. Specifying custom widths and heights for items in a table with no columns
Lines 1-3: Creates a display and shell, and sets the shell’s bounds.
Lines 4-6: Creates the table with no columns, sets its bounds, and sets its lines to be visible.
Lines 7-9: Creates the table’s items.
Lines 10-11 Adds an SWT.MeasureItem listener to the table, which will be invoked whenever the size of a cell’s content is needed.
Line 12: Gets the table’s client width, which will be used when specifying the cell's content width.
Line 13: Sets the event’s height field to double the height of the font. This effectively doubles the height of the item in the event’s item field relative to its default height.
Line 14: Sets the event’s width field to double the width of the table. This specifies that the width of the cell should be this value regardless of its content. Note that since this table has no columns, the width of the cell is equivalent to that of the full item.
Lines 17 to 21: Opens the shell, runs the event loop until the shell has been disposed, and disposes the display just before exiting.
Figure 1 shows a screenshot of the snippet in Listing 1 running. Note the increased item heights (caused by line 13), and increased item widths (caused by line 14) which can be inferred from the table’s horizontal scrollbar. Figure 2 shows a screenshot of the same snippet running with lines 10 through 16 commented out, allowing the table to draw in its default manner.
Figure 1. Screenshot of Listing 1 running, which specifies custom widths and heights for the items in a table
Figure 2. Screenshot of Listing 1 running without the SWT.MeasureItem listener
Note that attempts to change a cell’s width or height in SWT.MeasureItem events are subject to the following constraints:
Listing 2 (snippet) demonstrates the use of SWT.MeasureItem to specify cell widths when a table column is packed.
Listing 2. Specifying custom cell content widths that are used by TableColumn.pack() to size a column
Lines 1-3: Creates a display and shell, and sets the shell’s bounds.
Lines 4-7: Creates the table, sets its bounds, and sets its header and lines to be visible.
Lines 8-11: Creates two table columns and sets the initial width of each to 100 pixels.
Lines 12-21: Adds an SWT.Selection listener to each of the table’s columns. These listeners will invoke pack() on the column whenever its header is clicked by the user.
Lines 22-26: Creates the table’s items.
Lines 27-28: Adds an SWT.MeasureItem listener to the table, which will be invoked whenever the size of a cell’s content is needed.
Line 29: Sets the event’s width field to double the default width of the cell. This specifies that the width of the cell should be this value regardless of its content.
Lines 32-36: