Método DoCmd.ApplyFilter (Access)

O método ApplyFilter realiza a ação ApplyFilter no Visual Basic.

Sintaxe

expressão. ApplyFilter (FilterName, WhereCondition, ControlName)

expression Uma variável que representa um objeto DoCmd.

Parâmetros

Nome Obrigatório/Opcional Tipo de dados Descrição
FilterName Opcional Variant Uma expressão de cadeia de caracteres que é o nome válido de um filtro ou de uma consulta no banco de dados atual. Ao usar esse método para aplicar um filtro de servidor, o argumento FilterName deve estar em branco.
WhereCondition Opcional Variant Uma expressão de cadeia de caracteres que é uma cláusula WHERE do SQL válida sem a palavra WHERE.
Controlname Opcional Variant

Comentários

Use a ação ApplyFilter para aplicar um filtro, uma consulta ou uma cláusula SQL WHERE a uma tabela, formulário ou relatório para restringir ou classificar os registros na tabela ou nos registros da tabela subjacente ou consulta do formulário ou relatório. Para relatórios, é possível usar esta ação somente em uma macro especificada pela propriedade de evento AoAbrir do relatório.

Use essa ação para aplicar uma cláusula SQL WHERE somente ao aplicar um filtro de servidor. Um filtro de servidor não pode ser aplicado a uma fonte de registros do procedimento armazenado.

Observação

Use o argumento FilterName se você já definiu um filtro que fornece os dados apropriados. Use o argumento WhereCondition para inserir os critérios de restrição diretamente. Se você usar ambos os argumentos, o Microsoft Access aplicará a cláusula WHERE aos resultados do filtro. É preciso usar um ou ambos os argumentos.

Você pode aplicar um filtro ou uma consulta a um formulário no modo de formulário ou no modo de folha de dados.

O filtro e a condição WHERE que você aplica tornam-se a configuração da propriedade Filter do formulário ou da propriedade ServerFilter do relatório.

Quando você salva uma tabela ou formulário, o Access salva qualquer filtro atualmente definido nesse objeto, mas não aplicará o filtro automaticamente na próxima vez que o objeto for aberto (embora ele aplique automaticamente qualquer tipo que você aplicou ao objeto antes de ser salvo).

Para aplicar um filtro automaticamente quando um formulário é aberto pela primeira vez, especifique uma macro contendo a ação ApplyFilter ou um procedimento de evento contendo o método ApplyFilter do objeto DoCmd como a configuração da propriedade de evento OnOpen do formulário. Você também pode aplicar um filtro usando a ação OpenForm ou OpenReport ou os métodos correspondentes. Para aplicar um filtro automaticamente quando uma tabela é aberta pela primeira vez, abra a tabela usando uma macro contendo a ação OpenTable, seguida imediatamente da ação ApplyFilter.

É necessário incluir, pelo menos, um dos dois argumentos do método ApplyFilter. Quando você insere um valor em ambos os argumentos, o argumento WhereCondition é aplicado ao filtro.

O comprimento máximo do argumento WhereCondition é de 32.768 caracteres (ao contrário do argumento da ação Where Condition na janela Macro, cujo comprimento máximo é de 256 caracteres).

Exemplo

O exemplo a seguir usa o método ApplyFilter para exibir apenas registros que contêm o nome "King" no campo LastName .

DoCmd.ApplyFilter , "LastName = 'King'"

O exemplo a seguir mostra como usar a propriedade ApplyFilter para filtrar os registros exibidos quando um botão de alternância chamado tglFilter é escolhido.

Private Sub tglFilter_Click()
    With tglFilter
        If .Value = True Then
            .Caption = "P/T"
            .StatusBarText = "only full-timers"
            DoCmd.ApplyFilter , "[Hours]=40"
        ElseIf .Value = False Then
            .Caption = "All"
            .StatusBarText = "only part-timers"
            DoCmd.ApplyFilter , "[Hours]<40"
        Else
            .Caption = "F/T"
            .StatusBarText = "all employees"
            DoCmd.ShowAllRecords
            .SetFocus 'to activate the button's statusbar-text
        End If
    End With
End Sub

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.