Co to jest WinAPI Wg Wiki:
Windows API, lub krócej: WinAPI – interfejs programistyczny systemu Microsoft Windows – jest to zbiór niezbędnych funkcji, stałych i zmiennych umożliwiających działanie programu w systemie operacyjnym Microsoft Windows.
Zbiór ten jest bardzo obszerny i zawiera funkcje do tworzenia okien programów, elementów interfejsu graficznego, obsługi zdarzeń oraz umożliwiające dostęp do innych aplikacji, funkcji sieciowych czy sprzętu w komputerze.
Mianem WinAPI określamy standardowe funkcje przychodzące wraz z plikami bibliotek DLL dostarczanymi z systemem, np. kernel32.dll, user32.dll, gdi32.dll, wsock32.dll, znajdującymi się w katalogu \Windows\System.
Funkcje korzystające z WinAPI zawarte są w UDF'ie WinAPI.au3. Jest to największy UDF, ale część zawartych w nim funkcji dubluje funkcje wbudowane interpretera lub innych UDF'ów np.: GDIPlus.au3.
W niniejszym opisie skupię się więc na funkcjach udostępniających nowe możliwości.
Struktury (rekordy) Niektóre funkcje znajdujące się w UDF'ie wykorzystują struktury jako parametry wywołania lub używają ich do zwracania wyników.
Tworzenie takich struktur ułatwia plik StructureConstants.au3, który zawiera predefiniowane stringi z opisem budowy typowych struktur. Nie musimy dołączać go dyrektywą #include, gdyż robi to już sam UDF.
Poniżej przykład tworzenia struktury zawierającej dane o wielkości i położeniu prostokątnego obszaru:
;tworzenie struktury na podstawie stringu $tagRECT ;z biblioteki StructureConstants.au3 $tRect = DllStructCreate($tagRECT)
;nadanie wartości poszczególnym polom struktury DllStructSetData($tRect, "Left", 20) DllStructSetData($tRect, "Top", 50) DllStructSetData($tRect, "Right", 200) DllStructSetData($tRect, "Bottom", 200)
;jeżeli zamiast samej struktury potrzebny jest wskaźnik do niej ;należy dodatkowo użyć funkcji odczytującej ten wskaźnik $ptrRect = DllStructGetPtr($tRect)
;dalsza część progamu
Można też tak, wykorzystując skrócony sposób nadawania wartości pól struktury:
;tworzenie struktury na podstawie stringu $tagRECT ;z biblioteki StructureConstants.au3 $tRect = DllStructCreate($tagRECT)
;nadanie wartości poszczególnym polom struktury (sposób uproszczony) $tRect.Left = 20 $tRect.Top = 50 $tRect.Right = 200 $tRect.Bottom = 200
;dalsza część progamu
Dokładniejszy opis dotyczący struktur i funkcji na nich operujących, w rozdziale Korzystanie z bibliotek DLL.
_WinAPI_PtInRect #include _WinAPI_PtInRect($tRect, $tPoint) Funkcja zwraca True gdy punkt znajduje się wewnątrz prostokątnego obszaru, lub False w przeciwnym przypadku.
$tRect - struktura $tagRECT zawierająca dane o położeniu i wielkości prostokątnego obszaru
$tPoint - struktura $tagPOINT zawierająca współrzędne sprawdzanego punktu
Przykład:
#include
;opis prostokąta $tRect = DllStructCreate($tagRECT) $tRect.Left = 20 $tRect.Top = 50 $tRect.Right = 200 $tRect.Bottom = 200
;współrzędne sprawdzanego punktu $tPoint = DllStructCreate($tagPOINT) $tPoint.X = 120 $tPoint.Y = 120
If _WinAPI_PtInRect($tRect, $tPoint) Then $sTxt = "Punkt wewnątrz prostokąta" Else $sTxt = "Punkt na zewewnątrz prostokąta" EndIf
MsgBox(4096, 'Test PtInRect', $sTxt)
_WinAPI_RectIsEmpty #include _WinAPI_RectIsEmpty($tRect) Funkcja zwraca True gdy struktura opisująca prostokąt zawiera same zera, lub False w przeciwnym przypadku.
$tRect - struktura $tagRECT zawierająca dane o położeniu i wielkości prostokątnego obszaru
Przykład:
#include
;opis prostokąta $tRect = DllStructCreate($tagRECT) DllStructSetData($tRect, "Left", 0) DllStructSetData($tRect, "Top", 0) DllStructSetData($tRect, "Right", 0) DllStructSetData($tRect, "Bottom", 0)
MsgBox(4096, 'RectIsEmpty', _ "Czy prostokąt jest pusty: " & _WinAPI_RectIsEmpty($tRect))
_WinAPI_PointFromRect #include _WinAPI_PointFromRect($tRect [, $fCenter = True]) Funkcja zwraca w postaci struktury $tagPOINT współrzędne środka, lub lewego górnego narożnika prostokątnego obszaru.
$tRect - struktura $tagRECT zawierająca dane o położeniu i wielkości prostokątnego obszaru
$fCenter - jeśli True zwraca punkt środkowy tego prostokąta, jeśli False jego współrzędne lewego górnego narożniku
Przykład:
#include
;opis prostokąta $tRect = DllStructCreate($tagRECT) DllStructSetData($tRect, "Left", 20) DllStructSetData($tRect, "Top", 50) DllStructSetData($tRect, "Right", 200) DllStructSetData($tRect, "Bottom", 200)
$tPoint = _WinAPI_PointFromRect($tRect)
$iX = DllStructGetData($tPoint, 1) $iY = DllStructGetData($tPoint, 2)
MsgBox(4096, "PointFromRect", _ "Punkt środkowy prostokąta:" & @LF & _ "x = " & $iX & @LF & "y = " & $iY)
_WinAPI_GetXYFromPoint #include _WinAPI_GetXYFromPoint($tPoint, ByRef $iX, ByRef $iY) Funkcja zwraca przez referencję współrzędne punktu.
$tPoint - struktura $tagPOINT zawierająca współrzędne punktu
$iX i $iY - zmienne zawierające współrzędne punktu (nadpisywane przez referencję)
Przykład:
#include
Local $iX = 10, $iY = 10
;opis prostokąta $tPoint = DllStructCreate($tagPOINT) DllStructSetData($tPoint, "X", 100) DllStructSetData($tPoint, "Y", 666)
;odczyt współrzędnych (przez referencję) _WinAPI_GetXYFromPoint($tPoint, $iX, $iY)
MsgBox(4096, "GetXYFromPoint", _ "Odczytane współrzędne punktu:" & @LF & _ "x = " & $iX & @LF & "y = " & $iY)
Funkcje związane z kontekstem urządzenia (DC) Wszystkie funkcje graficzne WinAPI operują na kontekstach urządzeń. Podstawowe informacje o kontekstach można znaleźć w rozdziale Funkcje interfejsu GDI+.
Teraz postaram się opisać temat nieco dokładniej, gdyż UDF dostarcza dużej ilości funkcji operujących na kontekstach i głębsze zrozumienie problemu będzie bardzo pomoncne w ich efektywnym wykorzystaniu.
Twórcy Windows postanowili uprościć i ujednolicić operacje graficzne w systemie operacyjnym. Zamiast całej masy przypadków przesyłania informacji pomiędzy obiektami graficznymi (np. desktop -> okno, okno -> okno, okno -> bitmapa ... itd.) postanowili sprowadzić wszystko do jednego schematu: [Kontekst źródłowy] -> [Kontekst docelowy] Konteksty to jednak abstrakcje, same w sobie nie reprezentujące żadnego rzeczywistego obiektu. Dlatego kontekst musi być powiązany z rzeczywistym obiektem. Powiązanie to oznacza, że operacje wykonywane na kontekście będą jednocześnie wykonywane w tle na rzeczywistym obiekcie, bez konieczności zagłębiania się przez programistę w sam przebieg tego procesu. Wymiana informacji między kontekstami przebiega zawsze w ten sam sposób, natomiast przepływ informacji
[obiekt] [kontekst] jest realizowany przez OS bez udziału programisty: [Obiekt źródłowy]-[Kontekst źródłowy] -> [Kontekst docelowy]-[Obiekt docelowy] Oczywiście aby cały proces był możliwy do realizacji, konteksty i obiekty muszą być ze sobą zgodne (kompatybilne), tzn. zdolne do wymiany informacji.
Rozpatrzmy dwa przykłady:
1. Skopiowanie fragmentu desktopu do utworzonego okna GUI:
Mamy do czynienia z dwoma istniejącymi obiektami, które są ze sobą z natury kompatybilne (wszak okno to nic innego jak część desktopu).
Należy więc pobrać z systemu konteksty do obu obiektów (funkcja _WinAPI_GetDC), a następnie przesłać dane z kontekstu desktopu do kontekstu okna.
Prosto i bez wnikania w szczegóły procesu.
Przykładowy kod dla tego przypadku w opisie funkcji _WinAPI_BitBlt.2. Skopiowanie fragmentu desktopu do bitmapy:W tym przypadku istnieje tylko jeden obiekt (desktop), drugi obiekt (bitmapa) należy samodzielnie utworzyć.
Rozpoczynamy od pobrania kontekstu do desktopu (_WinAPI_GetDC), następnie tworzymy nowy kontekst kompatybilny z kontekstem desktopu (_WinAPI_CreateCompatibleDC).
Teraz tworzymy bitmapę kompatybilną z utworzonym kontekstem (_WinAPI_CreateCompatibleBitmap) i tworzymy powiązania pomiędzy kontekstem i bitmapą (_WinAPI_SelectObject).
Mamy teraz powiązanie między desktopem, a bitmapą (poprzez kompatybilne konteksty) i możemy przesłać dane obrazu.
Przykładowy kod dla tego przypadku w opisie funkcji _WinAPI_CreateCompatibleBitmap.
_WinAPI_GetDC #include _WinAPI_GetDC($hWnd) Funkcja odczytuje i zwraca kontekst do obszaru roboczego okna, lub 0 gdy wystąpił błąd.$hWnd - uchwyt do okna
Zwolnienie kontekstu za pomocą funkcji #_WinAPI_ReleaseDC.
Przykład:
#Include
$hWnd = GUICreate ("Test") $hDC = _WinAPI_GetDC($hWnd) MsgBox (0, "", "Uchwyt DC: " & $hDC) _WinAPI_ReleaseDC ($hWnd, $hDC)
_WinAPI_GetWindowDC #include _WinAPI_GetWindowDC($hWnd) Funkcja odczytuje i zwraca kontekst do całego okna, lub 0 gdy wystąpił błąd.$hWnd - uchwyt do okna, jeżeli wstawimy 0 to będzie to oznaczało cały ekran (desktop).
Zwolnienie kontekstu za pomocą funkcji _WinAPI_ReleaseDC .
Przykład:
#Include
$hWnd = GUICreate ("Test") $hDC = _WinAPI_GetWindowDC($hWnd) MsgBox (0, "", "Uchwyt DC: " & $hDC) _WinAPI_ReleaseDC ($hWnd, $hDC)
_WinAPI_CreateCompatibleDC #include _WinAPI_CreateCompatibleDC($hDC) Funkcja tworzy kontekst zgodny z istniejącym kontekstem urządzenia. Zwraca uchwyt do tego kontekstu, lub 0 gdy wystąpił błąd.$hDC - uchwyt do istniejącego kontekstu DC
Likwidacja kontekstu za pomocą funkcji _WinAPI_DeleteDC .
_WinAPI_DeleteDC #include _WinAPI_DeleteDC($hDC) Funkcja likwiduje kontekst. Zwraca True gdy sukces, lub False gdy wystąpił błąd.$hDC - uchwyt do kontekstu DC
Funkcji należy używać do usunięcia kontekstów utworzonych w skrypcie (_WinAPI_CreateCompatibleDC), a już nie wykorzystywanych, celem zwolnienia zasobów.
_WinAPI_ReleaseDC #include _WinAPI_ReleaseDC($hWnd, $hDC) Funkcja zwalnia wcześniej pobrany kontekst. Zwraca True gdy sukces, lub False gdy wystąpił błąd.$hWnd - uchwyt do okna$hDC - uchwyt do kontekstu DC
Funkcji należy używać do zwolnienia kontekstów pobranych w skrypcie (_WinAPI_GetDC lub _WinAPI_GetWindowDC), a już nie wykorzystywanych, celem zwolnienia zasobów.
_WinAPI_SelectObject #include _WinAPI_SelectObject($hDC, $hGDIObj) Funkcja przypisuje obiekt do określonego kontekstu urządzenia. Zwraca uchwyt do pierwotnego obiektu (tego który był poprzednio przypisany do kontekstu), lub liczbę ujemną gdy wystąpił błąd.
Obiekt musi być jednego z następujących typów: Bitmap, Brush, Font, Pen lub Region.$hDC - uchwyt do kontekstu DC$hGDIObj - uchwyt do przypisywanego obiektu
Przykład:
#include #include
;odczytanie kontekstu do desktopu $hDC = _WinAPI_GetWindowDC(0)
;tworzenie piór $hPen1 = _WinAPI_CreatePen($PS_SOLID, 12, 0x0000FF) $hPen2 = _WinAPI_CreatePen($PS_SOLID, 20, 0x00FF00)
;przypisanie pióra 1 do kontekstu _WinAPI_SelectObject($hDC, $hPen1) ;rysowanie linni w kontekście _WinAPI_DrawLine($hDC, 400, 500, 800, 700)
;przypisanie pióra 2 do kontekstu $hOld = _WinAPI_SelectObject($hDC, $hPen2) ;rysowanie linni w kontekście _WinAPI_DrawLine($hDC, 400, 700, 800, 400)
Sleep(5000)
;jeżeli chcemy wrócić do poprzedniego przypisania _WinAPI_SelectObject($hDC, $hOld)
;zwolnienie zasobów _WinAPI_DeleteObject($hPen1) _WinAPI_DeleteObject($hPen2) _WinAPI_ReleaseDC(0, $hDC)
_WinAPI_DeleteObject #include _WinAPI_DeleteObject ( $hObject ) Funkcja usuwa logiczne, obiekty takie jak pióro, pędzel, czcionka, bitmapa, region lub paleta. Zwraca True gdy sukces, lub False gdy wystąpił błąd.$hObject - uchwyt do usuwanego obiektu
_WinAPI_BitBlt #include _WinAPI_BitBlt($hDestDC, $iXDest, $iYDest, $iWidth, $iHeight, $hSrcDC, $iXSrc, $iYSrc, $iROP) Funkcja kopiuje blok grafiki pomiędzy dwoma kontekstami urządzeń. Zwraca True gdy sukces, lub False gdy wystąpił błąd.$hDestDC - uchwyt do kontekstu docelowego$iXDest i $iYDest - współrzędne lewego górnego narożnika wstawianego bloku w kontekście docelowym$iWidth i $iHeight - szerokość i wysokość kopiowanego bloku$hSrcDC - uchwyt do kontekstu źródłowego$iXSrc i $iYSrc - współrzędne lewego górnego narożnika kopiowanego bloku w kontekście źródłowym$iROP - kod operacji. Kody te określają, w jaki sposób dane kolorowego prostokątnego bloku kopiowanego z kontekstu źródłowego zostaną połączone z kolorami znajdującymi się w prostokącie docelowym: