An Introduction to Windows Win32 API Programming

Win32 API Programming

Event-driven, graphics oriented Example: User clicks mouse over a programs window area- Windows decodes HW signals from mouse figures out which window user has selected sends a message to that windows program:
"User has clicked over (X,Y) "Do something and return control to me

Program reads message data, does what's needed, returns control to Windows
(C) Richard R. Eckert (C) Richard R. Eckert

Overview of Win32 API Program Structure--2 main tasks:

Initial activities Process messages from Windows (the message loop)

(C) Richard R. Eckert

(C) Richard R. Eckert

PSEUDOCODE
Initialize variables, memory space Create & show program's Window Loop
Fetch any msg sent from Windows to this pgm If message is QUIT
terminate program, return control to Windows

Essential Parts of a Windows Pgm

I. The source program (.c/.cpp file):
A. WinMain() function
0. declarations, initialization, etc. 1. register window class 2. create a window based on a registered class 3. show window, make it update its client area 4. the message loop (get messages from Windows, dispatch back to Windows for forwarding to correct callback message-processing function)

If message is something else

take actions based on message & parameters return control to Windows

End Loop
(C) Richard R. Eckert

B. WndProc(): the msg-processing function.

(C) Richard R. Eckert

 II. The resource script (.rc file):

contains resource (Windows static) data separate from code and dynamic data compiled by a separate "Resource Compiler Examples:
Keyboard Accelerators, Bitmaps, Cursors, Dialog Box specs, Fonts, Icons, Menus, String Tables

Example Program
See Windows Program: winapp2.cpp

Separation of resources and program code==>

reduced memory demands separates tasks of programmer & designer can change user interface w/o touching code
(C) Richard R. Eckert (C) Richard R. Eckert

The WinMain() Function

int PASCAL WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpszCmdLine, int nCmdShow); WinMain() starts first int exit code returned to Windows PASCAL l-to-r parameter passing on stack 4 parameters passed in from Windows
hInstance: a handle, identifies current pgm instance lpszCmdLine: string containing command line args nCmdShow: how window is to appear when shown (C) Richard R. Eckert

Hungarian Notation
help clarify variable types precede name with key letters representing type named after Hungarian Microsoft programmer, Charles Simonyi

(C) Richard R. Eckert

prefix data type --------------------------------by BYTE (unsigned char) b BOOL (int, TRUE=1 FALSE=0) c char dw DWORD (4-byte unsigned long) fn function h handle l long (4 bytes) n short (int) near pointer p pointer sz null-terminated char string w word (two bytes) lpsz long ptr to null-terminated str
(C) Richard R. Eckert

RegisterClass(&wndclass);
typedef struct tagWNDCLASS { UINT style; LRESULT CALLBACK lpfnWndProc)(); int cbClsExtra; int cbWndExtra; HINSTANCE hInstance; HICON hIcon; HCURSOR hCursor; HBRUSH hBackground; LPSTR lpszMenuName LPSTR lpszClassName } WNDCLASS; if (!RegisterClass (&wndclass)) return 0;

Sets general properties(C) of all windows based on class Richard R. Eckert

CreateWindow() arguments:
window class name window caption window style (OR of style masks) initial x , y position in pixels initial width , height parent window handle (if main window, NULL) window menu handle (NULL if class menu used) program instance handle (passed in from Windows) creation parameters (for extra data, usually NULL)
(C) Richard R. Eckert

ShowWindow (hWnd,nCmdShow);
makes window visible on screen hWnd: which window to make visible nCmdShow: how (normal, minimized, etc.)
set by Windows environment when program is started; value is passed in from Windows; "normal" can be overridden

(C) Richard R. Eckert

UpdateWindow (hWnd);
Causes client area to be updated Painted with background brush

The Message Loop

User interaction-->a msg sent to a window Lots of other actions-->messages A message structure:
HWND hwnd; // target window handle UINT message; // msg ID value--WM_*** WPARAM wParam; // data passed in msg LPARAM lParam; // more data in msg DWORD time; // time msg was sent POINT pt; // mouse cursor position (x,y)

(C) Richard R. Eckert

(C) Richard R. Eckert

GetMessage()
Program must keep checking for messages Use message loop with GetMessage() BOOL GetMessage( LPMSG lpMsg, //ptr to msg struct HWND hWnd, //target window UINT wMsg1, //1st msg in range UINT wMsg2, //last msg in range)
(C) Richard R. Eckert

GetMessage()
Reads next msg from app's msg queue Fills MSG struct pointed to by first param. Place in a loop:
while (GetMessage(&msg, NULL, 0, 0)) { ... } return(msg.wParam);

Returns non-0, except for WM_QUIT msg Terminates msg loop & returns control to Windows
(C) Richard R. Eckert

Message Processing
What goes inside the message loop:
TranslateMessage (&msg)-"Cooks" keyboard input Converts raw key codes to ANSI codes

DispatchMessage (&msg)-Sends message on to Windows, which forwards it to program's "Window Procedure": WndProc()-2nd member of WNDCLASS structure Programmer must write this function
(C) Richard R. Eckert (C) Richard R. Eckert

The Window Procedure

"callback" function (called by Windows) Should contain a switch/case statement :
Looks at message ID of current message Acts appropriately on "interesting" messages Forwards other messages to default Window procedure--DefWindowProc()

WndProc()
LRESULT CALLBACK WndProc ( HWND hWnd, UINT wMessage, WPARAM wParam, LPARAM lParam) Parameters-Same as first four fields of MSG structure:
window associated with message message ID (what message is) message data (wParam & lParam)

(C) Richard R. Eckert

(C) Richard R. Eckert

The WM_DESTROY Message

Sent when user does something to kill window WndProc() should respond by calling:
PostQuitMessage();

Windows sends WM_QUIT msg to queue wParam = 0 implies:

0 returned by GetMessage() in WinMain() so program exits WinMain()'s message loop and return to Windows
(C) Richard R. Eckert (C) Richard R. Eckert

<Check out Winapp1.cpp code>

(C) Richard R. Eckert

(C) Richard R. Eckert

Some other important messages

WM_COMMAND--User clicked on menu item, LOWORD(wParam) = menu item ID WM_*BUTTONDOWN--left/right mouse button pressed (* = L or R, lParam=x,y coordinates) WM_MOUSEMOVE--mouse moved (lParam=x,y coords) WM_CHAR--User pressed valid ANSI code character keyboard key combination (wParam=ANSI code) WM_PAINT--Part of window was exposed & should be redrawn WM_KEYDOWN--keyboard key pressed (wParam= (C) Richard R. Eckert virtual key code)

II. The Resource Script (.rc file)

Resources--static data Example: a menu Defined in a script (.rc) file-#include "resource.h" MYMENU MENU BEGIN MENUITEM "&Circle", IDM_CIRCLE MENUITEM "&Rectangle", IDM_RECTANGLE MENUITEM "Clear &Screen", IDM_CLEAR MENUITEM "&Quit", IDM_QUIT END (C) Richard R. Eckert

The Resource header (.h file)

// resource.h #define IDM_CIRCLE #define IDM_RECTANGLE #define IDM_CLEAR #define IDM_QUIT 40006 40007 40008 40009

Key idea with menus:

when menu item is selected
Windows sends a WM_COMMAND msg low word of wParam=selected item ID extract with macro LOWORD() then do switch/case on LOWORD(wParam) to perform correct action

Must be #included in .CPP & .RC files Can use Dev Studio's resource editors to prepare .rc & .h files visually
ID numbers generated automatically (C) Richard R. Eckert

(C) Richard R. Eckert

TEXT AND GRAPHICS OUTPUT

Displaying something in a window Text & graphics done one pixel at a time Any size/shape/position possible Design goal: Device Independence
Same program works with different HW Windows takes care of HW interface Programmer concentrates on program
(C) Richard R. Eckert

Device Independent Graphics Interface

Windows programs dont access hardware devices directly Make calls to generic drawing functions within the Windows Graphics Device Interface (GDI) -- a DLL The GDI translates these into HW commands

Program

GDI
(C) Richard R. Eckert

Hardware

Device Independent Graphics Interface

n

Device Context
Windows programs dont draw directly on HW, but on a Device Context (DC)
Abstracts the device it represents Like a painters canvas Specifies drawing attribute settings
e.g., text color

May use device drivers (HW control programs)

Program
n n

GDI

Driver

Hardware

Thus graphics I/O done in a standard way Programs will run unaltered on other HW platforms

Contains drawing objects

e.g., pens, brushes, bitmaps, fonts

Must be obtained/released from Windows

(C) Richard R. Eckert (C) Richard R. Eckert

The DC and the GDI

Some GDI Attribute Settings

ATTRIBUTE DEFAULT FUNCTION ----------------------------------------------------------------Background color white SetBkColor() Background mode OPAQUE SetBkMode() Clipping Region whole surf. SelectClipRgn() Current Position (0,0) MoveToEx() Drawing Mode R2COPYPEN SetROP2() Mapping Mode MM_TEXT SetMapMode() Text Color Black SetTextColor()

(C) Richard R. Eckert

(C) Richard R. Eckert

Some GDI Drawing Objects

Object Default What it is
---------------------------------------------------------------------Bitmap none image object Brush WHITE_BRUSH area fill object Font SYSTEM_FONT text font object Pen BLACK_PEN line-drawing object Color Palette DEFAULT_PALETTE color combinations ----------------------------------------------------------------------

Can be created with GDI functions Must be selected into a DC to be used

(C) Richard R. Eckert

(C) Richard R. Eckert

Colors in Windows
Uses four-byte numbers to represent colors Simplest method--direct color:
typedef DWORD COLORREF; --------------------------------------------------------|0 | Blue (0-255) | Green (0-255) | Red (0-255) | -------------------------------------------------------- MSB=0:
==> RGB color used (default) other bytes specify R, G, B intensities
(C) Richard R. Eckert

RGB() Macro
Specify Red, Green, Blue intensities RGB() generates a COLORREF value can be used in color-setting functions, e.g.
COLORREF cr; cr = RGB (0,0,255); /* blue */

Example usage in a program

SetTextColor(hDC,RGB(255,0,0)); //red text SetBkColor(hDC,RGB(0,0,255)); //blue bkgnd
(C) Richard R. Eckert

A typical sequence with objects:

HPEN hOldP, hNewP; HDC hDC; hDC = GetDC(hWnd); hNewP = CreatePen(PS_SOLID, 3, RGB(0,0,71)); hOldP = (HPEN)SelectObject(hDC, hNewP); // DO SOME DRAWING WITH THE NEW PEN SelectObject(hDC,hOldP); //displace pen from DC DeleteObject(hNewP); //now can be deleted ReleaseDC(hWnd,hDC);
(C) Richard R. Eckert

Some GDI Drawing Primitives

Arc(hDC,x1,y1,x2,y2,xStart,yStart,xEnd,yEnd); Ellipse (hDC, x1,y1,x2,y2); MovetoEx (hDC,x1,y1,lpPoint); LineTo (hDC,x1,y1); Polygon (hDC,points_array,nCount); Polyline (hDC,points_array,nCount); Rectangle (hDC,x1,y1,x2,y2); SetPixel (hDC,x1,y1,colref); Many more (see on-line help)
(C) Richard R. Eckert

Stock Objects
Predefined in Windows Obtain with GetStockObject();
gets a handle to a predefined pen/brush/font

Some Stock Objects

Object Choices ----------------------------------------------------Pen Brush BLACK_PEN, WHITE_PEN, NULL_PEN DKGRAY_BRUSH, GRAY_BRUSH, BLACK_BRUSH, LTGRAY_BRUSH, NULL_BRUSH, WHITE_BRUSH ANSI_FIXED_FONT, ANSI_VAR_FONT, DEVICE_DEFAULT_FONT, SYSTEM_FONT, OEM_FIXED_FONT, SYSTEM_FIXED_FONT
(C) Richard R. Eckert

Stock objects are maintained by Windows

should not be deleted!

Example
SelectObject (hDC, GetStockObject(BLACK_PEN));
(C) Richard R. Eckert

Font

The winapp2.cpp application

Details of WndProc()- menu item clicked==>WM_COMMAND msg
wParam==IDM_RECTANGLE ("Rectangle menu item clicked): draw red-outlined rectangle (pen) with solid cyan interior ( brush) wParam==IDM_CIRCLE ("Circle" clicked): draw blue-outlined circle (pen) with crosshatched magenta interior (brush)
(C) Richard R. Eckert

wParam==IDM_CLEAR ("Clear Screen clicked): call InvalidateRect() ==> Windows sends WM_PAINT msg client area needs to be repainted default Window Procedure repaints client area with class background brush effectively erases window's client area

wParam==IDM_QUIT ("Quit clicked):

pgm calls DestroyWindow() causes Windows to destroy window and send a WM_DESTROY msg which causes app to terminate
(C) Richard R. Eckert

left mouse button pressed ==> WM_LBUTTONDOWN msg

get cursors x,y coordinates from lParam
use LOWORD & HIWORD macros output "L" at (x,y) on screen DC with TextOut()

User hits ANSI character keyboard key/s ==> WM_CHAR msg (wParam=char code)
copy character into a buffer output buffer to upper left corner w/TextOut()

right mouse button pressed ==> WM_RBUTTONDOWN msg

output "R at (x,y) on screen DC with TextOut()

User takes action to close window (double clicks on System menu or hits Alt-F4) ==> WM_DESTROY msg
post WM_QUIT msg to app's queue causes program to exit event loop and return control to Windows

(C) Richard R. Eckert

(C) Richard R. Eckert

<Look at Winapp2.cpp listing>

Using Dev Studio to Create a Win32 API application visually

1. create .cpp source file with a text editor
must have: #include resource.h

2. Get into Developer Studio, open a new Workspace, & create an empty Win32 application
File | New | Projects tab | Win32 Application

3. Enter or copy .cpp source file:

File | New | C++ Source and paste in
(C) Richard R. Eckert (C) Richard R. Eckert

4. Create the .rc file using:

File | New | Files Tab | Resource Script Give it the name winapp2.rc

5. SelectInsert | Resource | Menu | New

Brings up menu editor Double click in dotted rectangle on gray menu bar In resulting "Menu Item Properties" box, remove Pop-up check mark Enter ID: IDM_CIRCLE and Caption: &Circle Do same for &Rectangle, Clear &Screen, &Quit menu items (IDs: IDM_RECTANGLE, IDM_CLEAR, and IDM_QUIT)
(C) Richard R. Eckert (C) Richard R. Eckert

6. Minimize Menu Editor box (menu name is IDR_MENU1)

right click on that & click on "Properties" in resulting dialog box brings up "Menu Properties" box change ID to "MYMENU" (must be in quotes)

7. Save your script file (should be called winapp2.rc). 8. Build the project

(C) Richard R. Eckert

(C) Richard R. Eckert