User Tools

Site Tools


Configuring PrintList Pro

A PrintList Pro object is initialized in the On Printing Detail phase as the record is about to be printed.

This initialization will be contained in the PrintList Pro plug-in area object method or in the form method.

Using Defined Constants with PrintList Pro

There are defined constants that may be used as values for many parameters in the PrintList Pro commands. See the Constants tab of the Explorer in the 4D Design environment.

These constants are categorized according to the type of command that they are associated with, such as PLP Break Levels, PLP Colors, etc.

Specifying the Arrays to Print

4D arrays are passed to PrintList Pro via the PL_AddColumn or PL_SetArraysNam commands.

These commands must be called before any other PrintList Pro commands are executed.

These two functions return 0 if successful, or an error code indicating the problem:

Constant Value Action
PL SetArrays Passed0
PL Not an array1Check to make sure all arrays are correctly typed
PL Wrong type of array2Pointer and two-dimensional arrays are not allowed
PL Wrong number of rows3Make sure that all arrays have the same number of elements
PL Maximum number of arrays exc432767 arrays is the maximum
PL Not enough memory5Unlikely these days

Up to 32767 arrays can be printed by PrintList Pro, with up to fifteen columns specified in each call to PL_SetArraysNam.

The position of the first array, columnNumber, and the number of arrays, numArrays, are also specified in this command. All array types except for pointer are allowed, and all arrays must have the same number of elements.

The maximum number of rows is only limited by available memory.

Aternately to standard single-dimension arrays, one dimension of a two-dimensional array may be passed to PL_SetArraysNam e.g. “My2DArray{1}” may be passed as array1.

PL_AddColumn can be used to add or insert an array or field column through a pointer.

Printing Records

PrintList Pro provides the capability to print 4D records directly, rather than using arrays. Please read the section Field and Record Commands for more information.


The column header labels are set using PL_SetHeaders. The headers can be printed on all pages, the first page or not at all using PL_SetHdrOpts.

The font, size, and style of each header may be set individually using PL_SetHdrStyle. The justification may be set using PL_SetFormat and the color of the headers using PL_SetForeClr or PL_SetForeRGBColor.

Multiple lines of text may be shown in the headers using PL_SetHeight.

Sorting Arrays

PrintList Pro can perform multi-level sorting upon all the arrays using PL_SetSort.

Up to 15 levels of sorting are available when using PL_SetSort, and each column specified in the sort order can be sorted in either ascending or descending order.

Note: there is no limit to the number of sorted columns when using ALP_Area_SortList, ALP_Area_SortListNS, ALP_Object_SortList, ALP_Object_SortListNS.

All the arrays passed to PrintList will stay “in sync” and reflect the new sort order.

Some of the arrays can be hidden from printing using PL_SetColOpts, which allows all the arrays to be kept in sync for sorting purposes, yet hides them during actual printing.

If the arrays passed to PrintList Pro are already sorted, use PL_SetBrkOrder to communicate the sort order to PrintList Pro without performing another sort.

Also, repeated values in a list can be suppressed using PL_SetRepeatVal. Please read the section Break Level Processing for more information.

If a column containing a picture array is passed to PL_SetSort, it will be ignored (skipped).


Use PL_SetFormat to control the format and justification of all array information.

All valid 4D formats may be used including any custom formats created in the Design Environment.

If you are calling PrintList Pro from a component, make sure that the Design formats that you are using are defined in the component itself.

See Break Level Processing for information about formatting break headers and break footers.



Styles are set using 4D constants. The different values in the table below can be added together to produce combinations of styles. For example, bold italic has a value of 3.

Value Style (constant)
8Outline (obsolete)
16Shadow (obsolete)
32Condensed (obsolete)
64Extended (obsolete)

Column and Header Styles

Styles for arrays can be set on a column by column basis using PL_SetStyle to set the style for the data, and PL_SetHdrStyle to set the header style.

If a 0 (zero) is used in the columnNumber parameter, the style will be applied to all columns.

Row-Specific Styles

PL_SetRowStyle is used to set the font and style of a specified row, and will override any column specification.

Do not use row specific commands to modify all rows if you want to set the whole area. Set the columns instead.

Cell-Specific Styles

Individual array elements, called cells, can be assigned a unique font, size and style.

This capability can be used to provide special formatting to design more attractive and useful reports.

You can use PL_SetCellStyle to set the font, size and style configuration for an individual cell, a range of cells, or a selection of discontiguous cells. You can choose to set all or just one of the style attributes of this command.

PrintList Pro will keep the cell and row-specific style settings with a row when the list is sorted.

If you do not want the cell and row style settings to move when the list is sorted, you should use the cell and row style routines after the call to PL_SetSort.

Styled text

PrintList Pro supports the styled text feature of 4D v12 and above. When 4D passes styled text to PrintList Pro, it should be printed correctly if the attributed option has been set with PL_SetFormat.

If this option is set, special tags can also be used in any text contained in a PrintList Pro area to print styled characters.

These tags work just like HTML tags: <tag>styled text</tag>. See PrintList Pro Text Style Tags


When using color or grayscale printers, many PrintList objects can be given color settings. Be sure to set the printer Color/Grayscale option to obtain the proper results.

Defining colors

There are three ways to define colors in PrintList Pro.

PrintList Pro’s palette

PrintList Pro has its own palette, including the following colors:

Color Constant
WhitePL White
BlackPL Black
MagentaPL Magenta
RedPL Red
CyanPL Cyan
GreenPL Green
BluePL Blue
YellowPL Yellow
GrayPL Gray
Light grayPL Light gray

4D’s palette

The 4D color palette is a 16 by 16 grid. To determine a color’s value, you can locate the color’s position on the color grid in the Design environment (the Color submenu which is available in the Form and Method editors), and count the number of rows down and columns across.

The equation is: ColorValue = ((RowNumber – 1) x 16) + ColumnNumber.

RGB colors

In addition, PL_SetForeRGBColor and PL_SetBackRGBColor can be used to perform similar settings with standard RGB values.

Column and Header Colors

Foreground and background colors can be specified for a PrintList Pro object using PL_SetForeClr and PL_SetBackClr.

The foreground color can be specified for each column and column header, and the background color can be specified for the list and header areas.

Row-Specific Colors

PL_SetRowColor is used to set the foreground and background color of a specified row, and will override any column specification.

You can revert to the original column settings by setting the plpRowForeColor or plpRowBackColor parameter to the empty string (“”), and the 4dRowForeColor or 4dRowBackColor parameter to -1.

PL_SetRowRGBColor can be used to perform similar settings with standard RGB values. Use this command to override all row-specific color settings by passing 0 for the rowNumber parameter.

Do not use row specific commands to modify all rows if you want to set the whole area. Set the columns instead.

Cell-Specific Colors

Individual array elements, called cells, can be assigned a unique foreground color and background color.

This capability can be used to set negative numbers in red, provide special formatting to show the current selected or enterable cell, and design more attractive and useful lists.

You can use PL_SetCellColor or PL_SetCellRGBColor to set the color configuration for an individual cell, a range of cells, or a selection of discontiguous cells.

PrintList Pro will keep the cell and row-specific color setting with a row when the list is sorted.

If you do not want the cell and row color settings to move when the list is sorted, be sure to call the cell and row color routines after the call to PL_SetSort.

Multiple Lines in each Row

Multiple lines of text can be shown for each row using PL_SetHeight. All rows will be printed with the number of lines specified, or with a variable height for each row.

PL_SetHeight can also be used to give each row additional space above and below the row’s contents to give more spread out rows vertically.

Variable Height Rows

All rows can be printed with a varying height depending on the data that is to be printed. For rows, PrintList Pro will examine each row’s text and picture element using the applied font and style settings to determine the tallest cell of each row.

Any given row can be of no height (i.e. no data) up to the height of an entire page. For any row that is larger than a page, PrintList Pro will attempt to show as much of it as possible by starting the row at the top of the page. The row will be truncated to a page — no one row can span two pages.

To set all rows to be variable height, use PL_SetHeight and set the numRowLines parameter to zero.

Setting an individual row or cell font size may cause PrintList Pro to override a fixed height row setting and print the row using a larger height.

In order to accommodate the larger font, PrintList Pro uses the variable height calculation to determine the height of the row based upon the font size setting.

When variable row height is used, Picture columns are used for row height calculation, too (even when usePictHeight in PL_SetFormat was set to zero).

Column Widths

Columns are automatically sized by default; however, a column size can be programmed using PL_SetWidths

All widths are given in pixels.

Dividing Lines, Frame and Header Separator Lines

Dividing lines can be added between rows and columns using PL_SetDividers or PL_SetRGBDividers. The line width, pattern (transparency ratio), and color of the lines can be specified. The default is no dividing lines.

The PrintList Pro frame and header separator (the line between the headers and the list or detail area) lines can be set using PL_SetFrame.

You (or the database end-user) must be sure to set the Color/Grayscale option in the print dialog when using colors.

Hairline Line Width

Lines can be printed a fraction of the line width seen on screen (1 pixel).

Typically, ¼ (.25) pixel produces the best results. All the lines that PrintList Pro prints may be given a fractional line width.

Double lines

Double lines (typical in accounting) are now supported in breaks: just use 2.0 as the lineWidth (5th parameter to PL_SetBrkColOpt / PL_SetBrkColRGBOpt / PL_SetBkHColOpt / PL_SetBkHColRGBOpt). Two 0.25 point lines will be printed.

Using Picture Arrays

PrintList Pro supports the printing of picture arrays. The format parameter of PL_SetFormat will cause the picture to be printed in one of five ways:

  • truncated and justified to the upper left of the cell
  • truncated and centered in the cell
  • scaled to fit the cell
  • scaled proportionally to fit the cell
  • scaled proportionally to fit the cell and centered

The usePictHeight parameter of PL_SetFormat will tell PrintList Pro whether to use a picture’s original height, which is stored with the picture, when calculating the row height for the PrintList Pro area.

If you choose not to use the picture’s height in the row height calculation and additional space is needed to print the picture, the numRowLines parameter of PL_SetHeight should be used to increase the row height.

End of Page Callback Method

In 4D, a “callback” method is a project method called from an plug-in. 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 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.

Performance Issues with Formatting Commands

PrintList Pro uses an algorithm to automatically size the columns. Because of this, there is usually no need to use PL_SetWidths to manually size a column prior to printing a list.

However, if the number of items in the list is very large (several thousand items with many columns), then the list might take a few seconds longer to generate, due to the automatic sizing calculation.

If this is the case, using PL_SetWidths will improve the generation time of the list. Text arrays will take the longest to automatically size.

Since you can use PL_SetWidths on just some of the columns, if you are printing very large arrays, but only one is text, you could use PL_SetWidths on just the text array, and let PrintList Pro automatically calculate the other column widths.

PL_SetFormat does not affect the performance of PrintList Pro, regardless of the size of the arrays being printed.

Borders and Frames

PL_SetCellBorder provides the ability to set the border style for a cell.

PL_SetCellFrame prints a frame around a range of cells.

Both commands use RGB colors.

Header / Cell Icon Support

Picture Objects in Cells

PL_SetCellIcon uses 4D Picture Library items or PrintList Pro's own picture library populated by PL_SetIcon to place icons into individual cells.

This routine includes an iconRef parameter, which is the reference number of a picture from the Design environment Picture Library or PrintList Pro's own picture library. Pass zero (0) if you do not want any icon for the cell.

Picture Objects in Headers

In addition, PL_SetCellIcon provides the ability to procedurally place icons in column headers using 4D Picture Library objects or PrintList Pro's own picture library populated by PL_SetIcon.

Pass zero (0) in the cellRow parameter to set the header.

configuring_printlist_pro.txt · Last modified: 2017/10/24 17:06 by plp_admin