AUTHOR

Kevin Ostrom

USAGE

PrintField longFieldDesc, margins, leftheader, centerHeader, rightHeader, leftFooter, centerFooter, rightFooter, headerFont, footerFont, headerFontSize, footerFontSize

PrintField (the long id of cd fld "StuffToPrint"), "72,72,72,72,36,36", "Region Report", "", the date, "", "¶", "", "Times", "Times", 12, 12
 

DESCRIPTION

The PrintField external command (XCMD) is used to print the contents of a field to the printer, using the field's current text font, size and styles, automatically breaking the page as necessary.
 

COMMENTS

The PrintField XCMD requires 12 parameters, which must all be passed: there are no optional parameters. These parameters are:

Parameter Description

longFieldDesc This parameter holds the identifier of the field to print. This must be in long id form; any other form will return an error message (see below).

Example: the long id of card field 1

margins This parameter holds an list of margin settings, separated by comma characters: top, left, bottom, right, header, and footer. The margins are measured in pixels (points), where 72 pixels is equivalent to 1 inch, and must be 1 or greater, If you try to use 0 for a margin, and error will be returned (see below)

The header and footer margins specify where the header and footer should be printed, and the other margins indicate where the field text should be printed.

The header margin is added to the top margin to determine where the field text should be printed, that is, if the header is 36 and the top is 36, the header is printed 1/2 inch from the top of the page and the field text is printed 1 inch from the top of the page.

The same holds true for the bottom and footer margins; if the footer is 36 and the bottom is 72, then the footer is printed 1/2 inch from the bottom of the page, and the field text ends 1-1/2 inches from the bottom of the page.

Example: "36,72,36,72,36,36"

leftHeader This parameter holds the text to print in the header, left-aligned to the left margin defined above, with the top of the header text set at the header margin. You may use the ASCII value 166 ("¶" or option-7 on American keyboards) as a special character to indicate where to print the current page number. If you do not need to print text at this header locaton, you should provde an empty string ("").

Example: "Quarterly Report"

centerHeader Same as leftHeader, but the text is centered between the left and right margins.

rightHeader Same as leftHeader, but the text is right-aligned to the right margin.

leftFooter This parameter holds the text to print in the footer, left-aligned to the left margin defined above, with the bottom of the footer text set at the footer margin. You may use the ASCII value 166 ("¶" or option-7 on American keyboards) as a special character to indicate where to print the current page number. If you do not need to print text at this footer locaton, you should provde an empty string ("").

Example: the short date

centerFooter Same as leftFooter, but the text is centered between the left and right margins.

rightFooter Same as leftFooter, but the text is right-aligned to the right margin.

headerFont This parameter contains the name of the text font to use for the header text. Note that this applies to all the text provided in the leftHeader, centerHeader and rightHeader parameters.

Example: "Palatino"

footerFont This parameter contains the name of the text font to use for the footer text. Note that this applies to all the text provided in the leftFooter, centerFooter and rightFooter parameters.

headerFontSize This parameter contains the text size to use for the header text. Note that this applies to all the text provided in the leftHeader, centerHeader and rightHeader parameters.

footerFontSize This parameter contains the text size to use for the footer text. Note that this applies to all the text provided in the leftFooter, centerFooter and rightFooter parameters.
 

The following example shows how to use PrintField to print the contents of a field with headers and footers at 1/2 an inch, and field text printing with 1 inch margins all around:

on PrintIt

-- Set up the header text

put "Status Report" into LH

put "" into CH

put the date into RH

-- Set up the footer text

put "" into LF

put "Page " & numToChar(166) into CF -- Page number symbol

put "" into RF

PrintField (long id of cd fld "Report"), "72,36,72,36,36,36", LH, CH, RH, LF, CF, RF, "Times", "Times", 10, 10

end PrintIt

RETURNED VALUE

The returned value of the PrintField XCMD may be checked by examining the value of the result function. If the XCMD was successful, the result will contain true. If the XCMD was not successful, the first line of the result will contain false, and the second line will contain the error condition.
 

SPECIAL CONSIDERATIONS

In order for PrintField to be able to print the text of the field, the field must be open, that is the insertion point must be blinking in the field in order for the XCMD to access it. If the field is not open (or is locked), you must temporarily open it. The following example shows how this is done (the example is for a locked field; also note printing without a header or footer):

on PrintLockedFld

lock screen -- So user won't see us opening the field

set the lockText of cd fld 1 to false

select beforetext of cd fld 1 -- Open field this way

PrintField (long id of cd fld 1), "36,35,36,35,1,1", "", "", "", "", "", "", "", "", "", ""

set the lockText of cd fld 1 to true

unlock screen

end PrintLockedFld

The PrintField XCMD does not display a Page Setup or Print dialog box, and as such, is unaffected by the Page Setup and Print settings defined using the open printing command (or even the scPageSetup XCMD, for that matter). The pages to be printed are sent directly to the printer using the margins specified on US Letter-sized paper.

ERROR CONDITIONS

If you pass a field descriptor that is not in long id form, the second line of the result function will contain the string "Not a valid field descriptor".

If you do not provide all twelve parameters to the XCMD, the second line of the result function will contain the string "Invalid number of parameters".

If you attempt to use PrintField and your computer cannot access the printer, the second line of the result function will contain the string "Cant open printer". (sic)

If you attempt to pass a margin setting of 0 for any of the margins, the second line of the result function will contain the string "Not valid margins".