ReplaceTextA-Funktion (commdlg.h)

Artikel
08/22/2023

Erstellt ein systemdefiniertes, modusloses Dialogfeld, in dem der Benutzer eine zu suchende Zeichenfolge und eine Ersatzzeichenfolge sowie Optionen zum Steuern der Such- und Ersetzungsvorgänge angeben kann.

Syntax

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

Parameter

[in, out] unnamedParam1

Typ: LPFINDREPLACE

Ein Zeiger auf eine FINDREPLACE-Struktur , die Informationen enthält, die zum Initialisieren des Dialogfelds verwendet werden. Das Dialogfeld verwendet diese Struktur, um Informationen über die Eingabe des Benutzers an Ihre Anwendung zu senden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Typ: HWND

Wenn die Funktion erfolgreich ist, ist der Rückgabewert das Fensterhandle zum Dialogfeld. Sie können das Fensterhandle verwenden, um mit dem Dialogfeld zu kommunizieren oder es zu schließen.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Rufen Sie zum Abrufen erweiterter Fehlerinformationen die Funktion CommDlgExtendedError auf, die einen der folgenden Fehlercodes zurückgeben kann:

Hinweise

Die ReplaceText-Funktion führt keinen Textersetzungsvorgang aus. Stattdessen sendet das Dialogfeld FINDMSGSTRING-registrierte Nachrichten an die Fensterprozedur des Besitzerfensters des Dialogfelds. Wenn Sie das Dialogfeld erstellen, ist das hwndOwner-Element der FINDREPLACE-Struktur ein Handle für das Besitzerfenster.

Bevor Sie ReplaceText aufrufen, müssen Sie die Funktion RegisterWindowMessage aufrufen, um den Bezeichner für die FINDMSGSTRING-Nachricht abzurufen. Die Dialogfeldprozedur verwendet diesen Bezeichner, um Nachrichten zu senden, wenn der Benutzer auf die Schaltflächen Weiter suchen, Ersetzen oder Alle ersetzen klickt oder wenn das Dialogfeld geschlossen wird. Der lParam-Parameter einer FINDMSGSTRING-Nachricht enthält einen Zeiger auf die FINDREPLACE-Struktur . Das Flags-Element dieser Struktur gibt das Ereignis an, das die Nachricht verursacht hat. Andere Elemente der Struktur geben die Eingabe des Benutzers an.

Wenn Sie ein Dialogfeld Ersetzen erstellen, müssen Sie auch die Funktion IsDialogMessage in der Standard Nachrichtenschleife Ihrer Anwendung verwenden, um sicherzustellen, dass das Dialogfeld Tastatureingaben, z. B. die TAB- und ESC-Tasten, ordnungsgemäß verarbeitet. Die IsDialogMessage-Funktion gibt einen Wert zurück, der angibt, ob das Dialogfeld Ersetzen die Nachricht verarbeitet hat.

Sie können eine FRHookProc-Hookprozedur für ein Dialogfeld Ersetzen bereitstellen. Die Hookprozedur kann Nachrichten verarbeiten, die an das Dialogfeld gesendet werden. Um eine Hookprozedur zu aktivieren, legen Sie das FR_ENABLEHOOK-Flag im Flags-Member der FINDREPLACE-Struktur fest, und geben Sie die Adresse der Hookprozedur im lpfnHook-Element an.

Hinweis

Der commdlg.h-Header definiert ReplaceText als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	commdlg.h (einschließlich Windows.h)
Bibliothek	Comdlg32.lib
DLL	Comdlg32.dll
APIs	ext-ms-win-shell-comdlg32-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)