GUI Elements API
This section provides documentation for the Windows API functions related to creating and managing graphical user interfaces (GUIs).
Window Management
CreateWindowEx
Creates an overlapping, top-level window. It includes an extended window style parameter for more advanced window features.
HWND CreateWindowEx(
DWORD dwExStyle,
LPCTSTR lpClassName,
LPCTSTR lpWindowName,
DWORD dwStyle,
int x,
int y,
int nWidth,
int nHeight,
HWND hWndParent,
HMENU hMenu,
HINSTANCE hInstance,
LPVOID lpParam
);
Parameters
dwExStyle: Extended window styles.lpClassName: Registered class name.lpWindowName: Window text.dwStyle: Window styles.x: Horizontal position.y: Vertical position.nWidth: Width.nHeight: Height.hWndParent: Handle to the parent window.hMenu: Handle to a menu or child-window identifier.hInstance: Handle to the application instance.lpParam: Pointer to window-creation data.
Return Value
- If the function succeeds, the return value is the handle to the new window.
- If the function fails, the return value is NULL.
Remarks
This is a fundamental function for creating any window in a Windows application. It allows for customization through extended styles and standard styles.
Example
// Pseudo-code example:
HWND hWnd = CreateWindowEx(
0, // dwExStyle
L"MyWindowClass", // lpClassName
L"My Application Window", // lpWindowName
WS_OVERLAPPEDWINDOW,
CW_USEDEFAULT, CW_USEDEFAULT,
500, 300,
NULL, // hWndParent
NULL, // hMenu
hInstance,
NULL // lpParam
);
Message Handling
DefWindowProc
Calls the default window procedure to provide default processing for any window messages that a window procedure has not processed.
LRESULT DefWindowProc(
HWND hWnd,
UINT Msg,
WPARAM wParam,
LPARAM lParam
);
Parameters
hWnd: Handle to the window procedure.Msg: Message identifier.wParam: Additional message information.lParam: Additional message information.
Return Value
- The return value is the result of the message processing and depends on the message sent.
Remarks
Every window procedure must call DefWindowProc to process messages that it does not handle itself. This ensures that standard window behavior is maintained.
Drawing and Updates
InvalidateRect
Adds the specified rectangle to the update region of the specified window. The update region consists of all invalid areas of the client area of a window.
BOOL InvalidateRect(
HWND hWnd,
const RECT *lpRect,
BOOL bErase
);
Parameters
hWnd: Handle to the window to be repainted.lpRect: Pointer to a RECT structure that specifies the portion of the client area to be updated. If NULL, the entire client area is added to the update region.bErase: Specifies whether the background is to be erased.
Return Value
- If the function succeeds, the return value is TRUE.
- If the function fails, the return value is FALSE.
Remarks
Call this function when a part of your window needs to be redrawn. The system will send a WM_PAINT message to the window when it is appropriate to draw.
GDI Interaction
BeginPaint
Prepares the specified window for painting and fills the PAINTSTRUCT structure that is returned by the function.
PAINTSTRUCT PAINTSTRUCT(
HWND hWnd
);
Parameters
hWnd: Handle to the window to be painted.
Return Value
- If the function succeeds, the return value is an HDC (handle to a device context) for the specified window.
- If the function fails, the return value is NULL.
Remarks
This function should only be called once per paint cycle, typically in response to a WM_PAINT message. It must be paired with EndPaint.
EndPaint
Completes a paint cycle started by a call to the BeginPaint function. It validates the update region.
VOID EndPaint(
HWND hWnd,
const PAINTSTRUCT *lpPaint
);
Parameters
hWnd: Handle to the window that was painted.lpPaint: Pointer to the PAINTSTRUCT structure returned by a previous call toBeginPaint.
Return Value
This function does not return a value.
Remarks
It is important to call EndPaint after drawing operations to inform the system that painting is complete and that the window's update region can be cleared.