CreateGroupLevel Function

Description

You can use the CreateGroupLevel function to specify a field or expression on which to group or sort data in a report.

For example, suppose you are building a custom wizard that provides the user with a choice of fields on which to group data when designing a report. Call the CreateGroupLevel function from your wizard to create the appropriate groups according to the user's choice.

Syntax

CreateGroupLevel(report, expression, header, footer)

The CreateGroupLevel function has the following arguments.

Argument	Description

report	A string expression identifying the name of the report that will contain the new group level.
expression	A string expression identifying the field or expression to sort or group on.
header, footer	An Integer value that indicates whether a field or expression will have an associated group header and/or group footer. If the header or footer argument is True (–1), the field or expression will have a group header or footer. If the header or footer argument is False (0), the field or expression won't. You can create both a header and a footer by setting both arguments to True.

Remarks You can use the CreateGroupLevel function when designing a wizard that creates a report with groups or totals. The CreateGroupLevel function groups or sorts data on the specified field or expression and creates a header and/or footer for the group level.

The CreateGroupLevel function is available only in report Design view.

Microsoft Access uses an array, the GroupLevel property array, to keep track of the group levels created for a report. The CreateGroupLevel function adds a new group level to the array, based on the expression argument. The CreateGroupLevel function then returns an index value that represents the new group level's position in the array. The first field or expression you sort or group on is level 0, the second is level 1, and so on. You can have up to ten group levels in a report (0 to 9).

When you specify that either the header or footer argument, or both, is True, the GroupHeader and GroupFooter properties in a report are set to Yes, and a header and/or footer is created for the group level.

Once a header or footer is created, you can set other GroupLevel properties: GroupOn, GroupInterval, and KeepTogether. You can set these properties in Visual Basic or in the report's Sorting And Grouping box, available by clicking the Sorting And Grouping button on the Report Design toolbar.

Note If your wizard creates group levels in a new or existing report, it must open the report in Design view.

See Also GroupHeader, GroupFooter properties, GroupInterval property, GroupLevel property, GroupOn property, KeepTogether property — groups, SortOrder property.

Example

The following example creates a group level on an OrderDate field on a report called OrderReport. The report on which the group level is to be created must be open in Design view. Since the header and footer arguments are set to True (–1), the function creates both the header and footer for the group level. The header and footer are then sized.

Sub CreateGL()
    Dim varGroupLevel As Variant

    ' Create new group level on OrderDate field.
    varGroupLevel = CreateGroupLevel("OrderReport", "OrderDate", _
        True, True)
    ' Set height of header/footer sections.
    Reports!OrderReport.Section(acGroupLevel1Header).Height = 400
    Reports!OrderReport.Section(acGroupLevel1Footer).Height = 400
End Sub