The WkTableWidget widget provides a vertical, multi-column tree of items which shows a row of cells for each item in the list. Cells are edited in-line, simply by selecting them with the mouse or keyboard, and changing the text with the text editor that appears in the selected cell. The items in the list are typically actual application objects, not strings or arrays. For example, the items (rows) might be employee objects, and the columns might show the name, salary, and hire date for each employee. The application should only set the root level items in the tree as the items in the widget. The descendants of those root items can then be shown by clicking on the collapse/expand icons.

The programmer chooses how the objects in the table will be viewed by defining a collection of fields, one for each column. These fields are each instances of the class WkTableColumn, and describe the header, font, justification, field width, fore and back color, validation functions and accessor methods for a particular column. The header is the string that will be displayed at the top of the listbox for that field. The font is the font used to display the column. The justification can be one of left, right, and center. The field width is the number of pixels wide that this field should be; if it is autosizable, the field will be as wide as the widest value displayed in this column. The fore and back colors affect the presentation of data in the cells. The validation functions can be any of those supported by WbEnhancedText. The accessor methods are the messages which will be sent to the object to retrieve a string to display for this field and to update the object when the user changes a cell’s value.

The visual aspect of each columns can be further augmented by using the cellValueCallback. The application may hook this callback on each column. This callback fires whenever the widget needs to know what value to put in a cell for a given item. The application can then set the callData value to be the renderable object (see below) which is to reside in the cell. For example, when the widget needs to place an employee’s salary in the salary column, it fires the callValueCallback. The callData tells for which employee the salary is needed (callData item). The application might hook the cellValueCallback from the Salary column to a method like:

To access cells in the table, use the methods #atRow:column: and #atRow:column:put:. These can take either numeric indices, or the string names of the corresponding row or column.

The application may or may not hook the headingCellValueCallback. Column headings can be set via the WkTableColumn>>heading: method or via the headingCellValueCallback.

Both the headingCellValueCallback and cellValueCallback can be used to set color for a particular cell. Colors can be specified for the foreground, background, selectedForeground, and selectedBackground of a cell

The objects used for cell values and headings are typically Strings, Numbers, and CgIcons, but this is not a requirement. It is possible for an application to use any object as the cell value or heading. Any item which understands #ewHeightUsing:, #ewWidthUsing: and #ewDrawUsing: (called a “renderable object”) can be used for a cell value. Since String, Number, and CgIcon already implement the standard renderable object protocol, they can easily be used. Also, since Object provides default renderable behavior, any object can be rendered, although the default rendering is to render the object’s printString.

Navigation, selection, and editing modes determine the operation of a table pane at runtime. Two navigation modes govern whether the right and left arrow keys move the input focus between the characters within a cell or between cells. In the default mode, Arrow Keys Edit, the arrow keys move within a cell; Ctrl plus right or left arrow moves between cells. In Arrow Keys Move mode, the right and left arrow keys move the focus between cells.

If the entire table pane is in Read Only mode, arrow keys move between cells and no alphanumeric keyboard input is accepted. Columns or individual cells can be set to read only or disabled.

Cells can behave like simple text entry fields, drop-down lists, combo boxes or check boxes. If editing is allowed in a cell, it processes normal keyboard input according to the type of cell. For example, if a cell contains a drop-down list, you can open the list by clicking on the downward pointing arrow that is visible when the cell has focus and move the selection in the list with the up and down arrow keys.

Cell editing can take place automatically or under program control. For cell editing to be automatic, the widget must have editable true, and the columns in which cells may be edited must also have editable true. Under program control, this is not required.

When a cell is about to be edited, either because the user clicked in it or because the program called #editCellAt: or #editSelectedCell, the column fires its beginEditCallback. The application may hook this callback to augment the default cell editing process. At a minimum, the callData doit: must be set to true to allow editing to begin (this is the default).

The callData also includes a default editPolicy. The edit policy defines the type of widget to be used for editing as well as some other edit semantics. The default edit policy is an WkTextEditPolicy set up to use a single-line CwText as the edit widget or an WkComboBoxEditPolicy set up to use a combo box as the edit widget. The application can substitute a more appropriate edit policy for the cell about to be edited. Applications can define their own custom edit policies by overriding the behavior in EwEditPolicy as required. The supplied subclasses of EwEditPolicy serve as good examples for this.

When editing is about to end, or when the value in the edit widget has been changed (the exact details of when a change has occurred depend on the edit policy), the column automatically updates the appropriate application object using the #setSelector:. The column also fires its endEditCallback. The callData includes the old value and the new value. The application can hook this callback and use the newValue to change some application object. The cell is then automatically refreshed after the callback fires, so the new value is obtained and displayed.

The WkTableWidget supports Cell, Single, Multi, and Extended selection modes. Cell select mode is the default mode of operation. In this mode, you can select single cells only; clicking on row headers has no effect. In single select mode, the table acts like a single select list box when either a row header or a disabled/read-only cell is selected. Clicking on a cell that supports data entry causes the cell to be selected and the row selection to be lost. In multi select mode, the table behaves like a multiple select list box. Multiple rows may be selected and deselected. In extended select mode, the table emulates an extended select list box. Without modifier keys, extended select mode acts like single select mode. If the Shift or Ctrl keys are held down, multiple rows can be selected.

Setting up the children for each object is done similarly: at initialization time, you supply the list box with a message to send to each object in the list box to retrieve a collection of its children. This is accomplished by sending the message #childrenSelector: to the WkTableWidget, with a symbol matching the message you want sent. If no children method is provided, the list box will not be hierarchical, and will act as a normal list box.

As mentioned above, each object in the list box can have an icon associated with it. As with #childrenSelector:, this is accomplished by supplying an #iconSelector: to the list box at initialization time. The associated method will then be sent to each object in the list, giving the object the opportunity to pass back an icon (or any other renderable object including nil if no icon should be displayed). If no #iconSelector: is specified, the list box will not display an icons. An optional different icon may be displayed when the object is expanded via sending #iconExpandSelector: to the list box.

The hierarchical aspect of the list be further augmented by using the visualInfoCallback and the childrenCallback. The application must hook the visualInfoCallback and set the callData hasChildren to true or false to indicate whether the item in callData item has children. The application must also hook the childrenCallback and set the callData value to be the list of children for the item in callData item. The childrenCallback only fires for items for which hasChildren is true.

The hierarchyPolicy determines how the hierarchy is to be shown. This includes what the indentation level should be as well as whether to draw lines connecting the items and whether to show some kind of button beside items which have children. By default the hierarchyPolicy is an instance of EwHierarchyPolicy with lines set to true. The other hierarchy policy class provided is EwIconHierarchyPolicy. This class shows an icon beside each item to act as an expand/collapse button. The application can specify which icon to use in different situations so that the button can animate properly as it is pressed. The indentation, lines, and buttons are only shown in the first column.

Default: XmTREEHIERARCHYBUTTONS (Buttons)

Default: XmACROSSROWS (Across Rows)

Default: XmARROWKEYSEDIT (Edit)

Default: XmETCHCELLS (Etch Cells)

Default: XmBROWSESELECT (Browse Select)

Default: XmFLAT (Flat)

The following example code creates a WkTableWidget used to view a person object. The widget specifies a children selector that will be used to display person objects hierarchically. The disabled selector is used to determine whether a particular row is disabled or not. The color selector is used to query each row object for its preferred foreground color (which may be overridden by individual columns). The reorderable and sortable flags determine whether the user will be able to reorder the columns by dragging them left and right and sort them in place by clicking on the column headers. The heading font has been set to a 14 point Times Roman.

The widget defines five columns: first name, last name, company, shoe size and exec status. For each column, get and set selectors are specified which are used to query the person object a particular row for the data to display in the column and to update the person object when the user has entered new data. Columns can specify their heading, alignment, width, font, character and field validations, and foreground and background colors. Note that the company column hardcodes its colors while the shoe size specifies selectors. This means that each row of the shoe size column may have different foreground and background colors depending on the values returned from the various person objects. The company column also specifies a list selector that is a signal to the widget to use a drop down list as the column editor. The values returned by sending the list selector to the row object are used to populate the list (each row object can actually supply its own list). The exec column returns boolean cell values. The widget will automatically display boolean values as checked and unchecked check boxes without further developer intervention.

This example corresponds to the top image at the beginning of the WkTableWidget section.