User Tools

Site Tools


break_level_processing

Warning: "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /homepages/26/d173627097/htdocs/e-node/docs/PLP/inc/parser/handler.php on line 1552

Break Level Processing

About PrintList Pro Break Level Processing

The PrintList Pro break level processing routines provide the functionality of 4D’s Quick Report capabilities, and much more.

You can choose to display a variety of information for any break level and any column within that break including: static text, Quick Report calculations, custom calculations or break data insertion for each break.

Each piece of information can be shown in different fonts, sizes and styles as well as different colors. You can also control the display of repeated values.

When Do Breaks Occur?

When a list is sorted, often some of the sorted array elements will have groups of identical values.

For example, if the membership of a club that consisted of members from many different countries was sorted by country, the membership list would likely consist of many members that were from the same country. Because the list is sorted, all the members from the same country would be grouped together in the list. A “break” would occur in the list anytime the group changes (the country is different).

Multiple break levels occur when the list is sorted on multiple criteria. The number of any break level is determined by its position in the sort order.

If the same membership list is sorted by country first and then by city, a break for break level one (country) would occur whenever the country changes in the list, and a break for break level two (city) would occur whenever the city changes in the list.

When a break occurs for a certain level, every break level higher than it will occur as well. In the club example, break level 2 (city) will always break whenever a break for break level 1 (country) occurs.

You may want to show leading or summary information for the groups of information within the list. In PrintList Pro, these areas are called break headers and break footers respectively.

A break header will print information just prior to the group of related values while a break footer will print information immediately after the group.

The following is an illustration of the location of break headers and footers within a list:

Using PrintList Pro Break Level Processing

Any break level routine that accepts a column number requires that the column / array be set using PL_SetArraysNam or PL_AddColumn prior to calling that routine.

PrintList Pro provides up to 15 break levels and a total line at the end of list. For any given list, the number of break levels can be no greater than the number of sorted arrays.

PrintList Pro will only print a break for a break level that has been configured using PL_SetBrkText for break footers or PL_SetBkHText for break headers.

A break level can be configured regardless if lower breaks have been configured. This is different than 4D’s Quick Report Editor that requires the users to “stack” break levels upon lower (closer to 0) break levels and hide the break levels that are not desired.

With PrintList Pro, a break level can be configured regardless if lower breaks have been configured; therefore, there is no need to “hide” a break. In the people example, information can be shown for a group of people in the same city without necessarily showing any information for the state.

In conjunction with PL_SetArraysNam, PrintList Pro uses the information in PL_SetSort to determine where the breaks occur within the arrays.

If the arrays passed to PrintList Pro are pre-sorted, PL_SetBrkOrder should be used to notify PrintList Pro of the sort order without forcing an unnecessary sort.

The break level parameter used in many break level routines is the position of a particular column within the sort order given.

For example, if a list of people were to be sorted by state, county, and city respectively, the calls to set and sort the arrays would be:

PL_SetArraysNam (eList;1;4;aPeople;aCity;aCounty;aState)

PL_SetSort (eList;4;3;2)

Break level 1 is state (column 4), break level 2 is county (column 3), and break level 3 is city (column 2).

The following commands are used to configure breaks: PL_SetBrkColOpt, PL_SetBrkColRGBOpt, PL_SetBrkColor, PL_SetBrkRGBColor, PL_SetBrkFunc, PL_SetBrkHeight, PL_SetBrkStyle, PL_SetBrkText.

The following commands are used to configure break headers: PL_SetBkHColOpt, PL_SetBkHColRGBOpt, PL_SetBkHColor, PL_SetBkHRGBColor, PL_SetBkHFunc, PL_SetBkHHeight, PL_SetBkHStyle, PL_SetBkHText.

PL_SetBrkRowDiv and PL_SetBrkRowRGBDiv are not specifically break footer or header routines.These commands specify the line that are drawn between a break footer and the following break header or group of rows.

Setting a Break Level

To show information for a break level, you will need to use PL_SetBrkText for break footers and PL_SetBkHText for break headers.

A text variable containing the information to be printed is passed in for a particular cell within the break. Because a break can consist of more than one text line, the supplied text may wrap into several lines. See Multiple Lines in a Break and Variable Height Breaks for more information.

Carriage returns may be embedded into the text to force wrapping.

Text Overflow and Justification in Breaks

Unlike a Quick Report, information to be printed in a cell can overflow into adjacent columns depending on the justification.

As specified in the call to PL_SetBrkText or PL_SetBkHText, the area used to print the text is taken from the column specified and adjacent columns to the right for left justification, columns to the left for right justification, and columns on both sides for center justification.

Built-in Calculations

Calculations may be embedded into the text passed to PL_SetBrkText or PL_SetBkHText.

Built-in functions — sum, minimum, average, maximum, count, variance, standard deviation and break value — can be inserted into the text at any desired location. These are identical to 4D’s QuickReport calculations except for break value which inserts the value from the array that caused the break.

Custom Calculations

You may create custom calculations to be used with or instead of the built-in calculations.

When PrintList Pro sees the custom calculation delimiter, it will execute a callback method, specified using PL_SetBrkFunc for break footers and PL_SetBkHFunc for break headers, that performs the custom calculation.

The callback method may use most 4D commands, but should not call any PrintList Pro commands or any 4D commands that affect the arrays.

Also, the callback method should preserve the current selection of the printing layout’s file by saving and restoring the selection if necessary. The value returned by the callback method will then be printed at the embedded position within the break text.

Suppressing Repeated Values

Repeated values in a sorted list can be suppressed using PL_SetRepeatVal. The repeated value is shown on the first occurrence and at the top of each page thereafter.

PL_SetRepeatVal works on any sorted list regardless of whether any break level information is shown or not.

Style and Color in Breaks

Style and color settings can be provided for each column within each break level using:

  • PL_SetBrkColor for break footers and PL_SetBkHColor for break headers to set foreground and background colors using PrintList Pro’s palette or 4D’s palette.
  • PL_SetBrkRGBColor for break footers and PL_SetBkHRGBColor for break headers to set foreground and background colors using standard RGB values.
  • PL_SetBrkStyle for break footers and PL_SetBkHStyle for break headers to set text style settings

If no style or color information is given, PrintList Pro will use the corresponding column settings from the list.

Multiple Lines in a Break

Both break headers and footers can be configured to be a fixed number of lines per break or a variable number of lines.

To set the number of lines to be printed in a break level, use PL_SetBrkHeight for break footers and PL_SetBkHHeight for break headers. Please read the section Variable Height Breaks for more information.

If no calls to PL_SetBrkText are made for a specific break level, nothing will be displayed for any break occurring for that level regardless of the number of lines or height pad specified in PL_SetBrkHeight.

Lines Displayed in a Break

PrintList Pro provides complete control over all the lines printed in a break as shown in the following illustration:

Whenever a break or group of breaks is printed, the line following the last break, referred to as the Break / Row Divider, can be configured using PL_SetBrkRowDiv or PL_SetBrkRowRGBDiv. If the Break / row divider is not set, the row divider (if set) will be printed by default.

If column dividers have been set using PL_SetDividers or, they can be printed in the break using PL_SetBrkColOpt / PL_SetBrkColRGBOpt for break footers and PL_SetBkHColOpt / PL_SetBkHColRGBOpt for break headers.

If set, the column divider will be printed in the break area to the right of each column within the break level.

A horizontal line, referred to in the illustration on the previous page as the Horizontal Break line, may be printed within the break areas as well.

  • for break footers, use PL_SetBrkColOpt / PL_SetBrkColRGBOpt to print a line at the top of the cell within the break footer area
  • for break headers, use PL_SetBkHColOpt / PL_SetBkHColRGBOpt to print a line at the bottom of the cell within the break header area

Hide the Detail Area

The detail area (the list of array data) can be hidden to show only the break level information on the page using PL_SetColOpts. This is ideal for giving a summary of the array information.

Page Breaks

PL_SetPageBreak tells PrintList Pro whether or not to force a page break on any given break level.

The page break will occur immediately after the break footer is printed for that break level. However, a page break can be set for a break level regardless of whether a break level is configured to print a break footer.

PL_SetBrkOpts can be called with the parameter printLastPageBreak to print or suppress a a page break if it occurs on the last page. This option is used to avoid the printing of an unneeded blank page at the end of a PrintList Pro report.

Variable Height Breaks

Any given break level can be set to be a variable height. The same rules apply to breaks as to the rows in that a break can be of no height or up to the height of an entire page.

When a break level is set to be variable height, PrintList Pro will perform the necessary break level calculation(s) to determine the height of the text that is to be printed in the break.

To set a break level to be variable height use PL_SetBrkHeight for break footers and PL_SetBkHHeight for break headers.

Using Break Headers

The ability to configure break headers is identical to that of break footers including:

  • all calculations: sum, min, average, max, count, variance, standard deviation and break value
  • a callback for the break function (one callback for all break headers)
  • full style (font, size, style) control for each cell within the break
  • horizontal and vertical line/divider control
  • foreground and background colors for each cell within the break
  • variable height breaks

Break headers can be configured using six commands: PL_SetBkHText, PL_SetBkHFunc, PL_SetBkHStyle, PL_SetBkHColor / PL_SetBkHRGBColor, PL_SetBkHHeight, and PL_SetBkHColOpt / PL_SetBkHColRGBOpt. These commands are identical in syntax to the break footer commands.

PL_SetBrkColOpt / PL_SetBrkColRGBOpt can be called to print horizontal lines at the top of a cell with a break footer. With break headers, the equivalent commands PL_SetBkHColOpt / PL_SetBkHColRGBOpt will print lines at the bottom of a cell within the break header.

Just as with break footers, break headers will only be printed if the command to set the break text, PL_SetBkHText, has been called for a particular break level.

Break headers can be configured to be fixed or variable height and have full background color control as is now available with break footers.

Using Computed Breaks

These powerful commands can be used as array utilities without need to print anything and don't even require to set up a plug-in area.

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 (pointers to arrays).

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

PL_ProcessArrays operates on a copy of the arrays, you can freely modify them in the callback.

The callback method is called by PrintList Pro as:

callbackMethodName (handle:L; row:L; breakLevel:L)

PL_GetBreakValue can only be called from the callback method with the specified handle that was received.

This command performs any break level processing calculation (sum, minimum, average, maximum, count, variance, standard deviation) for the current break level (or individual row) and the specified column (from the list previously defined by the dataArrays parameter).

See Example 5 — Computed Breaks.

Commands

PL_SetPageBreak

(areaRef:L; breakLevel:L; insertPageBreak:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→insertPageBreak longint Insert a page break after the break level.

PL_SetPageBreak is used to set a page break after each break at the specified break level.

A page break can be inserted provided the rows are sorted. However, it is not necessary to configure a break level using PL_SetBrkText or PL_SetBkHText in order to insert a page break.

For the specified break level, the break header, the rows, and the break footer will print (if so configured) prior to the page break. Any subsequent break footers or rows will be printed at the top of the following page.

breakLevel — The position in the sort order specified in PL_SetSort or PL_SetBrkOrder i.e. 1 through n, where n is the number of levels of sort.

insertPageBreak — 0 or 1:

Value Mode
0 No page break will be inserted (default)
1 A page break will be inserted after each break at the specified break level

Refer to PL_SetBrkOpts to see how to print or suppress a page break on the last page of a PrintList report.

Example

  PL_SetPageBreak(eList;1;1) // force a page break after printing each break of break level 1

PL_SetBrkOpts

(areaRef:L;printLastPageBreak:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→printLastPageBreak longint Print a page break on the last page.

PL_SetBrkOpts is used to set options pertaining to break levels.

printLastPageBreak — 0 or 1:

Value Mode
0 The page break will be suppressed (default)
1 If there is a page break on the last page, it will be printed

Refer to PL_SetPageBreak for configuring page breaks.

Example

  PL_SetBrkOpts(eList;0) // don’t print the last page break

PL_SetBrkOrder

(areaRef:L; colNum1:L; …; colNumN:L)

Parameter Type Description
→areaRef longint  Reference of PrintList Pro object on layout.
→ colNum1; …; colNumN longint Column(s) that reflects the sort order.

PL_SetBrkOrder is used to communicate the sort order of a previously sorted list to PrintList Pro. The sort information is used by PrintList Pro to determine where breaks occur within the sorted list.

The syntax of this call is identical to that of PL_SetSort.

colNum — A value greater than 0 indicates that an ascending sort was performed upon that column, while a value less than 0 indicates a descending sort. If a columnNum is 0 then all successive columns will be ignored.

Note: PL_SetBrkOrder does not perform a sort.

Examples

  PL_SetBrkOrder(eContacts;3;4;7) // was sorted on columns 3, 4, and 7 (all ascending)
  PL_SetBrkOrder (eContacts;-1;3;-2) // was sorted on columns 1 descending, 3 ascending, 2 descending

PL_SetRepeatVal

(areaRef:L; columnNum:L; repeatValues:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→columnNum longint Column number.
→repeatValues longint Hide/print repeated values for this column.

PL_SetRepeatVal is used to control the printing of repeated values within a sorted column.

Use PL_SetSort to sort the arrays or if already sorted, use PL_SetBrkOrder to communicate the sorted order to PrintList Pro.

columnNum — The column number to apply this command to. Use a value of zero (0) to apply the repeat settings to all columns in the list.

repeatValues — 0 or 1:

Value Mode
0 Print all repeated values (default)
1 Only print the first occurence of a repeated value after reaching a break and at the top of each page thereafter

Examples

  PL_SetRepeatVal(eList;3;0) // show repeat values for column 3
  PL_SetRepeatVal(eList;0;1) // hide repeat values for all columns

PL_SetBrkText

(areaRef:L; breakLevel:L; columnNum:L; breakText:T; numColsToOverflow:L; justification:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Column number.
→breakText longint Text to be printed when a break occurs.
→numColsToOverflow longint Number of adjacent columns to overflow into.
→justification longint Justification of the break text.

PL_SetBrkText is used to specify the text, passed in as breakText, to be printed in the breakLevel and columnNum specified.

Calculations can be performed upon the corresponding values in the list. A calculation is performed by embedding a special calculation string(s) into breakText as described below.

Text can overflow to adjacent columns using the numColsToOverflow parameter. The text is justified within a column(s) using the justification parameter.

If no call to PL_SetBrkText is made for breakLevel, no break information will be printed for that break level.

breakLevel — The position in the sort order specified in PL_SetSort or PL_SetBrkOrder — i.e., 1 through n, where n is the number of levels of sort. Use a value of 0 to specify the total line to be printed at the end of the list.

columnNum — The column number at which the specified text will be placed for the specified breakLevel.

breakText — The text to be shown in columnNum whenever a break occurs for breakLevel. The text may automatically wrap to multiple lines or carriage returns can be embedded to force text wrapping. Use PL_SetBrkHeight or PL_SetBkHHeight to set the number of text lines for a break level if more than 1 line is anticipated.

A calculation may be performed on all the values in columnNum since the last break for breakLevel.

breakText can include embedded calculation strings which inform PrintList Pro to perform the desired calculation using the array values associated with columnNum. The result of the calculation is formatted into a string which replaces the calculation string at its location within breakText.

The following table shows a list of the calculations and the associated strings (not case-sensitive) that can be included in breakText:

Calculation Calculation String
Sum “\Sum”
Minimum “\Minimum”
Average “\Average”
Maximum “\Maximum”
Count “\Count”
Variance “\Var”
Standard deviation “\Dev”
Break Value Insertion “\BreakValue”

Sum, Minimum, Average, Maximum, Count and Standard deviation are identical to that of 4D’s QuickReport editor.

Break Value Insertion will use the array value from the sorted column that is associated with breakLevel for insertion into breakText.

Custom Calculation will execute the callback function specified in PL_SetBrkFunc or PL_SetBkHFunc to retrieve a string for insertion into breakText.

See PL_SetBrkFunc and PL_SetBkHFunc for details of performing custom calculations using the callback function.

Not all calculations are available on all array types. The following table lists the possible calculations for the various array data types and the resulting type of the calculation:

Column Data Type Calculation Data Type of Result
numeric Sum same as column
numeric Minimum same as column
numeric Average real
numeric Maximum same as column
all Count longint
 numeric  Variance same as column
numeric Standard deviation same as column
all  Break Value Insertion same as break column
all  Custom Calculation  formatted text

When the resulting value’s data type is the same as the columnNum data type, the value is formatted using the column’s format. Otherwise, the calculations’ results will use PrintList Pro’s real and integer default formats where appropriate.

The result of the custom calculation is formatted by the callback function which returns text. numColsToOverflow — Number of adjacent columns to use when overflowing to the right (when left justified), or left (when right justified), or both (when center justified) of columnNum. A value of zero, which is the default, indicates that breakText will only be printed within the column.

justification — The justification of breakText within the column (or columns if numColsToOverflow is greater than 0):

Value Justification
0 Default (justification of columnNum in the list detail area will be used)
1  Left
2 Center
3 Right

Examples

  //Break level 1, column 3, overflow 2 columns to the right, left-justified
  PL_SetBrkText(eList;1;3;"Company Subtotals";2;1)
  //Break level 3, column 6, no column overflow, use default justification
  PL_SetBrkText (eList;3;6;"\Sum";0;0)
  //Break level 4, column 3, overflow into 1 column on both sides of this column, center-justified
  PL_SetBrkText(eList;4;3;"There are \Count people in this department.";1;2)

PL_SetBkHText

(areaRef:L; breakLevel:L; columnNum:L; breakText:T; numColsToOverflow:L; justification:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Column number.
→breakText longint Text to be printed when a break occurs.
→ numColsToOverflow longint Number of adjacent columns to overflow into.
→justification longint Justification of the break text.

PL_SetBkHText is used to specify the text that is to be printed in the break header. The syntax of this command is identical to that of PL_SetBrkText.

PL_SetBrkFunc

(areaRef:L; functionName:T)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→functionName text Function name to be called back.

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.

The callback function should be created using the following interface:

  //Function: MyBreakFunction (breakLevel; column; colFormat; startRow; endRow)
  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
  //... perform the custom calculation
  $0:=String(customCalc;$3) // format the string using the column format

The callback function is passed the break level number for which the break has occurred, the column number, the format of that column, and the starting and ending indexes of the corresponding array.

The function should return, as formatted text, the result of the calculation. The return variable, $0, should be of type text and should be 255 characters or less.

Example

  PL_SetBrkFunc(eList;"Break Function") custom calculation callback

See Example 4 - Break Level Processing for an example of a custom calculation callback function.

PL_SetBkHFunc

(areaRef:L; functionName:T)

Parameter Type
→areaRef longint Reference of PrintList Pro object on layout.
→ functionName text Function name to be called back.

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.

PL_SetBrkStyle

(areaRef:L; breakLevel:L; columnNum:L; fontName:T; size:L; styleNum:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout
→breakLevel longint Break level number
→columnNum longint Column number
→fontName  text Name of the font
→size longint  Size of the font
→styleNum longint Style of the font

PL_SetBrkStyle is used to control the appearance of the break level text for the breakLevel and columnNum specified. The columns can be controlled individually or as a group.

breakLevel — This parameter specifies the break level to apply this command to.

columnNum — The column to apply this command to. Use a value of zero (0) to apply the parameters to all columns within that break level.

fontName — This specifies the font for the break. The break font may be left unchanged by setting fontName to the empty string (“”). If the font specified is not found, it will be treated as an empty string and ignored.

fontSize — This specifies the font size for the break. The break font size may be left unchanged by setting fontSize to 0.

styleNum — This parameter is a font style code. Use the Style constants, which can be combined.

Note: if bold or italic styles are set, but not installed for the font, PrintList Pro will print regular (plain) characters.

PL_SetBkHStyle

(areaRef:L; breakLevel:L; columnNum:L; fontName:T; size:L; styleNum:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Column number.
→fontName text Name of the font.
→size longint Size of the font.
→styleNum longint Style of the font.

PL_SetBkHStyle is used to set the style of the text that is to be printed in the break header.

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

PL_SetBrkColor

(areaRef:L; breakLevel:L; columnNum:L; plpForeColor:T; 4dForeColor:L; plpBackColor:T; 4dBackColor:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→ columnNum longint Column number.
→plpForeColor text Foreground color from PrintList Pro’s palette.
→4dForeColor longint Foreground color from 4D’s palette.
→plpBackColor text Background color from PrintList Pro’s palette.
→4dBackColor longint Background color from 4D’s palette.

PL_SetBrkColor is used to specify the color of the text to be printed in the specified columnNum and breakLevel. breakLevel — This parameter specifies the break level to apply this command to.

columnNum — The column to apply this command to. Use a value of zero (0) to apply the colors to all columns within that break level.

plpForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the break. If the name is not in PrintList Pro’s palette or it is the empty string (“”), then 4dForeColor will be used.

4dForeColor — 1 to 256. Foreground color number for the break (from 4D’s palette). If a break foreground color has been previously set, it may be removed by setting plpForeColor to the empty string (“”), and 4dForeColor to 1. The break foreground color may be left unchanged by setting plpForeColor to the empty string (“”), and 4dForeColor to 0.

plpBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the break. If the name is not in PrintList Pro’s palette or it is the empty string (“”), then 4dBackColor will be used.

4dBackColor — 1 to 256. Background color number for the break (from 4D’s palette). If a break background color has been previously set, it may be removed by setting plpBackColor to the empty string (“”), and 4dBackColor to 1. The break background color may be left unchanged by setting plpBackColor to the empty string (“”), and 4dBackColor to 0.

Examples

  //Set the foreground color for the break in column 3, break level 1, to red - no background color
  PL_SetBrkColor (eList;1;3;"red";0;"";0)
  //Set the background color for the break in column 3, break level 1, to blue - no foreground color
  PL_SetBrkColor (eList;1;3;"";0;"Blue";0)

PL_SetBrkRGBColor

(areaRef:L; breakLevel:L; columnNum:L; breakForeRed:L; breakForeGreen:L; breakForeBlue:L; breakBackRed:L; breakBackGreen:L; breakBackBlue:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Column number.
→breakForeRed longint Foreground red.
→breakForeGreen longint Foreground green.
→breakForeBlue longint Foreground blue.
→breakBackRed longint Background red.
→breakBackGreen longint Background green.
→breakBackBlue longint Background blue.

PL_SetBrkRGBColor is used to specify the color of the text to be printed in the specified columnNum and breakLevel.

This routine works in the same manner as PL_SetBrkColor, except it allows you to specify the colors using standard RGB values.

PL_SetBkHColor

(areaRef:L; breakLevel:L; columnNum:L; plpForeColor:T; 4dForeColor:L; plpBackColor:T; 4dBackColor:L)

Parameter Type Description
→areaRef longint  Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Column number.
→plpForeColor text Foreground color from PrintList Pro’s palette.
→4dForeColor longint Foreground color from 4D’s palette.
→plpBackColor text Background color from PrintList Pro’s palette.
→4dBackColor longint  Background color from 4D’s palette.

PL_SetBkHColor is used to specify the color of the text to be printed in the break header for the specified columnNum and breakLevel.

breakLevel — This parameter specifies the break level to apply this command to.

columnNum — The column to apply this command to. Use a value of zero (0) to apply the colors to all columns within that break level.

plpForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the break. If the name is not in PrintList Pro’s palette or it is the empty string (“”), then 4dForeColor will be used.

4dForeColor — 1 to 256. Foreground color number for the break header (from 4D’s palette). If a break header foreground color has been previously set, it may be removed by setting plpForeColor to the empty string (“”), and 4dForeColor to 1. The break header foreground color may be left unchanged by setting plpForeColor to the empty string (“”), and 4dForeColor to 0.

plpBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the break header. If the name is not in PrintList Pro’s palette or it is the empty string (“”), then 4dBackColor will be used.

4dBackColor — 1 to 256. Background color number for the break header (from 4D’s palette). If a break header background color has been previously set, it may be removed by setting plpBackColor to the empty string (“”), and 4dBackColor to 1. The break header background color may be left unchanged by setting plpBackColor to the empty string (“”), and 4dBackColor to 0.

Examples

  //Set the foreground color for the break header in column 3, break level 1, to red - no background color
  PL_SetBkHColor (eList;1;3;"red";0;"";0)
  //Set the background color for the break header in column 3, break level 1, to blue - no foreground color
  PL_SetBrkColor (eList;1;3;"";0;"Blue";0)

PL_SetBkHRGBColor

(areaRef:L; breakLevel:L; columnNum:L; brkHdrForeRed:L; brkHdrForeGreen:L; brkHdrForeBlue:L; brkHdrBackRed:L; brkHdrBackGreen:L; brkHdrBackBlue:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint  Column number.
→ brkHdrForeRed longint Foreground red.
→brkHdrForeGreen longint Foreground green.
→brkHdrForeBlue longint Foreground blue.
→brkHdrBackRed longint Background red.
→brkHdrBackGreen longint Background green.
→brkHdrBackBlue longint  Background blue.

PL_SetBkHRGBColor is used to specify the color of the text to be printed in the break header for the specified columnNum and breakLevel.

This routine works in the same manner as PL_SetBkHColor, except it allows you to specify the colors using standard RGB values.

PL_SetBrkHeight

(areaRef:L; breakLevel:L; numBreakLines:L; breakHeightPad:L)

Parameter Type Description
→areaRef longint   Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→ numBreakLines longint Number of text lines in the break.
→breakHeightPad longint Extra height for the break.

PL_SetBrkHeight is used to set the number of lines of text along with additional height pad for breakLevel. If no calls to PL_SetBrkText are made for breakLevel, nothing will be displayed for any break occurring for that level regardless of the number of lines or height pad specified in PL_SetBrkHeight.

numBreakLines — The number of lines to give to each break of the specified break level. A value greater than 0 means that the height of each break is the same. The fixed height will be a function of the number of text lines specified. A value of zero means that the height of each break is to be calculated automatically based on the data that is to be printed. Default is 1.

breakHeightPad — The extra height to give to the break level. breakHeightPad sets an additional padding to allow more space around the break. Text will be centered vertically within the break. Default is 0.

The padding applies to the entire break and not on a line by line basis within the break.

Examples

  //Allocate 5 lines and no pad for break level 3
  PL_SetBrkHeight (eList;3;5;0)
  //Break level 2, Pad by 4 pixels, only 1 line
  PL_SetBrkColor (eList;2;1;4)

PL_SetBkHHeight

(areaRef:L; breakLevel:L; numBreakLines:L; breakHeightPad:L)

Parameter Type Description
→areaRef  longint Reference of PrintList Pro object on layout.
→breakLevel longint  Break level number.
→ numBreakLines longint Number of text lines in the break.
→breakHeightPad longint Extra height for the break.

PL_SetBkHHeight is used to set the number of lines of text along with additional height pad for the specified break header level. The syntax of this command is identical to that of PL_SetBrkHeight.

numBreakLines — The number of lines to give to each break of the specified break level. A value greater than 0 means that the height of each break is the same. The fixed height will be a function of the number of text lines specified. A value of zero means that the height of each break is to be calculated automatically based on the data that is to be printed. Default is 1.

breakHeightPad — The extra height to give to the break level. breakHeightPad sets an additional padding to allow more space around the break. Text will be centered vertically within the break. Default is 0.

The padding applies to the entire break and not on a line by line basis within the break.

PL_SetBrkRowDiv

(areaRef:L; lineWidth:F; pattern:T; plpColor:T; 4dColor:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→lineWidth real Width of the break / row divider line.
→pattern text Pattern of the line.
→plpColor text Color from PrintList Pro’s palette for the line.
→4dColor longint Color from 4D’s palette for the line.

PL_SetBrkRowDiv is used to set the line width, pattern (transparency ratio) and color of the break / row divider line which is drawn between any/all break level information and the rows of list data (detail area) that immediately follow.

lineWidth — 0 to 1. This option controls the line width of the break / row divider line. A value of 0.25 pixels should be used for hairlines. A value of 0 means that no line will be printed.

pattern — Name of the pattern (transparency ratio) for the break / row divider line. If a null string is used then no line will be printed. See the Patterns item in the Compatibility Notes.

plpColor — Name of the color in PrintList Pro’s palette. This will be the color for the break / row divider line. If the name is not in PrintList Pro’s palette or it is a null string, then 4dColor will be used.

4dColor — 1 to 256. The color at this position in 4D’s palette will be used for the break / row divider line.

If PL_SetBrkRowDiv is not called, then the settings for the detail area row dividers, if any, will be used.

Examples

  //Print 1 pixel wide, solid Red break/row divider line
  PL_SetBrkRowDiv (eList;1;"Black";"Red";0)
  //Print hairline width, solid gray break/row divider line
  PL_SetBrkRowDiv (eList;0.25;"Black";"Gray";0)

PL_SetBrkRowRGBDiv

(areaRef:L; lineWidth:F; dividerRed:L; dividerGreen:L; dividerBlue:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→lineWidth  real Width of the break / row divider line.
→dividerRed longint  Divider line — Red.
→dividerGreen longint Divider line — Green.
→dividerBlue longint Divider line — Blue.

PL_SetBrkRowRGBDiv is used to set the line width and color of the break / row divider line which is drawn between any/all break level information and the rows of list data (detail area) that immediately follow.

This routine works in the same manner as PL_SetBrkRowDiv, except it allows you to specify the colors using standard RGB values.

PL_SetBrkColOpt

(areaRef:L; breakLevel:L; columnNum:L; showColDivider:L; lineWidth:F; pattern:T; plpColor:T; 4dColor:L)

Parameter Type Description
→ areaRef  longint Reference of PrintList Pro object on layout.
→breakLevel  longint Break level number.
→columnNum longint Number of column.
→showColDividerlongint
→lineWidth real Width of the horizontal break line.
→pattern text Pattern of the horizontal break line.
→ plpColor  text Color from PrintList Pro’s palette for the horizontal break line.
→4dColor  longint Color from 4D’s palette for the horizontal break line.

PL_SetBrkColOpt is used to control the printing of column dividers and horizontal lines within the breakLevel for each columnNum and to print a horizontal line within a column for this break level.

If showColDivider is 1, a column divider will be printed along the right side of the column specified. The line characteristics are identical to the column divider shown in the list (detail area).

PL_SetBrkColOpt may be called to show a horizontal line at the top of the break specified in breakLevel in the column specified by columnNum. This horizontal line could be used as a subtotal line to separate a column of values from a sum or average that is calculated in the break.

If PL_SetBrkColOpt is not called for any columns in a given break level, then no column dividers or horizontal break lines will be printed for that break level.

showColDivider — 0 or 1:

Value Mode
0 Don’t show a column divider (default)
1 Show the column divider along the right side of the column specified in the columnNum parameter whenever a break for the break level specified in breakLevel occurs

lineWidth — 0 to 1. This option controls the line width of the horizontal break line. A value of 0.25 pixels should be used for hairlines. A value of 0 means that no line will be printed. Double lines (typical in accounting) are supported in breaks: just use 2.0 as the lineWidth: two 0.25 point lines will be printed.

pattern — Name of the pattern (transparency ratio) for the horizontal break line. If a null string is used then no line will be printed. See the Patterns item in the Compatibility Notes.

plpColor — Name of the color in PrintList Pro’s palette. This will be the color for the horizontal break line. If the name is not in PrintList Pro’s palette or it is a null string, then 4dColor will be used.

4dColor — 1 to 256. The color at this position in 4D’s palette will be used for the horizontal break line.

Examples

  //Break level 2, column 3, print column divider and a hairline wide, solid Blue horizontal line in column
  PL_SetBrkColOpt (eList;2;3;1;0.25;"Black";"Blue";0)
  //Break level 4, print the column dividers in all columns, no horizontal break lines
  PL_SetBrkColOpt (eList;4;0;1;0;"";"";0)

PL_SetBrkColRGBOpt

(areaRef:L; breakLevel:L; columnNum:L; showColDivider:L; lineWidth:F; dividerRed:L; dividerGreen:L; dividerBlue:L)

Parameter Type Description
→areaRef longint  Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint
→showColDivider longint
→lineWidth real Width of the horizontal break line.
→dividerRed longint Horizontal break line — Red.
→dividerGreen longint Horizontal break line — Green.
→dividerBlue longint Horizontal break line — Blue.

PL_SetBrkColRGBOpt is used to control the printing of column dividers and horizontal lines within the breakLevel for each columnNum and to print a horizontal line within a column for this break level.

This routine works in the same manner as PL_SetBrkColOpt, except it allows you to specify the colors using standard RGB values.

PL_SetBkHColOpt

(areaRef:L; breakLevel:L; columnNum:L; showColDivider:L; lineWidth:F; pattern:T; plpColor:T; 4dColor:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint Break level number.
→columnNum longint Number of column.
→showColDivider longint Show column divider, if any, in the break .
→lineWidth real Width of the horizontal break line.
→pattern text Pattern of the horizontal break line.
→plpColor text Color from PrintList Pro’s palette for the horizontal break line.
→4dColor longint Color from 4D’s palette for the horizontal break line.

PL_SetBkHColOpt is used to control the printing of column dividers and horizontal lines within a break header cell.

This command is identical to PL_SetBrkColOpt, except PL_SetBkHColOpt will print the horizontal lines at the bottom of the cell instead of at the top.

If showColDivider is 1, a column divider will be printed along the right side of the column specified. The line characteristics are identical to the column divider shown in the list (detail area).

PL_SetBkHColOpt may be called to show a horizontal line at the bottom of the break specified in breakLevel in the column specified by columnNum.

If PL_SetBkHColOpt is not called for any columns in a given break level, then no column dividers or horizontal break lines will be shown for that break level.

showColDivider — 0 or 1:

Value Mode
0 Don’t show a column divider (default)
1 Show the column divider along the right side of the column specified in the columnNum parameter whenever a break for the break level specified in breakLevel occurs 

lineWidth — 0 to 1. This option controls the line width of the horizontal break line. A value of 0.25 pixels should be used for hairlines. A value of 0 means that no line will be printed. Double lines (typical in accounting) are supported in breaks: just use 2.0 as the lineWidth: two 0.25 point lines will be printed.

pattern — Name of the pattern (transparency ratio) for the horizontal break line. If a null string is used then no line will be printed. See the Patterns item in the Compatibility Notes.

plpColor — Name of the color in PrintList Pro’s palette. This will be the color for the horizontal break line. If the name is not in PrintList Pro’s palette or it is a null string, then 4dColor will be used.

4dColor — 1 to 256. The color at this position in 4D’s palette will be used for the horizontal break line.

PL_SetBkHColRGBOpt

(areaRef:L; breakLevel:L; columnNum:L; showColDivider:L; lineWidth:F; dividerRed:L; dividerGreen:L; dividerBlue:L)

Parameter Type Description
→areaRef longint Reference of PrintList Pro object on layout.
→breakLevel longint  Break level number.
→columnNum longint Number of column.
→showColDivider longint Show column divider, if any, in the break.
→lineWidth real Width of the horizontal break line.
→dividerRed longint Horizontal break line — Red.
→dividerGreen longint Horizontal break line — Green.
→dividerBlue longint Horizontal break line — Blue.

PL_SetBkHColRGBOpt is used to control the printing of column dividers and horizontal lines within a break header cell.

This routine works in the same manner as PL_SetBkHColOpt, except it allows you to specify the colors using standard RGB values.

PL_ProcessArrays

(callbackMethodName:T; breakArrays:Y; dataArrays:Y; useDetail:L) ª error:L

Parameter Type Description
→callbackMethodName text Name of the Computed Break callback project method.
→breakArrays array Array of pointers to arrays where breaks must occur (one array for each break level).
→dataArrays  array  Array of pointers to arrays containing the data to be processed in the callback method.
→useDetail longint 0 = callback method is called only on breaks
1 = callback method is called on breaks and on each row.

PL_ProcessArrays is used to set Computed Breaks. No plugin area is needed, this feature is pure computing on previously sorted arrays (e.g. with MULTI SORT ARRAY)

callbackMethodName — 4D project method to be called on breaks as defined by breakArrays and also on each row according to useDetail.

The callback method is called as: callbackMethodName (handle:L; row:L; breakLevel:L)

  • handle is to be used as parameter 1 when calling PL_GetBreakValue for the callback
  • row is the current row number
  • breakLevel is the current break level, -1 for data row (if useDetail = 1)

breakArrays — ARRAY POINTER containing pointers to previously sorted arrays where breaks should occur and callbackMethodName be called. Local arrays are allowed. First element determines break level 1, second 2, etc.

When breakArrays is empty, the only break generated will be 0.

dataArrays — ARRAY POINTER containing pointers to arrays that will be passed by callbackMethodName to PL_GetBreakValue in order to retrieve the computed break values. Local arrays are allowed. First element is column 1 for PL_GetBreakValue, second is 2, etc.

When dataArrays is empty, no calculations are performed.

useDetail — set to 0 for callbackMethodName to be called only with break information, set it to 1 to call the callback method with every data row and with breaks.

PL_ProcessArrays operates on a copy of the arrays, you can freely modify them in the callback.

PL_GetBreakValue

(handle:L; column:L; calculation:L) ª value:F

Parameter Type Description
→handle text Identification of the current PL_ProcessArrays call.
→column array Index of the column to be processed in the dataArrays array set by PL_ProcessArrays array.
→calculation array Calculation type.

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

The calculation result is returned in value by PL_GetBreakValue.

handle is an identification of the current PL_ProcessArrays call. This is actually the process ID. Make sure not to call PL_ProcessArrays in the callback!

column is the index from the dataArrays pointer array defined by PL_ProcessArrays. When column is out of range, zero is returned.

calculation can be one of the following values:

Value Calculation
1 Sum
2 Minimum
3 Average
4 Maximum
5 Count
6  Variance 
7 Standard deviation

callbackMethodName is the only place where you can call PL_GetBreakValue, using the handle provided as the first parameter received by the callback method.

Calculations are performed “on the fly” after fetching each data row. So when you call PL_GetBreakValue on a data row (not on a break), you will get the current values for that row.

For example, using empty breakArrays and useDetail=1, calling PL_GetBreakValue to get the SUM (1), the command will return the sum of rows 1 through current row.

See also Using Computed Breaks and Example 5 — Computed Breaks.

break_level_processing.txt · Last modified: 2017/05/19 14:09 by plp_admin