?name s_name

Handle to the field. To reference it, use:

formHandle->hiFieldSym

?title t_title

Report title, which is displayed above the report.

?titleAlignment g_titleAlignment

Alignment of the report title. Use one of the following values:

’left

’center

’right

The default value is ’left.

?headers g_headers

The list of columns in the report. Specify each column as a list that contains the following elements:

’(columnName columnWidth colNameAlignment type sortable comparisonFunction userData)

• columnName is the heading of the column
• columnWidth is the initial width of the column. The width can be changed interactively after the form is created.
  If the column width is set to 0, the column gets hidden in the report.
• colNameAlignment is the alignment of the column heading and the data in the column: ’left, ’right, or ’center
• type is the type of data in the column: ’int, ’float[n], or ’string. You can specify float in the following ways:
• ’floatn (where n is the number of decimal points to be displayed in the float field). For example, ’float4.
• ’float (which defaults to ’float3)
• ’scientificn (where n is an optional integer specifying the precision). For example, ’scientific4.
• ’scientific (which defaults to ’scientific3)
• sortable indicates if the column is sortable. Specify t if you want the column to be sortable; nil, otherwise. The report field can sort integer, float, and string data. Clicking on the column header sorts the data in the column.
• comparisonFunction (optional) is the name (string) of the comparison function that is called by the sorting algorithm. The comparison function is called with two arguments that point to the elements being compared. The return value of this sorting function must be -1, 0, or 1.

comparisonFunction(row1 row2 userData)

where row1 and row2 are members of the l_choices list (that is, they are entire rows, not just the specific elements in the columns).

If userData is nil, comparisonFunction is called as described in comparisonFunction above.

You need to specify type, sortable, compareFunction, and userData only if you want the column to be sortable.

Once the report field is instantiated, you can modify the headers (specifically, the name, width, and alignment of the columns) with the headers property by using the following commands:

form->reportField->headers=newHeaders

or (putprop form->reportField newHeaders ’headers)

where newHeaders is a list in the same format as the g_headers argument described above except that only columnName, columnWidth, and colNameAlignment values are used (the remaining values, if specified, are ignored). Also, any nil elements in the newHeaders list are ignored and do not replace the corresponding elements in the existing headers list.

For example, if the old headers list is:

’(("one" 100 left) ("two" 200 right float) ("three" 300 center))

and the new headers list is:

’(nil ("TWO" nil left int))

then the new headers:

’(("one" 100 left) ("TWO" 200 left float) ("three" 300 center))

?choices l_choices

List containing the items in the report. Each item forms a row of the report. For example:

?choices list(
list(1 "ABC" "buy" 62.0 "Buy & Hold")
list(2 "DEF" "sell" 17.0 "Sell")
list(3 "XYZ" "hold" 9.5 "Hold")
)

To retrieve or change the value of l_choices, use:

formHandle->hiFieldSym->choices

?value g_value

Initial value of the field, indicating which items in the report are selected when the form first appears.

Specify g_value as a list of integers in the ascending order, in which each integer represents an item in ?choices. The first item in ?choices is 0, the second item is 1, the third item is 2, and so on. You can specify a range of items as a list within the list.

For example:

?value ’(1 3 6);selects items 1, 3, 6
?value ’(’(2 4)); selects items 2, 3, 4
?value ’(’(1 3) 9 11); selects items 1, 2, 3, 9, 11

After the form is instantiated, you can use the value property to retrieve or change the list of currently selected items. To retrieve the list of selected items, use the following syntax:

formHandle->hiFieldSym->value

The value property returns a list of integers. This list contains packed values if the g_returnPackedValue argument is t.

To change the list of selected items with the value property, use the following syntax:

formHandle->hiFieldSym->value = listOfItems

Setting the value through the value property always triggers the callback of the report field. If you want to set the value without triggering the callback, use the functions hiReportSelectItem, hiReportSelectItems, or hiReportSelectAllItems, with the g_notify argument set to nil.

?defValue g_defaultValue

Default value of the field, indicating which items in the report are selected when the Defaults button is clicked. After the form is instantiated, you can use the defValue property to retrieve or change the default value.

Specify g_defaultValue as a list of integers in the ascending order, in which each integer represents an item in ?choices. The first item in ?choices is 0, the second item is 1, the third item is 2, and so on. You can specify a range of items as a list within the list.

For example:

?defValue ’(1 3 6) ; selects items 1, 3, 6
?defValue ’(’(2 4)) ; selects items 2, 3, 4
?defValue ’(’(1 3) 9 11) ; selects items 1, 2, 3, 9, 11

Use the following syntax for the defValue property

formHandle->hiFieldSym->defValue

The defValue property returns a list of integers. This list contains packed values if the g_returnPackedValue argument is t.

?returnPackedValue g_returnPackedValue

Return packed values for value, defValue, and lastValue properties to return packed values. g_returnPackedValue also determines whether the second argument passed to S_callback contains packed values.

A packed value is a range of items specified as a list within the list. For example, if items 1, 2, 3, 4, 5, 9, and 11 are selected in the report, the value property returns the following:

’(’(1 5) 9 11) ; if g_returnPackedValue is t
’(1 2 3 4 5 9 11) ; if g_returnPackedValue is nil

?help g_fieldHelp

A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.

?callback g_callback

A string, a symbol, or a function object that specifies the name of the callback function to be called when items are selected. If you want the callback to also be called when items are deselected, specify t as the value of the ?enableDeselectCB argument.

If you specify a symbol for this argument, or a non-empty string without space or parentheses, it is assumed to be the callback function name. The callback function is passed two arguments. The first argument is the symbol representing the field name. The second argument is a list of integers representing the selected items of the report (the first item is 0, the second item is 1, and so forth). The second argument contains packed values if the value of the g_returnPackedValue argument is t.

If you specify a string with space or parentheses for this argument, it is assumed to be a SKILL expression and is passed to SKILL to be evaluated.

For example:

procedure( reportCB(fieldName selectedItems "sl")
  printf( "Report field callback, fieldName = %L, selectedItems = %L"           fieldName selectedItems )
reportField = hiCreateReportField(
?name       ’reportField
?title      "Report Field"
?selectMode ’single
?headers    ’(("Property"   120 ’left)
("Operator"    70 ’left)
("Value"      120 ’left))
?choices ’(("test" "==" "argh")
("test2" ">" "argh")
("test3" "<" "test4"))
?callback   ’reportCB
)

reportField can also take a single click ?callback called hiClickedCallback, which enables you to retrieve selected column, row or symbol information for a mouse click selection. For example:

(defun myClickedCallback (fieldSymbol row column "sxx")...)
rptProps->hiClickedCallback=’myClickedCallback

If specified, clicking on a reportField item cause hiClickedCallback to be applied. The callback then is passed three arguments; fieldSymbol, row number and column number, where both row and column numbers are zero-based. Here hiClickedCallback is called before hiReportSelectItems is executed.

?enableDeselectCB S_enableDeselectCB

t or nil. Specify t if you want the callback procedure (specified with the ?callback argument) to be called when items are deselected, in addition to being called when items are selected. If you specify nil, the callback procedure is called only when items are selected.

The default value of S_enableDeselectCB is nil.

?doubleClickCB g_doubleClickCB

A string, symbol or function object specifying the callback procedure to be called when an item is double-clicked.

If specified as a symbol, the procedure gets passed two arguments. The first argument is a string representing the report field name; the second argument is an integer representing the item that was double-clicked (the first item is 0, the second item is 1, and so forth).

If specified as a string, the string is evaluated and the callback function is not passed any arguments.

The default value of this argument is an empty string (""), which means that a double-click callback has not been specified.

If specified as a function object, it is passed following arguments:

< double click callback > ( o_field g_scope x_item_index )

where o_field is the report field, g_scope specifies where the report is instantiated, and x_item_index is the index of the item being double-clicked.

?sortCallback g_sortCallback

A string, symbol, or function object type callback that is used to notify when the field is sorted. The sort callback procedure is passed two arguments. The first argument is the field name symbol; the second argument is list(columnToSort sortDirection), where columnToSort is an integer indicating the column to sort (the first column is 0, the second is 1, and so on) and sortDirection is t or nil (t indicates descending order, nil indicates ascending order). The sorting is then done by the comparisonFunction, which is passed as part of the column description in the ?headers argument.

If callback is of function object type, it is passed following arguments:

< sort callback > ( o_field g_scope l_sort_property )

, where l_sort_property is a list of (columnToSort sortDirection). Same as that used to sort callback of string or symbol type.

?sort l_sort

Indicates which column is sorted when the form first appears. Specify l_sort as a list of two elements:

’(columnToSort sortDirection)

where columnToSort is an integer indicating the column to sort (the first column is 0, the second is 1, and so on) and sortDirection is t or nil (t indicates descending order, nil indicates ascending order).

You can also use the sort property to sort a column after the form is instantiated.

Use the following format for the sort property:

formHandle->hiFieldSym->sort

Clicking on the column header sorts the column. Clicking again on the column header changes the sorting direction, from ascending to descending or vice versa.

?selectMode s_selectMode

Specifies the selection mode for the report field. Use one of the following symbols:

’single: Only one item can be selected at a time. Click to select the item. To deselect an item, click it again or select another item.

’multiple: Multiple items can be selected. Click to select the items. To deselect an item, click it again.

’browse: One item always remains selected. Click or drag to select the item. To deselect an item, select another item.

’extended: One or more items always remain selected. Multiple contiguous ranges of items can be selected. Click to select a single item. Click and drag to select a range of items. Press the CTRL key and click to select an additional item or a range of additional items. To deselect an item, press the CTRL key and click the item. CTRL+click also deselects the last selected item. You can also use CTRL+SHIFT to select or deselect a range of items.

’none: Disables the selection, which means no item can be selected in the report field. It displays the report field in a read-only mode.

The default mode is ’extended.

You can modify the value of this argument with the selectMode property. For example:

formHandle->fieldSym->selectMode = ’single

?invisible g_invisible

Specifies whether the layout and the fields within are invisible. The default value is nil.

?enabled g_enabled

Specifies whether the fields in the layout are enabled. The default value is t.

?nextField g_nextField

Symbol or string indicating the next field to bring into focus when the Tab key is pressed. If you specify nil or do not specify this argument, the Tab traversal order is determined by the tabOrderIsAddOrder argument of hiCreateAppForm or hiCreateScrollRegion. If the tabOrderIsAddOrder argument is not set or if its value is nil, the default traversal order is based on the form layout —left-to-right and top-to-bottom— beginning with the field at the top-left corner of the form.

?altRowHilight g_rowHighlight

Specifies whether background of alternate rows in the table should be highlighted. The default is nil, which means that highlight is not enabled.

r_fieldHandle

Handle to the report field.