PrintList Pro version 6 documentation

A “callback” is a 4D project method which is executed by a plug-in. PrintList Pro lets you make use of callbacks when printing a PrintList Pro object.

PrintList Pro provides five different callback methods:

• when the end of a printed page is reached (callbackMethod parameter of PL_SetPageProc)
• custom calculations in a break (functionName parameter of PL_SetBrkFunc)
• custom calculations in a break header (functionName parameter of PL_SetBkHFunc)
• calculated columns (calcCallback parameter of PL_SetCalcCall) in field display or array display mode
• computed breaks, with or without printing (callbackMethodName parameter of PL_ProcessArrays)

• Callback methods may use most 4D commands, but should not call any PrintList Pro commands or any 4D commands that affect the arrays.

Note: this limitation does not apply to computed break callbacks.

• Callback methods should preserve the current selection of the printing layout’s file by saving and restoring the selection if necessary.
• All callbacks receive parameters, which need to be declared as documented below.

PrintList Pro makes use of a callback method to inform you when the end of a printed page is reached. This enables you to perform any necessary processing associated with the end of the page, for example, changing information printed in the footer area of that page or the header area of the next page.

Use PL_SetPageProc to specify the 4D project method PrintList Pro is to call. PrintList Pro will pass the method specified by callbackMethod two parameters: the first indicates which PrintList Pro area is calling the method, and the second specifies the last row printed on that page.

You must use the following declaration in your callback method:

  C_LONGINT ($1;$2)

PL_SetBrkFunc is used to specify the callback function for use with custom calculations. The callback function functionName is called whenever PrintList Pro encounters the string “\Function” within the text that is to be printed for a specific break level.

Refer to PL_SetBrkText for details on how to embed the custom calculation string.

PrintList Pro passes information needed for the custom calculation to the callback function.

You must use the following declarations in your callback method:

  C_LONGINT ($1;$2) // break level, column
  C_TEXT ($3) // column format
  C_LONGINT($4;$5) // start row, end row
  C_TEXT ($0) // custom calculation result to print

A break header will print information just prior to the group of related values. PL_SetBkHFunc is used to specify the name of the break header callback function. This function will be called for any break header that contains a break function.

Refer to PL_SetBrkText and PL_SetBkHText to determine how to set a break function for a break level.

The syntax of this command is identical to that of PL_SetBrkFunc.

The callback function functionName is called whenever PrintList Pro encounters the string “\Function” within the text that is to be printed for a specific break level. PrintList Pro passes information needed for the custom calculation to the callback function.

You must use the following declarations in your callback method:

  C_LONGINT ($1;$2) // break level, column
  C_TEXT ($3) // column format
  C_LONGINT($4;$5) // start row, end row
  C_TEXT ($0) // custom calculation result to print

A 4D callback may be attached to a specific column. When information is needed for this column, PrintList Pro will execute the callback to allow you to fill the column with data.

This allows the printing of data calculated from one or more fields or arrays as well as any ad hoc data that is desired.

The first three parameters are not absolutely necessary to determine how to fill the column. They are provided to give you more flexibility in the implementation of the callback method.

• The first parameter is the area long integer reference. This gives you the ability to use this callback method for more than one PrintList Pro object.
• The second parameter is the column number. This gives you the ability to use this callback method for many columns within a PrintList Pro object.
• The third parameter is the type of data in the column (field type or array type).

The last three parameters are absolutely necessary.

• In field mode, the fourth parameter is a pointer to one of the temporary 4D Arrays used internally by PrintList Pro. This is where you will load the data to be printed in the column. In array mode, this is a declared, fully sized 4D array (by you as the developer), you have to fill the requested elements
• The fifth parameter is the number of the first cell that needs to be filled in the column. This is the same as the selected number of the row that contains this cell.
• The sixth parameter is the number of cells (rows) to be filled in the column.

You must declare all six parameters ($1 to $6) in the calculated column callback. If any of these parameters are not declared, you will get an error when compiling the database.

You must use the following declarations in your callback method:

  C_LONGINT ($1;$2;$3;$5;$6)

  C_POINTER ($4)

See Calculated Columns for details.

This powerful feature makes all break calculations available for subtotals or other calculated values in any break level, as well as any individual row sub-selection from the top.

These values are returned by PrintList Pro without need for actual printing.

PL_ProcessArrays is used to specify the name of the computed break callback function. This function will be called for the break levels and the columns specified by the breakArrays and dataArrays parameters.

In addition, the useDetail parameter allows calling the callback only on breaks, or for each individual row as well.

The Computed Break callback method receives three parameters: a handle needed to call PL_GetBreakValue, the current row number and the current break level, or -1 if individual rows are set to call the callback with PL_ProcessArrays.

You must use the following declarations in your callback method:

  C_LONGINT ($1) // handle to pass over to PL_GetBreakValue
  C_LONGINT($2) // current row number
  C_LONGINT ($3) // break level (or -1 for an individual row)

PL_GetBreakValue is called from the callback method to perform usual break level processing calculations such as sum, minimum,etc. for the current break level (or individual row) and the specified column.

See Using Computed Breaks for details.