TReport

Source: source/classes/report.prg

TReport is FiveWin's high-level report engine. It automates the creation of tabular reports from DBF files or any data source, with support for column headers, grouping, subtotals, grand totals, page numbering, shadows, grid lines, and export to Excel. TReport uses TPrinter internally for output.

Report Processing Flow

flowchart TD A[Init] --> B[bInit Block] B --> C[StartPage] C --> D{Check Groups} D -->|New Group| E[StartGroup
Print Group Header] D -->|Same Group| F[Print Column Data] E --> F F --> G[EndLine / Skip] G --> H{End of Data?} H -->|No| I{Page Full?} I -->|Yes| J[EndPage / StartPage] I -->|No| D J --> D H -->|Yes| K[EndGroup
Print Totals] K --> L[Grand Total Line] L --> M[EndPage] M --> N[bEnd Block] N --> O[Preview / Print]

Key DATA Members

DATA	Type	Description
`oDevice`	TPrinter	Output printer device
`aGroups`	Array	Array of TRGroup objects (grouping levels)
`aColumns`	Array	Array of TRColumn objects (report columns)
`aFont`	Array	Array of TFont objects used in the report
`aPen`	Array	Array of TPen objects for lines/grid
`bFor`	Block	FOR condition (filter records)
`bWhile`	Block	WHILE condition (stop condition)
`bInit`	Block	Executed before report starts
`bEnd`	Block	Executed after report ends
`bSkip`	Block	Custom skip block (default: DBSKIP())
`bStartPage`	Block	Executed at the start of each page
`bEndPage`	Block	Executed at the end of each page
`bStartLine`	Block	Executed before each data line
`bEndLine`	Block	Executed after each data line
`bStartGroup`	Block	Executed when a new group starts
`bEndGroup`	Block	Executed when a group ends
`nRow`	Numeric	Current row position on page
`nPage`	Numeric	Current page number
`nMargin`	Numeric	Left margin
`nBottomRow`	Numeric	Bottom margin row (triggers new page)
`nStdLineHeight`	Numeric	Standard line height in pixels
`lSummary`	Logical	Summary-only mode (no detail lines)
`lTotal`	Logical	Show grand totals
`lShadow`	Logical	Print shadows under totals
`lGrid`	Logical	Print grid lines
`nRptAlign`	Numeric	Report alignment (RPT_LEFT, RPT_CENTER, RPT_RIGHT)

Key Methods

Method	Description
`New( aTitle, aHead, aFoot, aFont, aPen, lSummary, ... )`	Create the report
`Activate( bFor, bWhile, bInit, bEnd, ... )`	Run the report
`AddColumn( oColumn )`	Add a column to the report
`DelColumn( nColumn )`	Remove a column
`InsColumn( oColumn, nPos )`	Insert a column at a specific position
`AddGroup( oGroup )`	Add a grouping level
`Say( nCol, xText, nFont, nPad, nRow )`	Print text in a column
`SayBitmap( nRow, nCol, cBitmap, nWidth, nHeight, ... )`	Print an image
`Box( nRow, nCol, nBottom, nRight, nPen, nScale )`	Draw a box
`Line( nRow, nCol, nBottom, nRight, nPen, nScale )`	Draw a line
`TotalLine( nType, nGrid )`	Print total/subtotal line
`NewLine( nHeight )`	Advance to next line
`BackLine( nLine )`	Move back by n lines
`NeedNewPage()`	Check if current row exceeds bottom margin
`Margin( nValue, nType, nScale )`	Set margins (left, right, top, bottom)
`CellView()`	Enable cell-view mode (grid around every cell)
`ToExcel( bProgress )`	Export report to Excel

Report Commands

REPORT oRpt ;
   [ TITLE cTitle1, cTitle2, ... ] ;
   [ HEADER cHead1, cHead2, ... ] ;
   [ FOOTER cFoot1, cFoot2, ... ] ;
   [ FONT oFont1, oFont2, ... ] ;
   [ PEN oPen1, oPen2, ... ] ;
   [ SUMMARY ] ;
   [ PREVIEW ] ;
   [ TO PRINTER ] ;
   [ TO FILE cFile ] ;
   [ NAME cReportName ]

COLUMN [ TITLE cTitle ] ;
   [ DATA bData ] ;
   [ SIZE nWidth ] ;
   [ PICTURE cPicture ] ;
   [ FONT nFontIndex ] ;
   [ LEFT | CENTER | RIGHT ] ;
   [ TOTAL ] ;
   [ SHADOW ] ;
   [ GRID ]

GROUP [ ON bGroupExpr ] ;
   [ HEADER cHeader ] ;
   [ FOOTER cFooter ] ;
   [ FONT nFontIndex ] ;
   [ EJECT ]

END REPORT

Example: Simple List Report

#include "FiveWin.ch"

function Main()

   local oRpt, oFont1, oFont2

   USE customers

   DEFINE FONT oFont1 NAME "Arial" SIZE 0, -14
   DEFINE FONT oFont2 NAME "Arial" SIZE 0, -10

   REPORT oRpt TITLE "Customer List" ;
      FONT oFont1, oFont2 PREVIEW

   COLUMN TITLE "Name"    DATA customers->name    SIZE 30
   COLUMN TITLE "City"    DATA customers->city    SIZE 20
   COLUMN TITLE "State"   DATA customers->state   SIZE  5
   COLUMN TITLE "Phone"   DATA customers->phone   SIZE 15
   COLUMN TITLE "Balance" DATA customers->balance SIZE 12 ;
      PICTURE "999,999.99" TOTAL

   END REPORT

   oFont1:End()
   oFont2:End()

   USE

return nil

Example: Grouped Report with Subtotals

#include "FiveWin.ch"

function Main()

   local oRpt, oFont1, oFont2, oFont3

   USE invoices INDEX invoices

   SET ORDER TO TAG "CUSTOMER"

   DEFINE FONT oFont1 NAME "Arial Bold" SIZE 0, -16
   DEFINE FONT oFont2 NAME "Arial"      SIZE 0, -10
   DEFINE FONT oFont3 NAME "Arial Bold" SIZE 0, -11

   REPORT oRpt ;
      TITLE "Invoice Report by Customer" ;
      HEADER "Period: " + DToC( Date() - 365 ) + " to " + DToC( Date() ) ;
      FOOTER "Page: " + Str( oRpt:nPage, 3 ) ;
      FONT oFont1, oFont2, oFont3 ;
      PREVIEW

   // Group by customer
   GROUP ON invoices->custid ;
      HEADER "Customer: " + invoices->custname ;
      FOOTER "Subtotal" ;
      FONT 3 ;
      EJECT

   COLUMN TITLE "Invoice #"  DATA invoices->invnum    SIZE 12
   COLUMN TITLE "Date"       DATA invoices->invdate   SIZE 10
   COLUMN TITLE "Description" DATA invoices->descript SIZE 30
   COLUMN TITLE "Amount"     DATA invoices->amount    SIZE 12 ;
      PICTURE "999,999.99" TOTAL

   END REPORT

   oFont1:End()
   oFont2:End()
   oFont3:End()

   USE

return nil

Example: Custom Report with Events

#include "FiveWin.ch"

function Main()

   local oRpt, oFont1, oFont2
   local nTotal := 0

   USE products INDEX products

   DEFINE FONT oFont1 NAME "Calibri" SIZE 0, -14
   DEFINE FONT oFont2 NAME "Calibri" SIZE 0, -10

   REPORT oRpt TITLE "Product Catalog" ;
      FONT oFont1, oFont2 PREVIEW

   COLUMN TITLE "Code"     DATA products->code     SIZE 10
   COLUMN TITLE "Product"  DATA products->name     SIZE 30
   COLUMN TITLE "Category" DATA products->category SIZE 15
   COLUMN TITLE "Price"    DATA products->price    SIZE 12 ;
      PICTURE "999,999.99" TOTAL
   COLUMN TITLE "Stock"    DATA products->stock    SIZE  8 TOTAL

   END REPORT

   // Custom activation with event blocks
   oRpt:Activate( ;
      { || products->active },                ; // bFor: only active products
      ,                                        ; // bWhile
      { || oRpt:Margin( 1, 1, 1 ) },         ; // bInit
      { || MsgInfo( "Report completed" ) },   ; // bEnd
      { || oRpt:Say( 1, "Page " + ;
         LTrim( Str( oRpt:nPage ) ), 2 ) },  ; // bStartPage
      ,                                        ; // bEndPage
      ,                                        ; // bStartGroup
      )                                          // bEndGroup

   oFont1:End()
   oFont2:End()

   USE

return nil

Example: Export to Excel

#include "FiveWin.ch"

function Main()

   local oRpt

   USE customers

   REPORT oRpt TITLE "Customers" PREVIEW

   COLUMN TITLE "Name"    DATA customers->name    SIZE 30
   COLUMN TITLE "Email"   DATA customers->email   SIZE 30
   COLUMN TITLE "Balance" DATA customers->balance SIZE 12 ;
      PICTURE "999,999.99" TOTAL

   END REPORT

   // Export to Excel after preview
   oRpt:ToExcel( { |n| SysRefresh() } )

   USE

return nil

Tips

Font indices in COLUMN and GROUP commands are 1-based and refer to the FONT array in the REPORT command.
Use EJECT in GROUP to force a page break when the group changes.
lSummary mode prints only group headers/footers and totals -- no detail lines.
The CellView() method enables a spreadsheet-like appearance with grid borders around each cell.
Use nRptAlign to control how the report is positioned on the page (RPT_LEFT, RPT_CENTER, RPT_RIGHT).
NeedNewPage() returns .T. when the current row position has reached the bottom margin, useful in bStartLine to insert manual page breaks.