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 syntax 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 footer. If header and/or footer is True (-1), the field or expression will have a group header and/or footer. If header and/or footer is False (0), it won’t.


Remarks

Use the CreateGroupLevel function when designing a wizard that creates a report with groups or totals. CreateGroupLevel will group or sort data on the specified field or expression and create 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. CreateGroupLevel adds a new group level to the array, based on the expression argument. CreateGroupLevel 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 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 you can set them in the report’s Sorting and Grouping Box.

Tip 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 function 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, 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 = 400Sub