Introduction to Rave Reports - Part I: Code Based Reports

Delphi 7 has included Rave Reports as the default reporting solution, replacing Quick Reports. Since they work in very different paradigms, many people were confused by the new environment. This is intended as an introduction for people who haven't worked with Rave yet, and would like to start.

Delphi 7 ships with Rave Reports 5.0.8. If you haven't already, download the update from the registered users page, since it fixes some important problems.

You can develop reports with Rave using two different ways: Code Based or with the Visual Designer. This document describes how to work with the code based engine. Part II will describe the Visual Designer.

Code Based Reports

With Code Based, you write reports using plain Delphi code. That provides a very flexible way displaying any kind of data, allowing any kind of complex layouts.

To write a code based report, just drop a TRvSystem component on the form and write the report on the OnPrint event handler. Sender is the report you are creating, and can be typecasted to TBaseReport. It contains all the methods you need to output information to that particular report.

Simple Code Base Report

procedure TFormMain.RvSystemPrint(Sender: TObject);
begin
  with Sender as TBaseReport do
  begin
    SetFont('Arial', 15);
    GotoXY(1,1);
    Print('Welcome to Code Based Reporting in Rave');
  end;
end;

To execute this report, call RvSystem.Execute method.

So, what does that simple code do? First, it calls SetFont to select the font and size of the text that will be printed from that point on. Then it positions the cursor on the coordinates (1,1). These coordinates are expressed using the units set in the SystemPrinter.Units property of the RvSystem object, and it defaults to Inches. You can set it to unUser and set a number relative to Inches in the SystemPrinter.UnitsFactor property. For example, if UnitsFactor was set to 0.5 then 1 unit would correspond to half an inch. Finally, the code calls the Print method to output the text. Here's the output:

Tabular Code Based Report

Here's another example. It displays a list of the folders in the root of the current drive, along with a recursive count of number of files and folder, and total size of the files included in each folder.

procedure TFormMain.PrintTabularReport(Report: TBaseReport);
var
  FolderList : TStringList;
  i          : Integer;
  NumFiles   : Cardinal;
  NumFolders : Cardinal;
  SizeFiles  : Cardinal;
  Root       : string;
begin
  with Report do
  begin
    SetFont('Arial', 15);
    NewLine;
    PrintCenter('List of Folders in the Drive Root', 4);
    NewLine;
    NewLine;
    ClearTabs;
    SetTab(0.2, pjLeft, 1.7, 0, 0, 0);
    SetTab(1.7, pjRight, 3.1, 0, 0, 0);
    SetTab(3.1, pjRight, 3.5, 0, 0, 0);
    SetTab(3.5, pjRight, 4.5, 0, 0, 0);
    SetFont('Arial', 10);
    Bold := True;
    PrintTab('Folder Name');
    PrintTab('Number of Files');
    PrintTab('Number of Folders');
    PrintTab('Size of Files');
    Bold := False;
    NewLine;
    FolderList := TStringList.Create;
    try
      Root := IncludeTrailingPathDelimiter(ExtractFileDrive(ParamStr(0)));
      EnumFolders(FolderList, Root);
      for i := 0 to FolderList.Count - 1 do
      begin
        PrintTab(FolderList[i]);
        GetFolderInfo(IncludeTrailingPathDelimiter(Root+FolderList[i]),
          NumFiles, NumFolders, SizeFiles);
        PrintTab(Format('%u',[NumFiles]));
        PrintTab(Format('%u',[NumFolders]));
        PrintTab(Format('%u bytes',[SizeFiles]));
        NewLine;
      end;
    finally
      FolderList.Free;
    end;
  end;
end;

Notice that a different approach has been taken: instead of specifying the coordinates of each text output, the printing was done using Lines and Columns as references. The line heigh depends on the size of the current font: each unit represents 1/72nds of an inch, so each line printed with a size 10 font will have, aproximatelly, a height of 0.138 inches. Lines are advanced after calls to PrintLn or NewLine. Colums are defined using calls to the SetTabs method, and the PrintTab method will print the text in the current column and advance to the next one. Here's the output:

You can find the full source, including the implementation of EnumFolders and GetFolderInfo, on CodeCentral.

Graphical Code Based Report

You can include shapes and images in your code based report, along with the text. The following example demonstrates that:

procedure TFormMain.PrintGraphicsReport(Report: TBaseReport);
var
  Bitmap : TBitmap;
begin
  with Report do
  begin
    Canvas.Brush.Color := clGray;
    Rectangle(0.3, 0.3, 4.7, 3.3);
    SetFont('Arial', 15);
    FontColor := clRed;
    PrintXY(0.5,0.5, 'Just look at all the graphics!');
    Bitmap := TBitmap.Create;
    try
      Bitmap.LoadFromFile('delphi.bmp');
      PrintBitmap(3.5,0.3,1,1, Bitmap);
      PrintBitmap(1,2,3,3, Bitmap);
      Canvas.Pen.Color := clBlue;
      Canvas.Brush.Bitmap := Bitmap;
      Ellipse(5,0.3,6,3.3);
      Ellipse(2,1,4,1.9);
    finally
      Bitmap.Free;
    end;
    Canvas.Pen.Color := clBlack;
    Canvas.Brush.Style := bsSolid;
    Canvas.Brush.Color := clYellow;
    Pie(0.7,0.7,1.7,1.7,1,1,1,2);
    Canvas.Brush.Color := clGreen;
    Pie(0.7,0.7,1.7,1.7,1,2,1,1);
  end;
end;

In this example the methods Rectangle, Ellipse and Pie have been used draw shapes with different fills. Bitmaps were outputted using PrintBitmap and as the brush of the ellipses. Here's the output:

A sample application, containing full source code for those three examples can be found at CodeCentral.

Conclusion

As you can see, code based reporting offers a great flexibility and control of the layout you want, but require some work to implement them. In Part II we will see how the Visual Designer can be used to build powerful reports in a very easy way.