It has proven to be useful to record the layout of the report to be generated and to note the appropriate type, size specifications and possibly colors or other design specifications such as font and font heights for the report containers (ReportHBox, ReportVBox, ReportVPanel, ReportPanel) with the report controls they contain (which can also be report containers).

You should proceed as follows when designing a report:

• The standard for every new report for the (paper) format for printing is A4. Decide on the paper format at an early stage.
• Determine which sections the report should consist of. For example, a cover page (Section1: Cover) before the pages of the actual report (Section2: Pages) and a summary (Section3: Summary) are conceivable
• Find out which sections the report header should consist of and which section should be repeated on each page. The first page has a special position here, containing, for example, the database name, the name of the database table, the name of the editor and the print date. This information is then omitted from the second page onwards and only the report name is displayed after a suitable logo as part of your organization's corporate design.
• Mark the report controls whose content is to be repeated on each page. In the case of a tabular report, this would be the table header and a subsequent table row, which must be repeated as often as there are data records in the data source. You must specify or determine the number of repetitions.
• A footer on all pages with the page numbers in the format 'Page 2 of 5' provides a clear overview, especially for longer reports. Whether this information is left-aligned, centered, right-aligned or alternating should be noted.
• Determine whether the report needs to be split so that individual sections always start on a new page. This would be conceivable for a summary of the statements in the report.
• To define distances between report containers, you can also use report controls such as ReportPanel or ReportHBox.
• Consider whether such distances can also be realized, for example, using values for the Padding property of the ReportPadding type. However, this depends on whether the report control is repeated on every page or only in the report container.
• Design considerations should always focus on the use of a few colors and one font. You should use special effects such as color gradients sparingly.
• As a preventative measure, you should also plan a text summary of the report's statements at the end of the report, which is displayed on the last pages. Remember, however, that there is no ReportTextArea class to display simple (ASCII) text in the report! You must split the text in a suitable way in order to print it via ReportLabel or ReportTextLabel.

The following notes are intended to help you implement layout planning with the Report Designer in Gambas. Try out the effect of the values of the individual properties on the layout of your report in the preview and change properties and values until you are satisfied with the result.

Notes on properties for the arrangement of report containers:

• Property Arrangement: This property currently only exists for the ReportPanel. You can define 3 different values: None, Vertical, Horizontal. Vertical and Horizontal act as if you had used a ReportVBox or ReportHBox.
• Spacing property: This property defines a horizontal distance between two report controls.
• ForceNewPage property: This is a very special property. Every time a report container with the property Container.ForceNewPage = True is repeated, it forces a new page.
• Property OnePiece: The content of this report container must be displayed on one page. Everything is done by the class to achieve this goal.

Notes on properties of the arrangement of report controls:

Attention: These report controls are not report containers.

• Expand property: The report control height is the remaining space (on the page). If the Expand option is activated for more than one report control in a ReportVBox, then the report control height is the remaining space divided by the number of report controls on the current page.
• Ignore property: This report control is not arranged by the report container and instead its Left and Top properties are used to place it relative to the report container position.
• Fixed property: For Fixed = True, the report control is repeated each time its report container is repeated.
• Margin property: This property allows the report control to define a minimum distance between the report control and another. The largest value between two report controls is taken into account. The margin can also be set individually for each partial margin of the report control.

The following descriptions for the ReportLabel also apply to the ReportTextLabel report control element. While the ReportLabel only prints text, the ReportTextLabel prints rich text.

Use the Data property of the String data type to provide the content of a ReportLabel control during the Data() event handler via the Data property.

The most important event is therefore Data ( argIndex As Integer ). This event is triggered when text is to be stored in the ReportLabel control. The argument `argIndex` returns the current index of the control. Index is a property of a ReportLabel.

Example:

Private hResult As Result
 
Public Sub Report_Open()
 
  ...
' Generates the result of a database query from a selected database table
  hResult = curDBConnection.Exec("SELECT * FROM tablename")
' Sets the number of repetitions of the three TextLabels in the container ReportHBox1
  ReportHBox1.DataCount = hResult.Count
  ...
 
End
 
Public Sub ReportLabelName_Data(Index As Integer)
 
' Use the `Index` argument to navigate through the query result.
  hResult.MoveTo(Index)
' The content of the database field "surname" is displayed in the "ReportLabelName" control element
  hResult.MoveTo(Index)
  Last.Data = hResult["nachname"]
' Last.Data = hResult!nachname     '-- Alternative
 
End
 
Public Sub ReportLabelVorname_Data(Index As Integer)
  hResult.MoveTo(Index)
  Last.Data = hResult["vorname"]
End
 
Public Sub ReportLabelGebDatum_Data(Index As Integer)
  hResult.MoveTo(Index)
  Last.Data = Format(hResult["gebdatum"], "d. mmmm yyyy") '-- Note the formatting
End

Figure 22.11.2.2.1: Database report (excerpt)

Notes
If you set the UseField property in the ReportLabel to True, the component is initially backwards compatible with gb.report.The Range property is currently (August 2019) not used.

This class implements a report control that displays and prints an image.

The ReportImage class has the following properties, among others:

Table 22.11.2.3.1 : Properties of the ReportImage class

Note: If the Image width and Image height values are zero, the control behaves as if its property Autoresize = True.

Example: Inserting an image into a ReportImage

Public Sub Report_Open()
 
  Dim hReportImageLogo As Image  
  ...
  hReportImageLogo = Image.Load(".../logo-ide.png")
 
  ReportImage1.Image = hReportImageLogo
 
  ReportImage1.Stretch = Report.Proportional
 
' Output of the original values for image height and image width
  Print "Logo.H = "; hReportImageLogo.Height; " Pixel"
  Print "Logo.W = "; hReportImageLogo.Width; " Pixel"
 
End

The Gambas logo adorns the cover page of a report:

Figure 22.11.2.3.1: Report cover page with image (excerpt)