functions

Optional sort and alignment parameters require version 5.0.8.  The optional strExpression parameter requires version 8.

fhOutputResultSetColumn(strColumnHeading, strColumnType, tblData, iCount[, iWidthInChar4ths[, sAlignment[, iSortPriority[, bSortAscending,strItemSortType,strVisibility[,strExpression]]]]])

strColumnHeading

string: Heading for Column

strColumnType

string: Column type must be one of the following:

text	strings
item	Item Pointer Objects
date-point	Date point Objects
integer	integers

tblData

table: contents for the column, type must match the declared column type, or be nil. The table must be a simple indexed table.

iCount

integer: number of items in the table. For fully popuated tables (e.g ones which contain no nil elements) you can prefix the table name with a # to get the number of items in the table.

iWidthInChar4ths

integer: Column width in ¼ character widths (e.g. 80 = about 20 chars). Defaults to 80 if not supplied.

strAlignment

string: Column alignment:

align_left	column is left aligned
align_right	Column is right aligned
align_mid	Column is centered

iSortPriority

integer: Defaults to 0 if not supplied (0 = no sort). See remarks below.

bSortAscending

boolean: if true (the default) sort is ascending. Otherwise it is descending.

strItemSortType

string: Applicable only if the strColumnType is 'item'. Otherwise ignored. [NOTE: This parameter will have no affect in versions earlier than 5.0.8].

default	Column uses alphabetic-sorting
date	Column uses date-sorting
integer	Column uses integer-sorting

strVisibility

string: Indicates whether column is visible, or some kind of hidden column.[NOTE: This parameter will have no affect in versions earlier than 5.0.8].

show	Column is visible (the default)
hide	Column is hidden. Is useful if you want to sort on a hidden column.
buddy	Column is hidden and is a 'buddy' column of the previous column (that is, the column created in the previous call to fhOutputResultSetColumn). A 'buddy' column can be specified only if the previous column is not an item column. It associates each cell of that previous column with an item (unless NULL) to link that cell back to an item of data. If the user double-clicks on a data-linked cell, the Property Box will be opened to show that item of data. Also, the text in a data-linked cells displays in a slightly different colour to non-data-linked cells (the defaults are black for the former, and grey for the latter). Ordinary item columns are data-linked automatically. But if you want a non-item column to be data-linked, you must define a buddy column for it. If you want to specify a column as a buddy column, the following must all be true: The buddy column must be an 'item' column (see strColumnType) There must be a previous column The previous column must NOT be an 'item' column The previous column must not be hidden or a buddy column If any of these are not the case, it is an error and the call will fail. NOTE: You can have NULL values in a buddy column. However, it is strongly recommended that if the buddy column contains NULL for a given row, the column it is linked to should normally also have NULL for that row or, exceptionally, some text that indicates that the value is NULL. Otherwise, the user is likely to believe that they can double-click on the cell and will be confused when nothing happens if they do so.

strExpression

string: If supplied, must be an empty string, unless strColumnType is 'item'.  When used with an 'item' column type, this parameter can be used to provide an expression (data reference or built-in function) which will be called with the column's data items, to return a value derived from that data item.  For example, if the data item is a 'fact' type data item, you could supply data items in this column which reference a fact (event or attribute), and if the expression is '%FACT.DATE:COMPACT%', the cells will display the date of the fact in compact format.  If the expression is '=FactValue(%FACT%)', the cells will display the attribute value (for attributes).  It is an error to enter an invalid expression.  It is not an error to enter an expression which is valid but does not take an item pointer of the type stored in the column.  However, in that case, the cells will be blank.

none

The first call creates the first column, the second call creates the second column, and so on. If you create multiple columns, they do not have to have the same number of items. The result set displayed will have enough rows for the largest column, and columns which have fewer values will be displayed with blank values in the rows for which they have no value.

You can call fhOutputResultSetColumn at any point in your script, but the normal practice is to make all calls to this function at or near the end of the script - given that it is producing output for when the script has completed.

When assigning object values to table variables, use the object's 'Clone' function to avoid storing the same underlying object in multiple variables (if you do, they will all display the same value).

• Sorting only happens AFTER the plugin has completed.
• Sorting rearranges the result set rows, based on values in columns.
• You can specify which column you wish to base the sort on (and this can be a hidden column)
• You can sort on more than one column (e.g. you might wish to sort rows based on a column containing surnames, but where the surname fields match, do a further sort based on a column which contains given names).
• You specify which columns to sort on by giving them a non-zero value for iSortPriority. It is an error to give any two columns the same non-zero priority.
• Sort priority values do not have to be contiguous.
• Low values have a higher priority than higher values. For example, to sort on the surname column first, and then on the given names column, you might give the surname column a priority of 1 and the given names column a priority of 2. If you do not wish to sort on any columns, set all their iSortPriority values to zero (or do not specify a sort priority, as zero is the default).
• The nature of the sort (alphabetic, date or integer) is normally determined by the column contents. But if the column type is 'item' (and bearing in mind that you can put items of any type in an 'item' column), you must specify the sort you require, if not alphabetic, using the strItemSortType parameter.

The following script creates a result set with 10 rows and 3 columns. Result sets can be saved in PDF, CSV or text format, copied to the clipboard, or printed. You can select and delete any data items in any column (one column at a time - but you can delete an entire column in one go if you wish). You can view Properties for any data item too. You can click on any column heading to sort on that heading (you will be given the chance to revert to the normal sort order before printing or saving to PDF).

ptrInd = fhNewItemPtr()
ptrInd:MoveToFirstRecord('INDI')
    a = {}
 
ptrInd:MoveNext()
a[1] = ptrInd:Clone()
ptrInd:MoveNext()
a[2] = ptrInd:Clone()
ptrInd:MoveNext()
a[3] = ptrInd:Clone()
ptrInd:MoveNext()
a[4] = ptrInd:Clone()
a[5] = ptrInd:Clone()
a[6] = ptrInd:Clone()
a[7] = ptrInd:Clone()
a[8] = ptrInd:Clone()
a[10] = ptrInd:Clone()
 
b = {}
b[1] = "Apples"
b[2] = "Pears"
b[3] = "Oranges"
b[4] = "Bananas"
b[6] = "Blackcurrants"
b[9] = "NOt blank here"
 
c = {}
c[1] = 142
c[2] = 4
c[7] = 1600
c[5] = 1700
 
fhOutputResultSetColumn("Individuals", "item", a, 10, 180, "align_left", 1, true)
fhOutputResultSetColumn("Fruit", "text", b, 9, 0, "align_mid")
fhOutputResultSetColumn("Count", "integer", c, 7, 80, "align_right", 2, false)
 
fhOutputResultSetTitles("Display Title", "Print Title", "Print Subtitle")