Signatur
Beschreibung
imagegrabwindow() nimmt einen Screenshot eines einzelnen Fensters auf einem Windows-System. Dabei wird das Fenster über sein Handle (HWND) identifiziert, das beispielsweise mit der WinAPI ermittelt werden kann. Die Funktion ist ausschließlich auf Windows verfügbar und steht auf anderen Betriebssystemen nicht zur Verfügung.
Mit dem optionalen Parameter client_area lässt sich steuern, ob nur der Client-Bereich (also der innere Inhalt ohne Titelleiste, Rahmen usw.) oder das gesamte Fenster inklusive Dekorationen erfasst werden soll. Das Ergebnis ist ein GdImage-Objekt, das anschließend wie jedes andere GD-Bild gespeichert, bearbeitet oder ausgegeben werden kann.
Ein typischer Anwendungsfall ist die automatisierte Erzeugung von Bildschirmfotos bestimmter Anwendungsfenster in Windows-Skripten, etwa für Monitoring-, Test- oder Dokumentationszwecke. Das erzeugte Bild kann mit Funktionen wie imagepng(), imagejpeg() oder imagedestroy() weiterverarbeitet werden.
- Die Funktion erfordert, dass PHP unter Windows läuft und das Fenster tatsächlich existiert.
- Das Fenster muss sichtbar sein; verdeckte Bereiche können möglicherweise nicht korrekt erfasst werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handle Pflicht | int | Das Windows-Fenster-Handle (HWND) des zu erfassenden Fensters als Integer-Wert. | |
| $client_area | bool | false | Wenn true, wird nur der Client-Bereich (Fensterinhalt ohne Rahmen und Titelleiste) erfasst. Bei false (Standard) wird das gesamte Fenster inklusive Dekorationen aufgenommen. |
Rückgabewert
GdImage-Objekt zurück, das den Screenshot enthält. Bei einem Fehler (z. B. ungültiges Handle oder nicht unterstütztes Betriebssystem) wird false zurückgegeben.Beispiele
Screenshot eines Fensters anhand seines Handles speichern
<?php
// Beispiel unter Windows: Handle eines Fensters ermitteln und Screenshot erstellen
// Das Handle wird hier als bekannter Wert angenommen (z. B. aus einer WinAPI-Abfrage)
$handle = 0x000A0B2C; // Beispiel-HWND
$screenshot = imagegrabwindow($handle);
if ($screenshot === false) {
echo 'Fehler: Fenster konnte nicht erfasst werden.';
} else {
// Screenshot als PNG speichern
imagepng($screenshot, 'fenster_screenshot.png');
imagedestroy($screenshot);
echo 'Screenshot erfolgreich gespeichert.';
}Nur den Client-Bereich eines Fensters aufnehmen
<?php
// Nur den inneren Bereich (ohne Titelleiste und Rahmen) erfassen
$handle = 0x000A0B2C; // Beispiel-HWND
$clientBild = imagegrabwindow($handle, true);
if ($clientBild !== false) {
// Breite und Höhe des aufgenommenen Bereichs ausgeben
echo 'Breite: ' . imagesx($clientBild) . ' px' . PHP_EOL;
echo 'Höhe: ' . imagesy($clientBild) . ' px' . PHP_EOL;
imagepng($clientBild, 'client_bereich.png');
imagedestroy($clientBild);
} else {
echo 'Fehler beim Erfassen des Client-Bereichs.';
}// Wichtig · Fallstricke
Plattformbeschränkung: imagegrabwindow() ist ausschließlich unter Windows verfügbar. Der Aufruf unter Linux oder macOS führt zu einem fatalen Fehler oder gibt false zurück.
Sichtbarkeit: Das Zielfenster muss auf dem Desktop sichtbar und nicht vollständig von anderen Fenstern verdeckt sein, da andernfalls verdeckte Bereiche im Screenshot möglicherweise schwarz oder unvollständig erscheinen.
Berechtigungen: Unter neueren Windows-Versionen (Vista und höher) können Berechtigungen oder UAC-Einschränkungen das Erfassen bestimmter Fenster (z. B. von Systemdialogen) verhindern.