row-section-with-sort-gadget-mixin

An application can mix this class into a grid-row-section subclass to give that row-section a default interactive interface to the row-sorting functionality of a grid-widget. The mixin will cause mouse clicks on cells in that row section to sort the grid and/or to select the current sort-column. Typically it is mixed into a row section that is used for column headers, containing a single grid-row.

Note that if the particular interactive interface provided by this mixin is not suitable, an application can instead define its own cell-click methods that initiate a call to sort-grid in a custom way, and also perhaps define draw-cell methods that indicate the current sort-column and/or sort-reverse status in a custom way. This mixin is simply a suggested interactive interface to the standard programmatic sorting functionality of grid-widgets.

In addition to implementing mouse clicks for sorting, this mixin draws a "sort gadget" at the very right end of the row section, in the space where the row section's scrollbar would be if it had one. (Therefore, this section's scrollbars property should be nil so as not to cover the scroll gadget. Normally this is not a problem since a row section used for sorting is a header row that would not scroll.) The sort gadget is drawn simply as a group of horizontal lines that are longer toward the bottom when the grid-widget's sort-reverse property is nil, and longer toward the top when sort-reverse is true. This provides a visual indication of the current sort direction.

Another visual cue provided by this mixin is to underline the text in the cell in the current sort-column. This is implemented by a cell-font method that calls vary-font on the usual font for the cell to add underlining to it.

The mouse click behavior of this mixin depends on the value of the sort-on-click property of the row section, which provides two alternate styles.

If sort-on-click is true (the default), then a simple left click in a cell of this row-section will set the sort-column of the grid to the column of the clicked cell, and then call sort-grid to sort the grid-row-section just below this row section by the values in the column. If the clicked column was already the sort-column of the grid, then the value of the sort-reverse property is first toggled so that the sort is done in the opposite direction. The sort gadget at the right always indicates the direction in which the most recent sort was done. Clicks on the sort gadget itself will do nothing. This sort-on-click option provides the more intuitive click behavior which is similar to how the list-view control works, for example. The drawback is that it overrides whatever left-click behavior the cells in this row section would otherwise have.

If sort-on-click is nil, then mouse clicks are handled in an alternate style that was always used by this mixin through version release 6.0 (the property that provides the choice of behavior was added in release 6.1).

This option is provided mostly for backward compatibility, because it is less intuitive. The mixin was written this way originally so as not to override the usual left-click functionality of any grid cells. With this option, the user first sets the current sort-column by right-clicking on the cell where that column and this row-section intersect. Then the user left-clicks the sort gadget itself to do the sort. (If no current sort column has been set yet, a warning dialog is shown.) Right-clicking the sort gadget will reverse the order of the sort that is to be done (so with this option, the appearance of the sort gadget reflects the order of any subsequent sort, rather than the order of the most recent sort).

For either sort-on-click option, the click that sets a new current sort-column will do so only if that column's sortable property is true, as it is by default.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.