WinMain
All Windows programs begin execution with a call to WinMain(). WinMain is the Windows equivalent of the C function main() and serves as the primary entry point for any Win32-based application. It contains the code required to initialise and register the application, create and display its main window, and enter the message retrieval and dispatch loop.
The prototype of this function is as follows
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, PWSTR pCmdLine, int nCmdShow);
The four parameters are:
hInstance – A handle to the current instance of the application. The operating system uses this value to identify the executable (EXE) when it is loaded into memory.
hPrevInstance – Used in 16-bit applications to provide a handle to the previous application instance. In a Win32-based application, this parameter is always NULL and has no meaning.
pCmdLine – A pointer to a null-terminated string used to pass command-line parameters to Windows programs.
nCmdShow – A flag that specifies whether the main application window is minimised, maximised, or shown normally.
The function returns an int value. Although the operating system does not utilise this value, it can convey a status code to another program.
Defining and Registering the Windows Class
The Windows class structure WNDCLASSEX contains information relating to the behaviour and appearance of a window. The syntax of the WNDCLASSEX structure is as follows:
typedef struct _WNDCLASSEX
{
UINT cbSize; // size of this structure
UINT style; // style flags (see below)
WNDPROC lpfnWndProc; // function pointer to the windows callback procedure
int cbClsExtra; // extra window-class info (usually 0)
int cbWndExtra; // extra window info (usually 0)
HANDLE hInstance; // the instance of the application
HICON hIcon; // the main icon that will represent the application
HCURSOR hCursor; // the cursor for the window
HBRUSH hbrBackground; // the background brush to paint the window
LPCTSTR lpszMenuName; // the name of the menu to attach if any
LPCTSTR lpszClassName; // the name of the registered class itself
HICON hIconSm; // the handle of the small icon
} WNDCLASSEX;
style – Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. The style can be any combination of the following: CS_BYTEALIGNCLIENT, CS_BYTEALIGNWINDOW, CS_CLASSDC, CS_DBLCLKS, CS_GLOBALCLASS, CS_HREDRAW, CS_NOCLOSE, CS_OWNDC, CS_PARENTDC, CS_SAVEBITS, CS_VREDRAW.
RegisterClassEx – Before a window can be displayed on the screen, it must be registered. RegisterClassEx() takes a single parameter: the address of the WNDCLASS struct. The registered class name is later called in the CreatWindowsEx function.
In addition to the WNDCLASSEX structure, a window can be registered using the deprecated WNDCLASS structure and the associated RegisterClass function. The main difference between the two is that WNDCLASSEX includes a size member and an additional member that specifies a handle to a small icon for the window.
For a more detailed explanation of these styles and options, refer to the following resource:
https://docs.microsoft.com/en-us/windows/win32/api/winuser/ns-winuser-wndclassexw
Windows also provides a standard set of predefined child window classes, which can be used to implement the functionality of common controls.
CreateWindow
A Window is created by a call to the CreateWindowEx() or CreateWindow() function. CreateWindowEx differs from CreateWindow in that it uses an extended window style. The prototype for this function is
HWND CreateWindowEx( DWORD dwExStyle, LPCTSTR lpClassName, LPCTSTR lpWindowName, DWORD dwStyle, int x, int y, int nWidth, int nHeight, HWND hwndParent, HMENU hmenu, HANDLE hinst, LPVOID lpvParam )
The parameter description is as follows –
DWORD dwExStyle – Defines the extended window style. For an in-depth description of extended styles, see:https://docs.microsoft.com/en-gb/windows/win32/winmsg/extended-window-styles
LPCTSTR lpClassName – A pointer to a null-terminated string containing the predefined control class names. The class name can be registered using RegisterClass, or it can be one of the predefined classes used to create child controls.
LPCTSTR lpWindowName – A pointer to a null-terminated string that specifies the window name.
DWORD dwStyle – Indicates the style of window to be created. The style consists of values combined using the | operator. For a full list of styles, see: https://docs.microsoft.com/en-gb/windows/win32/winmsg/window-styles
int x – The horizontal position of the window.
int y – The vertical position of the window.
int nWidth – The width of the window.
int nHeight – The height of the window.
HWND hwndParent – A handle to the parent or owner window. A NULL value is used if there is no parent window.
HMENU hMenu – A handle to the menu, or a child window identifier.
HINSTANCE hInst – A handle to the application instance.
LPVOID lpvParam – A pointer to additional data passed to the window during creation.
The function returns a handle to the new window or NULL if it fails.
Message Loop
A Windows program is event-driven. This means that program flow is determined by a continuous stream of notifications generated by the system or by users, such as a key press, mouse click, or application change. Each of these events is converted into a message. Windows creates a message queue for every running application. The application, in turn, contains a small message loop that retrieves these queued messages and dispatches them back to the window.
Windows, by way of a message handler, then identifies and calls the appropriate window procedure, WndProc(), passing the message as one of its parameters. Each time the application is ready to read a message, it must call the API function GetMessage(). The prototype for the GetMessage function is:
BOOL GetMessage(
LPMSG lpMsg, // point to MSG structure containing message information
HWND hWnd, // specifies for which window messages will be obtained. To receive all messages directed at the application this value must be null.
UINT wMsgFilterMin, // first message
UINT wMsgFilterMax // last message
);
Inside the message loop, there are two functions
Translate message() – This Windows API call translates virtual key codes into messages.
Dispatch message() – Dispatches message back to windows.
What is a Message?
All messages are 16-bit integers of structure type MSG and have the following format –
typedef struct tagMSG{
HWND hwnd;//Identifies the window whose window procedure receives the message.
UINT message;//Specifies the message number.
WPARAM wParam;//Specifies additional information about the message.
LPARAM lParam;//Specifies additional information about the message.
DWORD time; //Specifies the time at which the message was posted.
POINT pt; //Specifies screen coordinates of cursor, when the message was posted.
} MSG;
SendMessage Function
The SendMessage() API function, used throughout the examples on this site, allows specified messages to be sent to a window by directly calling the window procedure associated with that window. The prototype for the SendMessage function is as follows:
LRESULT SendMessage(HWND hWnd,UINT Msg,WPARAM wParam,LPARAM lParam);
where
HWND hWnd – A handle to the window whose window procedure will receive the message. If this parameter is set to HWND_BROADCAST, the message is sent to all top-level windows in the system, including those that are disabled or invisible.
UINT Msg – The message to be sent. For a full list and description of system-provided messages, see: https://docs.microsoft.com/en-gb/windows/win32/winmsg/about-messages-and-message-queues
WPARAM wParam – Holds additional, message-specific information.
LPARAM lParam – Holds additional, message-specific information.
The return value specifies the result of the message processing and will depend on the message sent.
Windows Procedure
The Windows procedure WndProc() is used by a Windows application to process messages until the application is terminated. Each application window must have a WndProc declaration with the return type LRESULT and the calling convention CALLBACK. In Windows, a callback function is any function that is invoked by the operating system.
Although the system generates hundreds of different messages, an application typically needs to filter and process only a small fraction of them. In our simple window, WndProc calls DefWindowProc() to ensure default processing for messages that the application does not handle.
The prototype of WndProc is.
LRESULT CALLBACK WindowProc(HWND hwnd, UINT uMsg,WPARAM wParam, LPARAM lParam );
The four Parameters are-
HWND hwnd – A handle to the window to which the message was sent.
UINT uMsg – Specifies the message.
WPARAM wParam – Specifies additional message-specific information.
LPARAM lParam – Specifies additional message-specific information.