ReplaceTextA-Funktion (commdlg.h)

Artikel
11/20/2024

Erstellt ein vom System definiertes Dialogfeld ohne Modus, in dem der Benutzer eine zu suchbare Zeichenfolge und eine Ersetzungszeichenfolge 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 für das Dialogfeld. Sie können das Fensterhandle verwenden, um mit dem Dialogfeld zu kommunizieren oder zu schließen.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie zum Abrufen erweiterter Fehlerinformationen die CommDlgExtendedError-Funktion auf, die eine der folgenden Fehlercodes zurückgeben kann:

Bemerkungen

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

Bevor Sie ReplaceText-aufrufen, müssen Sie die RegisterWindowMessage--Funktion 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 "Weitersuchen", "Ersetzen" oder Schaltflächen "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 Mitglied 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 IsDialogMessage--Funktion in der Hauptmeldungsschleife Ihrer Anwendung verwenden, um sicherzustellen, dass das Dialogfeld tastatureingaben ordnungsgemäß verarbeitet, z. B. die TAB- und ESC-Tasten. 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 Hook-Prozedur kann Nachrichten verarbeiten, die an das Dialogfeld gesendet werden. Um eine Hook-Prozedur zu aktivieren, legen Sie das FR_ENABLEHOOK Flag im Flags Member der FINDREPLACE Struktur fest, und geben Sie die Adresse der Hook-Prozedur im lpfnHook Member an.

Anmerkung

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 Code, der nicht codierungsneutral ist, 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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	commdlg.h (enthalten Windows.h)
Library	Comdlg32.lib
DLL-	Comdlg32.dll
API-Satz	ext-ms-win-shell-comdlg32-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)