ApplyFilter Event

The ApplyFilter event can occur within a Microsoft Access project (.adp) or Access database (.mdb).

Within an Access database, an ApplyFilter event occurs when the user does one of the following:

• Clicks Apply Filter/Sort on the Records menu in Form view, clicks Apply Filter/Sort on the Filter menu in the Filter window, or clicks Apply Filter on the toolbar. This applies the most recently created filter (created by using either the Filter By Form feature or the Advanced Filter/Sort window).
  
  
• On the Records menu in Form view, points to Filter and clicks Filter By Selection, or clicks Filter By Selection on the toolbar. This applies a filter based on the current selection in the form.
  
  
• On the Records menu in Form view, points to Filter and clicks Filter Excluding Selection. This applies a filter excluding the current selection in the form.
  
  
• Clicks Remove Filter/Sort on the Records menu in Form view, or clicks Remove Filter on the toolbar. This removes any filter (or sort) currently applied to the form.
  
  
• Clicks Filter By Selection, Filter Excluding Selection, or Remove Filter/Sort or enters a value or expression in the Filter For box on the shortcut menu when a bound control has the focus.
  
  
• Closes the Advanced Filter/Sort window or the Filter By Form window.
  
  
• Clicks Advanced Filter/Sort on the Filter menu while the Filter By Form window is open, or clicks Filter By Form on the Filter menu while the Advanced Filter/Sort window is open. This causes the ApplyFilter event to occur when the open filter window is closed, and then the Filter event to occur when the other filter window is opened.

Within an Access project, an ApplyFilter event occurs when the user does one of the following:

• Clicks Apply Filter/Sort on the Records menu in Form view, clicks Apply Filter/Sort on the Filter menu in the Filter window, or clicks Apply Filter on the toolbar. This applies the most recently created filter (created by using the Filter By Form feature).
  
  
• Clicks Apply Server Filter on the Records menu in Form view, clicks Apply Server Filter on the Filter menu in the Filter window, or clicks Apply Server Filter on the toolbar. This applies the most recently created filter (created by using the Server Filter By Form feature).
  
  
• On the Records menu in Form view, points to Filter and clicks Filter By Selection, or clicks Filter By Selection on the toolbar. This applies a filter based on the current selection in the form.
  
  
• On the Records menu in Form view, points to Filter and clicks Filter Excluding Selection. This applies a filter excluding the current selection in the form.
  
  
• Clicks Filter By Selection or Filter Excluding Selection or enters a value or expression in the Filter For box on the shortcut menu when a bound control has the focus.

Remarks

To run a macro or event procedure when this event occurs, set the OnApplyFilter property to the name of the macro or to [Event Procedure].

You can use the ApplyFilter event to:

• Make sure the filter that is being applied is correct. For example, you may want to be sure that any filter applied to an Orders form includes criteria restricting the OrderDate field. To do this, check the form's Filter or ServerFilter property value to make sure this criteria is included in the WHERE clause expression.
  
  
• Change the display of the form before the filter is applied. For example, when you apply a certain filter, you may want to disable or hide some fields that aren't appropriate for the records displayed by this filter.
  
  
• Undo or change actions you took when the Filter event occurred. For example, you can disable or hide some controls on the form when the user is creating the filter, because you don't want these controls to be included in the filter criteria. You can then enable or show these controls after the filter is applied.

The actions in the ApplyFilter macro or event procedure occur before the filter is applied or removed; or after the Advanced Filter/Sort, Filter By Form, or Server Filter By Form window is closed, but before the form is redisplayed. The criteria you've entered in the newly created filter are available to the ApplyFilter macro or event procedure as the setting of the Filter or ServerFilter property.

Note   The ApplyFilter event doesn't occur when the user does one of the following:

• Applies or removes a filter by using the ApplyFilter, OpenForm, or ShowAllRecords actions in a macro, or their corresponding methods of the DoCmd object in Visual Basic.
  
  
• Uses the Close action or the Close method of the DoCmd object to close the Advanced Filter/Sort, Filter By Form, or Server Filter By Form window.
  
  
• Sets the Filter or ServerFilter property or FilterOn or ServerFilterByForm property in a macro or Visual Basic (although you can set these properties in an ApplyFilter macro or event procedure).

Example

The following example shows how to hide the AmountDue, Tax, and TotalDue controls on an Orders form when the applied filter restricts the records to only those orders that have been paid for.

To try this example, add the following event procedure to an Orders form that contains AmountDue, Tax, and TotalDue controls. Run a filter that lists only those orders that have been paid for.

Private Sub Form_ApplyFilter(Cancel As Integer, ApplyType As Integer)
    If Not IsNull(Me.Filter) And (InStr(Me.Filter, "Orders.Paid = -1")>0 _
            Or InStr(Me.Filter, "Orders.Paid = True")>0)Then
        If ApplyType = acApplyFilter Then
            Forms!Orders!AmountDue.Visible = False
            Forms!Orders!Tax.Visible = False
            Forms!Orders!TotalDue.Visible = False
        ElseIf ApplyType = acShowAllRecords Then
            Forms!Orders!AmountDue.Visible = True
            Forms!Orders!Tax.Visible = True
            Forms!Orders!TotalDue.Visible = True
        End If
    End If
End Sub