CLASSPublished

FWMsPrinter

FWMsPrinter():New( <cFilePrinter>, [nDevice], [lAdjustToLegacy], [cPathInServer], [lDisableSetup], ... )

Creates an object for generating, previewing and printing graphical reports in AdvPL.

ReportsPrintingPDFFrameworkFWMsPrinter

01 · OVERVIEW

Overview

FWMsPrinter is the framework printing class used to build graphical reports, generate PDF files or send output to spool/printers. It replaces direct TMSPrinter usage in new development while keeping compatibility options for legacy reports. The usual flow is to create the object, configure resolution, orientation, paper and margins, start the page, draw text, lines, boxes or images, finish the page and then preview, print or generate the file.

02 · SYNTAX

Syntax

FWMsPrinter():New( <cFilePrinter>, [nDevice], [lAdjustToLegacy], [cPathInServer], [lDisableSetup], ... )

Parameters

cFilePrinter

CharacterRequired

Report file name to be created. Avoid special characters to reduce generation and usage issues.

nDevice

NumericOptional

Output type. IMP_SPOOL sends to printer/spool; IMP_PDF generates a PDF file from the report.

Default: IMP_SPOOL

lAdjustToLegacy

LogicalOptional

When true, recalculates coordinates for legacy TMSPrinter proportions. For new reports, .F. is commonly used.

Default: .T.

cPathInServer

CharacterOptional

Server directory where the report file will be saved.

lDisableSetup

LogicalOptional

When .T., does not display the setup screen; the program is responsible for destination and settings.

Default: .F.

oPrintSetup

ObjectOptional

FWPrintSetup object supplied by the user when the routine needs to control print settings.

cPrinter

CharacterOptional

Destination printer name, relevant when setup is disabled and output must go to a specific device.

lServer

LogicalOptional

Indicates server-side printing, without copying the .REL file to the client.

Default: .F.

lRaw

LogicalOptional

Indicates RAW/PCL printing for compatible printer-specific scenarios.

lViewPDF

LogicalOptional

For PDF output, defines whether the file will be displayed after generation.

Default: .T.

nQtdCopy

NumericOptional

Number of copies for spool printing, especially useful in jobs or schedules without user interaction.

lPDFAsPNG

LogicalOptional

Parameter related to PDF generation/handling as an image, depending on the available LIB and TotvsPrinter version.

lConvertFont

LogicalOptional

Indicates whether font size conversion is applied. When .F., conversion is not performed.

Default: .T.

lHasBuffer

LogicalOptional

Available from LIB 20240520 onward to indicate whether the file buffer should be used.

Default: .T.

Methods

NewClass constructor. Use it to create the print object before configuring page, destination and content.

FWMsPrinter():New( <cFilePrinter>, [nDevice], [lAdjustToLegacy], [cPathInServer], [lDisableSetup], [lTReport], [@oPrintSetup], [cPrinter], [lServer], [lPDFAsPNG], [lRaw], [lViewPDF], [nQtdCopy], [lConvertFont], [lHasBuffer] ) --> oPrinter

Parameters

NameFormatRequiredDescriptionNotes

cFilePrinterCaractereRequired

Nome do arquivo de relatório.

nDeviceNuméricoOptional

Dispositivo de saída, como IMP_SPOOL ou IMP_PDF.

lAdjustToLegacyLógicoOptional

Compatibiliza coordenadas com relatórios legados.

cPathInServerCaractereOptional

Caminho no servidor para gravação do arquivo.

lDisableSetupLógicoOptional

Quando verdadeiro, não exibe a tela de configuração.

lTReportLógicoOptional

Indica uso integrado com TReport quando aplicável.

oPrintSetupObjetoOptional

Objeto de configuração de impressão passado por referência.

cPrinterCaractereOptional

Nome da impressora de destino.

lServerLógicoOptional

Indica geração/impressão pelo servidor.

lPDFAsPNGLógicoOptional

Controla tratamento do PDF como imagem quando suportado.

lRawLógicoOptional

Indica uso de impressão RAW/PCL.

lViewPDFLógicoOptional

Define se o PDF será exibido após a geração.

nQtdCopyNuméricoOptional

Quantidade de cópias.

lConvertFontLógicoOptional

Controla conversão de tamanho de fonte.

lHasBufferLógicoOptional

Indica uso de buffer de arquivo nas LIBs que suportam o recurso.

Return value

oPrinter: objeto FWMsPrinter criado.

SetParmDefines internal parameters. The documented "-RFS" option reduces font-size differences between PDF, preview and print queue.FWMsPrinter():SetParm( "-RFS" ) -->

Parameters

NameFormatRequiredDescriptionNotes

cParmCaractereRequired

Chave de parâmetro. Use "-RFS" para Real Font Sizes.

BoxInserts a rectangle in the report. Use it for frames, highlighted areas and visual separators.FWMsPrinter():Box( <nRow>, <nCol>, <nBottom>, <nRight>, [cPixel] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Coordenada vertical inicial.

nColNuméricoRequired

Coordenada horizontal inicial.

nBottomNuméricoRequired

Coordenada inferior do retângulo.

nRightNuméricoRequired

Coordenada direita do retângulo.

cPixelCaractereOptional

Indica tratamento de coordenadas em pixels quando aplicável.

CancelCancels the current report generation.FWMsPrinter():Cancel() -->

CanceledReturns the report cancellation state, useful for safely stopping long loops.FWMsPrinter():Canceled() --> lRet

Return value

lRet: .T. quando o relatório foi cancelado.

Cmtr2PixConverts measurement coordinates to pixels by reference.FWMsPrinter():Cmtr2Pix( [nLinha], [nCol] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nLinhaNuméricoOptional

Linha/posição vertical a converter.

nColNuméricoOptional

Coluna/posição horizontal a converter.

EAN13Prints an EAN13 barcode. According to the documentation, it is available only for horizontal printing and requires compatible LIB/TOTVS Printer versions.FWMsPrinter():EAN13( <nRow>, <nCol>, <cCodeBar>, <nTotalWidth>, <nHeight> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição relativa ao topo.

nColNuméricoRequired

Posição relativa à esquerda.

cCodeBarCaractereRequired

Texto a transformar em código de barras.

nTotalWidthNuméricoRequired

Largura total do código de barras.

nHeightNuméricoRequired

Altura da barra.

Code128Prints a Code128 barcode.FWMsPrinter():Code128( <nRow>, <nCol>, <cCodeBar>, <nWidth>, <nHeight>, [lSay], [oFont], [nTotalWidth] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cCodeBarCaractereRequired

Conteúdo a codificar.

nWidthNuméricoRequired

Largura do código.

nHeightNuméricoRequired

Altura do código.

lSayLógicoOptional

Indica se o texto deve ser exibido junto ao código.

oFontObjetoOptional

Fonte usada no texto.

nTotalWidthNuméricoOptional

Largura total desejada.

Code128CPrints a Code128C barcode, usually suitable for compact numeric sequences.FWMsPrinter():Code128C( <nRow>, <nCol>, <cCodeBar>, <nSizeBar> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cCodeBarCaractereRequired

Conteúdo a codificar.

nSizeBarNuméricoRequired

Tamanho do código de barras.

FwMsBarPrints barcodes supported by MsBar, such as EAN13, EAN8, UPCA, CODE128, INT25, IND25, CODABAR and CODE3_9.

FWMsPrinter():FWMsBar( <cTypeBar>, <nRow>, <nCol>, <cCode>, <oPrint>, [lCheck], [nColor], [lHorz], [nWidth], [nHeight], [lBanner], [cFont], [cMode], [lPrint], [nPFWidth], [nPFHeight], [lCmtr2Pix] ) -->

Parameters

NameFormatRequiredDescriptionNotes

cTypeBarCaractereRequired

Tipo do código de barras.

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cCodeCaractereRequired

Texto a transformar em código de barras.

oPrintObjetoRequired

Objeto de impressão.

lCheckLógicoOptional

Calcula dígito de controle.

nColorNuméricoOptional

Cor do código de barras.

lHorzLógicoOptional

Imprime na horizontal.

nWidthNuméricoOptional

Largura da barra.

nHeightNuméricoOptional

Altura da barra.

lBannerLógicoOptional

Imprime o texto abaixo do código.

cFontCaractereOptional

Fonte usada no texto.

cModeCaractereOptional

Modo do código de barras.

lPrintLógicoOptional

Executa Print() pelo MsBar.

nPFWidthNuméricoOptional

Ajuste de largura da fonte.

nPFHeightNuméricoOptional

Ajuste de altura da fonte.

lCmtr2PixLógicoOptional

Usa Cmtr2Pix() para converter coordenadas.

DataMatrixPrints a two-dimensional DataMatrix code.FWMsPrinter():DataMatrix( <nCol>, <nRow>, <cCodeBar>, <nSizeBar> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nColNuméricoRequired

Posição horizontal.

nRowNuméricoRequired

Posição vertical.

cCodeBarCaractereRequired

Conteúdo a codificar.

nSizeBarNuméricoRequired

Tamanho do código.

EllipseInserts an ellipse in the report.FWMsPrinter():Ellipse( <nLeft>, <nTop>, <nBottom>, <nRight>, [nColorIn], [nColorOut], [nLineType], [cPixel] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nLeftNuméricoRequired

Coordenada esquerda.

nTopNuméricoRequired

Coordenada superior.

nBottomNuméricoRequired

Coordenada inferior.

nRightNuméricoRequired

Coordenada direita.

nColorInNuméricoOptional

Cor interna.

nColorOutNuméricoOptional

Cor da borda.

nLineTypeNuméricoOptional

Tipo de linha.

cPixelCaractereOptional

Tratamento de coordenadas em pixels.

EndPageEnds the current page. Call it after drawing all page content.FWMsPrinter():EndPage() -->

FillRectCreates a filled rectangle for backgrounds, bands and highlighted areas.FWMsPrinter():FillRect( <aCoords>, [oBrush], [cPixel] ) -->

Parameters

NameFormatRequiredDescriptionNotes

aCoordsArrayRequired

Coordenadas do retângulo.

oBrushObjetoOptional

Objeto TBrush usado no preenchimento.

cPixelCaractereOptional

Tratamento de coordenadas em pixels.

GetFontWidthsReturns character-width information for a font.FWMsPrinter():GetFontWidths( [oFont], [@aFontSize] ) --> aRet

Parameters

NameFormatRequiredDescriptionNotes

oFontObjetoOptional

Fonte usada no cálculo.

aFontSizeArrayOptional

Array passado por referência para receber informações de tamanho.

Return value

aRet: vetor com larguras da fonte.

GetOrientationReturns the report orientation.FWMsPrinter():GetOrientation() --> nOrientation

Return value

nOrientation: orientação atual, como retrato ou paisagem.

GetTextHeightReturns the height occupied by a text using the selected font.FWMsPrinter():GetTextHeight( <cTexto>, <oFont> ) --> nHeight

Parameters

NameFormatRequiredDescriptionNotes

cTextoCaractereRequired

Texto a medir.

oFontObjetoRequired

Fonte usada no cálculo.

Return value

nHeight: altura calculada.

GetTextWidthReturns the width occupied by a text using the selected font.FWMsPrinter():GetTextWidth( <cTexto>, <oFont>, <nType> ) --> nWidth

Parameters

NameFormatRequiredDescriptionNotes

cTextoCaractereRequired

Texto a medir.

oFontObjetoRequired

Fonte usada no cálculo.

nTypeNuméricoRequired

Tipo de cálculo de largura.

Return value

nWidth: largura calculada.

GetViewPDFReturns whether the PDF should be displayed after generation.FWMsPrinter():GetViewPDF() --> lViewPDF

Return value

lViewPDF: .T. para exibir o PDF.

IsPrinterActiveReturns whether the printer is active or available for the report.FWMsPrinter():IsPrinterActive() -->

LineInserts a line in the report.FWMsPrinter():Line( <nTop>, <nLeft>, <nBottom>, <nRight>, [nColor], [cPixel] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nTopNuméricoRequired

Coordenada superior/inicial.

nLeftNuméricoRequired

Coordenada esquerda/inicial.

nBottomNuméricoRequired

Coordenada inferior/final.

nRightNuméricoRequired

Coordenada direita/final.

nColorNuméricoOptional

Cor da linha.

cPixelCaractereOptional

Tratamento de coordenadas em pixels.

nHorzResReturns the horizontal resolution of the configured printer.FWMsPrinter():nHorzRes() --> nResult

Return value

nResult: resolução horizontal.

nHorzSizeReturns the page width.FWMsPrinter():nHorzSize() --> nHorzSize

Return value

nHorzSize: largura da página.

nLogPixelXReturns the horizontal logical-pixel resolution of the configured printer.FWMsPrinter():nLogPixelX() --> nResult

Return value

nResult: pixels lógicos no eixo X.

nLogPixelYReturns the vertical logical-pixel resolution of the configured printer.FWMsPrinter():nLogPixelY() --> nResult

Return value

nResult: pixels lógicos no eixo Y.

nVertResReturns the vertical resolution of the configured printer.FWMsPrinter():nVertRes() --> nResult

Return value

nResult: resolução vertical.

nVertSizeReturns the page height.FWMsPrinter():nVertSize() --> nVertSize

Return value

nVertSize: altura da página.

PaperSizeReturns the configured paper size.FWMsPrinter():PaperSize() --> nPaperSize

Return value

nPaperSize: código do tamanho do papel.

PreviewOpens the generated report preview.FWMsPrinter():Preview() -->

PrintSends the report to the printer or configured destination.FWMsPrinter():Print() -->

PrinterNameReturns the configured printer name.FWMsPrinter():PrinterName() --> cImpressora

Return value

cImpressora: nome da impressora.

QRCodePrints a QR Code in the report.FWMsPrinter():QRCode( <nRow>, <nCol>, <cCodeBar>, <nSizeBar> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cCodeBarCaractereRequired

Conteúdo a codificar.

nSizeBarNuméricoRequired

Tamanho do QR Code.

SayInserts text in the report. This is the base method for writing titles, fields and messages.FWMsPrinter():Say( <nRow>, <nCol>, <cText>, [oFont], [nWidth], [nClrText], [nAngle] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cTextCaractereRequired

Texto a imprimir.

oFontObjetoOptional

Fonte utilizada.

nWidthNuméricoOptional

Largura disponível para o texto.

nClrTextNuméricoOptional

Cor do texto.

nAngleNuméricoOptional

Ângulo de rotação.

SayAlignInserts text with horizontal and vertical alignment inside an area.

FWMsPrinter():SayAlign( <nRow>, <nCol>, <cText>, [oFont], [nWidth], [nHeight], [nClrText], [nAlignHorz], [nAlignVert] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cTextCaractereRequired

Texto a imprimir.

oFontObjetoOptional

Fonte utilizada.

nWidthNuméricoOptional

Largura da área.

nHeightNuméricoOptional

Altura da área.

nClrTextNuméricoOptional

Cor do texto.

nAlignHorzNuméricoOptional

Alinhamento horizontal.

nAlignVertNuméricoOptional

Alinhamento vertical.

SayBitmapInserts an image in the report. Validate format, path and availability in the execution environment.FWMsPrinter():SayBitmap( <nRow>, <nCol>, <cBitmap>, [nWidth], [nHeight] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cBitmapCaractereRequired

Caminho e nome do arquivo de imagem.

nWidthNuméricoOptional

Largura desejada.

nHeightNuméricoOptional

Altura desejada.

SetDeviceSelects the report output device, such as spool or PDF.FWMsPrinter():SetDevice( <nDevice> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nDeviceNuméricoRequired

Dispositivo, como IMP_SPOOL ou IMP_PDF.

SetFontDefines the font used in the report.FWMsPrinter():SetFont( <oFont>, <lForceFont> ) -->

Parameters

NameFormatRequiredDescriptionNotes

oFontObjetoRequired

Objeto TFont.

lForceFontLógicoRequired

Força a aplicação da fonte informada.

SetLandscapeSets report orientation to landscape.FWMsPrinter():SetLandscape() -->

SetMarginDefines report margins.FWMsPrinter():SetMargin( <nLeft>, <nTop>, <nRight>, <nBottom> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nLeftNuméricoRequired

Margem esquerda.

nTopNuméricoRequired

Margem superior.

nRightNuméricoRequired

Margem direita.

nBottomNuméricoRequired

Margem inferior.

SetPaperSizeDefines the paper size used by the page.FWMsPrinter():SetPaperSize( <nPaperSize>, [nHeight], [nWidth] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nPaperSizeNuméricoRequired

Código do tamanho de papel, como DMPAPER_A4.

nHeightNuméricoOptional

Altura personalizada.

nWidthNuméricoOptional

Largura personalizada.

SetPortraitSets report orientation to portrait.FWMsPrinter():SetPortrait() -->

SetResolutionDefines report resolution.FWMsPrinter():SetResolution( [nResolution] ) -->

Parameters

NameFormatRequiredDescriptionNotes

nResolutionNuméricoOptional

Resolução desejada.

SetupDisplays the printer setup window when the flow allows user interaction.FWMsPrinter():Setup() -->

SetViewPDFDefines whether the generated PDF should be displayed after generation.FWMsPrinter():SetViewPDF( <lViewPDF> ) -->

Parameters

NameFormatRequiredDescriptionNotes

lViewPDFLógicoRequired

.T. para exibir o PDF após gerar.

Pdf417Prints a two-dimensional PDF417 barcode.FWMsPrinter():Pdf417( <nRow>, <nCol>, <cCodeBar>, <nSizeBar>, <nHeight> ) -->

Parameters

NameFormatRequiredDescriptionNotes

nRowNuméricoRequired

Posição vertical.

nColNuméricoRequired

Posição horizontal.

cCodeBarCaractereRequired

Conteúdo a codificar.

nSizeBarNuméricoRequired

Tamanho do código de barras.

nHeightNuméricoRequired

Altura da barra.

StartPageStarts a new print page. It must be called before adding page content.FWMsPrinter():StartPage() -->

03 · PRACTICAL EXAMPLE

Basic PDF with initial setup

#Include "TOTVS.ch"
#Include "RPTDef.ch"
#Include "FWPrintSetup.ch"

User Function ExFWMsPrinter()
    Local oPrinter
    Local cFile          := "report.rel"
    Local lLegacyAdjust  := .F.
    Local lDisableSetup  := .T.

    oPrinter := FWMsPrinter():New(cFile, IMP_PDF, ;
        lLegacyAdjust, , lDisableSetup)

    oPrinter:SetResolution(72)
    oPrinter:SetPortrait()
    oPrinter:SetPaperSize(DMPAPER_A4)
    oPrinter:SetMargin(60, 60, 60, 60)
    oPrinter:cPathPDF := "c:\temp\"

    oPrinter:StartPage()
    oPrinter:Say(100, 100, "Sample report")
    oPrinter:EndPage()
    oPrinter:Preview()
Return

Expected result

Creates an A4 PDF report with margins, writes one text line and opens the preview.

04 · PRACTICAL EXAMPLE

Spool printing without setup

#Include "TOTVS.ch"
#Include "RPTDef.ch"
#Include "FWPrintSetup.ch"

User Function ExSpool()
    Local oPrinter
    Local cImpressora := "Microsoft Print to PDF"

    oPrinter := FWMsPrinter():New("spool.rel", IMP_SPOOL, ;
        .F., , .T., , , cImpressora)

    oPrinter:SetResolution(72)
    oPrinter:SetPortrait()
    oPrinter:SetPaperSize(DMPAPER_A4)

    oPrinter:StartPage()
    oPrinter:Say(100, 100, "Saída enviada ao dispositivo configurado")
    oPrinter:EndPage()
    oPrinter:Print()
Return

Expected result

When setup is disabled, the destination must be configured explicitly in code.

05 · PRACTICAL EXAMPLE

Image in a report

#Include "TOTVS.ch"
#Include "RPTDef.ch"

User Function ExImagemRel()
    Local oPrinter := FWMsPrinter():New("imagem.rel", IMP_PDF, .F., , .T.)

    oPrinter:StartPage()
    oPrinter:SayBitmap(100, 200, "c:\temp\logo.bmp", 300, 120)
    oPrinter:EndPage()
    oPrinter:Preview()
Return

Expected result

SayBitmap inserts an image in the report. Validate path, format and permissions in the generation environment.

06 · PRACTICAL EXAMPLE

Common methods and properties

// Basic cycle
oPrinter:StartPage()
oPrinter:Say(100, 100, "Text")
oPrinter:Line(130, 100, 130, 500)
oPrinter:Box(150, 100, 250, 500)
oPrinter:EndPage()

// Output
oPrinter:Preview() // preview
oPrinter:Print()   // print

Expected result

Drawing methods build the page. Properties such as cPathPDF, cPrinter, nDevice, lServer, lViewPDF, nPageWidth and nPageHeight help control destination, device and dimensions.

BEST PRACTICES

For new reports, prefer FWMsPrinter over TMSPrinter, which appears in documentation as discontinued.
Configure resolution, orientation, paper size and margins right after creating the object and before drawing content.
For automatic PDF without interface, use IMP_PDF, disable setup when appropriate and define the output path for the environment.
For printing without the selection screen, correctly provide cPrinter; setup selection does not work in reverse to preselect values in FWMsPrinter.
Use FWMsExcel, FWMsExcelEx, FWMsExcelXlsx or FwPrinterXlsx when the requirement is a spreadsheet; FWMsPrinter targets PDF or spool/printing.
Use SayBitmap for images and validate the supported format in the environment.
Use SetParm("-RFS") when you need to reduce font-size differences between PDF, print queue and preview, respecting build/TotvsPrinter availability.
Organize drawing in page cycles: StartPage(), content, EndPage() and finally Preview(), Print() or PDF generation.

COMMON PITFALLS

PDF generation may require a graphical operating-system interface according to the official documentation.
lAdjustToLegacy may distort elements such as BOX and FILLRECT in new reports; validate the visual result before relying on it.
When the user cancels the print screen, check the modal/result state before applying definitions or continuing.
Generated files may be saved in lower case by the Protheus binary even if the name is manipulated with Upper().
Do not expect FWMsPrinter to generate XLS, XLSX or XML; use spreadsheet classes for that.
In jobs or schedules, avoid relying on interactive screens and explicitly configure path, device, printer and copies.
When running on the server, images and paths must be accessible by the server machine, not only by the user workstation.
The local TMSPrinter documentation mentions a historical 128KB limit per page; use it as a warning when maintaining legacy reports and prefer restructuring large reports with FWMsPrinter/SmartView.

FWMsPrinter

Overview

Syntax

Parameters

Methods

Basic PDF with initial setup

Spool printing without setup

Image in a report

Common methods and properties

Related content

Comments