REFERENCE GUIDE
BORLAND
Windows API Guide
Reference Volume 1
Version 3.0
for the MS-DOS and PC-DOS Operating Systems
BORLAND INTERNATIONAL INC. 1800 GREEN HILLS ROAD P.O. BOX 660001, scons VALLEY, CA 95067-0001
Copyright 1991, Borland International. All rights reserved.
Copyright © 1991 by Borland International. All rights reserved. All Borland products are trademarks or registered trademarks of Borland International, Inc. Other brand and product names are trademarks or registered trademarks of their respective holders.
c o N T
Introduction 1
Windows features . . . .. 1
Window manager interface ... 2
Window manager interface function groups ... 3
Graphics device interface ... 3
Graphics device interface function groups ... 3
System services interface . . . .. 4
System services interface function groups ... 4
Naming conventions ... 4
Parameter names ... 5
Windows calling convention ... 5
Manual overview ... 6
Volume 1 ... 6
Volume2 ... 7
Document conventions ... 8
Other recommended reading ... 10
Windows functions ... 10
Part 1 Windows functions Chapter 1 Window manager interface functions 13 Message functions ... 14
Generating and processing messages . 15 Translating messages ... 16
Examining messages ... 17
Sending messages . . . .. 17
Avoiding message deadlocks ... 18
Window-creation functions. . . .. 19
Window classes . . . .. 20
System global classes ... 20
Application global classes ... 21
Application local classes ... 21
E N T s
How Windows locates a class. . . .. 21How Windows determines the owner of a class ... 22
Registering a Window class ... 22
Shared Window classes . . . .. 22
Predefined Window classes ... 22
Elements of a Window class ... 23
Class name . . . .. 24
Window-function address . . . .. 24
Instance handle ... 24
Class cursor . . . .. 25
Class icon ... 25
Class background brush ... 25
Class menu ... 26
Class styles ... 27
Internal data structures ... 28
Window subclassing ... 28
Redrawing the client area ... 29
Class and private display contexts .... 29
Window function ... 30
Window messages ... 32
Default window function ... 33
Window styles ... 34
Overlapped windows ... 34
Owned windows ... 35
Pop-up windows ... 35
Child windows ... 35
Multiple document interface windows. 37 Title bar ... 38
System menu . . . .. 38
Scroll bars ... 38
Menus ... 38
Window state ... 40
Life cycle of a window . . . .. 40
Display and movement functions ... 42
Input functions ... 43
Hard ware functions . . . .. 43
Painting functions ... 44
How Windows manages the display .. 45
Display context types . . . .. 46
Common display context. . . .. 46
Class display context ... 47
Private display context ... 48
Window display context ... 49
Display-context cache ... 49
Painting sequence ... 50
WM_P AINT message. . . .. 50
Update region .. . . .. 51
Window background . . . .. 52
Brush alignment ... 52
Painting rectangular areas . . . .. 53
Drawing icons . . . .. 53
Drawing formatted text . . . .. 54
Drawing gray text . . . .. 56
Nonclient-area painting ... 57
Dialog box functions ... 57
Uses for dialog boxes ... 59
Modeless dialog box . . . .. 59
Modal dialog box ... 59
System-modal dialog box ... 60
Creating a dialog box ... 60
Dialog box template ... 60
Dialog box measurements ... 61
Return values from a dialog box ... 61
Controls in a dialog box. . . .. 62
Control identifiers ... 62
General control styles. . . .. 62
Buttons ... 63
Edit controls ... 64
List boxes and directory listings . . .. 64
Combo boxes . . . .. 65
Owner-draw dialog box controls ... 65
Messages for dialog box controls ... 66
Dialog box keyboard interface ... 66
Scrolling in dialog boxes ... 68
Scrolling functions ... 68
Standard scroll bars and scroll-bar controls . . . .. 68
Scroll-bar thumb . . . .. 69
Scrolling requests ... 70
Processing scroll messages ... 70
Scrolling the client area ... 71
Hiding a standard scroll bar . . . .. 71
Menu functions . . . .. 72
Information functions ... 73
System functions . . . .. 73
Clipboard functions ... 74
Error functions ... 74
Caret functions ... 75
Creating and displaying a caret ... 75
Sharing the caret ... 76
Cursor functions ... 76
Pointing devices and the cursor .. . . .. 77
Displaying and hiding the cursor .... 77
Positioning the cursor ... 78
The cursor hotspot and confining the cursor ... 78
Creating a custom cursor ... 78
Hook functions ... 79
Filter-function chain . . . .. 79
Installing a filter function ... 80
Property functions ... 80
Using property lists ... 81
Rectangle functions ... 82
Using rectangles in a Windows application ... 83
Rectangle coordinates ... 83
Creating and manipulating rectangles. 84 Chapter 2 Graphics device interface functions 87 Device-context functions . . . .. 88
Device-context attributes ... 88 Saving a device context ... . Deleting a device context ... . Compatible device contexts ... . Information contexts ... . Drawing-tool functions ... . Drawing-tool uses ... . Brushes ... . Pens ... .
90 90 90 90 91 92 92 93
Color ... 93
Color-palette functions ... 95
How color palettes work . . . .. 96
U sing a color palette . . . .. 98
Drawing-attribute functions ... 99
Background mode and color . . . .. 99
Stretch mode ... 100
Text color ... 100
Mapping functions ... 100
Constrained mapping modes ... 102
Partially constrained and unconstrained mapping modes ... 102
Partially constrained mapping mode ... 103
Unconstrained mapping mode .... 103
Transformation equations ... 103
Example: MM_TEXT ... 104
Example: MM_LOENCLISH ... 105
Coordinate functions ... 105
Region functions . . . .. 106
Clipping functions ... 106
Line-output functions ... 107
Function coordinates ... 108
Pen styles, colors, widths. . . .. 108
Ellipse and polygon functions ... 109
Function coordinates ... 109
Bounding rectangles . . . .. 110
Bitmap functions. . . .. 110
Bitmaps and devices. . . .. 111
Device-independent bitmap functions ... 111
Text functions ... 112
Font functions ... 112
Font family ... 114
Character cells ... 115
Altering characters . . . .. 116
Italic ... 116
Bold ... 116
Underline. . . .. 116
Strikeout. . . .. 116
Leading ... 116
Internal leading . . . .. 117
Externalleading ... 117
iii Character set ... 117
ANSI character set ... 118
OEM character set ... 118
Symbol character set ... 118
Vendor-specific character sets .... 118
Pitch ... 118
Average character width ... 119
Maximum character width ... 119
Digitized aspect ... 119
Overhang ... 119
Selecting fonts with CDI ... 120
Font-mapping scheme ... 120
Example of font selection ... 123
Font files and font resources ... 124
Metafile functions . . . .. 124
Creating a metafile ... 125
Storing a metafile in memory or on disk. . . .. 126
Deleting a metafile ... 127
Changing how Windows plays a metafile. . . .. 127
Printer-control functions ... 127
Printer-escape function ... 128
Creating output on a printer ... 128
Banding output ... 129
Starting and ending a print job ... 130
Terminating a print job ... 130
Information escapes. . . .. 130
Additional escape calls ... 131
Environment functions ... 131
Chapter 3 System services interface functions 133 Module-management functions ... 134
Memory-management functions ... 134
Segment functions ... 136
Operating-system interrupt functions .. 137
Task functions. . . .. 138
Resource-management functions ... 138
String-manipulation functions ... 139
Atom-management functions . . . .. 140
Initialization-file functions ... 141
Communication functions ... 142
Sound functions ... . Utility macros and functions ... . File 1/ 0 functions ... . Debugging functions ... . Optimization-tool functions ... . Application-execution functions ... . Chapter 4 Functions directory AccessResource ... . AddAtom ... . AddFontResource ... , AdjustWindowRect ... . AdjustWindowRectEx ... . AllocDStoCSAlias ... . AllocResource ... . AllocSelector ... . AnimatePalette ... . AnsiLower ... . AnsiLowerBuff ... . AnsiNext
AnsiPrev ... . AnsiToOem ... . AnsiToOemBuff ... . AnsiUpper ... . AnsiUpperBuff ... . AnyPopup ... . AppendMenu ... . AppendMenu ... . Arc ... . ArrangeIconicWindows ... , BeginDeferWindowPos ... . BeginPaint ... . BitBlt ... . BringWindowToTop ... . )ki3uildCommDCB ... . CallMsgFilter ... . CallWindowProc ... . Catch ... . ChangeClipboardChain ... . ChangeMenu ... . ChangeSelector ... . CheckDIgButton ... . CheckMenuItem ... .
142 143 144 144 145 145 147 147 148 148 149 150 150 151 152 152 153 153 154 154 154 155 155 156 156 156 157 159 160 160 161 162 164 164 165 166 166 167 167 168 168 169
CheckRadioButton ... . ChildWindowFromPoint ... . Chord ... . +€learCommBreak ... . ClientToScreen ... . ClipCursor ... . CloseClipboard ... . i(CloseComm ... . CloseMetaFile ... . CloseSound ... . Close Window ... . CombineRgn ... . CopyMetaFile ... . CopyRect ... . CountClipboardFormats ... . CountVoiceNotes ... . CreateBitmap ... . CreateBitmapIndirect ... . CreateBrushIndirect ... . Crea teCaret ... . CreateCompatibleBitmap ... . CreateCompatibleDC ... . Create Cursor ... . CreateDC ... . Create Dialog ... . Callback function ... . CreateDialogIndirect ... . Callback function ... . Crea teDialogIndirectParam ... . CreateDialogParam ... . CreateDIBitmap ... . CreateDIBPatternBrush ... . CreateDiscardableBitmap ... . CreateEllipticRgn ... . CreateEllipticRgnIndirect ... . CreateFont ... . CreateFontIndirect ... . CreateHatchBrush ... . CreateIC ... . Createlcon ... . CreateMenu ... , ... " ..
CreateMetaFile ... . CreatePalette ... .
170 171 171 172 172 173 173 174 174 174 175 175 176 176 177 177 177 178 179 179 180 181 182 182 183 184 185 186 187 188 189 190 191 192 192 193 195 196 196 197 198 198 199
CreatePatternBrush ... 199
CreatePen ... 200
CreatePenlndirect ... " 200 CreatePolygonRgn ... " 201 CreatePolyPolygonRgn ... 201
CreatePopupMenu ... , .. " ... " 202 CreateRectRgn ... " 203 CreateRectRgnlndirect ... 203
CreateRoundRectRgn ... " ... " 204 CreateSolidBrush ... 204
CreateVVindovv ... 205
CreateVVindovvEx ... 218
DebugBreak ... " 219 DefDlgProc ... 220
DeferVVindovvPos ... 221
DefFrameProc ... 222
DefHookProc ... " 224 DefineHandleTable ... 224
DefMDIChildProc ... 225
DefVVindovvProc ... 226
DeleteAtom ... " 227 DeleteDC ... 227
DeleteMenu . . . .. 228
DeleteMetaFile ... 229
DeleteObject ... 229
DestroyCaret ... " 230 DestroyCursor ... " 230 Destroylcon ... 230
DestroyMenu ... , ... 231
DestroyVVindovv ... 231
DeviceCa pabilities ... 232
DeviceMode ... 235
DialogBox ... 235
Callback Function ... " 236 DialogBoxlndirect ... " 237 Callback Function . . . .. 238
DialogBoxlndirectParam ... " 239 DialogBoxParam ... " 239 DispatchMessage ... 240
DlgDirList ... 241
DlgDirListComboBox ... 242
DlgDirSelect ... 244
DlgDirSelectComboBox ... " 244 v DOS3Call ... 245
DPtoLP ... 246
DravvFocusRect ... , ... 247
DravvIcon . . . .. 247
DravvMenuBar ... 248
DravvText . . . .. 248
Ellipse. . . .. 251
EmptyClipboard . . . .. 252
EnableHardvvarelnput . . . .. 252
EnableMenuItem ... 253
EnableVVindovv ... 254
EndDeferVVindovvPos ... 254
End Dialog ... 255
EndPaint ... 255
EnumChildVVindovvs . . . .. 256
Callback function ... 257
EnumClipboardFormats ... 257
EnumFonts ... 258
Callback function ... 258
EnumMetaFile . . . .. 260
Callback function ... 260
EnumObjects ... , 261
Callback function ... 262
EnumProps ... 262
Fixed data segments. . . .. 263
Callback function ... 263
Moveable data segments . . . .. 264
Callback function ... 264
EnumTaskVVindovvs . . . .. 265
Callback function ... 265
Enum VVindovvs . . . .. 266
Callback function ... 266
EqualRect . . . .. 267
EqualRgn ... 267
Escape ... 268
A(EscapeCommFunction ... , 269
ExcludeClipRect ... 269
ExcludeUpdateRgn ... 270
ExitVVindovvs . . . .. 271
ExtDeviceMode . . . .. 271
ExtFloodFill . . . .. 273
ExtTextOut ... 274
FatalAppExit . . . .. 276
FatalExit ... 276
FillRect ... . . . .. 277
FillRgn ... 278
FindAtom . . . .. 278
FindResource . . . .. 278
FindWindow . . . .. 280
Flash Window ... 280
FloodFill ... 281
\?<,FlushComm . . . .. 282
_FPlnit ... 282
_FPTerm ... 283
FrameRect ... 283
FrameRgn ... 284
FreeLibrary ... 284
FreeModule ... 285
FreeProcInstance . . . .. 285
FreeResource . . . .. 285
FreeSelector . . . .. 286
GetActiveWindow ... 286
GetAspectRatioFilter ... 287
GetAsyncKeyState ... 287
GetAtomHandle . . . .. 287
GetAtomName ... 288
GetBitmapBits . . . .. 288
GetBitmapDimension ... 289
GetBkColor ... 289
GetBkMode ... 289
GetBrush()rg . . . .. 290
GetBValue ... 290
GetCapture ... 290
GetCaretBlinkTime . . . .. 291
GetCaretPos . . . .. 291
GetCharWidth . . . .. 291
GetClasslnfo ... 292
GetClassLong ... 293
GetClassN ame . . . .. 294
GetClassWord ... . . . .. 294
GetClientRect ... 295
GetClipboardData ... 295
GetClipboardFormatName ... 296
GetClipboard()wner ... 297
GetClipboardViewer ... 297
GetClipBox ... 297
GetCodeHandle ... 298
GetCodelnfo ... 298
I
GetCommError . . . .. 300-fGetCommEventMask . . . .. 301
7GetCommState ... 301
GetCurrentPDB . . . .. 302
GetCurrentPosition ... 302
GetCurrentTask ... 302
GetCurrentTime ... 303
GetCursorPos ... 303
GetDC ... 303
GetDC()rg ... 304
GetDesktopWindow ... 304
GetDeviceCaps ... 305
GetDialogBaseUnits ... 308
GetDIBits ... 309
GetDIgCtrlID . . . .. 310
GetDIgItem ... 310
GetDIgItemlnt . . . .. 311
GetDIgItemText ... 312
GetD()SEnvironment . . . .. 312
GetDoubleClickTime ... 313
GetDriveType ... 313
GetEnvironment ... 313
GetFocus ... 314
GetFreeSpace ... 315
GetGValue ... 316
GetInputState ... 316
GetInstanceData ... 316
GetKBCodePage ... 317
GetKeyboardState ... 317
GetKeyboardType ... 318
GetKeyNameText . . . .. 319
GetKeyState . . . .. 320
GetLastActivePopup ... 320
GetMapMode ... 321
GetMenu ... 321
GetMenuCheckMarkDimensions ... 321
GetMenuItemCount . . . .. 322
GetMenuItemID ... 322
GetMenuState ... 322
GetMenuString ... 323
GetMessage ... , 324
Get~essagePos ... 326
Get~essageTime ... 326
Get~etaFile . . . .. 327
Get~etaFileBits ... , 327
Get~oduleFileName ... 327
Get~oduleHandle ... 328
Get~oduleUsage ... 328
GetNearestColor ... 329
GetN earestPaletteIndex ... , 329
GetNextDlgGroupltem ... 329
GetNextDlgTabltem . . . .. 330
GetN extWindow . . . .. 330
GetNumTasks ... . . . .. 331
GetObject . . . .. 331
GetPaletteEntries ... 332
GetParent ... 333
GetPixel ... 333
GetPolyFill~ode ... 334
GetPriorityClipboardFormat ... 334
GetPrivateProfileInt ... 335
GetPrivateProfileString ... 336
GetProcAddress ... 337
GetProfileInt ... 338
GetProfileString ... 338
GetProp ... 340
GetRgnBox . . . .. 340
GetROP2 ... 341
GetRValue ... 341
GetScrollPos ... 341
GetScrollRange ... 342
GetStockObject ... 343
GetStretchBlt~ode . . . .. 344
GetSub~enu ... 345
GetSysColor . . . .. 345
GetSys~odalWindow ... 345
GetSystemDirectory . . . .. 346
GetSystem~enu ... 346
GetSystem~etrics . . . .. 347
GetSystemPaletteEntries ... 349
GetSystemPaletteUse ... 349
GetTabbedTextExtent ... 350
GetTempDrive ... 351
GetTempFileName . . . .. 351
GetTextAlign ... " 352 GetTextCharacterExtra ... 354
GetTextColor ... " 354 GetTextExtent ., ... " 354 GetTextFace ... " 355 GetText~etrics ... 355
GetThresholdEvent ... 356
GetThresholdStatus ... 356
GetTickCount ... 356
GetTopWindow ... 357
GetUpdateRect ... 357
GetUpdateRgn ... 358
GetVersion ... " 359 GetViewportExt ... 359
GetViewportOrg ... " 359 GetWindow ... " 360 GetWindowDC ... " 360 GetWindowExt ... " ... " 361 GetWindowLong ... 361
GetWindowOrg ... 362
GetWindowRect ... 362
GetWindowsDirectory ... " 363 GetWindowTask ... 363
GetWindowText ... " 364 GetWindowTextLength ... " 364 GetWindowWord ... " 365 GetWinFlags ... 365
GlobalAddAtom ... " 366 GlobalAlloc ... 367
GlobalCompact . . . .. 368
GlobalDeleteAtom ... 369
GlobalDiscard ... 369
GlobalDosAlloc . . . .. 370
GlobalDosFree ... 370
GlobalFindAtom ... " 371 GlobalFix ... 371
GlobalFlags ... 372
GlobalFree .. . . .. 372
GlobalGetAtomName ... 373
GlobalHandle ... 373
GlobalLock ... 374
GlobalLRUN ewest ... . . . .. 374 GlobalLRUOldest ... " 375
vii
GlobalNotify ... 375
Callback function ... 376
GlobalPageLock ... 376
GlobalPageUnlock ... 377
GlobalReAlloc . . . .. 377
GlobalSize ... 379
GlobalUnfix ... 379
GlobalUnlock ... 380
GlobalUn Wire . . . .. 381
GlobalWire ... 381
GrayString .. . . .. 382
Callback function ... 383
HI BYTE ... 384
HideCaret ... 385
HiliteMenuItem ... 385
HIWORD ... 386
InflateRect ... 386
InitAtomTable ... 387
InSendMessage ... 387
InsertMenu ... 388
IntersectClipRect . . . .. 391
IntersectRect ... 392
InvalidateRect . . . .. 392
InvalidateRgn ... 393
InvertRect ... 394
InvertRgn . . . .. 394
IsCharAlpha ... 395
IsCharAlphaNumeric . . . .. 395
IsCharLo~er ... 395
IsCharUpper ... 396
IsChild ... 396
IsClipboardFormatAvailable . . . .. 396
IsDialogMessage . . . .. 397
IsDIgButtonChecked ... 398
IsIconic . . . .. 398
IsRectEmpty ... 398
Is Windo~ ... 399
IsWindo~Enabled ... 399
IsWindo~Visible ... 399
IsZoomed . . . .. 400
KillTimer ... 400
_lclose . . . .. 401
_lcreat . . . .. 401
LimitEmsPages ... . . . .. 402
LineDDA ... 402
Callback function ... 403
LineTo ... 403
_llseek . . . .. 404
LoadAccelerators ... 404
LoadBitmap . . . .. 405
LoadCursor ... 406
LoadIcon ... 407
LoadLibrary . . . .. 408
LoadMenu . . . .. 409
LoadMenuIndirect ... 410
LoadModule ... 410
LoadResource ... 412
LoadString . . . .. 412
LOBYTE ... 413
LocalAlloc ... 413
LocalCompact ... 414
LocalD~card ... 415
LocalFlags ... 415
LocalFree ... 416
LocalHandle ... 416
Locallnit . . . .. 416
LocaILock ... 417
LocalReAlloc . . . .. 417
LocalShrink ... 419
LocalSize ... 420
LocalUnlock ... 420
LockData ... 420
LockResource ... 421
LockSegment ... 421
_lopen ... 422
LOWORD ... 423
LPtoDP ... 424
_lread ... 424
lstrcat ... 425
lstrcmp ... 425
lstrcmpi ... 426
lstrcpy . . . .. 426
lstrlen ... 427
_l~rite ... 427
MAKEINTATOM ... 428
MAKEINTRESOURCE ... 429
MAKELONG . . . .. 429
MAKE POINT ... 429
MakeProcInstance ... 429
MapDialogRect ... 430
MapVirtualKey ... 431
max ... 432
MessageBeep . . . .. 432
MessageBox . . . .. 432
min ... 434
ModifyMenu ... 435
MoveTo ... 438
MoveVVindovv ... 438
MulDiv ... 439
NetBIOSCall ... 440
OemKeyScan ... 440
Oem ToAnsi ... . . . .. 441
OemToAnsiBuff ... 442
OffsetClipRgn ... 442
OffsetRect . . . .. 443
OffsetRgn . . . .. 443
OffsetVievvportOrg ... 444
OffsetVVindovvOrg ... 444
OpenClipboard ... 445
f
OpenComm . . . .. 445OpenFile . . . .. 446
OpenIcon . . . .. 449
OpenSound ... 449
OutputDebugString ... 449
PaintRgn ... 450
P ALETTEINDEX ... 450
P ALETTERGB . . . .. 450
PatBlt ... 451
PeekMessage ... 452
Pie ... 454
PlayMetaFile ... 455
PlayMetaFileRecord ... 455
Polygon ... 456
Polyline ... 456
PolyPolygon ... 457
PostAppMessage ... 458
PostMessage ... 458
PostQuitMessage ... 459
Prof Clear ... 459
ix ProfFinish ... 460
ProfFlush ... . . . .. 460
ProfInsChk . . . .. 460
ProfSampRate ... 461
Prof Setup ... 462
Prof Start ... 462
Prof Stop . . . .. 462
PtInRect ... 463
PtInRegion . . . .. 463
PtVisible . . . .. 463
(<ReadComm ... 464
RealizePalette ... 465
Rectangle ... 465
RectInRegion . . . .. 466
RectVisible . . . .. 466
RegisterClass ... 467
Callback function ... 467
RegisterClipboardFormat ... 468
RegisterVVindovvMessage ... 468
ReleaseCapture ... 469
ReleaseDC ... 469
RemoveFontResource ... 470
RemoveMenu ... 470
RemoveProp ... 471
ReplyMessage ... 472
ResizePalette ... 473
RestoreDC ... 473
RGB ... 474
RoundRect . . . .. 474
SaveDC ... 476
ScaleVievvportExt ... 476
ScaleVVindovvExt ... 477
ScreenToClient ... 477
ScrollDC . . . .. 478
ScrollVVindovv . . . .. 479
SelectClipRgn ... 480
SelectObject ... 481
SelectPalette ... 483
SendDlgItemMessage ... 483
SendMessage ... 484
SetActiveVVindovv ... 485
SetBitmapBits ... 485
SetBitmapDimension ... 486
SetBkColor . . . .. 486
SetBkMode . . . .. 487
SetBrushOrg ... 487
SetCa pture . . . .. 488
SetCaretBlinkTime ... 488
SetCaretPos ... 488
SetClassLong ... 489
SetClass Word ... 490
SetClipboardData . . . .. 491
SetClipboardViewer . . . .. 493
1
SetCornmBreak .. . . .. 494t
SetCornmEventMask ... 494"f-.SetCornmState ... 495
SetCursor . . . .. 495
SetCursorPos ... 496
SetDIBits . . . .. 496
SetDIBitsToDevice ... 498
SetDlgItemlnt ... 499
SetDlgItemText . . . .. 500
SetDoubleClickTime ... 500
SetEnvironment ... 501
SetErrorMode ... 501
SetFocus ... 502
SetHandleCount ... . .. 502
SetKeyboardState ... 503
Set~ap~ode ... 503
Set~apperFlags ... 505
Set~enu . . . .. 505
Set~enuItemBitmaps . . . .. 506
Set~essageQueue . . . .. 507
Set~etaFileBits ... 507
SetPaletteEntries . . . .. 508
SetParent ... 508
SetPixel . . . .. 509
SetPolyFill~ode ... 509
SetProp . . . .. 510
SetRect ... 511
SetRectEmpty ... 511
SetRectRgn . . . .. 512
SetResourceHandler ... 512
Callback function ... 513
SetROP2 .. . . .. 514
SetScrollPos . . . .. 515
SetScrollRange ... 516
SetSoundNoise ... 516
SetStretchBlt~ode ... 517
SetSwapAreaSize ... 518
SetSysColors ... 519
SetSys~odalWindow . . . .. 520
SetSystemPaletteUse ... 520
SetTextAlign ... 522
SetTextCharacterExtra ... 523
SetTextColor ... 523
SetTextJustification . . . .. 524
SetTimer ... 525
Callback function ... 526
SetViewportExt ... 526
SetViewportOrg ... 527
SetVoiceAccent ... 528
SetVoiceEnvelope . . . .. 529
Set V oiceN ote . . . .. 530
SetVoiceQueueSize . . . .. 531
Set V oiceSound ... 531
SetVoiceThreshold ... 532
SetWindowExt ... 532
SetWindowLong ... 533
SetWindowOrg . . . .. 534
SetWindowPos ... 535
SetWindowsHook . . . .. 536
WH_CALLWNDPROC ... 538
WH_GET~ESSAGE ... 539
WH-10URNALPLAYBACK . . . . .. 540
WH-10URNALRECORD ... 541
WH_KEYBOARD . . . .. 542
WH_~SGFILTER . . . .. 543
WH_SYS~SGFILTER ... 544
SetWindowText ... 545
SetWindowWord ... 545
ShowCaret . . . .. 546
ShowCursor ... 546
ShowOwnedPopups ... 547
ShowScrollBar . . . .. 547
ShowWindow ... 548
SizeofResource ... 549
StartSound . . . .. 549
Stop Sound ... 550
StretchBlt ... . StretchDIBits ... . SwapMouseButton ... . SwapRecording ... . SwitchStackBack ... . SwitchStackTo ... . SyncAllV oices ... . TabbedTextOut ... . TextOut ... . Throw ... . ToAscii ... . TrackPopupMenu ... . TranslateAccelerator ... . TranslateMDISysAccel ... . TranslateMessage ... .
"J4rransmitCommChar ... . )!UngetCommChar ... . UnhookWindowsHook ... . UnionRect ... . UnlockData ... . U nlockResource ... . UnlockSegment ... . UnrealizeObject ... . UnregisterClass ... . UpdateColors ... . UpdateWindow ... . ValidateCodeSegments ... . ValidateFreeSpaces ... . ValidateRect ... . Valida teRgn ... . VkKeyScan ... . WaitMessage ... . WaitSoundState ... . WindowFromPoint ... . WinExec ... . WinHelp ... . -+WriteComm ... . WritePrivateProfileString ... . WriteProfileString ... . wsprintf ... . wvsprintf ... . Yield ... .
550 552 554 554 555 555 556 556 557 558 559 560 560 562 562 563 563 564 565 565 565 566 566 567 568 568 568 569 569 570 570 571 572 572 573 574 576 577 578 579 581 583
xi
Part 2 Windows messages
Chapter 5 Messages overview 587
Window-management messages ... 587
Initialization messages ... 589
Inputmessages ... 589
System messages ... 590
Clipboard messages . . . .. 591
System information messages ... 592
Control messages ... 592
Button-control messages ... 593
Edit-control messages ... 593
List-box messages. . . .. 594
Combo-box messages. . . .. 595
Owner draw-control messages . . . . .. 596
Notification messages ... 597
Button notification codes ... 597
Edit-control notification codes ... 597
List-box notification codes ... 598
Combo-box notification codes ... 598
Scroll-bar messages ... 598
Nonclient-area messages ... 598
Multiple document interface messages. 600 Chapter 6 Messages directory 601 BM_GETCHECK ... 603
BM_ GETSTATE ... 603
BM_SETCHECK . . . .. 603
BM_SETSTATE ... 604
BM_SETSTYLE ... 604
BN_CLICKED ... 605
BN_DOUBLECLICKED . . . .. 606
CB_ADDSTRING ... . . . .. 606
CB_DELETESTRING ... 606
CB_DIR ... 607
CB _FIND STRING . . . .. 607
CB_GETCOUNT ... 608
CB _ GETCURSEL ... 608
CB _ GETEDITSEL . . . .. 608
CB_GETITEMDATA ... 609
CB_ GETLBTEXT . . . .. 609
CB _ GETLBTEXTLEN . . . .. 609
CB_INSERTSTRING ... 610
CB _LIMITTEXT ... 610
CB_RESETCONTENT ... 610
CB_SELECTSTRING ... 611
CB_SETCURSEL . .. . . .. . . .. .. . . .. 611
CB_SETEDITSEL ... 612
CB_SETITEMDATA ... 612
CB_SHOWDROPDOWN ... 612
CBN_DBLCLK ... 613
CBN_DROPDOWN ... 613
CBN_EDITCHANGE . . . .. 613
CBN_EDITUPDATE ... 614
CBN_ERRSPACE ... 614
CBN_KILLFOCUS ... 614
CBN_SELCHANGE ... 615
CBN_SETFOCUS ... 615
DM_GETDEFID ... 615
DM_SETDEFID .. . .. . . .. .. ... 615
EM_CANUNDO ... 616
EM_EMPTYUNDOBUFFER .. . . .. 616
EM_FMTLINES .. .. . .. . .. . .. . .. . .. .. 616
EM_GETHANDLE ... 617
EM_GETLINE ... 617
EM_GETLINECOUNT ... 617
EM_GETMODIFY. . . .. 618
EM_GETRECT ... 618
EM_GETSEL ... 618
EM_LIMITTEXT ... " 618 EM_LINEFROMCHAR ... 619
EM_LINE INDEX ... 619
EM_LINELENGTH ... 619
EM_LINESCROLL ... 620
EM_REPLACESEL ... 620
EM_SETHANDLE ... 620
EM_SETMODIFY ... " 621 EM_SETPASSWORDCHAR ... 621
EM_SETRECT ... " 621 EM_SETRECTNP ... 622
EM_SETSEL . . . .. 622
EM_SETTABSTOPS ... ; ... 622
EM_SETWORDBREAK . . . .. 623
Callback Function . . . .. 623
EM_UNDO ... 624
EN_CHANGE ... 624
EN_ERRSP ACE. . . .. . .. . . .. 625
EN_HSCROLL ... 625
EN_KILLFOCUS .. . .. .. . . . .. . .. . . ... 625
EN_MAXTEXT ... . . .. 626
EN_SETFOCUS ... 626
EN_UPDATE ... 626
EN_ VSCROLL . . . .. 627
LB_ADDSTRING ... 627
LB_DELETESTRING ... 627
LB_DIR ... 628
LB_FINDSTRING . . . .. 628
LB_GETCARETINDEX ... 629
LB_GETCOUNT ... 629
LB_GETCURSEL ... 629
LB_GETHORIZONTALEXTENT ... 630
LB_GETITEMDATA ... 630
LB_GETITEMHEIGHT ... 630
LB_GETITEMRECT ... 631
LB_GETSEL . . . .. 631
LB_ GETSELCOUNT ... 631
LB_GETSELITEMS ... 631
LB_ GETTEXT ... 632
LB_ GETTEXTLEN ... 632
LB_GETTOPINDEX ... 632
LB_INSERTSTRING ... 633
LB_RESETCONTENT ... 633
LB_SELECTSTRING ... 633
LB_SELITEMRANGE ... 634
LB_SETCARETINDEX ... 634
LB_SETCOLUMNWIDTH ... 635
LB_SETCURSEL ... 635
LB_SETHORIZONTALEXTENT ... 635
LB_SETITEMDATA " ... 636
LB_SETITEMHEIGHT ... 636
LB_SETSEL ... 636
LB_SETTABSTOPS ... 637
LB_SETTOPINDEX ... 637
LBN_DBLCLK ... 638
LBN_ERRSP ACE ... 638
LBN_KILLFOCUS ... 638
LBN_SELCHANGE ... 639
LBN_SETFOCUS ... 639
WM_ACTIVATE ... 639
WM_ACTIVATEAPP ... 640
WM_ASKCBFORMATNAME ... 640
WM_CANCELMODE ... 641
WM_CHANGECBCHAIN ... 641
WM_CHAR ... 641
WM_CHARTOITEM ... 642
WM_CHILDACTIVATE ... 643
WM_CLEAR ... 643
WM_CLOSE ... 643
WM_COMMAND ... 644
WM_COMPACTING ... 644
WM_COMPAREITEM ... 645
WM_COPY ... 645
WM_CREATE ... 646
WM_CTLCOLOR ... 646
WM_CUT ... 647
WM_DEADCHAR . . . .. 647
WM_DELETEITEM ... 648
WM_DESTROY . . . .. 648
WM_DESTROYCLIPBOARD . . . .. 649
WM_DEVMODECHANGE ... 649
WM_DRAWCLIPBOARD ... 649
WM_DRAWITEM ... 650
WM_ENABLE .. .. .. .. . . .. . . .. 650
WM_ENDSESSION ... 650
WM_ENTERIDLE . . . .. 651
WM_ERASEBKGND ... 651
WM_FONTCHANGE ... 652
WM_GETDLGCODE ., ... 652
WM_GETFONT ... 653
WM_GETMINMAXINFO ... 653
WM_GETTEXT ... 654
WM_GETTEXTLENGTH ... 654
WM_HSCROLL ... 655
WM_HSCROLLCLIPBOARD . . . .. 656
WM_ICONERASEBKGND . . . .. 656
WM_INITDIALOG .. . . .. . . ... 657
WM_INITMENU ... 657
WM_INITMENUPOPUP ... 658
WM_KEYDOWN ... 658
WM_KEYUP ... 659
WM_KILLFOCUS . . . .. . . .. . . .. 660
WM_LBUTTONDBLCLK ... 660
WM_LBUTTONDOWN ... 661
xiii WM_LBUTTONUP ... 661
WM_MBUTTONDBLCLK ... 662
WM_MBUTTONDOWN . . . .. 662
WM_MBUTTONUP . . . .. 663
WM_MDIACTIVATE ... 663
WM_MDICASCADE ... 664
WM_MDICREATE ... 664
WM_MDIDESTROY ... 665
WM_MDIGETACTIVE ... 665
WM_MDIICONARRANGE ... 666
WM_MDIMAXIMIZE ... 666
WM_MDINEXT ... 666
WM_MDIRESTORE . . . .. 667
WM_MDISETMENU ... 667
WM_MDITILE ... 667
WM_MEASUREITEM ... . . .. 668
WM_MENUCHAR .. .. .. . . .. 668
WM_MENUSELECT ... 669
WM_MOUSEACTIVATE ... 669
WM_MOUSEMOVE ... 670
WM_MOVE . . . .. .. . . .. .. .. 671
WM_NCACTIVATE ... 671
WM_NCCALCSIZE . . . .. 671
WM_NCCREATE ... 672
WM_NCDESTROY ... 672
WM_NCHITTEST ... 672
WM_NCLBUTTONDBLCLK ... 673
WM_NCLBUTTONDOWN ... 674
WM_NCLBUTTONUP ... 674
WM_NCMBUTTONDBLCLK ... 674
WM_NCMBUTTONDOWN . . . .. 675
WM_NCMBUTTONUP . . . .. 675
WM_NCMOUSEMOVE ... 675
WM_NCPAINT ... 676
WM_NCRBUTTONDBLCLK . . . .. 676
WM_NCRBUTTONDOWN ... 676
WM_NCRBUTTONUP ... 677
WM_NEXTDLGCTL ... 677
WM_P AINT ... 677
WM_PAINTCLIPBOARD ... 678
WM_PAINTICON ... 678
WM_PALETTECHANGED ... 679
WM_PARENTNOTIFY ... 679
WM_P ASTE . . . .. 680
WM_QUERYDRAGICON ... 680
WM_QUERYENDSESSION ... 681
WM_QUERYNEWPALETTE ... 681
WM_QUERYOPEN ... 681
WM_QUIT ... 682
WM_RBUTTONDBLCLK ... 682
WM_RBUTTONDOWN ... 682
WM_RBUTTONUP ... 683
WM_RENDERALLFORMATS ... 683
WM_RENDERFORMAT ... 684
WM_SETCURSOR ... 684
WM_SETFOCUS . . . .. 684
WM_SETFONT . . . .. 685
WM_SETREDRAW ... 685
WM_SETTEXT ... 686
WM_SHOWWINDOW ... 686
WM_SIZE ... 687
WM_SIZECLIPBOARD . . . .. 687
WM_SPOOLERSTATUS ... 688
WM_SYSCHAR ... 688
WM_SYSCOLORCHANGE ... 689
WM_SYSCOMMAND ... . . .. 690
WM_SYSDEADCHAR . . . .. 691
WM_SYSKEYDOWN . . . .. 691
WM_SYSKEYUP . . . .. 693
WM_TIMECHANGE ... 694
WM_TIMER ... 694
WM_UNDO ... 695
WM_ VKEYTOITEM . . . .. 695
WM_ VSCROLL . . . .. 695
WM_ VSCROLLCLIPBOARD .. . . .. 696
WM_WININICHANGE ... 697
Index 699
T A B L E s
0.1: Standard prefixes ... 5 4.4: Control styles ... 211
0.2: Document conventions ... 8 4.5: Extended window styles ... 219
0.3: Windows API guide ... 9 4.6: DOS file attributes ... 242
1.1: Window class elements ... 23 4.7: DrawText formats ... 250
1.2: Window class styles ... 27 4.8: Communications error codes ... 300
1.3: Default actions for messages ... 33 4.9: CDI information indexes ... 305
1.4: Defaults for a display context ... 46 4.1 0: System metric indexes ... 348
1.5: Drawing format styles ... 54 4.11: Message box types ... 433
1.6: Control characters and actions ... 55 4.12: Raster operations ... 452
1.7: Dialog box controls ... 65 4.13: Predefined data formats ... 492
1.8: Dialog box keyboard interface ... 67 4.14: Event values ... 494
2.1: Default device-context attributes and 4.15: Mapping modes ... 504
related CDI functions ... 89 4.16: Drawing modes ... 514
2.2: Font-mapping characteristics ... 121 4.17: System color indexes ... 519
4.1: Raster operations ... 163 4.18: Window states ... 548
4.2: Control classes ... 207 6.1: Button styles ... 604
4.3: Window styles ... 209 6.2: Hit-test codes ... 673
xv
F G u
1.1: Caret shapes ... 76
1.2: Property list ... 81
1.3: Rectangle limits ... 84
1.4: Intersection of two rectangles ... 85
1.5: Union of two rectangles ... 85
2.1: Information flow to an output device .88 2.2: Hatched brush patterns ... 92
2.3: Pen patterns ... 93
2.4: Palette manager color-mapping algorithm ... 97
2.5: Mapping with MM_TEXT ... 104
2.6: Mapping with MM_LOENGLISH ... 105
R E s
2.7: Arc and its bounding rectangle ... 1082.8: Styled-Pen and Solid-Pen Rectangles ... 109
2.9: Fonts from two typefaces ... 113
2.1 0: Cross-stroke and stem ... 114
2.11: Serifs ... 114
2.12: Character-cell dimensions ... 115
2.13: Strikeout characters ... 116
2.14: Internal leading ... 117
2.15: External leading ... 117
2.16: A GDI font table ... 120
2.17: Sample font selection ratings ... 123
N T R
o
Du c
To
NThis manual describes the application programming interface (API) of the Microsoft® Windows™ presentation manager. The API contains the functions, messages, data structures, data types, statements, and files that application developers use to create programs that run with Windows.
The API can be thought of as a set of tools which, when properly used, creates a Windows application that is portable across a variety of computers.
Windows features
Introduction
A Windows application can take advantage of a number of features provided by the API. These features include the following:
Il Shared display, memory, keyboard, mouse, and system timer
III Data interchange with other applications
1:1 Device-independent graphics c Multitasking
c Dynamic linking
Windows allows applications, running simultaneously on the system, to share hardware resources; application developers do not need to write specific code to accomplish this complex task.
The clipboard, another Windows feature, acts as a place for data interchange between applications. The information sent between applications can be in the form of text, bitmaps, or graphic operations. Windows provides a number of functions and messages that regulate the transmission of information with the clipboard. These functions and the corresponding messages are part of the window manager interface, one of several libraries in the API.
Window manager interface
Windows contains functions that an application can use for device-independent graphic operations. These functions create output that is compatible with raster displays and printers of varying resolution, as well as with a number of vector devices (plotters). These functions are part of the graphics device interface (GDI), the second of the API libraries.
Windows provides multitasking, which means that several applications can run simultaneously. The functions that affect multitasking and memory management in general are part of the system services interface, the third API library.
Because of the memory limitations imposed by DOS, it is
important to keep applications as compact as possible. Windows accomplishes this compaction through dynamic linking and the use of discardable code, which allows an application to load and execute a subset of the library of functions at run time. Only a single copy of a library is necessary, no matter how many applications access it.
The window manager interface contains the functions that create, move, and alter a window, the most basic element in a Windows application. A window is a rectangular region that contains graphic representations of user input, input options, and system output.
Windows is a menu-driven environment; menus are the principal means of presenting options to a user from within an application.
The functions that create menus, alter their contents, and obtain the status of menu items are also part of the window manager interface.
The window manager interface also contains functions that create system output. An example of this output is the dialog box that applications use to request user input and to display information.
The window manager interface also contains messages and the functions that process them. A message is a special data structure that contains information about changes within an application.
These changes include keyboard, mouse, and timer events, as well as requests for information or actions that an application should carry out.
Window manager interface function groups
Graphics device interface
Graphics device interface function groups
Introduction
The following list describes the function groups found in the window manager interface:
[J Message functions
[J Information functions
[J Window-creation functions
[J System functions
[J Display and movement functions
[J Clipboard functions
[J Error functions
J:I Input functions
[J Caret functions
[J Hardware functions
[J Cursor functions
[J Painting functions
[J Hook functions
[J Dialog functions
[J Property functions
[J Scrolling functions
[J Rectangle functions
[J Menu functions
The graphics device interface (CD!) contains the functions that perform device-independent graphic operations within a Windows application. These functions create a wide variety of line, text, and bitmap output on a number of different output devices. CDI allows an application to create pens, brushes, fonts, and bitmaps for specific output operations.
The following list describes the function groups found in CDI:
[J Device-context functions
[J Ellipse and polygon functions
[J Drawing-tool functions
[J Bitmap functions
[J Drawing-attribute functions
[J Text functions
[J Mapping functions c Font functions
[J Coordinate functions
3
• Metafile functions .. Region functions
• Printer-escape functions
• Clipping functions
• Environment functions
• Line-output functions
• System functions
System services interface
System seNices interface function groups
Naming conventions
The system services interface contains the functions that access code and data in modules, allocate and manage memory (both local and global), manage tasks, load program resources, translate strings from one character set to another, alter the Windows initialization file, assist in system debugging, carry out
communications through the system's I/O ports, create and open files, and create sounds using the system's sound generator.
The following list describes the function groups found in the system services interface:
.. Module-management functions
• Initialization-file functions
• Memory-management functions
• Communication functions
• Task functions
1:1 Sound functions
• Resource-management functions .. Utility functions
.. String-translation functions
• File I/O functions
.. Atom-management functions .. System functions
Many Windows functions have been named with a verb-noun model to help you remember and become familiar with the function. The function name indicates both what the function does (verb) and the target of its action (noun). All function names begin with an uppercase letter. If the name is composed of several words, each word begins with an uppercase letter and all words
are adjoined (no spaces or underscore characters separate the words). Some examples of function names are shown below:
Il CreateWindow
Il RegisterClass
1:1 SetMapMode
Parameter names Most parameters and local variables have a lowercase prefix that indicates the general type of the parameter, followed by one or more words that describe the content of the parameter. The standard prefixes used in parameter and variable names are defined below:
Table 0.1
Standard prefixes Prefix Meaning b
c dw
Boolean (a nonzero value means true, zero means false) Character (a one-byte value)
Windows calling convention
Introduction
f
h 1 lp n P pt rgb wLong (32-bit) unsigned integer Bit flags packed into a 16-bit integer 16-bit handle
Long (32-bit) integer Long (32-bit) pointer Short (16-bit) integer Short (16-bit) pointer
x-and y-coordinates packed into an unsigned 32-bit integer
RGB color value packed into a 32-bit integer Short (16-bit) unsigned integer
If no lowercase prefix is given, the parameter is a short integer whose name is descriptive.
Some examples of parameter and variable names are shown as follows:
blconic ptXY fAction rgbColor hWnd Height
IpString X nBytes Width pMsg Y
Windows uses the same calling convention used by Microsoft Pascal. Throughout this manual, this calling convention will be referred to as the Pascal calling convention. The Pascal calling convention entails the following:
5
Manual overview
• Parameters are pushed onto the stack in the order in which they appear in the function call.
• The code that restores the stack is part of the called function (rather than the calling function).
This convention differs from the calling convention used in other languages, such as C. In C, parameters are pushed onto the stack in reverse order, and the calling function is responsible for restoring the stack.
When developing Windows applications in a language that does not ordinarily use the Pascal calling convention, such as C, you must ensure that the Pascal calling convention is used for any function that is called by Windows. In C, this requires the use of the PASCAL key word when the function is declared.
This manual gives the Windows-application developer general as well as detailed information about Windows functions, messages, data types, resource-compiler statements, assembly-language macros, and file formats. It does not attempt to explain how to create a Windows application. Rather, this manual provides detailed descriptions of each component of the Windows API for readers who already have a basic understanding of Windows programming.
This manual is divided into two volumes. The following sections describe the purpose and contents of each volume.
Volume 1 Volume 1 contains reference information describing the Windows functions and messages. It is made up of six chapters:
Chapter 1, "Window manager interface functions, II categorizes window-manager functions into their related groups and briefly describes individual functions. This chapter also supplies additional information about particular function groups, including definitions of new terms and descriptions of models that are unique to Windows. This chapter is designed to assist the application developer who is new to Windows or who has questions about a particular group of Windows functions.
Chapter 2, "Graphics device interface functions, II categorizes the functions that perform device-independent graphics operations in the Windows environment, provides brief descriptions of the
Introduction
functions, and explains the most important features of the Windows graphics interface.
Chapter 3, "System services interface functions, II categorizes the various utility functions that perform services not directly related to managing a window or producing graphical output.
Chapter 4, "Functions directory," contains an alphabetical list of Windows functions. The documentation for each function gives the syntax, states the function's purpose, lists its input parameters, and describes its return value. For some functions, additional information the developer needs in order to use those functions is given.
Chapter 5, "Messages overview," categorizes messages into their related groups and briefly describes individual messages. This chapter also supplies additional information about particular message groups, including definitions of new terms and
descriptions of models that are unique to Windows. This chapter is designed to assist the application developer who is new to Windows or who has questions about a particular group of Windows messages.
Chapter 6, "Messages directory," contains an alphabetical list of Windows messages. The documentation for each message states the message's purpose, lists its input parameters, and describes its return value (if one exists). For some messages, additional
information the developer needs in order to use those messages is given.
Volume 2 Volume 2 contains reference material for other components of the Windows APLIt contains nine chapters and three appendixes:
Chapter 7, II Data types and structures," contains a table of data types and an alphabetical list of structures found in Windows.
Chapter 8, "Resource script statements, II describes the statements that define resources which the Resource Compiler adds to an application's executable file. The statements are arranged according to functional groups.
Chapter 9, II File formats," describes the formats of five types of files: bitmap files, icon resource files, cursor resource files, clipboard files, and metafiles. Each description gives the general file structure and information about specific parts of the file.
7
Chapter 10, "Module-definition statements," describes the statements contained in the module-definition file that defines the application's contents and system requirements for the LINK program.
Chapter 11, "Binary and ternary raster-operation codes, II describes the raster operations used for line output and those used for bitmap output.
Chapter 12, "Printer escapes," lists the printer escapes that are available in Windows.
Chapter 13, "Windows DDE protocol definition," contains an alphabetical listing and description of the Windows messages which comprise the Windows Dynamic Data Exchange protocol.
Appendix A, "Virtual-key codes, II lists the symbolic names and hexadecimal values of Windows virtual-key codes and includes a brief description of each key.
Appendix B, II RC diagnostic messages, II contains a listing of Resource Compiler error messages and provides a brief description of each message.
Document conventions Throughout this manual, the term "DOS" refers to both MS-DOS®
and PC-DOS, except when noting features that are unique to one or the other.
Table 0.2 Document conventions
The following document conventions are used throughout this manual:
Convention Bold text
()
Italic text
Description of Convention
Bold letters indicate a specific term or punctuation mark intended to be used literally: language key words or functions (such as EXETYPE or CreateWindow), DOS commands, and command-line options (such as /Zi). You must type these terms and punctuation marks exactly as shown.
However, the use of uppercase or lowercase letters is not always significant. For instance, you can invoke the linker by typing either LINK, link, or Link at the DOS prompt.
In syntax statements, parentheses enclose one or more parameters that you pass to a function.
Words in italics indicate a placeholder; you are expected to provide the actual value. For example, the following syntax for the
Table 0.3 Windows API guide
Introduction
Table 0.2: Document conventions (continued)
Monospaced type
[[]]
{ }
SMALL CAPITAL LETTERS
3.0
Title Reference
SetCursorPos function indicates that you must substitute values for the X and Y coordinates, separated by a comma:
SetCursorPos(X, Y)
Code examples are displayed in a nonproportional typeface.
Vertical ellipses in program examples indicate that a portion of the program is omitted.
Ellipses following an item indicate that more items having the same form may appear. In the following example, the horizontal ellipses indicate that you can specify more than one breakaddress for the 9 command:
9 [[ =startaddress]] [[breakaddress]] ...
Double brackets enclose optional fields or parameters in command lines and syntax statements. In the following example, option and executable-file are optional parameters of the RC command:
RC [[option]] filename [[executable-file]]
A vertical bar indicates that you may enter one of the entries shown on either side of the bar. The following command-line syntax illustrates the use of a vertical bar:
DB [[address I range]]
The bar indicates that following the Dump Bytes command (DB), you can specify either an address or a range.
Quotation marks set off terms defined in the text.
Curly braces indicate that you must specify one of the enclosed items.
Small capital letters indicate the names of keys and key sequences, such as:
ALT + SPACEBAR
A Microsoft Windows version number indicates that a function, message, or data structure is compatible only with the specified version and later versions.
Contents
Is a comprehensive guide to all the details of the Microsoft Windows application program interface (API). The Reference lists in alphabetical order all the current functions, messages, and data structures of the API, and provides extensive overviews on how to use the API.
9
The Windows API guide will answer many of your programming questions. This book provides information on each Windows application programming interface (API) and describes its calls and services.
Other recommended reading
The following books are recommended for efficient Windows programming:
Programming Windows. Charles Petzold. 862 pages, softcover. An updated second edition will be available in October 1990.
Windows: Programmer's Problem Solver. Richard Wilton. 400 pages, softcover. Available November 1990.
Microsoft C Run-Time Library Reference. Covers version 6. Microsoft Corporation. 852 pages, softcover.
p A R T
1
Windows functions
Part 1 describes the functions that are the core of the Windows application programmer interface (API). You use these functions as part of a
c-
or assembly-language program to create an application that takes advantage of Windows' user-interface, graphics and multitasking capabilities.11
c
H A p T E R1
Window manager interface functions
This chapter describes the Microsoft Windows functions that process messages, create, move, or alter a window, or create system output. These functions constitute the window manager interface. This chapter describes the following topics:
[J Message functions
13 Window-creation functions
iii Display and movement functions
[J Input functions
E:I Hardware functions
C1 Painting functions
[J Dialog box functions
[J Scrolling functions
[J Menu functions
[J Information functions
[J System functions
[J Clipboard functions
[J Error functions
1:1 Caret functions
[J Cursor functions
I'l Hook functions
[J Property functions
IJ Rectangle functions
Chapter 1, Window manager interface functions 13
Message functions
Message functions read and process Windows messages in an application's queue. Messages represent a variety of input to a Windows application. A message is a data structure that contains a message identifier and message parameters. The content of the parameters varies with the message type. The following list briefly describes each function:
Function CallWindowProc DispatchMessage GetMessage GetMessagePos GetMessageTime InSendMessage
PeekMessage PostAppMessage PostMessage PostQuitMessage ReplyMessage Send Message SetMessageQueue TranslateAccelerator TranslateMDISysAccel
TranslateMessage WaitMessage WinMain
Description
Passes message information to the specified function.
Passes a message to a window function of the specified window.
Retrieves a message from the specified range of messages.
Returns the position of the mouse at the time the last message was retrieved.
Returns the time at which the last message was retrieved.
Determines whether the current window function is processing a message passed to it through a call to the Send Message function.
Checks the application queue and places the message appropriately.
Posts a message to the application.
Places a message in the application queue.
Posts a WM_ QUIT message to the application.
Replies to a message.
Sends a message to a window or windows.
Creates a new message queue of a different size.
Processes keyboard accelerators for menu commands.
Processes multiple document interface (MDI) child window command accelera tors.
Translates virtual key-stroke messages into character messages.
Yields control to other applications.
Serves as an entry point for execution of a Windows application.
Generating and processing messages
Windows generates a message at each input event, such as when the user moves the mouse or presses a keyboard key. Windows collects these input messages in a system-wide queue and then places these messages, as well as timer and paint messages, in an application's queue. The application queues are first-in/ first-out queues that belong to individual applications; however, timer and paint messages are held in the queue until the application has processed all other messages. Windows places messages that belong to a specific application in that application's queue. The application then reads the messages by using the GetMessage function and dispatches them to the appropriate window function by using the DispatchMessage function.
Windows sends some messages directly to an application's window function, without placing them in the application queue.
Such messages are called unqueued messages. In general, an unqueued message is any message that affects the window only.
The SendMessage function sends messages directly to a window.
For example, the CreateWindow function directs Windows to send a WM_CREATE message to the window function of the application and to wait until the message has been processed by the window function. Windows sends this message directly to the function and does not place it in the application queue.
Although most messages are generated by Windows, applications can create their own messages and place them in the application queues of other applications.
An application can pull messages from its queue by using the GetMessage function. This function searches the application queue for messages and, if a message exists, returns the top message in the application queue. If the application queue is empty, GetMessage waits for a message to be placed in the queue.
While waiting, GetMessage relinquishes control to Windows, allowing other applications to take control and process their own messages.
Once a main function has a message from a queue, it can dispatch the message to a window function by using the DispatchMessage function. This function directs Windows to call the window function of the window associated with the message, and then passes the content of the message as function arguments. The
Chapter 7, Window manager interface functions 15
window function can then process the message and carry out any requested changes to the window. When the window function returns, Windows returns control to the main function. The main function can then pull the next message from the queue.
_ Unless noted otherwise, Windows can send messages in any sequence. An application should not rely on receiving messages in a particular order.
Translating
Windows generates a virtual-key message each time the user presses a keyboard key. The virtual-key message contains a virtual-key code that defines which key was pressed, but does not define the character value of that key. To retrieve the character value, the main function must translate the virtual-key message by using the TranslateMessage function. This function puts another message with an appropriate character value in the application queue. The message can then be dispatched to a window function.
messages
In general, a main function should use the TranslateMessage function to translate every message, not just virtual-key messages.Although TranslateMessage has no effect on other types of messages, it guarantees that any keyboard input is translated correctly.
The following program fragment illustrates the typical loop that a main function uses to pull messages from the queues and
dispatch them to window functions:
int PASCAL WinMain(hlnstance, hPrevlnstance, lpCmdLine, nShowCmd) HANDLE hlnstance;
HANDLE hPrevlnstance;
LPSTR lpCmdLine;
int nShowCmd;
MSG msg;
while (GetMessage((LPMSG)&msg, NULL, 0, 0))
{
TranslateMessage((LPMSG)&msg);
DispatchMessage((LPMSG)&msg);
exit(msg.wParam);
