User Tools

Site Tools


configuration_commands

Configuration Commands

In addition to the commands below, PrintList Pro v6 can use all relevant (i.e. non entry or drag and drop related) AreaList Pro properties.

You must install AreaList Pro v9 or v10 to make the ALP_XXX property constants available in your 4D code editor, but you don't need to register AreaList Pro to use them in PrintList Pro.

Specific getter and setter commands are available to access (get or set) such properties.

See the AreaList Pro v9 manual for a description of the AreaList Pro v9 API properties.

Some AreaList Pro v9 properties have been modified and enhanced in AreaList Pro v10.

In addition, many new AreaList Pro v10 properties are also available.

PL_Register

(registrationCode:T; options:L; email:T) → result

Parameter Type Description
→ registrationCodetextPass the registration key to register your copy of PrintList Pro. The key is either linked to the 4D or 4D Server serial number (individual licenses), to the machine ID (merged licenses), to the name of the company / developer (unlimited annual licenses) or to the product (master keys for Online instant activation).
→ optionslongintAn optional longint combining up to 4 bits.
→ emailtextOnline instant activation option: developer email to notify when a license is issued or resent.
← resultlongint0 or error code.

PL_Register is used to register the PrintList Pro plugin for standalone or server use.

Please see the License Types section for detailed information about the licensing options available for PrintList Pro.

Multiple calls to PL_Register are allowed. The plugin will be activated if at least one valid key is used, and all subsequent calls to PL_Register will return 0, unless the force check bit is set to true in the options parameter.

registrationCode — You must call PL_Register with a valid registration key, otherwise PrintList Pro will operate in demonstration mode - it will cease to function after 20 minutes. In case a master key is used the plugin will attempt a connection to e-Node’s license server for Online instant activation.

options — Optional. This parameter combines up to 4 bits as described below. The default mode (registrationCode being a passed as the only parameter) is silent: no force check, no confirmation, no alert, no email.

Bit number Description
0Force check: if this bit is is on (true), registrationCode is tested regardless of current registration state. If the plugin was not previously registered and the result is 0, it is registered the same way as if the bit was off (or the whole options parameter omitted)If the plugin was previously successfully registered, a registration error will be returned in result in case registrationCode is invalid, but the plugin will remain registered
1Online instant activation option: confirm connection “Is it OK to connect to e-Node’s license server to register PrintList Pro?”
2Online instant activation option: display alert if registration error
3Online instant activation option: display alert if registered

email — Optional. The developer email address where to send Online instant activation information.

result — 0 or error code:

Result code Description
0
1Beta license has expired
2Invalid license
3The license has expired
4The OEM license has expired
5The maximum number of users has been exceeded
6The license is for a different environment (e.g. the licence is for a single-user version, but you are using it with 4D Server)
7The license is linked to a different 4D license
8Invalid merged license
9Only serial / ID licenses are allowed in text license files (includes Register button and Online instant activation)
10Unauthorized master key (Online instant activation)
11Can't connect to e-Node's license server to perform Online instant activation
12No Online instant activation license available for this master key (unknown or all used)

When PL_Register is called with an empty string, the license dialog will be displayed if PrintList Pro is not registered and the dialog was not yet displayed. This allows you to show the registration dialog to your users without effectively calling a PrintList Pro command or displaying a PrintList Pro area.

Note: alternately to PL_Register, you can place a plain text file into your 4D Licenses folder or use the Demo mode dialog “Register” button. This is only valid for non-unlimited licenses.

Basic example

C_LONGINT ($result)
$result:=PL_Register ("YourRegistrationKey")
Case of
 :($result=2)
  ALERT ("The PrintList Pro licence is invalid.")
 :($result=3)
  ALERT ("The PrintList Pro licence has expired.")
 etc.
End case

Example with multiple calls

C_LONGINT ($result) // ignored in this case
$result:=PL_Register ("Registration key one")
$result:=PL_Register ("Registration key two")
$result:=PL_Register ("Registration key three")

etc.

If ($result#0) // registration failed on all keys
 ALERT ("PrintList Pro could not be registered.")
End if

Force check example

In this example we assume that only “Registration key two” is valid, but you want to check the other keys status.

C_LONGINT ($result)
$result:=PL_Register ("Registration key one";1) // invalid, will return an error, the plugin isn’t registered
$result:=PL_Register ("Registration key two";1) // valid, will return 0, the plugin is registered
$result:=PL_Register ("Registration key three";1) // invalid, will return an error, the plugin is still registered

Online instant activation examples

Confirm connection, alert if successful, alert if failed, send email notification to developer@4dchampions.com:

C_LONGINT ($result)
$result:=PL_Register ("Master key";0 ?+1 ?+2 ?+3;"developer@4dchampions.com")

Silent connection, alert if successful, alert if failed, no email notification:

C_LONGINT ($result)
$result:=PL_Register ("Master key";0 ?+2 ?+3)

%PrintListPro

%PrintListPro is the command used to identify the PrintList Pro plugin area when you create a plugin area object on a layout.

This command is only used in the object definition for a PrintList Pro object, and should never be used as a command in a method.

PL_AddColumn

(areaRef:L; dataPointer:Z; insertAt:L) → result:L

Parameter Type Description
→ areaReflongintPrintList Pro area reference.
→ dataPointerpointerPointer to an array or a field.
→ insertAtlongintPosition where to insert the column.
← resultlongint0 if successful.

PL_AddColumn adds a column at the specified position. areaRef — PrintList Pro area reference.

dataPointer — This parameter specifies the data to print in the inserted column.

  • when in Records mode, this parameter must be a pointer to a field
  • when in Arrays mode, this parameter must be a pointer to an array (not a local array!)

insertAt — Position where to insert the column. Zero means “append to the end”.

This command supports the component architecture (using arrays from the host database in a component and vice versa).

This command can be used as an alternative to PL_SetArraysNam, but requires one line per array. See the Calculated columns Array mode example.

Examples

  $error:= PL_AddColumn(eList;->aState;0) // add a column containing aState array at the end
  $error:= PL_AddColumn(eList;->aCity;1) // insert a column containing aCity array at position 1

PL_AddCalculatedColumn

(areaRef:L; dataType:L; callbackMethodName:T; insertAt:L) → result:L

Parameter Type Description
→ areaReflongintPrintList Pro area reference.
→ dataType longint The array type to use.
→ callbackMethodNametextName of the method to execute to fill the array.
→ insertAtlongint Position at which to insert a column; 0 means add to the end.
← resultlongint0 if successful.

PL_AddCalculatedColumn adds a calculated column at the specified position.

areaRef — PrintList Pro area reference.

dataType — This parameter specifies the data type to calculate and print in the inserted column:

Array TypeConstantValue
AlphaIs Alpha Field0
BooleanIs Boolean6
DateIs Date4
IntegerIs Integer8
LongintIs Longint9
PictureIs Picture3 or 10
RealIs Real1
TextIs Text2
TimeIs Time11
Universal date/time Mapped to 2 (Text)

callbackMethodName — Name of the method to execute to fill the array. The following parameters will automatically be passed to the callback method:

ParameterTypeDescription
$1AreaList Pro areaLongint
$2columnLongint
$3typeLongint
$4pointer to temporary 4D arrayPointer
$5 first record for which to calculate cellLongint
$6count (number of cells to calculate in the column) Longint

Note: this command is only useful in field mode.

Example

In our database we have retail prices for our products. However, account holders in different levels receive a discount of between 5 and 15%. We want to display the prices with the appropriate discount for the account holder’s level. So instead of adding the Price column, we can add a calculated column.

The actual calculation is done in a callback method whose name you pass when you add the column.

First, we create our callback method:

  // CalculateDiscountPrice
  // Callback method to calculate discount prices
  C_LONGINT($1;$2;$3;$5;$6) // must be declared
  C_POINTER($4) // this must be declared
  SELECTION RANGE TO ARRAY($5;$5+$6-1;[product]retail_price;$price)
  For ($i;1;$6)
    Case of 
      :(<>DiscLevel=1) // <>DiscLevel was set when the user logged in
        $4->{$i}:=Round($price{$i}*0.95;2) // 5% discount
      :(<>DiscLevel=2) 
        $4->{$i}:=Round($price{$i}*0.9;2) // 10% discount
      :(<>DiscLevel=3)
        $4->{$i}:=Round($price{$i}*0.85;2) // 15% discount
    End case
  End for

Now all we need to do is add the calculated column to our AreaList Pro area:

  $err:=AL_AddCalculatedColumn (area;Is real;"CalculateDiscountPrice")

PL_SetArraysNam

(areaRef:L; columnNumber:L; numArrays:L; array1:T; …; arrayN:T) ) → result:L

Parameter Type Description
→ areaRef longint PrintList Pro area reference.
→ columnNumber longint Column at which to set the first array.
→ numArrays longint Number of arrays to set (up to 15).
→ array1; …; arrayN textName(s) of 4D array(s).
← result longint 0 if successful.

PL_SetArraysNam tells PrintList Pro what arrays to print. Up to fifteen arrays can be set at a time. Any 4D array type can be used except pointer and two-dimensional arrays.

Since PrintList Pro can print up to 32767 arrays, this command may have to be used more than once.

There are three very important points to note about this command:

  • This command must be called first, before any of the other commands, in the On Printing Detail phase.
  • The columns must be added in sequential order, unless the particular column has already been added. In other words, to set 30 arrays, you must set arrays 1 through 15 prior to setting arrays 16 through 30.
  • All arrays set with this command must have the same number of elements as each other and as any other arrays previously set.

You can pass process arrays and interprocess arrays to PrintList Pro, but not local arrays (a local array has a name that starts with a “$” character; an interprocess array has a name that starts with “<>” characters).

One dimension of a two-dimensional array may be passed in the array1; …; arrayN parameters. For example: “my2DArray{1}” may be passed as array1.

areaRef — PrintList Pro area reference.

columnNumber— This parameter specifies the column number to set the first array being passed by this call of PL_SetArraysNam.

numArrays — This parameter specifies the number of columns being set with this call to PL_SetArraysNam.

Examples

  Case of
   :(Form event=On Printing Detail)
    SELECTION TO ARRAY([Contacts]FN;aFN;[Contacts]LN;aLN;[Contacts]City;aCity;\
     [Contacts]State;aState) // load the arrays
    $error:=PL_SetArraysNam (eNameList;1;4;"aFN";"aLN";"aCity";"aState") // starting at column 1,
     set 4 arrays to print through the plugin area eNameList
  End case
  
  // Set up the eList PrintList Pro object with 25 arrays
  // two calls must be made since only 15 arrays can be passed each time
  $error:=PL_SetArraysNam (eList;1;15;"array1";"array2";"array3";"array4";"array5";
   "array6";"array7";"array8";"array9";"array10";"array11";"array12";"array13";"array14";"array15")
  $error:=PL_SetArraysNam (eList;16;10;"array16";"array17";"array18";"array19";"array20";
   "array21";"array22";"array23";"array24";"array25")

PL_RemoveColumn

(areaRef:L; column:L; {count:L}) → error:L

Parameter Type Description
→ areaRef longint PrintList Pro area reference.
→ column longint Number of the (first) column to remove.
→ count text Number of columns to remove, starting at column (optional).
← result longint 0 if successful.

PL_RemoveColumn removes one column or several columns from an area. If the count parameter is omitted, only column number column will be removed. Otherwise count column(s) will be removed starting at column.

If you want to remove all the columns in one go, enter -2 for the column number.

Example

To remove columns 3 and 4 from area:

  $err:=PL_RemoveColumn (area;3;2)

PL_SetHeaders

(areaRef:L; columnNumber:L; numHeaders:L; header1:T; …; headerN:T)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn at which to set up the first header.
→ numHeaderlongintNumber of headers to set (up to 15).
→ header1; …; headerNtextValue(s) to print in column header(s).

PL_SetHeaders is used to specify the value to print in the header for each column. Up to fifteen headers can be set at a time.

The size of the header value is used by the automatic column sizing algorithm. If you are printing a text array containing 2 character strings, the column will be very narrow, unless you specify a header which contains several characters.

For example, states are usually stored in a database as a two-character string. But if you specify a header of “State” the column will be sized about two and a half times wider.

If the header length is less than the values being printed in the column, then the header length will not affect the column width.

A, B, C, etc. will be printed in the headers if PL_SetHeaders is not used.

Examples

  $error:=PL_SetArraysNam (eNameList;1;4;"aFN";"aLN";"aCity";"aState")
  PL_SetHeaders(eNameList;1;4;"First Name";"Last Name";"City";"State")
  
  $error:=PL_SetArraysNam (eNames;1;2;"aFN";"aLN"
  PL_SetHeaders(eNames;1;2;Field name([People]FirstName);Field name([People]LastName))

PL_SetFormat

(areaRef:L; columnNumber:L; format:T; columnJust:L; headerJust:L; usePictureHeight:L; attributed:L; lineSpacing:F; vertAlignment:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn at which to set the format and justification.
→ formattextFormat to use.
→ columnJustlongintJustification for column list items.
→ headerJustlongintJustification for column header.
→ usePictHeightlongintUse the picture height in the row height calculation.
→ attributedlongintUse attributed (multi-style) text: 0 = no, 1 = yes.
→ lineSpacingrealLine spacing to use.
→ vertAlignmentlongintVertical alignment: 0 = default, 1 = top, 2 = center, 3 = bottom.

PL_SetFormat is used to control the format and justification of a column being printed. You can control the format of integer, real, date, boolean, and picture columns with the format parameter. Time values can be formatted also, since they use long integer arrays.

Any valid 4D format, including custom formats created in the Design environment, may be used with these column types.

Text columns can only be formatted using styled text with the attributed parameter set to 1.

Additionally, null time and date values can be set to print a blank by appending a dash character (“-”) to the format text parameter.

The defaults for the different column types are:

Column Type Format
(Long) Integer“#,###,##0”
Real“#,###,##0.00”
Boolean“True;False”
Date“0”
Picture“0”

Note: since version 5.3, unused characters are stripped from the format instead of replacing “number sign” placeholders by non-breaking space (e.g. “1234” formatted with “###-###-###” will produce “1-234”, not “ - 1-234” as before).

format (for text arrays) — Not supported, except for attributed text according to the value set by the attributed parameter. format (for numeric arrays) — See the 4D command String in the 4D Language Reference for the possible values. Any valid 4D numeric format may be used.

format (for boolean arrays) — The string contains two formats, one for the True value, the other for the False value, separated by a semicolon. Examples: “Male;Female” and “MacOS;Windows”.

format (for date arrays) — See the 4D command String in the 4D Language Reference for the possible values. Any valid 4D date format may be used. Examples: “0” or “3” are valid formats.

Format Example
009/21/16 (default)
19/21/16
2Wed, Sep 21, 2016
3Wednesday, September 21, 2016
409/21/16 or 09/21/1996
5September 21, 2016
6Sep 21, 2016

format (for “time” arrays) — See the 4D String command in the 4D Language Reference, and the 4D Design Reference discussion of formatting for the possible values. There are no time arrays in 4D as such, they are in reality long integer arrays. These arrays are printed as time PL_SetFormat values by using the proper format. The format is the two character sequence “&/” followed by the number given in the discussion of the String command. For example, one proper format for a time array would be “&/2”.

Format Example
001:02:03
101:02
21 hour 2 minutes 3 seconds
31 hour 2 minutes
41:02 AM

format (for picture arrays):

Format Description
0The picture will be truncated, if necessary, and justified to the upper left (default)
1The picture will be truncated, if necessary, and centered in the cell
2The picture will be scaled to fit the cell
3The picture will be scaled to fit the cell, and remain proportional to its original size
4The picture will be scaled to fit the cell, remain proportional to its original size, and centered in the cell

In addition:

  • If format is not specified or out of range, the value will be interpreted as 0
  • Formats 1 and 4 are always centered, format 2 fills the whole rectangle
  • Only formats 0 and 3 will use the specified columnJust (default alignment is centered for these two formats)

columnJust and headerJust — The justification for a column and its header can be controlled independently.

The possible values are:

Value Justification
0Default
1Left
2Center
3Right

By default, headers are left justified, unless the column elements are center justified. In that case, the header will default to center justification.

The default column justifications for the different column types are:

Column type Default column justification
Long Integer (including Time)Right
RealRight
BooleanLeft
DateRight
TextLeft
PictureDepending on the format parameter

The columnJust parameter is only used for picture columns where the format parameter is set to 0 or 3 (or not specified or out of range). Other values will use the format parameter to justify picture columns.

usePictHeight:

Value Mode
0Ignore the picture height when calculating the row height (default)
1Use height of the largest picture when calculating the row height

If the column columnNumber does not have a picture column, this parameter will be ignored.

If the list is configured to automatically calculate variable height rows, then picture array elements are always included in the automatic calculation, and this parameter is ignored. See PL_SetHeight and Variable Height Rows for more information.

attributed — Styled text:

Value Mode
0Plain text (default)
1(or any non-zero value) — attributed (styled) text

Note: the styled text property is applied to all formatting in that column… breaks have to account for that!

lineSpacing — Line spacing to use (real value). 0 is substituted by 1.0 (default), which is also the default line spacing value used by AreaList Pro and SuperReport Pro.

Line spacing is used for space between lines.

It is computed from the font height as (Ascent + Descent) * lineSpacing

In other words it is a percentage of the font height to use for advancing the text to the next line.

When it is 1.0 (default), next line starts right below the previous one.

For example, if you enter 2 as lineSpacing you will get (in the same cell):

Line 1

Line 2

Line 3

Instead of:

Line 1
Line 2
Line 3

Examples

  // Format a real column (3rd column), default column justification, center header justification
  PL_SetFormat (names;3;"$###,###.00";0;2;0)
  // Format a boolean column (4th column), right column justification and left header justification
  PL_SetFormat (eList;4;"Male;Female";3;1;0)
  // Format style 3 for a date column, default justification (5th column), default column and header justification, suppress null dates
  PL_SetFormat (eNames;5;"3-")
  // Format style 2 for a time column, right justification for header and column (7th column)
  PL_SetFormat (eList;7;"&/2";3;3;0)
  // Custom format style, default justification for column, center header (5thcolumn), attributed text, "compatible" line spacing
  PL_SetFormat (eNames;5;"|Dollars";0;2;0;1;1)
  // Scale picture column to fit proportionally (1st column), use default header justification, use picture size in row height calculation
  PL_SetFormat (eList;1;"3";0;0;1)

vertAlignment — Vertical alignment:

Format Description
0Default
1Top
2Center
3Bottom

PL_SetWidths

(areaRef:L; columnNumber:L; numWidths:L; width1:L; …; widthN:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn at which to set the first width.
→ numWidthslongintNumber of widths to set (up to 15).
→ width1; …; widthNlongintPixel width(s) of column(s).

PL_SetWidths is used to set the pixel width for one or more columns. Up to fifteen widths can be set at a time.

A width of zero forces a column to be sized automatically based on its data type.

A column cannot be less than 3 pixels wide. If you pass a value of less than 3 but greater than zero, PrintList Pro will ignore it and use 3.

PrintList Pro will not let a column be wider than the width of the list area minus 20.

If not called, the default width for all columns is determined based on the type of array or field printed in the column.

Example

  $error:=PL_SetArraysNam (eNames;1;5;"aFN";"aLN";"aCity";"aState";"aZip")
  PL_SetWidths(eNames;1;5;150;50;0;100;0) // 0 forces autosizing for that column

PL_SetIcon

(areaRef:L; iconID:L; iconValue:P) → error:L|

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ iconIDlongintID number (assigned by the developer) of a picture to add to the PrintList Pro picture library. The number must be between 1 and 16777215.
→ iconValuepictureA picture variable that contains the specified picture. If this is empty, the picture is removed from the AreaList Pro picture library. The picture can be a variable or a 4D field.

PL_SetIcon is used to add a picture to PrintList Pro’s picture library, which is basically a picture cache.

You can use 0 as the areaRef to set an icon in the global workstation cache, or specify a given area.

You assign a reference number, which can then be used in the icon placement and formatting commands. Each picture is stored only once but can be used any number of times, thus being very efficient with memory usage.

Icon IDs 1 to 5 can be used to replace PrintList Pro's native icons for hierarchical lists. See “Displaying custom pictures instead of AreaList Pro's native icons” in the AreaList Pro v9 manual.

Note: the plugin picture library is not shared between AreaList Pro and PrintList Pro.

Example

To add a picture from a 4D field to the PrintList Pro picture library and assign it the reference number 100:

  $err:=PL_SetIcon (area;100;[pictures]clock_icon)

For detailed examples of using pictures in your PrintList Pro area, see the “Pictures” topic in the AreaList Pro v9 manual.

PL_SetHdrStyle

(areaRef:L; columnNumber:L; fontName:T; size:L; styleNum:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn for which to set the header style.
→ fontNametextName of the font to use.
→ sizelongintSize of the font.
→ stylenumlongintStyle of the font.

PL_SetHdrStyle is used to control the appearance of the PrintList Pro column headers.

The columns can be controlled individually or as a group.

columnNumber — This parameter specifies what column header to apply the style to. Use a value of zero (0) to apply the parameters to all columns.

fontName — Use this parameter to specify the font for the specified columnNumber. If not called, or the specified font name is not found, the header(s) will be printed in the OS defined System Font. If the font is not installed, then the System Font will be used.

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.

Examples

  PL_SetHdrStyle(eList;1;"Geneva";12;1) // Geneva 12 point bold, column 1
  PL_SetHdrStyle(Names;3;"New York";12;3) // New York 12 point bold italic, column 3
  PL_SetHdrStyle(Names;0;"Palatino";10;3) // Palatino 10 point bold italic, all columns

PL_SetHdrOpts

(areaRef:L; printHeaders:L; printPixelWidth:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ printHeaderslongintPrint the headers above the list.
→ printPixelWidthlongintPrint column widths in the header.

PL_SetHdrOpts is used to control several PrintList Pro options pertaining to column headers.

printHeaders:

Value Mode
0
1 Headers will be printed only on the first page
2Headers will be printed on all pages

printPixelWidth — Used during development to allow you to easily determine what pixel width looks best for each column:

Value Mode
0The normal header text will be printed (default)
1The width of the column will be printed in each header

Examples

  PL_SetHdrOpts(eList;2;0) // print headers on all pages, no pixel widths
  PL_SetHdrOpts(eList;1;1) // print headers on first page, and pixel widths

PL_SetMiscOptions

(areaRef:L; escapeChar:T; useEllipsis:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ escapeChartextEscape character (obsolete).
→ useEllipsislongintUse ellipsis.

PL_SetMiscOptions is used to control miscellaneous PrintList Pro options.

escapeChar — Obsolete, ignored.

useEllipsis — Determines if auto-ellipsis is used when columns are smaller than the printed data:

Value Mode
0Use ellipsis in header and column data
1Don’t use ellipsis in header and column data (default)

PL_SetStyle

(areaRef:L; columnNumber:L; fontName:T; size:L; styleNum:L)

Parameter Type
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn for which to set the style.
→ fontNametextName of the font to use.
→ sizelongintSize of the font.
→ styleNumlongintStyle of the font.

PL_SetStyle is used to control the appearance of the PrintList Pro columns. The columns can be controlled individually or as a group.

columnNumber — This parameter specifies what column to apply the style to. Use a value of zero (0) to apply the parameters to all columns.

fontName — Use this parameter to specify the font for the specified columnNumber. If not called, or the specified font name is not found, the column(s) will be printed in the OS defined System Font. If the font is not installed, then the System Font will be used.

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.

Examples

  PL_SetStyle(eNames;0;"Geneva";9;0) // Geneva 9 plain, all columns
  PL_SetStyle(eList;4;"Helvetica";12;32) // Helvetica 12 point condensed, 4th column
  PL_SetStyle(eNames;1;"Times";9;1) // Times 9 point bold, 1st column

PL_SetForeClr

(areaRef:L; columnNumber:L; plpHdrForeColor:T; 4dHdrForeColor:L; plpListForeColor:T; 4dListForeColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn number.
→ plpHdrForeColortextHeader foreground color from PrintList Pro’s palette.
→ 4dHdrForeColorlongintHeader foreground color from 4D’s palette.
→ plpListForeColortextList foreground color from PrintList Pro’s palette.
→ 4dListForeColorlongintList foreground color from 4D’s palette.

PL_SetForeClr is used to specify the foreground colors for a column header and a list area column.

columnNumber — The column for which to set the foreground color. Use a value of zero (0) to apply the parameters to all columns.

plpHdrForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the column header. If the name is not in PrintList Pro’s palette or it is a null string, then 4dHdrForeColor will be used.

4dHdrForeColor — 1 to 256. The color at this position in 4D’s palette will be used for the foreground color for the column header.

plpListForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the column. If the name is not in PrintList Pro’s palette or it is a null string, then 4dListForeColor will be used.

4dListForeColor — 1 to 256. The color at this position in 4D’s palette will be used for the foreground color for the column.

If PL_SetForeClr is not called, the default is black for both the header and list foreground colors.

Examples

  // Red for column header foreground, light gray for column foreground (all columns)
  PL_SetForeClr(eNames;0;"Red";0;"Light Gray";0)
  
  // Green for column header foreground, 13th color from 4D’s palette for column foreground (4th column)
  PL_SetForeClr (eNames;4;"Green";0;"";13)

PL_SetForeRGBColor

(areaRef:L; columnNumber:L; hdrForeRed:L; hdrForeGreen:L; hdrForeBlue:L; listForeRed:L; listForeGreen:L; listForeBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn number.
→ hdrForeRedlongintHeader fore red.
→ hdrForeGreenlongintHeader fore green.
→ hdrForeBluelongintHeader fore blue.
→ listForeRedlongintList fore red.
→ listForeGreenlongintList fore green.
→ listForeBluelongintList fore blue.

PL_SetForeRGBColor is used to specify the foreground colors for a column header and a list area column, using the RGB values. This routine is similar to PL_SetForeClr.

hdrForeRed — Header foreground RGB red value.

hdrForeGreen — Header foreground RGB green value.

hdrForeBlue — Header foreground RGB blue value.

listForeRed — List foreground RGB red value.

listForeGreen — List foreground RGB green value.

listForeBlue — List foreground RGB blue value.

Example

The following example will tell PrintList Pro to print the third column using a color scheme standard for MacOSX:

  PL_SetForeRGBColor (xArea;3;237;254;243;237;254;243)

PL_SetBackClr

(areaRef:L; plpHdrBackColor:T; 4dHdrBackColor:L; plpListBackColor:T; 4dListBackColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ plpHdrBackColortextHeader background color from PrintList Pro’s palette.
→ 4dHdrBackColorlongintHeader background color from 4D’s palette.
→ plpListBackColortextList background color from PrintList Pro’s palette.
→ 4dListBackColorlongintList background color from 4D’s palette.

PL_SetBackClr is used to specify the background colors for the header and list area.

While the foreground color can be specified for each column, the background color for the header or the list area can only be specified for all columns using this command. You need to use PL_SetColBackColor or PL_SetColBackRGBColor to set the background colors of each column’s header and each column itself.

plpHdrBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the column header. If the name is not in PrintList Pro’s palette or it is a null string, then 4dHdrBackColor will be used.

4dHdrBackColor — 1 to 256. The color at this position in 4D’s palette will be used for the background color for the column header. plpListBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the column. If the name is not in PrintList Pro’s palette or it is a null string, then 4dListBackColor will be used.

4dListBackColor — 1 to 256. The color at this position in 4D’s palette will be used for the background color for the column.

If PL_SetBackClr is not called, the default is white for both the header and list background colors.

Examples

  // Light gray for header background, white for list background, all columns
  PL_SetBackClr(eNames;0;"Light Gray";0;"White";0)
  // White for header background, 13th color from 4D’s palette for list background, 1st column
  PL_SetBackClr (eNames;1;"White";0;"";13)
  

PL_SetBackRGBColor

(areaRef:L; hdrBackRed:L; hdrBackGreen:L; hdrBackBlue:L; listBackRed:L; listBackGreen:L; listBackBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ hdrBackRedlongintHeader back red.
→ hdrBackGreenlongintHeader back green.
→ hdrBackBluelongintHeader back blue.
→ listBackRedlongintList back red.
→ listBackGreenlongintList back green.
→ listBackBluelongintList back blue.

PL_SetBackRGBColor is used to specify the background colors for the header and list area, using the RGB values. This routine is similar to PL_SetBackClr.

While the foreground color can be specified for each column, the background color for the header or the list area can only be specified for all columns using this command.

You need to use PL_SetColBackColor or PL_SetColBackRGBColor to set the background colors of each column’s header and each column itself.

hdrBackRed — Header background RGB red value.

hdrBackGreen — Header background RGB green value.

hdrBackBlue — Header background RGB blue value.

listBackRed — List background RGB red value.

listBackGreen — List background RGB green value.

listBackBlue — List background RGB blue value.

Example

The following example will tell PrintList Pro to print the list using a color scheme standard for MacOS X:

 PL_SetBackRGBColor (xArea;237;254;243;237;254;243)

PL_SetColBackColor

(areaRef:L; columnNumber:L; plpHdrBackColor:T; 4dHdrBackColor:L; plpListBackColor:T; 4dListBackColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn number.
→ plpHdrBackColortextHeader background color from PrintList Pro’s palette.
→ 4dHdrBackColorlongintHeader background color from 4D’s palette.
→ plpListBackColortextList background color from PrintList Pro’s palette.
→ 4dListBackColorlongintList background color from 4D’s palette.

PL_SetColBackColor is used to specify the background colors for a column header and a list area column.

columnNumber — The column for which to set the background color. Use a value of zero (0) to apply the parameters to all columns. plpHdrBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the column header. If the name is not in PrintList Pro’s palette or it is a null string, then 4dHdrBackColor will be used.

4dHdrBackColor — 1 to 256. The color at this position in 4D’s palette will be used for the background color for the column header.

plpListBackColor — Name of the color in PrintList Pro’s palette. This will be the background color for the column. If the name is not in PrintList Pro’s palette or it is a null string, then 4dListBackColor will be used.

4dListBackColor — 1 to 256. The color at this position in 4D’s palette will be used for the background color for the column.

If PL_SetColBackColor is not called, the default is white for both the header and list background colors.

Examples

  // Light gray for header background, white for list background, all columns
  PL_SetColBackColor(eNames;0;PL Light gray;0;PL White;0)
  // White for header background, 13th color from 4D’s palette for list background, 1st column
  PL_SetColBackColor(eNames;1;PL White;0;"";13)

PL_SetColBackRGBColor

(areaRef:L; columnNumber:L; hdrBackRed:L; hdrBackGreen:L; hdrBackBlue:L; listBackRed:L; listBackGreen:L; listBackBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ columnNumberlongintColumn number.
→ hdrBackRedlongintHeader back red.
→ hdrBackGreenlongintHeader back green.
→ hdrBackBluelongintHeader back blue.
→ listBackRedlongintList back red.
→ listBackGreenlongintList back green.
→ listBackBluelongintList back blue.

PL_SetColBackRGBColor is used to specify the background colors for a column header and a list area column, using the RGB values. This routine is similar to PL_SetColBackColor.

columnNumber — The column for which to set the background color. Use a value of zero (0) to apply the parameters to all columns. hdrBackRed — Header background RGB red value.

hdrBackGreen — Header background RGB green value.

hdrBackBlue — Header background RGB blue value. listBackRed — List background RGB red value.

listBackGreen — List background RGB green value.

listBackBlue — List background RGB blue value.

Example

The following example will tell PrintList Pro to print the third column using a color scheme standard for OSX:

  PL_SetColBackRGBColor (xArea;3;237;254;243;237;254;243)

PL_SetRowStyle (areaRef:L; rowNumber:L; styleNum:L; fontName:T; fontSize:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ rowNumberlongintNumber of row.
→ styleNumlongintStyle of the font.
→ fontNametextName of the font.
→ fontSizelongintSize of the font.

PL_SetRowStyle is used to set the style and font for a particular row. It will override the style and font settings for all columns in that row. The size settings of each column will still apply.

Any subsequent sorting using PL_SetSort will cause the row style setting to be moved with the arrays. This will keep the style setting “in sync” with the original row.

Keep in mind that any settings applied to a row will be moved with that row’s data if the data is later sorted using PL_SetSort. If you do not want the row’s settings to move, call PL_SetSort before applying the row settings.

rowNumber — The row for which to set the style. Use a value of zero (0) to apply the parameters to all rows.

styleNum — This parameter is used to set the style for the row. 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.

If a row style has been previously set, it may be removed by setting styleNum to -1. This may also be applied to all rows by passing a zero (0) for the rowNumber. This will have no effect on rows that have not been previously set.

The row style may be left unchanged by setting styleNum to 256.

fontName — This parameter specifies the font for a row. The row 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 a row. The row font size may be left unchanged by setting fontSize to 0.

Examples

  PL_SetRowStyle(eNames;10;2;"";0) // set row 10 to be italic - no change in font size
  PL_SetRowStyle(eNames;0;1;"Helvetica";14) // set all rows to be bold, Helvetica 14
  PL_SetRowStyle(eList;12;3;"Times";0) // set the 12th row to print the Times font in bold italic style

PL_SetRowColor

(areaRef:L; rowNumber:L; plpRowForeColor:T; 4dRowForeColor:L; plpRowBackColor:T; 4dRowBackColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ rowNumberlongintNumber of row.
→ plpRowForeColortextRow foreground color from PrintList Pro’s palette.
→ 4dRowForeColorlongintRow foreground color from 4D’s palette.
→ plpRowBackColortextRow background color from PrintList Pro’s palette.
→ 4dRowBackColorlongintRow background color from 4D’s palette.

PL_SetRowColor is used to specify the foreground and background colors for a row. It will override the foreground and background color settings for all columns in that row.

Any subsequent sorting using PL_SetSort will cause the row color setting to be moved with the arrays. This will keep the color setting “in sync” with the original row.

Keep in mind that any settings applied to a row will be moved with that row’s data if the data is later sorted using PL_SetSort. If you do not want the row’s settings to move, call PL_SetSort before applying the row settings.

rowNumber — The row for which to set the foreground color. Use a value of zero (0) to apply the parameters to all rows.

plpRowForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the row. If the name is not in PrintList Pro’s palette or it is a null string, then 4dRowForeColor will be used.

4dRowForeColor — 1 to 256. Foreground color number for the row (from 4D’s palette). The row foreground color may be left unchanged by setting plpRowForeColor to the empty string (“”), and 4dRowForeColor to 0.

If a row color has been previously set, it may be removed by setting plpRowForeColor to an empty string (“”), and 4dRowForeColor to -1. This may also be applied to all rows by passing a zero (0) for the rowNumber. This will have no effect on rows that have not been previously set.

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

4dRowBackColor —1 to 256. Background color number for the row (from 4D’s palette). The row background color may be left unchanged by setting plpRowBackColor to the empty string (“”), and 4dRowBackColor to 0.

If a row background color has been previously set, it may be removed by setting plpRowBackColor to the empty string (“”), and 4dRowBackColor to -1. This may also be applied to all rows by passing a zero (0) for the rowNumber. This will have no effect on rows that have not been previously set.

Examples

  PL_SetRowColor(eNames;10;"Blue";0;"Light gray";0) // set row 10 to foreground blue, background light gray
  PL_SetRowColor(eNames;0;"Blue";0;"Yellow";0) // set all rows to blue foreground, yellow background
  PL_SetRowColor(eNames;0;"";-1;"";-1) // reset all row colors to use the column color settings
  PL_SetRowColor(eList;10;"Blue";0;"Light Gray";0)
  // set the 10th row to print a foreground color of blue and background color of light gray
  PL_SetRowColor(eList;12;"Green";0;"";0)
  // set the 12th row to print a foreground color of green and the current background color

PL_SetRowRGBColor

(areaRef:L; rowNumber:L; rowForeRed:L; rowForeGreen:L; rowForeBlue:L; rowBackRed:L; rowBackGreen:L; rowBackBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ rowNumberlongintRow number.
→ rowForeRedlongintForeground red.
→ rowForeGreenlongintForeground green.
→ rowForeBluelongintForeground blue.
→ rowBackRedlongintBackground red.
→ rowBackGreenlongintBackground green.
→ rowBackBluelongintBackground blue.

PL_SetRowRGBColor provides the ability to set the foreground and background colors for an individual row using standard RGB colors.

This routine is similar to PL_SetRowColor, except that it uses RGB color values.

rowForeRed — Foreground RGB red value. rowForeGreen — Foreground RGB green value. rowForeBlue — Foreground RGB blue value. rowBackRed — Background RGB red value. rowBackGreen — Background RGB green value. rowBackBlue — Background RGB blue value.

Example

The following example will tell PrintList Pro to print the third row using a color scheme standard for MacOS X:

  PL_SetRowRGBColor (xArea;3;237;0;243;0;254;0)

PL_SetDividers

(areaRef:L; colDividerWidth:F; colDividerPattern:T; plpColDividerColor:T; 4dColDividerColor:L; rowDividerWidth:F; rowDividerPattern:T; plpRowDividerColor:T; 4dRowDividerColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ colDividerWidthrealWidth of the column divider line.
→ colDividerPatterntextPattern of the column divider.
→ plpColDividerColortextColor from PrintList Pro’s palette for the column divider.
→ 4dColDividerColorlongintColor from 4D’s palette for the column divider.
→ rowDividerWidthrealWidth of the row divider line.
→ rowDividerPatterntextPattern of the row divider.
→ plpRowDividerColortextColor from PrintList Pro’s palette for the row divider.
→ 4dRowDividerColorlongintColor from 4D’s palette for the row divider.

PL_SetDividers is used to set the pattern (transparency ratio) and color of the column and row dividers.

See the Patterns item in the Compatibility Notes.

colDividerWidth — 0 to 1. This option controls the line width of the column dividers. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no dividers will be printed.

colDividerPattern — Name of the pattern (transparency ratio) for the column divider. If a null string is used then no column divider will be printed.

plpColDividerColor — Name of the color in PrintList Pro’s palette. This will be the color for the column divider. If the name is not in PrintList Pro’s palette or it is a null string, then 4dColDividerColor will be used.

4dColDividerColor — 1 to 256. The color at this position in 4D’s palette will be used for the column divider. rowDividerWidth — 0 to 1. This option controls the line width of the row dividers. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no dividers will be printed.

rowDividerPattern — Name of the pattern (transparency ratio) for the row divider. If a null string is used then no row divider will be printed.

plpRowDividerColor — Name of the color in PrintList Pro’s palette for the row divider. If the name is not in PrintList Pro’s palette or it is a null string, then 4dRowDividerColor will be used.

4dRowDividerColor — 1 to 256. The color at this position in 4D’s palette will be used for the row divider. If neither PL_SetDividers nor PL_SetRGBDividers are called, then no column or row dividers will be printed.

Examples

  // Print solid gray column dividers and no row dividers
  PL_SetDividers (eNames;1;"Black";"Gray";0;0;"";"";0)
  // Print column and row hairline dividers in a gray pattern
  PL_SetDividers (eNames;0.25;"Gray";"Black";0;0.25;"Gray";"Black";0)

PL_SetRGBDividers

(areaRef:L; colDividerWidth:F; colDividerPattern:T; colDividerRed:L; colDividerGreen:L; colDividerBlue:L; rowDividerWidth:F; rowDividerPattern:T; rowDividerRed:L; rowDividerGreen:L; rowDividerBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ colDividerWidthrealWidth of the column divider line.
→ colDividerPatterntextColumn divider pattern string.
→ colDividerRedlongintColumn divider — Red.
→ colDividerGreenlongintColumn divider — Green.
→ colDividerBluelongintColumn divider — Blue.
→ rowDividerWidthrealWidth of the row divider line.
→ rowDividerPatterntextRow divider pattern string.
→ rowDividerRedlongintRow divider — Red.
→ rowDividerGreenlongintRow divider — Green.
→ rowDividerBluelongintRow divider — Blue.

PL_SetRGBDividers functions the same as the PL_SetDividers routine, except that the column and row divider colors use standard RGB values.

colDividerWidth — 0 to 1. This option controls the line width of the column dividers. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no dividers will be printed.

colDividerPattern — Text, name of the pattern (transparency ratio) for the column divider. If a null string is used then no column divider will be printed.

colDividerRed — Column divider RGB red value.

colDividerGreen — Column divider RGB green value.

colDividerBlue — Column divider RGB blue value.

rowDividerWidth — 0 to 1. This option controls the line width of the row dividers. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no dividers will be printed.

rowDividerPattern — Text, name of the pattern (transparency ratio) for the row divider. If a null string is used then no row divider will be printed.

rowDividerRed — Row divider RGB red value.

rowDividerGreen — Row divider RGB green value.

rowDividerBlue — Row divider RGB blue value.

If neither PL_SetDividers nor PL_SetRGBDividers are called, then no column or row dividers will be printed.

Example

The following example will set the column/row dividers using the PL_SetRGBDividers routine:

  // Print column and row dividers in a hairline gray pattern
  PL_SetRGBDividers(eNames;0.25;"Gray";209; 209; 209;0.25;"Gray"; 209; 209; 209)

PL_SetFrame

(areaRef:L; frameLineWidth:F; frameLinePattern:T; plpFrameLineColor:T; 4dFrameLineColor:L; headerLineWidth:F; headerLinePattern:T; plpHeaderLineColor:T; 4dHeaderLineColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ frameLineWidthrealWidth of the frame line.
→ frameLinePatterntextPattern of the frame line.
→ plpFrameLineColortextColor from PrintList Pro’s palette for the frame line.
→ 4dFrameLineColorlongintColor from 4D’s palette for the frame line.
→ headerLineWidthrealWidth of the header separator.
→ headerLinePatterntextPattern of the header separator.
→ plpHeaderLineColortextColor from PrintList Pro’s palette for the header separator.
→ 4dHeaderLineColorlongintColor from 4D’s palette for the header separator.

PL_SetFrame is used to set the pattern (transparency ratio) and color of the frame and header separator lines.

See the Patterns item in the Compatibility Notes.

frameLineWidth — 0 to 1. This option controls the line width of the frame. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no frame will be printed.

frameLinePattern — Name of the pattern (transparency ratio) for the frame. If a null string is used then no frame will be printed.

plpFrameLineColor — Name of the color in PrintList Pro’s palette. This will be the color for the frame. If the name is not in PrintList Pro’s palette or it is a null string, then 4dFrameLineColor will be used.

4dFrameLineColor — 1 to 256. The color at this position in 4D’s palette will be used for the frame.

headerLineWidth — 0 to 1. This option controls the line width of the header separator. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no header separator will be printed.

headerLinePattern — Name of the pattern (transparency ratio) for the header separator. If a null string is used then no header separator will be printed.

plpHeaderLineColor — Name of the color in PrintList Pro’s palette for the header separator. If the name is not in PrintList Pro’s palette or it is a null string, then 4dHeaderLineColor will be used.

4dHeaderLineColor — 1 to 256. The color at this position in 4D’s palette will be used for the header separator.

If neither PL_SetFrame nor PL_SetRGBFrame are called, then no frame or header separator line will be printed.

Examples

  // Print 1 pixel wide, solid gray header separator and no frame
  PL_SetFrame (eNames;0;"";"";0;1;"Black";"Gray";0)
  // Print hairline, solid black frame and header separator line
  PL_SetFrame (eNames;0.25;"Black";"Black";0;0.25;"Black";"Black";0)
  

PL_SetRGBFrame

(areaRef:L; frameLineWidth:F; frameLinePattern:T; frameLineRed:L; frameLineGreen:L; frameLineBlue:L; headerLineWidth:F; headerLinePattern:T; headerLineRed:L; headerLineGreen:L; headerLineBlue:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ frameLineWidthrealWidth of the frame line.
→ frameLinePatterntextPattern of the frame line.
→ frameLineRedlongintFrame line — Red.
→ frameLineGreenlongintFrame line — Green.
→ frameLineBluelongintFrame line — Blue.
→ headerLineWidthrealWidth of the header separator.
→ headerLinePatterntextPattern of the header separator.
→ headerLineRedlongintHeader separator — Red.
→ headerLineGreenlongintHeader separator — Green.
→ headerLineBluelongintHeader separator — Blue.

PL_SetRGBFrame functions the same as the PL_SetFrame routine, except that the frame and header separator colors use standard RGB values.

frameLineWidth — 0 to 1. This option controls the line width of the frame. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no frame will be printed.

frameLinePattern — Name of the pattern (transparency ratio) for the frame. If a null string is used then no frame will be printed.

frameLineRed — Frame line RGB red value. frameLineGreen — Frame line RGB green value. frameLineBlue — Frame line RGB blue value.

headerLineWidth — 0 to 1. This option controls the line width of the header separator. A value of 0.25 pixel should be used for hairlines. A value of 0 means that no header separator will be printed.

headerLinePattern — Name of the pattern (transparency ratio) for the header separator. If a null string is used then no header separator will be printed.

headerLineRed — Header separator RGB red value.

headerLineGreen — Header separator RGB green value.

headerLineBlue — Header separator RGB blue value.

If neither PL_SetFrame nor PL_SetRGBFrame are called, then no frame or header separator line will be printed.

Example

The following example sets the frame and header separator line using PL_SetRGBFrame:

  // Print frame and header separator line in a hairline gray pattern
  PL_SetRGBFrame(eNames;0.25;"Gray";209; 209; 209;0.25;"Gray"; 209; 209; 209)

PL_SetHeight

(areaRef:L; numHeaderLines:L; headerHeightPad:L; numRowLines:L; rowHeightPad:L; minimumHeight:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ numHeaderLineslongintNumber of text lines in the header.
→ headerHeightPadlongintExtra height for the header.
→ numRowLineslongintNumber of text lines in each row.
→ rowHeightPadlongintExtra height for each row.
→ minimumHeightlongintMinimum pixel height remaining on the page.

PL_SetHeight is used to set the number of lines of text along with additional height padding in the header and in the rows. Only text columns can wrap to more than one line.

If numRowLines is set to 2 or more, text elements will be able to wrap into the number of lines specified for each row. Note that all rows will be given the same number of lines regardless of the actual number of lines used by a specific text element.

Additional padding may be set using rowHeightPad to allow more space between rows. Text will be centered vertically in the header or row. Note that the padding applies to the entire row and not on a line by line basis within the row.

numHeaderLines — The number of lines in the header. Default is 1.

headerHeightPad — The extra height, in pixels, to give to the header. Default is 2.

numRowLines — The number of lines to give to each row. A value greater than 0 means that the height of each row is the same. The fixed height will either be a function of the number of text lines specified or the height of the largest picture in a picture array if so configured (refer to PL_SetFormat). A value of zero means that the height of each row is to be calculated automatically based on the data that is to be printed. PrintList Pro examines the elements of all text and picture arrays to determine the height of each row. Default is 1.

rowHeightPad — The extra height, in pixels, to give to each row. Default is 0.

minimumHeight — The minimum remaining available height, in pixels, for the PrintList Pro area to print on the page. For example, if there are several PrintList Pro areas on one form, and you want to make sure that at least two rows are printed on one page for the area specified by areaRef, and the row height is 12 points, you can set this parameter to 24. PrintList Pro will test if it has 24 pixels (two rows) left available on the page before printing the area. If not, it will proceed onto the following page. You should specify at least the height of one row in this parameter.

Examples

  PL_SetHeight(eList;1;4;1;2) // pad the header by 4 pixels and the rows by 2
  PL_SetHeight(eList;2;5;2;0) // set header lines to 2, pad to 5 pixels, set row lines to 2, no padding
  PL_SetHeight (eList;1;4;1;2;12) // check that 12 pixels (one row height here) are available before printing

PL_SetSort

(areaRef:L; column1:L; …; columnN:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ column1; …; columnNlongintColumn(s) to perform sort upon.

PL_SetSort is used to perform a multi-level sort.

column — These parameters specify the columns to use for the sort criteria.

A column greater than 0 causes an ascending sort to be performed upon that column, while a column less than 0 causes a descending sort to be performed upon that column.

If a column is 0, then all successive columns will be ignored.

If the arrays are already sorted, use PL_SetBrkOrder instead to communicate the sort order to PrintList Pro.

Examples

PL_SetSort(eNames;3;4;7) sort on columns 3, 4, and 7 (all ascending) PL_SetSort(eContacts;-1;3;-2) sort on columns 1 (descending), 3 (ascending), and 2 (descending)

PL_SetColOpts

(areaRef:L; hideLastColumns:L; hideDetailArea:L; drawingEngine:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
–>hideLastColumnslongintNumber of columns from the right to hide.
→ hideDetailArealongintHide the list and just show the breaks.
→ drawingEnginelongintDrawing engine (ignored on Mac): GDI or GDI+.

PL_SetColOpts is used to hide columns from being printed and to hide the entire detail area to show just break level information.

hideLastColumns — This parameter specifies the number of arrays from the right to not print. This parameter is useful for keeping many arrays “in sync” when sorting, but only a subset are to be printed. Default is 0.

hideDetailArea — 0 or 1:

Value Mode
0Print the array values in the list (default)
1Do not print the array values in the list

This is useful for printing a summary of break level information without printing the actual list

drawingEngine (ignored on Mac):

  • GDI: better rendering, no transparency, no horizontal scaling, limited text rotation features
  • GDI+: allows the three features above, but may affect precise rendering on Windows

This parameter is only meaningful on Windows. The two possible values are:

Value Mode
0Use GDI+ (default)
1Change the engine used for printing on Windows to GDI

Examples

  PL_SetColOpts (eList;2;0) // hide the last two columns
  PL_SetColOpts (eList;0;1;1) // hide the detail area, show only the breaks, use GDI on Windows

PL_SetCellStyle

(areaRef:L; firstCellCol:L; firstCellRow:L; lastCellCol:L; lastCellRow:L; cellArray:Y; styleNum:L; fontName:T; fontSize:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ firstCellCollongintFirst cell column.
→ firstCellRowlongintFirst cell row.
→ lastCellCollongintLast cell column.
→ lastCellRowlongintLast cell row.
→ cellArrayarrayDiscontiguous cells (two-dimensional longint array).
→ styleNumlongintStyle of the font.
→ fontNametextName of the font.
→ fontSizelongintSize of the font.

PL_SetCellStyle is used to set the font and / or style of a specific cell, range of cells, or list of cells.

To specify a single cell: if firstCellCol and firstCellRow are greater than 0 and lastCellCol or lastCellRow are less than or equal to 0 then only [firstCellCol, firstCellRow] will be set.

To specify a range of cells: if firstCellCol and firstCellRow are greater than 0 and lastCellCol and lastCellRow are greater than 0 then the range of cells from [firstCellCol, firstCellRow] to [lastCellCol, lastCellRow] will be set.

To specify discontiguous cells: if firstCellCol or firstCellRow are less than or equal to 0 then the cells in cellArray will be set.

cellArray — Two-dimensional long integer array. The first dimension must be two. The first array is for the column indices and the second array is for the row indices. The second dimension must be the same as the number of cells that are to be selected. See the following illustration:

styleNum —This parameter is used to set the style for the specified cells. 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.

If a cell style has been previously set, the style may be removed by setting styleNum to -1. The cell style may be left unchanged by setting styleNum to 256.

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

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

Keep in mind that any settings applied to a cell will be moved with that cell’s data if the data is later sorted usingPL_SetSort. If you do not want the cell’s settings to move, call PL_SetSort before applying the cell settings.

Example

  ARRAY LONGINT(aCellSet;2;4)
  // Set cell at column 1, row 3 to bold Helvetica - no change in font size
  PL_SetCellStyle (eArea;1;3;0;0;aCellSet;1;"Helvetica";0)
  // Set cells from column 2, row 2 to column 5, row 5 to font size 14, no change in style and font
  PL_SetCellStyle (eArea;2;2;5;5;aCellSet;256;"";14)
  // Set the cells in aCellSet to Times
  aCellSet{1}{1}:=1 // column 1, row 1
  aCellSet{2}{1}:=1
  aCellSet{1}{2}:=1 // column 1, row 2
  aCellSet{2}{2}:=2
  aCellSet{1}{3}:=2 // column 2, row 5
  aCellSet{2}{3}:=5
  aCellSet{1}{4}:=2 // column 2, row 6
  aCellSet{2}{4}:=6
  PL_SetCellStyle (eArea;0;0;0;0;aCellSet;256;"Times";0)

PL_SetCellColor

(areaRef:L; firstCellCol:L; firstCellRow:L; lastCellCol:L; lastCellRow:L; cellArray:Y; plpForeColor:T; 4dForeColor:L; plpBackColor:T; 4dBackColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ firstCellCollongintFirst cell column.
→ firstCellRowlongintFirst cell row.
→ lastCellCollongintLast cell column.
→ lastCellRowlongintLast cell row.
→ cellArrayarrayDiscontiguous cells (two-dimensional longint array).
→ plpForeColortextForeground color from PrintList Pro’s palette.
→ 4dForeColorlongintForeground color from 4D’s palette.
→ plpBackColortextBackground color from PrintList Pro’s palette.
→ 4dBackColorlongintBackground color from 4D’s palette.

PL_SetCellColor is used to set the foreground color and / or background color of a specific cell, range of cells, or list of cells.

To specify a single cell: if firstCellCol and firstCellRow are greater than 0 and lastCellCol or lastCellRow are less than or equal to 0 then only [firstCellCol, firstCellRow] will be set.

To specify a range of cells: if firstCellCol and firstCellRow are greater than 0 and lastCellCol and lastCellRow are greater than 0 then the range of cells from [firstCellCol, firstCellRow] to [lastCellCol, lastCellRow] will be set.

To specify discontiguous cells: if firstCellCol or firstCellRow are less than or equal to 0 then the cells in cellArray will be set.

cellArray — Two-dimensional long integer array. The first dimension must be two. The first array is for the column indices and the second array is for the row indices. The second dimension must be the same as the number of cells that are to be selected. See the following illustration.

plpForeColor — Name of the color in PrintList Pro’s palette. This will be the foreground color for the cell. 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 cell (from 4D’s palette). If a cell foreground color has been previously set, it may be removed by setting plpForeColor to the empty string (“”), and

4dForeColor to 1. The cell 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 cell. 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 cell (from 4D’s palette). If a cell background color has been previously set, it may be removed by setting plpBackColor to the empty string (“”), and

4dBackColor to 1. The cell background color may be left unchanged by setting plpBackColor to the empty string (“”), and 4dBackColor to 0.

Keep in mind that any settings applied to a cell will be moved with that cell’s data if the data is later sorted using PL_SetSort. If you do not want the cell’s settings to move, call PL_SetSort before applying the cell settings.

Examples

  ARRAY LONGINT(aCellArray;2;0) // MUST initialize a two-dimensional long integer array
  // Set the foreground color of the cell at column 1, row 3 to blue
  PL_SetCellColor (eList;1;3;0;0;aCellArray;"blue";0;"";0)
  // Set background color of cells from column 2, row 2 to column 5, row 5 to green
  PL_SetCellColor (eList;2;2;5;5;aCellArray;"";0;"Green";0)
  // Set all negative values in the third column, a real array, to have a foreground color of red
  For($i;1;Size of array(aRevenue)) // check each element in the array
   If(aRevenue{$i}<0) // is the value in this element negative?
    PL_SetCellColor(eList;3;$i;0;0;aCellArray;"Red";0;"";0) // if so, then print it in red
   End if
  End for

PL_SetCellRGBColor

(areaRef:L; firstCellCol:L; firstCellRow:L; lastCellCol:L; lastCellRow:L; cellArray:Y; cellForeRed:L; cellForeGreen:L; cellForeBlue:L; cellBackRed:L; cellBackGreen:L; cellBackBlue:L)

Parameter Type
→ areaReflongintReference of PrintList Pro object on layout.
→ firstCellCollongintFirst cell column.
→ firstCellRowlongintFirst cell row.
→ lastCellCollongintLast cell column.
→ lastCellRowlongintLast cell row.
→ cellArrayarrayDiscontiguous cells (two-dimensional longint array).
→ cellForeRedlongintForeground red.
→ cellForeGreenlongintForeground green.
→ cellForeBluelongintForeground blue.
→ cellBackRedlongintBackground red.
→ cellBackGreenlongintBackground green.
→ cellBackBluelongintBackground blue.

PL_SetCellRGBColor is used to set the foreground and / or background color of a specific cell, range of cells, or list of cells. This routine works in the same manner as PL_SetCellColor, except it allows you to specify the colors using standard RGB values.

cellForeRed — Foreground RGB red value.

cellForeGreen — Foreground RGB green value.

cellForeBlue — Foreground RGB blue value.

cellBackRed — Background RGB red value.

cellBackGreen — Background RGB green value.

cellBackBlue — Background RGB blue value.

PL_SetCellIcon

(areaRef:L; cellColumn:L; cellRow:L; iconRef:L; iconAlignment:L; horPosition:L; vertPosition:L; offsetOrWidth:L; scaling:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ cellColumnlongintColumn at which to set the icon.
→ cellRowlongintRow at which to set the icon (0 to set the header).
→ iconReflongintReference of the icon or picture to use.
→ iconAlignmentlongintPosition of icon.
→ horPositionlongintHorizontal position.
→ vertPositionlongintVertical position.
→ offsetOrWidthlongintPixel offset, or icon width depending on horPosition.
→ scalinglongintScaling.

PL_SetCellIcon provides the ability to procedurally print pictures in individual cells or headers.

One or two icons may be used (left and right). You can customize the icon(s) using items from the 4D Picture Library or PrintList Pro's own picture library populated by PL_SetIcon (see details below).

cellColumn — Cell column number.

cellRow — Cell row number (or 0 to set the header).

iconRef — Reference of the icon or picture to use from the Picture Library or PrintList Pro's own picture library. To associate an icon to the cell, pass 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.

See Header/Cell Icon Support for examples.

iconAlignment — Position of icon (each cell can contain up to two icons):

Value Mode
0Places icon on left of cell
1Places icon on right of cell

horPosition — One the following options:

Value Mode
0Default (left for left icon, right for right icon)
1Align left
2Align center
3Align right

vertPosition — One the following options:

Value Mode
0Default (top)
1Align top left
2Align center
3Align bottom

offsetOrWidth — when horizontal alignment in horPosition is zero (default position : left for left icon, right for right icon), the offsetOrWidth is the offset, i.e. the distance in pixels between the text and the icon (left or right):

horPosition = 0

Otherwise the offsetOrWidth is the pixel width that the icon will use - the icon will be aligned in this space:

horPosition = 2 (centered)

scaling — One the following options:

Value Mode
0Truncated
1Scaled

The cell content (text) is printed into the space that is left once the icon is printed.

For example, if the column width is 100 pixels and you print a 15 pixel icon, the remaining width can be calculated as 100 minus the padding (default horizontal indent is 3 for header and data rows on both sides = 6 points), minus the column divider if shown (1 point): 100 - 6 - 1 - 15 = 78 points where the text will be printed.

Example

The following example will print an icon in r3c2, using an item (ID 1717) from the 4D Picture Library:

  $col:=2
  $row:=3
  $iconRef:=1717
  $iconPos:=1 // right
  $horPos:=0 // default
  $verPos:=2 // align center
  $offset:=5
  $scaling:=0
  //**PL_SetCellIcon**// (ePLOutput;$col;$row;$iconRef;$iconPos;$horPos;$verPos;$offset;$scaling)

PL_SetCellBorder

(areaRef:L; cellColumn:L; cellRow:L; borderLeft:L; borderTop:L; borderRight:L; borderBottom:L; offset:L; width:F; redColor:L; greenColor:L; blueColor:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ cellColumnlongintColumn.
→ cellRowlongintRow.
→ borderLeftlongintPrint left border.
→ borderToplongintPrint top border.
→ borderRightlongintPrint right border.
→ borderBottomlongintPrint bottom border.
→ offsetlongintOffset from cell boundary in pixels.
→ widthrealWidth of line.
→ redColorlongintRed.
→ greenColorlongintGreen.
→ blueColorlongintBlue.

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

cellColumn — Column of cell where border will be applied.

cellRow — Row of cell where border will be applied.

borderLeft — Print left border.

borderTop — Print top border.

borderRight — Print right border.

borderBottom — Print bottom border.

offset — Offset from cell boundary in pixels. 0 if the border should be printed at cell boundary (default).

width — Width of line. This parameter is a real value, allowing fractional widths. See Demo mode dialog.

redColor — RGB red value used for the border.

greenColor — RGB green value used for the border.

blueColor — RGB blue value used for the border.

PL_SetCellFrame

(areaRef:L; firstCellCol:L; firstCellRow:L; lastCellCol:L; lastCellRow:L; offset:L; width:F; redLightColor:L; greenLightColor:L; blueLightColor:L; redDarkColor:L; greenDarkColor:L; blueDarkColor:L; clearAllBorders:L)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ firstCellCollongintFirst cell column.
→ firstCellRowlongintFirst cell row.
→ lastCellCollongintLast cell column.
→ lastCellRowlongintLast cell row.
→ offsetlongintOffset from cell boundary in pixels.
→ widthrealWidth of line.
→ redLightColorlongintRed (light color).
→ greenLightColorlongintGreen (light color).
→ blueLightColorlongintBlue (light color).
→ redDarkColorlongintRed (dark color).
→ greenDarkColorlongintGreen (dark color).
→ blueDarkColorlongintBlue (dark color).
→ clearAllBorderslongintClear all borders within the frame.

PL_SetCellFrame prints a frame around a range of cells. It uses RGB colors: light color for both left and top lines, dark color for both right and bottom line. The range of cells from [firstCellCol, firstCellRow] to [lastCellCol, lastCellRow] will be set.

offset — Offset from cell boundaries in pixels. 0 if the frame should be printed at cell boundaries (default).

width — Width of line. This parameter is a real value, allowing fractional widths. See Hairline Line Width.

redLightColor, greenLightColor, blueLightColor — RGB values used for both left and top lines colors.

redDarkColor, greenDarkColor, blueDarkColor — RGB values used for both right and bottom lines colors.

clearAllBorders — It this parameter value is 1, then all cells inside the frame will have their borders removed.

PL_SetPageProc

(areaRef:L; callbackMethod:T)

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ callbackMethodtextName of the page callback project method.

PL_SetPageProc is used to specify a 4D project method to be called at the end of PrintList Pro’s processing on every page. Keep in mind that a PrintList Pro page is not necessarily equivalent to a physical page.

It is possible to have several occurrences of a PrintList Pro object for a single page. Each occurrence will invoke the callback method at the end of its page. See End of Page Callback.

callbackMethod — The name of the callback method that is called at the end of every PrintList Pro page. You must use the following declaration in your callback method:

  C_LONGINT ($1;$2)

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.

Example

  PL_SetPageProc (eList;"MyCallback")

PL_GetVersion

→version:T

Parameter Type Description
← versiontextVersion of the PrintList Pro plugin.

PL_GetVersion returns the version number of the currently used PrintList Pro plugin. Note that getting this property will not trigger the registration dialog if PrintList Pro is not registered (allows to check version before registering)

Example

  C_TEXT($version)
  $version:=PL_GetVersion

PL_Load

(areaRef:L; XML:T) ª result:L

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ XMLtextXML data that was saved using the PL_Save command.
← resultlongint0 if the XML was loaded OK; 1 if not.

PL_Load initializes an area from an XML (using UTF-8) text that was saved to a text field or variable using the PL_Save command or AL_Save (from AreaList Pro).

PL_Load can be used without any other command use (e.g. no defined columns - they will be read from the XML). Do not call PL_Load more than once for the same area: it is not intended for that and many properties are not reinitialized to defaults.

Example

This example initializes a PrintList Pro area using settings that were saved into a field in the database.

  $err:=PL_Load (area;[Settings]PLP_template)
  

PL_Save

(areaRef:L; XML:T) ª result:L

Parameter Type Description
→ areaReflongintReference of PrintList Pro object on layout.
→ XMLtextA variable or field to save an area’s XML settings into.
← resultlongint0 if the XML was loaded OK; 2 if not.

PL_Save saves an area’s settings as XML (using UTF-8) in a text variable or field. Use PL_Save after configuring the area but before printing. PrintList Pro modifies properties during printing - you would not get the original settings.

Example

Save a PrintList Pro area’s settings into a field in the database.

  C_TEXT($Settings)
  $err:=PL_Save (area;$Settings)
  [Settings]PLP_template:=$Settings
configuration_commands.txt · Last modified: 2017/08/16 17:54 by plp_admin