SET-SORT-ARROW( ) method

Sets the sort-arrow indicator and, optionally, the sort-level number for a browse column.

Return type:

LOGICAL

Applies to:

BROWSE widget

 

Syntax 

SET-SORT-ARROW ( column-index , ascending [ , n ] )

column-index

An INTEGER expression that specifies the column for which the sort-arrow indicator is set. If the column does not exist, the AVM generates a run-time error.

ascending

A LOGICAL expression where TRUE indicates ascending sort order, and FALSE indicates descending sort order.

Set to the Unknown value (?) to remove a sort-arrow indicator that was previously set for this column. Use the CLEAR-SORT-ARROWS( ) method to clear sort-arrow indicators for all columns in the browse.

n

An optional INTEGER expression that specifies the sort level to display at the right of the sort arrow in the column label. Valid values are 1 through 9, inclusive, and the Unknown value (?). If you do not specify a value, or you specify the Unknown value (?), a sort-level number does not appear in the column label. If you specify an invalid value, the AVM generates a run-time error.

You can set two or more columns in a browse to the same sort-level number, and you can leave gaps in the sequence. This allows for rearranging values, as necessary.

The sort-arrow indicator, which consists of an arrow bitmap pointing upward to indicate ascending sort order and pointing downward to indicate descending sort order, is displayed with the column label. It appears at the immediate right of the column label, whether the label is right-justified or left-justified.

The optional sort-level number, if specified, indicates multi-level sorting and appears at the right of the sort arrow in the column label. For example, you can set the sort-level number to show that data in one column of a browse has first been sorted in ascending order and data in another column has then been sorted in descending order.

Note:

Setting a sort-arrow indicator and sort-level number on a column does not change the column’s sort order or the browse’s query. The browse’s query is responsible for actually sorting the data.

You can set a sort-arrow indicator and a sort-level number on a browse column before or after the browse widget is realized. Calling this method does not realize the widget.

If the column label text is too wide for the column, the AVM displays as much of the label as possible and clips the rest of the text. If there is no space in the column label to display the sort-arrow indicator, the AVM will not make the column wider at run time; consider increasing the width of the column.

If the browse has one or more stacked column labels, the sort-arrow indicators appear centered vertically within the label header. Note that the sort-arrow indicators are positioned based on the overall height of the label header, not based on the height of any individual column label.

In character interfaces, the ascending sort-arrow indicator is represented by the caret (0x5E) and the descending indicator is represented by the lower case “v” (0x76). These characters are not configurable. The sort-arrow indicator appears at the far right of the column label. This minimizes the chance of the user misreading the arrow as part of the column label. If the column label text is too wide for the column, the AVM displays as much of the label as possible and clips the rest of the text. If the browse has one or more stacked column labels, the sort-arrow indicators appear on the top row of the label header.

If successful, this method returns TRUE. Otherwise, it returns FALSE.

See also:

CLEAR-SORT-ARROWS( ) method