Função ReplaceTextA (commdlg.h)

Artigo
08/22/2023

Cria uma caixa de diálogo sem formatação definida pelo sistema que permite que o usuário especifique uma cadeia de caracteres para pesquisar e uma cadeia de caracteres de substituição, bem como opções para controlar as operações de localização e substituição.

Sintaxe

HWND ReplaceTextA(
  [in, out] LPFINDREPLACEA unnamedParam1
);

Parâmetros

[in, out] unnamedParam1

Tipo: LPFINDREPLACE

Um ponteiro para uma estrutura FINDREPLACE que contém informações usadas para inicializar a caixa de diálogo. A caixa de diálogo usa essa estrutura para enviar informações sobre a entrada do usuário para seu aplicativo. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

Digite: HWND

Se a função for bem-sucedida, o valor retornado será o identificador de janela para a caixa de diálogo. Você pode usar o identificador de janela para se comunicar com a caixa de diálogo ou fechá-la.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame a função CommDlgExtendedError , que pode retornar um dos seguintes códigos de erro:

Comentários

A função ReplaceText não executa uma operação de substituição de texto. Em vez disso, a caixa de diálogo envia mensagens registradas FINDMSGSTRING para o procedimento de janela da janela proprietário da caixa de diálogo. Quando você cria a caixa de diálogo, o membro hwndOwner da estrutura FINDREPLACE é um identificador para a janela do proprietário.

Antes de chamar ReplaceText, você deve chamar a função RegisterWindowMessage para obter o identificador da mensagem FINDMSGSTRING . O procedimento da caixa de diálogo usa esse identificador para enviar mensagens quando o usuário clica nos botões Localizar Próximo, Substituir ou Substituir Tudo ou quando a caixa de diálogo está fechando. O parâmetro lParam de uma mensagem FINDMSGSTRING contém um ponteiro para a estrutura FINDREPLACE . O membro Flags dessa estrutura indica o evento que causou a mensagem. Outros membros da estrutura indicam a entrada do usuário.

Se você criar uma caixa de diálogo Substituir, também deverá usar a função IsDialogMessage no loop de mensagem main do aplicativo para garantir que a caixa de diálogo processe corretamente a entrada do teclado, como as teclas TAB e ESC. A função IsDialogMessage retorna um valor que indica se a caixa de diálogo Substituir processou a mensagem.

Você pode fornecer um procedimento de gancho FRHookProc para uma caixa de diálogo Substituir . O procedimento de gancho pode processar mensagens enviadas para a caixa de diálogo. Para habilitar um procedimento de gancho, defina o sinalizador FR_ENABLEHOOK no membro Flags da estrutura FINDREPLACE e especifique o endereço do procedimento de gancho no membro lpfnHook .

Observação

O cabeçalho commdlg.h define ReplaceText como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	commdlg.h (inclua Windows.h)
Biblioteca	Comdlg32.lib
DLL	Comdlg32.dll
Conjunto de APIs	ext-ms-win-shell-comdlg32-l1-1-1 (introduzido no Windows 10, versão 10.0.14393)