Visual Basic Concepts

Understanding Control Placement on the Data Report Designer

Note   You will understand this topic better if you read the Data Report tutorial first, beginning at Creating a Simple Data Report.

One way of creating a data report is to:

1. Create a Data Environment designer containing a hierarchy of Command objects.

2. Set the DataSource property of the Data Report designer to the Data Environment designer.

3. Set the DataMember property to the topmost Command object.

4. Right-click the Data Report designer and click Retrieve Structure.

   After retrieving the structure, an appropriate number of Group headers and footers will be created, and each header/footer pair is assigned a name that corresponds to a Command object.

5. Drag Command objects from the Data Environment designer to the corresponding section on the Data Report designer.

   All of the data fields contained by a Command object are automatically created on the data report as TextBox controls on the section where the Command object is dropped. The DataMember and DataField properties of each TextBox are set in accordance with the Command object and its data fields.

6. Drag TextBox controls from the section where each was created onto a different section of the Data Report designer.

7. Add Function controls as needed to the report.

When the data report is bound to a data environment, the rules for placement of controls on the report are not immediately apparent. This topic explains how the hierarchy created in the data environment relates to the system of group headers and footers constructed in the data report.

Command Object Corresponds to Group Header/Footer or Details Section

With two exceptions, every Command object in the data environment corresponds either to a pair of group header and footer sections, or to the Detail section. The exceptions are discussed later in this topic.

Hierarchy Versus Headers, Footers, and Detail

The figure below shows a schematic view of the Data Environment designer with four Command objects, each in a parent/child relationship with at least one other command. The data fields that belong to the table are not shown.

The Data Report designer, on the other hand, is constructed as a series of sections. And each section can be categorized into one of four types: Report header/footers, Page header/footers, Group header/footers, and the Detail section. For the purposes of instruction, we can disregard the Report and Page header/footer pairs. This leaves the Group headers/footers and the Detail section.

The Detail section, the innermost section of the designer, corresponds to the lowest-level Command object. As you go up through the hierarchy, the Detail section is bracketed by pairs of sections, with each pair associated with a single Command object. The figure below correlates the Command objects with the sections:

Sections Corresponding to Command Objects

Thus the figure shows that the hierarchy of the data environment actually corresponds to an expanding series of brackets, with the innermost (Detail) section corresponding to the lowest level of the hierarchy, and the outermost corresponding to the highest-level Command object.

Controls Can Be Placed in Any Section in a Lower Level

The placement of a control is governed by what section (or pair of sections) it belongs to. In brief, a control can be placed in the section where it originates, and in all sections that are at a level lower than itself. For example, if a control belongs to the Command1 section pair, it can also be placed in the section pairs for Commands 2, 3, and 4. A second example: A control that originates in section 3 can also be placed in section 4, but not in sections 1 and 2. Taken to its conclusion, controls that originate in the Command 4 section (the Details section) cannot be placed anywhere else except in the Details section.

Placing the Function Control

The Function control has three exceptions to the above guidelines regarding control placement. The Function control is not directly bound to the recordset, as is the TextBox control. Instead, the Function control calculates its value as the report is generated. For this reason, a Function control can only be placed in Footer sections of the report.

A second exception for the Function control: it can only be placed in any section pair that is one level above its own. For example, if the Command 3 object contains a Quantity field, you can place a Function control that sums the Quantity values onto the footer section for Command 2, or the footer section for Command 1.

The third exception concerning the Function control is this: unlike the other data-bound control (the TextBox control), the Function control can be placed in the Report Footer section. When you do so, the scope of the control's calculation will be increased to include the whole report. For example, a Function control placed in the Report footer to calculate the sum of the Quantity field will calculate the sum of every Quantity control on the report.

The Exceptions: Grouping and Grand Total Aggregate

With two exceptions, every Command object in the Data Environment corresponds to a pair of group headers and footers. The first exception occurs when you use the Grouping feature of the Data Environment designer.

Grouping Fields

When you create grouping fields, the Data Environment designer creates two folders under a single Command object. The first contains the grouping fields, and the second contains the Detail fields. Even though a new Command object is not created for the grouping fields, you must create a new group header/footer pair on the data report and this requirement qualifies it as an exception.

Grand Total Aggregate Fields

The second exception occurs when you create a Grand Total aggregate field in the data environment. As happens when creating a grouping field, a new folder is created for the Command object. The new folder contains any Grand Total aggregate fields created, and you must add a new group header/footer pair to the data report.

For More Information   Details about creating aggregate field can be found in "Creating Aggregates" in "Using the Data Environment Designer."

Checking the Hierarchy

If you are in doubt as to the hierarchy of the Data Environment Command objects, you have two ways of ensuring that the data report has the correct group header/footer structure:

Retrieve Structure—If you have not placed many controls onto the Data Report designer, and you can tolerate the restructuring of your data report, use the Retrieve Structure command to automatically create the right number of group headers and footers.

**ADO Hierarchy Information—**Right-click the topmost Command object in the Data Environment designer and click Hierarchy Info to display the Hierarchy Information dialog box. Click the View ADO Hierarchy tab to see a graphical representation of the Command objects' hierarchy.