PCjs Machines

Home of the original IBM PC emulator for browsers.

Logo

MS Windows 3.0 SDK Programmer's Reference Vol. 1

The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.

Microsoft  Windows  Software Development Kit - Reference - Volume 1








────────────────────────────────────────────────────────────────────────────
 Microsoft (R) Windows (tm) Software Development Kit - Reference - Volume 1

     development tools for building Microsoft (R) Windows applications
                                VERSION 3.0
────────────────────────────────────────────────────────────────────────────


              for the MS-DOS (R) and PC-DOS Operating Systems








Microsoft Corporation

Information in this document is subject to change without notice and does
not represent a commitment on the part of Microsoft Corporation. The
software described in this document is furnished under a license agreement
or nondisclosure agreement. The software may be used or copied only in
accordance with the terms of the agreement. It is against the law to copy
the software on any medium except as specifically allowed in the license or
nondisclosure agreement. No part of this manual may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including
photocopying and recording, for any purpose without the express written
permission of Microsoft.
U.S. Government Restricted Rights


The SOFTWARE and documentation are provided with RESTRICTED RIGHTS. Use,
duplication, or disclosure by the Government is subject to restrictions as
set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013 or subparagraphs (c) (1) and
(2) of the Commercial Computer Software
─ Restricted Rights at 48 CFR 52.227-19, as applicable.
Contractor/manufacturer is Microsoft Corporation/One Microsoft Way/Redmond,
WA 98052-6399.


(C) Copyright Microsoft Corporation, 1990. All rights reserved.

Simultaneously published in the U.S. and Canada.


Printed and bound in the United States of America.


Microsoft, MS, MS-DOS, GW-BASIC, QuickC, CodeView, and
XENIX are registered trademarks and Windows, Windows/286, and Windows/386
are trademarks of Microsoft Corporation.

Epson is a registered trademark of Epson America, Inc.

IBM and PC/AT are a registered trademarks and PC/XT is
a trademark of International Business Machines Corporation.

Intel is a registered trademark of Intel Corporation.

Lotus and 1-2-3 are registered trademarks of Lotus Development
Corporation.

Nokia is a trademark of Nokia Corporation.

Paintbrush is a trademark of ZSoft Corporation.

Document No. SY0302a-300-R00-1089






Table of Contents
────────────────────────────────────────────────────────────────────────────



Introduction
     Application Programming Interface
     Windows Features
     Window Manager Interface
            Window Manager Interface Function Groups
     Graphics Device Interface
            Graphics Device Interface Function Groups
     System Services Interface
            System Services Interface Function Groups
     Naming Conventions
            Parameter Names
     Windows Calling Convention
     Manual Overview
            Document Conventions


PART I  Windows Functions
────────────────────────────────────────────────────────────────────────────


Chapter 1  Window Manager Interface Functions

     1.1   Message Functions
            1.1.1    Generating and Processing Messages
            1.1.2    Translating Messages
            1.1.3    Examining Messages
            1.1.4    Sending Messages
            1.1.5    Avoiding Message Deadlocks
     1.2   Window-Creation Functions
            1.2.1    Window Classes
            1.2.2    How Windows Locates a Class
            1.2.3    How Windows Determines the Owner of a Class
            1.2.4    Registering a Window Class
            1.2.5    Shared Window Classes
            1.2.6    Predefined Window Classes
            1.2.7    Elements of a Window Class
            1.2.8    Class Styles
            1.2.9    Internal Data Structures
            1.2.10   Window Subclassing
            1.2.11   Redrawing the Client Area
            1.2.12   Class and Private Display Contexts
            1.2.13   Window Function
            1.2.14   Window Styles
            1.2.15   Multiple Document Interface Windows
            1.2.16   Title Bar
            1.2.17   System Menu
            1.2.18   Scroll Bars
            1.2.19   Menus
            1.2.20   Window State
            1.2.21   Life Cycle of a Window
     1.3   Display and Movement Functions
     1.4   Input Functions
     1.5   Hardware Functions
     1.6   Painting Functions
            1.6.1    How Windows Manages the Display
            1.6.2    Display Context Types
            1.6.3    Display-Context Cache
            1.6.4    Painting Sequence
            1.6.5    WM_PAINT Message
            1.6.6    Update Region
            1.6.7    Window Background
            1.6.8    Brush Alignment
            1.6.9    Painting Rectangular Areas
            1.6.10   Drawing Icons
            1.6.11   Drawing Formatted Text
            1.6.12   Drawing Gray Text
            1.6.13   Nonclient-Area Painting
     1.7   Dialog-Box Functions
            1.7.1    Uses for Dialog Boxes
            1.7.2    Creating a Dialog Box
            1.7.3    Return Values from a Dialog Box
            1.7.4    Controls in a Dialog Box
            1.7.5    Dialog-Box Keyboard Interface
     1.8   Scrolling Functions
            1.8.1    Standard Scroll Bars and Scroll-Bar Controls
            1.8.2    Scroll-Bar Thumb
            1.8.3    Scrolling Requests
            1.8.4    Processing Scroll Messages
            1.8.5    Scrolling the Client Area
            1.8.6    Hiding a Standard Scroll Bar
     1.9   Menu Functions
     1.10  Information Functions
     1.11  System Functions
     1.12  Clipboard Functions
     1.13  Error Functions
     1.14  Caret Functions
            1.14.1   Creating and Displaying a Caret
            1.14.2   Sharing the Caret
     1.15  Cursor Functions
            1.15.1   Pointing Devices and the Cursor
            1.15.2   Displaying and Hiding the Cursor
            1.15.3   Positioning the Cursor
            1.15.4   The Cursor Hotspot and Confining the Cursor
            1.15.5   Creating a Custom Cursor
     1.16  Hook Functions
            1.16.1   Filter-Function Chain
            1.16.2   Installing a Filter Function
     1.17  Property Functions
            1.17.1
     1.18  Rectangle Functions
            1.18.1   Using Rectangles in a Windows Application
            1.18.2   Rectangle Coordinates
            1.18.3   Creating and Manipulating Rectangles
     1.19  Summary

Chapter 2  Graphics Device Interface Functions

     2.1   Device-Context Functions
            2.1.1    Device-Context Attributes
            2.1.2    Saving a Device Context
            2.1.3    Deleting a Device Context
            2.1.4    Compatible Device Contexts
            2.1.5    Information Contexts
     2.2   Drawing-Tool Functions
            2.2.1    Drawing-Tool Uses
            2.2.2    Color
     2.3   Color-Palette Functions
            2.3.1    How Color Palettes Work
            2.3.2    Using a Color Palette
     2.4   Drawing-Attribute Functions
            2.4.1    Background Mode and Background Color
            2.4.2    Stretch Mode
            2.4.3    Text Color
     2.5   Mapping Functions
            2.5.1    Constrained Mapping Modes
            2.5.2    Partially Constrained and Unconstrained Mapping Modes
            2.5.3    Transformation Equations
            2.5.4    Example: MM_TEXT
            2.5.5    Example: MM_LOENGLISH
     2.6   Coordinate Functions
     2.7   Region Functions
     2.8   Clipping Functions
     2.9   Line-Output Functions
            2.9.1    Function Coordinates
            2.9.2    Pen Styles, Colors, Widths
     2.10  Ellipse and Polygon Functions
            2.10.1   Function Coordinates
            2.10.2   Bounding Rectangles
     2.11  Bitmap Functions
            2.11.1   Bitmaps and Devices
            2.11.2   Device-Independent Bitmap Functions
     2.12  Text Functions
     2.13  Font Functions
            2.13.1   Font Family
            2.13.2   Character Cells
            2.13.3   Altering Characters
            2.13.4   Leading
            2.13.5   Character Set
            2.13.6   Pitch
            2.13.7   Selecting Fonts with GDI
            2.13.8   Font Files and Font Resources
     2.14  Metafile Functions
            2.14.1   Creating a Metafile
            2.14.2   Storing a Metafile in Memory or on Disk
            2.14.3   Deleting a Metafile
            2.14.4   Changing How Windows Plays a Metafile
     2.15  Printer-Control Functions
     2.16  Printer-Escape Function
            2.16.1   Creating Output on a Printer
            2.16.2   Banding Output
            2.16.3   Starting and Ending a Print Job
            2.16.4   Terminating a Print Job
            2.16.5   Information Escapes
            2.16.6   Additional Escape Calls
     2.17  Environment Functions
     2.18  Summary

Chapter 3  System Services Interface Functions

     3.1   Module-Management Functions
     3.2   Memory-Management Functions
     3.3   Segment Functions
     3.4   Operating-System Interrupt Functions
     3.5   Task Functions
     3.6   Resource-Management Functions
     3.7   String-Manipulation Functions
     3.8   Atom-Management Functions
     3.9   Initialization-File Functions
     3.10  Communication Functions
     3.11  Sound Functions
     3.12  Utility Macros and Functions
     3.13  File I/O Functions
     3.14  Debugging Functions
     3.15  Optimization-Tool Functions
     3.16  Application-Execution Functions
     3.17  Summary

Chapter 4  Functions Directory

            AccessResource
            AddAtom
            AddFontResource
            AdjustWindowRect
            AdjustWindowRectEx
            AllocDStoCSAlias
            AllocResource
            AllocSelector
            AnimatePalette
            AnsiLower
            AnsiLowerBuff
            AnsiNext
            AnsiPrev
            AnsiToOem
            AnsiToOemBuff
            AnsiUpper
            AnsiUpperBuff
            AnyPopup
            AppendMenu
            Arc
            ArrangeIconicWindows
            BeginDeferWindowPos
            BeginPaint
            BitBlt
            BringWindowToTop
            BuildCommDCB
            CallMsgFilter
            CallWindowProc
            Catch
            ChangeClipboardChain
            ChangeMenu
            ChangeSelector
            CheckDlgButton
            CheckMenuItem
            CheckRadioButton
            ChildWindowFromPoint
            Chord
            ClearCommBreak
            ClientToScreen
            ClipCursor
            CloseClipboard
            CloseComm
            CloseMetaFile
            CloseSound
            CloseWindow
            CombineRgn
            CopyMetaFile
            CopyRect
            CountClipboardFormats
            CountVoiceNotes
            CreateBitmap
            CreateBitmapIndirect
            CreateBrushIndirect
            CreateCaret
            CreateCompatibleBitmap
            CreateCompatibleDC
            CreateCursor
            CreateDC
            CreateDialog
            CreateDialogIndirect
            CreateDialogIndirectParam
            CreateDialogParam
            CreateDIBitmap
            CreateDIBPatternBrush
            CreateDiscardableBitmap
            CreateEllipticRgn
            CreateEllipticRgnIndirect
            CreateFont
            CreateFontIndirect
            CreateHatchBrush
            CreateIC
            CreateIcon
            CreateMenu
            CreateMetaFile
            CreatePalette
            CreatePatternBrush
            CreatePen
            CreatePenIndirect
            CreatePolygonRgn
            CreatePolyPolygonRgn
            CreatePopupMenu
            CreateRectRgn
            CreateRectRgnIndirect
            CreateRoundRectRgn
            CreateSolidBrush
            CreateWindow
            CreateWindowEx
            DebugBreak
            DefDlgProc
            DeferWindowPos
            DefFrameProc
            DefHookProc
            DefineHandleTable
            DefMDIChildProc
            DefWindowProc
            DeleteAtom
            DeleteDC
            DeleteMenu
            DeleteMetaFile
            DeleteObject
            DestroyCaret
            DestroyCursor
            DestroyIcon
            DestroyMenu
            DestroyWindow
            DeviceCapabilities
            DeviceMode
            DialogBox
            DialogBoxIndirect
            DialogBoxIndirectParam
            DialogBoxParam
            DispatchMessage
            DlgDirList
            DlgDirListComboBox
            DlgDirSelect
            DlgDirSelectComboBox
            DOS3Call
            DPtoLP
            DrawFocusRect
            DrawIcon
            DrawMenuBar
            DrawText
            Ellipse
            EmptyClipboard
            EnableHardwareInput
            EnableMenuItem
            EnableWindow
            EndDeferWindowPos
            EndDialog
            EndPaint
            EnumChildWindows
            EnumClipboardFormats
            EnumFonts
            EnumMetaFile
            EnumObjects
            EnumProps
            EnumTaskWindows
            EnumWindows
            EqualRect
            EqualRgn
            Escape
            EscapeCommFunction
            ExcludeClipRect
            ExcludeUpdateRgn
            ExitWindows
            ExtDeviceMode
            ExtFloodFill
            ExtTextOut
            FatalAppExit
            FatalExit
            FillRect
            FillRgn
            FindAtom
            FindResource
            FindWindow
            FlashWindow
            FloodFill
            FlushComm
            FrameRect
            FrameRgn
            FreeLibrary
            FreeModule
            FreeProcInstance
            FreeResource
            FreeSelector
            GetActiveWindow
            GetAspectRatioFilter
            GetAsyncKeyState
            GetAtomHandle
            GetAtomName
            GetBitmapBits
            GetBitmapDimension
            GetBkColor
            GetBkMode
            GetBrushOrg
            GetBValue
            GetCapture
            GetCaretBlinkTime
            GetCaretPos
            GetCharWidth
            GetClassInfo
            GetClassLong
            GetClassName
            GetClassWord
            GetClientRect
            GetClipboardData
            GetClipboardFormatName
            GetClipboardOwner
            GetClipboardViewer
            GetClipBox
            GetCodeHandle
            GetCodeInfo
            GetCommError
            GetCommEventMask
            GetCommState
            GetCurrentPDB
            GetCurrentPosition
            GetCurrentTask
            GetCurrentTime
            GetCursorPos
            GetDC
            GetDCOrg
            GetDesktopWindow
            GetDeviceCaps
            GetDialogBaseUnits
            GetDIBits
            GetDlgCtrlID
            GetDlgItem
            GetDlgItemInt
            GetDlgItemText
            GetDOSEnvironment
            GetDoubleClickTime
            GetDriveType
            GetEnvironment
            GetFocus
            GetFreeSpace
            GetGValue
            GetInputState
            GetInstanceData
            GetKBCodePage
            GetKeyboardState
            GetKeyboardType
            GetKeyNameText
            GetKeyState
            GetLastActivePopup
            GetMapMode
            GetMenu
            GetMenuCheckMarkDimensions
            GetMenuItemCount
            GetMenuItemID
            GetMenuState
            GetMenuString
            GetMessage
            GetMessagePos
            GetMessageTime
            GetMetaFile
            GetMetaFileBits
            GetModuleFileName
            GetModuleHandle
            GetModuleUsage
            GetNearestColor
            GetNearestPaletteIndex
            GetNextDlgGroupItem
            GetNextDlgTabItem
            GetNextWindow
            GetNumTasks
            GetObject
            GetPaletteEntries
            GetParent
            GetPixel
            GetPolyFillMode
            GetPriorityClipboardFormat
            GetPrivateProfileInt
            GetPrivateProfileString
            GetProcAddress
            GetProfileInt
            GetProfileString
            GetProp
            GetRgnBox
            GetROP2
            GetRValue
            GetScrollPos
            GetScrollRange
            GetStockObject
            GetStretchBltMode
            GetSubMenu
            GetSysColor
            GetSysModalWindow
            GetSystemDirectory
            GetSystemMenu
            GetSystemMetrics
            GetSystemPaletteEntries
            GetSystemPaletteUse
            GetTabbedTextExtent
            GetTempDrive
            GetTempFileName
            GetTextAlign
            GetTextCharacterExtra
            GetTextColor
            GetTextExtent
            GetTextFace
            GetTextMetrics
            GetThresholdEvent
            GetThresholdStatus
            GetTickCount
            GetTopWindow
            GetUpdateRect
            GetUpdateRgn
            GetVersion
            GetViewportExt
            GetViewportOrg
            GetWindow
            GetWindowDC
            GetWindowExt
            GetWindowLong
            GetWindowOrg
            GetWindowRect
            GetWindowsDirectory
            GetWindowTask
            GetWindowText
            GetWindowTextLength
            GetWindowWord
            GetWinFlags
            GlobalAddAtom
            GlobalAlloc
            GlobalCompact
            GlobalDeleteAtom
            GlobalDiscard
            GlobalDosAlloc
            GlobalDosFree
            GlobalFindAtom
            GlobalFix
            GlobalFlags
            GlobalFree
            GlobalGetAtomName
            GlobalHandle
            GlobalLock
            GlobalLRUNewest
            GlobalLRUOldest
            GlobalNotify
            GlobalPageLock
            GlobalPageUnlock
            GlobalReAlloc
            GlobalSize
            GlobalUnfix
            GlobalUnlock
            GlobalUnWire
            GlobalWire
            GrayString
            HIBYTE
            HideCaret
            HiliteMenuItem
            HIWORD
            InflateRect
            InitAtomTable
            InSendMessage
            InsertMenu
            IntersectClipRect
            IntersectRect
            InvalidateRect
            InvalidateRgn
            InvertRect
            InvertRgn
            IsCharAlpha
            IsCharAlphaNumeric
            IsCharLower
            IsCharUpper
            IsChild
            IsClipboardFormatAvailable
            IsDialogMessage
            IsDlgButtonChecked
            IsIconic
            IsRectEmpty
            IsWindow
            IsWindowEnabled
            IsWindowVisible
            IsZoomed
            KillTimer
            _lclose
            _lcreat
            LimitEmsPages
            LineDDA
            LineTo
            _llseek
            LoadAccelerators
            LoadBitmap
            LoadCursor
            LoadIcon
            LoadLibrary
            LoadMenu
            LoadMenuIndirect
            LoadModule
            LoadResource
            LoadString
            LOBYTE
            LocalAlloc
            LocalCompact
            LocalDiscard
            LocalFlags
            LocalFree
            LocalHandle
            LocalInit
            LocalLock
            LocalReAlloc
            LocalShrink
            LocalSize
            LocalUnlock
            LockData
            LockResource
            LockSegment
            _lopen
            LOWORD
            LPtoDP
            _lread
            lstrcat
            lstrcmp
            lstrcmpi
            lstrcpy
            lstrlen
            _lwrite
            MAKEINTATOM
            MAKEINTRESOURCE
            MAKELONG
            MAKEPOINT
            MakeProcInstance
            MapDialogRect
            MapVirtualKey
            max
            MessageBeep
            MessageBox
            min
            ModifyMenu
            MoveTo
            MoveWindow
            MulDiv
            NetBIOSCall
            OemKeyScan
            OemToAnsi
            OemToAnsiBuff
            OffsetClipRgn
            OffsetRect
            OffsetRgn
            OffsetViewportOrg
            OffsetWindowOrg
            OpenClipboard
            OpenComm
            OpenFile
            OpenIcon
            OpenSound
            OutputDebugString
            PaintRgn
            PALETTEINDEX
            PALETTERGB
            PatBlt
            PeekMessage
            Pie
            PlayMetaFile
            PlayMetaFileRecord
            Polygon
            Polyline
            PolyPolygon
            PostAppMessage
            PostMessage
            PostQuitMessage
            ProfClear
            ProfFinish
            ProfFlush
            ProfInsChk
            ProfSampRate
            ProfSetup
            ProfStart
            ProfStop
            PtInRect
            PtInRegion
            PtVisible
            ReadComm
            RealizePalette
            Rectangle
            RectInRegion
            RectVisible
            RegisterClass
            RegisterClipboardFormat
            RegisterWindowMessage
            ReleaseCapture
            ReleaseDC
            RemoveFontResource
            RemoveMenu
            RemoveProp
            ReplyMessage
            ResizePalette
            RestoreDC
            RGB
            RoundRect
            SaveDC
            ScaleViewportExt
            ScaleWindowExt
            ScreenToClient
            ScrollDC
            ScrollWindow
            SelectClipRgn
            SelectObject
            SelectPalette
            SendDlgItemMessage
            SendMessage
            SetActiveWindow
            SetBitmapBits
            SetBitmapDimension
            SetBkColor
            SetBkMode
            SetBrushOrg
            SetCapture
            SetCaretBlinkTime
            SetCaretPos
            SetClassLong
            SetClassWord
            SetClipboardData
            SetClipboardViewer
            SetCommBreak
            SetCommEventMask
            SetCommState
            SetCursor
            SetCursorPos
            SetDIBits
            SetDIBitsToDevice
            SetDlgItemInt
            SetDlgItemText
            SetDoubleClickTime
            SetEnvironment
            SetErrorMode
            SetFocus
            SetHandleCount
            SetKeyboardState
            SetMapMode
            SetMapperFlags
            SetMenu
            SetMenuItemBitmaps
            SetMessageQueue
            SetMetaFileBits
            SetPaletteEntries
            SetParent
            SetPixel
            SetPolyFillMode
            SetProp
            SetRect
            SetRectEmpty
            SetRectRgn
            SetResourceHandler
            SetROP2
            SetScrollPos
            SetScrollRange
            SetSoundNoise
            SetStretchBltMode
            SetSwapAreaSize
            SetSysColors
            SetSysModalWindow
            SetSystemPaletteUse
            SetTextAlign
            SetTextCharacterExtra
            SetTextColor
            SetTextJustification
            SetTimer
            SetViewportExt
            SetViewportOrg
            SetVoiceAccent
            SetVoiceEnvelope
            SetVoiceNote
            SetVoiceQueueSize
            SetVoiceSound
            SetVoiceThreshold
            SetWindowExt
            SetWindowLong
            SetWindowOrg
            SetWindowPos
            SetWindowsHook
            SetWindowText
            SetWindowWord
            ShowCaret
            ShowCursor
            ShowOwnedPopups
            ShowScrollBar
            ShowWindow
            SizeofResource
            StartSound
            StopSound
            StretchBlt
            StretchDIBits
            SwapMouseButton
            SwapRecording
            SwitchStackBack
            SwitchStackTo
            SyncAllVoices
            TabbedTextOut
            TextOut
            Throw
            ToAscii
            TrackPopupMenu
            TranslateAccelerator
            TranslateMDISysAccel
            TranslateMessage
            TransmitCommChar
            UngetCommChar
            UnhookWindowsHook
            UnionRect
            UnlockData
            UnlockResource
            UnlockSegment
            UnrealizeObject
            UnregisterClass
            UpdateColors
            UpdateWindow
            ValidateCodeSegments
            ValidateFreeSpaces
            ValidateRect
            ValidateRgn
            VkKeyScan
            WaitMessage
            WaitSoundState
            WindowFromPoint
            WinExec
            WinHelp
            WriteComm
            WritePrivateProfileString
            WriteProfileString
            wsprintf
            wvsprintf
            Yield


PART II  Windows Messages
────────────────────────────────────────────────────────────────────────────


Chapter 5  Messages Overview

     5.1   Window-Management Messages
     5.2   Initialization Messages
     5.3   Input Messages
     5.4   System Messages
     5.5   Clipboard Messages
     5.6   System-Information Messages
     5.7   Control Messages
            5.7.1    Button-Control Messages
            5.7.2    Edit-Control Messages
            5.7.3    List-Box Messages
            5.7.4    Combo-Box Messages
            5.7.5    Owner Draw-Control Messages
     5.8   Notification Messages
            5.8.1    Button Notification Codes
            5.8.2    Edit-Control Notification Codes
            5.8.3    List-Box Notification Codes
            5.8.4    Combo-Box Notification Codes
     5.9   Scroll-Bar Messages
     5.10  Nonclient-Area Messages
     5.11  Multiple Document Interface Messages
     5.12  Summary

Chapter 6  Messages Directory

            BM_GETCHECK
            BM_GETSTATE
            BM_SETCHECK
            BM_SETSTATE
            BM_SETSTYLE
            BN_CLICKED
            BN_DOUBLECLICKED
            CB_ADDSTRING
            CB_DELETESTRING
            CB_DIR
            CB_FINDSTRING
            CB_GETCOUNT
            CB_GETCURSEL
            CB_GETEDITSEL
            CB_GETITEMDATA
            CB_GETLBTEXT
            CB_GETLBTEXTLEN
            CB_INSERTSTRING
            CB_LIMITTEXT
            CB_RESETCONTENT
            CB_SELECTSTRING
            CB_SETCURSEL
            CB_SETEDITSEL
            CB_SETITEMDATA
            CB_SHOWDROPDOWN
            CBN_DBLCLK
            CBN_DROPDOWN
            CBN_EDITCHANGE
            CBN_EDITUPDATE
            CBN_ERRSPACE
            CBN_KILLFOCUS
            CBN_SELCHANGE
            CBN_SETFOCUS
            DM_GETDEFID
            DM_SETDEFID
            EM_CANUNDO
            EM_EMPTYUNDOBUFFER
            EM_FMTLINES
            EM_GETHANDLE
            EM_GETLINE
            EM_GETLINECOUNT
            EM_GETMODIFY
            EM_GETRECT
            EM_GETSEL
            EM_LIMITTEXT
            EM_LINEFROMCHAR
            EM_LINEINDEX
            EM_LINELENGTH
            EM_LINESCROLL
            EM_REPLACESEL
            EM_SETHANDLE
            EM_SETMODIFY
            EM_SETPASSWORDCHAR
            EM_SETRECT
            EM_SETRECTNP
            EM_SETSEL
            EM_SETTABSTOPS
            EM_SETWORDBREAK
            EM_UNDO
            EN_CHANGE
            EN_ERRSPACE
            EN_HSCROLL
            EN_KILLFOCUS
            EN_MAXTEXT
            EN_SETFOCUS
            EN_UPDATE
            EN_VSCROLL
            LB_ADDSTRING
            LB_DELETESTRING
            LB_DIR
            LB_FINDSTRING
            LB_GETCOUNT
            LB_GETCURSEL
            LB_GETHORIZONTALEXTENT
            LB_GETITEMDATA
            LB_GETITEMRECT
            LB_GETSEL
            LB_GETSELCOUNT
            LB_GETSELITEMS
            LB_GETTEXT
            LB_GETTEXTLEN
            LB_GETTOPINDEX
            LB_INSERTSTRING
            LB_RESETCONTENT
            LB_SELECTSTRING
            LB_SELITEMRANGE
            LB_SETCOLUMNWIDTH
            LB_SETCURSEL
            LB_SETHORIZONTALEXTENT
            LB_SETITEMDATA
            LB_SETSEL
            LB_SETTABSTOPS
            LB_SETTOPINDEX
            LBN_DBLCLK
            LBN_ERRSPACE
            LBN_KILLFOCUS
            LBN_SELCHANGE
            LBN_SETFOCUS
            WM_ACTIVATE
            WM_ACTIVATEAPP
            WM_ASKCBFORMATNAME
            WM_CANCELMODE
            WM_CHANGECBCHAIN
            WM_CHAR
            WM_CHARTOITEM
            WM_CHILDACTIVATE
            WM_CLEAR
            WM_CLOSE
            WM_COMMAND
            WM_COMPACTING
            WM_COMPAREITEM
            WM_COPY
            WM_CREATE
            WM_CTLCOLOR
            WM_CUT
            WM_DEADCHAR
            WM_DELETEITEM
            WM_DESTROY
            WM_DESTROYCLIPBOARD
            WM_DEVMODECHANGE
            WM_DRAWCLIPBOARD
            WM_DRAWITEM
            WM_ENABLE
            WM_ENDSESSION
            WM_ENTERIDLE
            WM_ERASEBKGND
            WM_FONTCHANGE
            WM_GETDLGCODE
            WM_GETFONT
            WM_GETMINMAXINFO
            WM_GETTEXT
            WM_GETTEXTLENGTH
            WM_HSCROLL
            WM_HSCROLLCLIPBOARD
            WM_ICONERASEBKGND
            WM_INITDIALOG
            WM_INITMENU
            WM_INITMENUPOPUP
            WM_KEYDOWN
            WM_KEYUP
            WM_KILLFOCUS
            WM_LBUTTONDBLCLK
            WM_LBUTTONDOWN
            WM_LBUTTONUP
            WM_MBUTTONDBLCLK
            WM_MBUTTONDOWN
            WM_MBUTTONUP
            WM_MDIACTIVATE
            WM_MDICASCADE
            WM_MDICREATE
            WM_MDIDESTROY
            WM_MDIGETACTIVE
            WM_MDIICONARRANGE
            WM_MDIMAXIMIZE
            WM_MDINEXT
            WM_MDIRESTORE
            WM_MDISETMENU
            WM_MDITILE
            WM_MEASUREITEM
            WM_MENUCHAR
            WM_MENUSELECT
            WM_MOUSEACTIVATE
            WM_MOUSEMOVE
            WM_MOVE
            WM_NCACTIVATE
            WM_NCCALCSIZE
            WM_NCCREATE
            WM_NCDESTROY
            WM_NCHITTEST
            WM_NCLBUTTONDBLCLK
            WM_NCLBUTTONDOWN
            WM_NCLBUTTONUP
            WM_NCMBUTTONDBLCLK
            WM_NCMBUTTONDOWN
            WM_NCMBUTTONUP
            WM_NCMOUSEMOVE
            WM_NCPAINT
            WM_NCRBUTTONDBLCLK
            WM_NCRBUTTONDOWN
            WM_NCRBUTTONUP
            WM_NEXTDLGCTL
            WM_PAINT
            WM_PAINTCLIPBOARD
            WM_PAINTICON
            WM_PALETTECHANGED
            WM_PARENTNOTIFY
            WM_PASTE
            WM_QUERYDRAGICON
            WM_QUERYENDSESSION
            WM_QUERYNEWPALETTE
            WM_QUERYOPEN
            WM_QUIT
            WM_RBUTTONDBLCLK
            WM_RBUTTONDOWN
            WM_RBUTTONUP
            WM_RENDERALLFORMATS
            WM_RENDERFORMAT
            WM_SETCURSOR
            WM_SETFOCUS
            WM_SETFONT
            WM_SETREDRAW
            WM_SETTEXT
            WM_SHOWWINDOW
            WM_SIZE
            WM_SIZECLIPBOARD
            WM_SPOOLERSTATUS
            WM_SYSCHAR
            WM_SYSCOLORCHANGE
            WM_SYSCOMMAND
            WM_SYSDEADCHAR
            WM_SYSKEYDOWN
            WM_SYSKEYUP
            WM_TIMECHANGE
            WM_TIMER
            WM_UNDO
            WM_VKEYTOITEM
            WM_VSCROLL
            WM_VSCROLLCLIPBOARD
            WM_WININICHANGE

Index


→


Introduction
────────────────────────────────────────────────────────────────────────────


Application Programming Interface

This manual describes the application programming interface (API) of the
Microsoft (R) Windows (tm) 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

A Windows application can take advantage of a number of features provided by
the API. These features include the following:


  ■   Shared display, memory, keyboard, mouse, and system timer

  ■   Data interchange with other applications

  ■   Device-independent graphics

  ■   Multitasking

  ■   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.

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.


Window Manager Interface

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

The following list describes the function groups found in the window manager
interface:


  ■   Message functions

  ■   Information functions

  ■   Window-creation functions

  ■   System functions

  ■   Display and movement functions

  ■   Clipboard functions

  ■   Error functions

  ■   Input functions

  ■   Caret functions

  ■   Hardware functions

  ■   Cursor functions

  ■   Painting functions

  ■   Hook functions

  ■   Dialog functions

  ■   Property functions

  ■   Scrolling functions

  ■   Rectangle functions

  ■   Menu functions



Graphics Device Interface

The graphics device interface (GDI) 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. GDI allows an application to create pens,
brushes, fonts, and bitmaps for specific output operations. The following
figure shows a sample of text, line, and bitmap output from Microsoft
Windows Paintbrush(tm), an application that was created with GDI functions:


(This figure may be found in the printed book.)


Graphics Device Interface Function Groups

The following list describes the function groups found in GDI:


  ■   Device-context functions

  ■   Ellipse and polygon functions

  ■   Drawing-tool functions

  ■   Bitmap functions

  ■   Drawing-attribute functions

  ■   Text functions

  ■   Mapping functions

  ■   Font functions

  ■   Coordinate functions

  ■   Metafile functions

  ■   Region functions

  ■   Printer-escape functions

  ■   Clipping functions

  ■   Environment functions

  ■   Line-output functions

  ■   System functions



System Services Interface

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.


System Services Interface Function Groups

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

  ■   Sound functions

  ■   Resource-management functions

  ■   Utility functions

  ■   String-translation functions

  ■   File I/O functions

  ■   Atom-management functions

  ■   System functions



Naming Conventions

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:


  ■   CreateWindow

  ■   RegisterClass

  ■   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:

Prefix                            Meaning
────────────────────────────────────────────────────────────────────────────
b                                 Boolean (a nonzero value means true,
                                  zero means false)

c                                 Character (a one-byte value)

dw                                Long (32-bit) unsigned integer

f                                 Bit flags packed into a 16-bit integer

h                                 16-bit handle

l                                 Long (32-bit) integer

lp                                Long (32-bit) pointer

n                                 Short (16-bit) integer

p                                 Short (16-bit) pointer

pt                                x- and y-coordinates packed into an
                                  unsigned 32-bit integer

rgb                               RGB color value packed into a 32-bit
                                  integer

w                                 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:

bIconic                           ptXY

fAction                           rgbColor

hWnd                              Height

lpString                          X

nBytes                            Width

pMsg                              Y


Windows Calling Convention

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:


  ■   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.


Manual Overview

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," 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," categorizes the functions
that perform device-independent graphics operations in the Windows
environment, provides brief descriptions of the functions, and explains the
most important features of the Windows graphics interface.

Chapter 3, "System Services Interface Functions," 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
API. It contains nine chapters and five appendixes:

Chapter 7, "Data Types and Structures," contains a table of data types and
an alphabetical list of structures found in Windows.

Chapter 8, "Resource Script Statements," 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, "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.

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," 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, "Assembly-Language Macros Overview," categorizes and briefly
describes the Windows assembly-language macros which provide a simplified
interface to the function and segment conventions of high-level languages.

Chapter 14, "Assembly-Language Macros Directory," lists the
assembly-language macros alphabetically and, for each macro, provides a
detailed description and one or more examples of how to use it in a program.


Chapter 15, "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," lists the symbolic names and hexadecimal
values of Windows virtual-key codes and includes a brief description of each
key.

Appendix B, "RC Diagnostic Messages," contains a listing of Resource
Compiler error messages and provides a brief description of each message.

Appendix C, "Windows Debugging Messages," contains a listing of Windows
debugging messages and provides a brief description of each message.

Appendix D, "Character Tables," shows the layout of the ANSI character set
and the IBM PC Extended Character set.

Appendix E, "32-Bit Memory Management DLL," describes how to implement a
32-bit flat memory model for your application.


Document Conventions

Throughout this manual, the term "DOS" refers to both MS-DOS(R) and PC-DOS,
except when noting features that are unique to one or the other.

The following document conventions are used throughout this manual:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Convention       Description of Convention
────────────────────────────────────────────────────────────────────────────
Bold text        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
Convention       Description of Convention
────────────────────────────────────────────────────────────────────────────
                 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.

Italic text      Words in italics indicate a placeholder; you are expected
                 to provide the actual value. For example, the following
                 syntax for the SetCursorPos function indicates that you
                 must substitute values for the X and Y coordinates,
                 separated by a comma:

                 SetCursorPos(X, Y)

Standout type    Code examples are displayed in standout emphesis. This
                 emohesis represents code that is displays in a Monospaced
                 type in the printed book.
Convention       Description of Convention
────────────────────────────────────────────────────────────────────────────
                 type in the printed book.

BEGIN            Vertical ellipses in program examples indicate that a
 .               portion of the program is omitted.
 .
 .
END

. . .            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 g command:

                 g «=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:
Convention       Description of Convention
────────────────────────────────────────────────────────────────────────────
                 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 | 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.

Convention       Description of Convention
────────────────────────────────────────────────────────────────────────────

CAPITAL LETTERS  capital letters indicate the names of keys and key
                 sequences, such as:

                 ALT + SPACEBAR

 Version 3.0   A box containing a Microsoft Windows version number
                 indicates that a function, message, or data structure is
                 compatible only with the specified version and later
                 versions.




Microsoft Windows Software Development Kit Documentation Set

Throughout this documentation set, "SDK" refers specifically to the
Microsoft Windows Software Development Kit and its contents. The SDK
includes the following manuals:

Title                             Contents
────────────────────────────────────────────────────────────────────────────
Installation and                  Provides an orientation to the SDK,
Update Guide                      explains how to install the SDK software,
                                  and highlights the changes for version
                                  3.0.

Guide to Programming              Explains how to write Windows
                                  applications, and provides sample
                                  applications that you can use as
                                  templates for writing your own programs.
                                  The Guide to Programming also addresses
                                  some more advanced Windows programming
                                  topics.

Tools                             Explains how to use the
                                  software-development tools you'll need
                                  to build Windows applications, such as
                                  debuggers and specialized SDK editors.

Reference                         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.

System Application Architecture,  Provides guidelines and recommendations
Common User Access: Advanced      for writing programs that look and act
Interface Design Guide            consistently with other Microsoft
                                  Windows applications.






PART I  Windows Functions
────────────────────────────────────────────────────────────────────────────

Part 1 describes the functions which 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.






Chapter 1  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:


  ■   Message functions

  ■   Window-creation functions

  ■   Display and movement functions

  ■   Input functions

  ■   Hardware functions

  ■   Painting functions

  ■   Dialog-box functions

  ■   Scrolling functions

  ■   Menu functions

  ■   Information functions

  ■   System functions

  ■   Clipboard functions

  ■   Error functions

  ■   Caret functions

  ■   Cursor functions

  ■   Hook functions

  ■   Property functions

  ■   Rectangle functions



1.1  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                          Description
────────────────────────────────────────────────────────────────────────────
CallWindowProc                    Passes message information to the
                                  specified function.

DispatchMessage                   Passes a message to a window function of
                                  the specified window.

GetMessage                        Retrieves a message from the specified
                                  range of
                                  messages.

GetMessagePos                     Returns the position of the mouse at the
                                  time the last message was retrieved.

GetMessageTime                    Returns the time at which the last
                                  message was
                                  retrieved.

InSendMessage                     Determines whether the current window
                                  function is processing a message passed
                                  to it through a call to the SendMessage
                                  function.

PeekMessage                       Checks the application queue and places
                                  the message appropriately.

PostAppMessage                    Posts a message to the application.

PostMessage                       Places a message in the application
                                  queue.

PostQuitMessage                   Posts a WM_QUIT message to the
                                  application.

ReplyMessage                      Replies to a message.

SendMessage                       Sends a message to a window or windows.

SetMessageQueue                   Creates a new message queue of a
                                  different size.

TranslateAccelerator              Processes keyboard accelerators for menu
                                  commands.

TranslateMDISysAccel              Processes multiple document interface
                                  (MDI) child window command accelerators.

TranslateMessage                  Translates virtual key-stroke messages
                                  into character messages.

WaitMessage                       Yields control to other applications.

Function                          Description
────────────────────────────────────────────────────────────────────────────
WinMain                           Serves as an entry point for execution
                                  of a Windows application.


1.1.1  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 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.

────────────────────────────────────────────────────────────────────────────
NOTE

Unless noted otherwise, Windows can send messages in any sequence. An
application should not rely on receiving messages in a particular order.
────────────────────────────────────────────────────────────────────────────

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.



1.1.2  Translating 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(hInstance, hPrevInstance, lpCmdLine, nShowCmd)
  HANDLE hInstance;
  HANDLE hPrevInstance;
  LPSTR lpCmdLine;
  int nShowCmd;
  {
       MSG msg;
       .
       .
       .
      while (GetMessage((LPMSG)&msg, NULL, 0, 0))
      {
          TranslateMessage((LPMSG)&msg);
          DispatchMessage((LPMSG)&msg);
      }
      exit(msg.wParam);
  }

Applications that use accelerator keys must load an accelerator table from
the resource file by using the LoadAccelerator function, and then translate
keyboard messages into accelerator-key messages by using the
TranslateAccelerator function. The main loop for applications that use
accelerator keys should have the following form:

  while (GetMessage((LPMSG)&msg, (HWND)NULL, 0, 0))
      {
      if (TranslateAccelerator(hWindow, hAccel, ((LPMSG)&msg) == 0)
       {
        TranslateMessage((LPMSG)&msg);
        DispatchMessage((LPMSG)&msg);
       }
      }
  exit(msg.wParam);

The TranslateAccelerator function must appear before the standard
TranslateMessage and DispatchMessage functions. Furthermore, since
TranslateAccelerator automatically dispatches the accelerator message to the
appropriate window function, the TranslateMessage and DispatchMessage
functions should not be called if TranslateAccelerator returns a nonzero
value.


1.1.3  Examining Messages

An application can use the PeekMessage function when it checks the queues
for messages but does not want to pull the message from the queue. The
function returns a nonzero value if a message is in the queue, and lets the
application retrieve the message and process it without going through the
application's main loop.

Typically, an application uses PeekMessage to check periodically for
messages when the application is carrying out a lengthy operation, such as
processing input and output. For example, this function can be used to check
for messages that terminate the operation. PeekMessage also gives the
application a chance to yield control if no messages are present because
PeekMessage can yield if no messages are in the queue.


1.1.4  Sending Messages

The SendMessage and PostMessage functions let applications pass messages to
their windows or to the windows of other applications.

The PostMessage function directs Windows to post the message by placing it
in the application queue. Control returns immediately to the calling
application, and any action to be carried out as a result of the message
does not occur until the message is read from the queue.

The SendMessage function directs Windows to send a message directly to the
given window function, bypassing the application queue. Windows does not
return control to the calling application until the window function that
receives the message processes the message.

When an application transmits a message, it must send the message by calling
SendMessage if the application relies on the return value of a message. The
return value of SendMessage is the same as the return value of the function
that processed the message. PostMessage returns immediately after sending
the message, so its return value is only a Boolean value indicating whether
the message was successfully sent and so does not indicate how the message
was processed.

Windows communicates with applications through window messages. The messages
are passed (sent or posted) to an application's window function to let the
function process the messages as desired. Although an application's main
function may read and dispatch window messages, in most cases only the
window function processes them.


1.1.5  Avoiding Message Deadlocks

An application can create a deadlock condition in Windows if it yields
control while processing a message sent from another application (or by
Windows on behalf of another application) by means of the SendMessage
function. The application does not have to yield explicitly. Calling any one
of the following functions can result in the application yielding control:


  ■   DialogBox

  ■   DialogBoxIndirect

  ■   DialogBoxIndirectParam

  ■   DialogBoxParam

  ■   GetMessage

  ■   MessageBox

  ■   PeekMessage

  ■   Yield


Normally a task that calls SendMessage to send a message to another task
will not continue executing until the window procedure that receives the
message returns. However, if a task that receives the message yields
control, Windows can be placed in a deadlock situation where the sending
task needs to execute and process messages but cannot because it is waiting
for SendMessage to return.

A window function can determine whether a message it receives was sent by
SendMessage by calling the InSendMessage function. Before calling any of the
functions listed above while processing a message, the window function
should first call InSendMessage. If InSendMessage returns TRUE, the window
function must call the ReplyMessage function before calling any function
that yields control.

As an alternative, can use a system modal dialog box or message box. Because
system modal windows prevent other windows from receiving input focus or
messages, an application should use system modal windows only when
necessary.


1.2  Window-Creation Functions

Window-creation functions create, destroy, modify, and obtain information
about windows. The following list briefly describes each window-creation
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AdjustWindowRect                  Computes the size of a window to fit a
                                  given client area.

AdjustWindowRectEx                Computes the size of a window with
                                  extended style to fit a given client
                                  area.

CreateWindow                      Creates overlapped, pop-up, and child
                                  windows.

CreateWindowEx                    Creates overlapped, pop-up, and child
                                  windows with extended styles.

DefDlgProc                        Provides default processing for those
                                  dialog-box messages that an application
                                  does not process.

DefFrameProc                      Provides default processing for those
                                  multiple document interface (MDI) frame
                                  window messages that an application does
                                  not process.

DefMDIChildProc                   Provides default processing those for
                                  MDI child window messages an that
                                  application does not process.

DefWindowProc                     Provides default processing for those
                                  window messages that an application does
                                  not process.

DestroyWindow                     Destroys a window.

GetClassInfo                      Retrieves information about a specified
                                  class.

GetClassLong                      Retrieves window-class information from
                                  a WNDCLASS structure.

GetClassName                      Retrieves a window-class name.

GetClassWord                      Retrieves window-class information from
                                  a WNDCLASS structure.

GetLastActivePopup                Determines which popup window owned by
                                  another window was most recently active.

GetWindowLong                     Retrieves information about a window.

GetWindowWord                     Retrieves information about a window.

RegisterClass                     Registers a window class.

Function                          Description
────────────────────────────────────────────────────────────────────────────
SetClassLong                      Replaces information in a WNDCLASS
                                  structure.

SetClassWord                      Replaces information in a WNDCLASS
                                  structure.

SetWindowLong                     Changes a window attribute.

SetWindowWord                     Changes a window attribute.

UnregisterClass                   Removes a window class from the
                                  window-class table.


1.2.1  Window Classes

A window class is a set of attributes that defines how a window looks and
behaves. Before an application can create and use a window, it must define
and register a window class for that window. An application registers a
class by passing values for each element of the class to the RegisterClass
function. Any number of window classes can be registered. Once a class has
been registered, Windows lets the application create any number of windows
belonging to that class. The registered class remains available until it is
deleted or the application terminates.

Although the complete window class consists of many elements, Windows
requires only that an application supply a class name, an address to the
window procedure that will process all messages sent to windows belonging to
this class, and an instance handle that identifies the application that
registered the class. The other elements of the window class define default
attributes for windows of the class, such as the shape of the cursor and the
content of the menu for the window.

There are three types of window classes. They differ in scope and when they
are created and destroyed.


System Global Classes

Windows creates system global classes when it starts. These classes are
available for use by all applications at all times. Because Windows creates
system global classes on behalf of all applications, an application cannot
create or destroy any of these classes. Examples of system global classes
include edit-control and list-box control classes.


Application Global Classes

An application or (more likely) a library creates an application global
class by specifying the CS_GLOBALCLASS style for the class. Once created, it
is globally available to all applications within the system. Most often, a
library creates an application global class so that applications which call
the library can use the class. Windows destroys an application global class
when the application or library that created it terminates. For this reason,
it is essential that all applications destroy all windows using that class
before the library or application that created the class terminates.


Application Local Classes

An application local class is any window class created by an application for
its exclusive use. This is the most common type of class created by an
application.


1.2.2  How Windows Locates a Class

When an application creates a window with a specified class, Windows uses
the following algorithm to find the class:


  1.  Windows searches for a local class of the specified name.

  2.  If Windows does not find a local class with the name, then it searches
      the application global class list.

  3.  If Windows does not find the name in the application global class
      list, then it searches the system global class list.


This procedure is used for all windows created by the application, including
windows created on the application's behalf, such as dialog controls. It is
possible, then, to override system global classes without affecting other
applications.


1.2.3  How Windows Determines the Owner of a Class

Windows determines class ownership from the hInstance field of the WNDCLASS
structure passed to the RegisterClass function when the application or
library registers the class. For Windows libraries, this must be the
instance handle of the library. When the application that registered the
class terminates or the library that registered the class is unloaded, the
class is destroyed. For this reason, all windows using the class must be
destroyed before the application or library terminates.


1.2.4  Registering a Window Class

When Windows registers a window class, it copies the attributes into its own
memory area. Windows uses the internally stored attributes when an
application refers to the window class by name; it is not necessary for the
application that originally registered the class to keep the structure
available.


1.2.5  Shared Window Classes

Applications must not share registered classes with other applications. Some
information in a window class, such as the address of the window function,
is specific to a given application and cannot be used by other applications.
However, applications can share an application global class. See
"Application Global Classes," in Section 1.2.1 for more information.

Although applications must not share registered classes, different instances
of the same application can share a registered class. Once a window class
has been registered by an application, it is available to all subsequent
instances of that application. This means that new instances of an
application do not need to, and should not, register window classes that
have been registered by previous instances.


1.2.6  Predefined Window Classes

Windows provides several predefined window classes. These classes define
special control windows that carry out common input tasks that let the user
input text, direct scrolling, and select from a list of names. The
predefined window classes are available to all applications and can be used
any number of times to create any number of these control windows.


1.2.7  Elements of a Window Class

The elements of the window class define the default behavior of the windows
created from that class. The application that registers the window class
assigns elements to the class by setting appropriate fields in a WNDCLASS
data structure and passing the structure to the RegisterClass function. An
application can retrieve information about a given window class with the
GetClassInfo function.

Table 1.1 shows the window class elements:

Table 1.1  Window Class Elements

Element                           Purpose
────────────────────────────────────────────────────────────────────────────
Class name                        Distinguishes the class from other
                                  registered classes.

Window-function address           Points to the function that processes
                                  all messages that are sent to windows in
                                  the class, and defines the behavior of
                                  the window.

Instance handle                   Identifies the application that
                                  registered the class.

Class cursor                      Defines the shape of the cursor when the
                                  cursor is in a window of the class.


Table 1.1  Window Class Elements (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Element                           Purpose
────────────────────────────────────────────────────────────────────────────
Class icon                        Defines the shape of the icon Windows
                                  displays when a window belonging to the
                                  class is closed.

Class background brush            Defines the color and pattern Windows
Element                           Purpose
────────────────────────────────────────────────────────────────────────────
Class background brush            Defines the color and pattern Windows
                                  uses to fill the client area when the
                                  window is opened or painted.

Class menu                        Specifies the default menu used for any
                                  window in the class that does not
                                  explicitly define a menu.

Class styles                      Defines how to update the window after
                                  moving or resizing, how to process
                                  double-clicks of the mouse, how to
                                  allocate space for the display context,
                                  and other aspects of the window.

Class extra                       Specifies the amount of memory (in bytes)
                                  that Windows should reserve at the end
                                  of the class data structure.

Window extra                      Specifies the amount of memory (in bytes)
Element                           Purpose
────────────────────────────────────────────────────────────────────────────
Window extra                      Specifies the amount of memory (in bytes)
                                  that Windows should reserve at the end
                                  of any window structure an application
                                  creates with this class.

────────────────────────────────────────────────────────────────────────────



The following sections describe the elements of a window class and explain
the default values for these elements if no explicit value is given when the
class is registered.


Class Name

Every window class needs a class name. The class name distinguishes one
class from another. An application assigns a class name to the class by
setting the lpszClassName field of the WNDCLASS structure to the address of
a null-terminated string that contains the name.

In the case of an application global class, the class name must be unique to
distinguish it from other application global classes. If an application
registers another application global class with the name of an existing
application global class, the RegisterClass function returns FALSE,
indicating failure. A conventional method for ensuring this uniqueness is to
include the application name in the name of the application global class.

The class name must be unique among all the classes registered by an
application. An application cannot register an application local class and
an application global class with the same class name.


Window-Function Address

Every class needs a window-function address. The address defines the entry
point of the window function that is used to process all messages for
windows in the class. Windows passes messages to the function when it wants
the window to carry out tasks, such as painting its client area or
responding to input from the user. An application assigns a window function
address by copying the address to the lpfnWndProc field of the WNDCLASS
structure. The window function must be exported in the module-definition
(.DEF) file. See Chapter 10, "Module-Definition Statements," in Reference,
Volume 2, for more information on exporting functions.

For details about the window function, see Section 1.2.13, "Window
Function."


Instance Handle

Every window class needs an instance handle to identify the application that
registered the class. As a multitasking system, Windows lets several
applications run at the same time, so it needs instance handles to keep
track of all applications. Windows assigns a unique handle to each copy of a
running application.

Windows passes an instance handle to an application when the application
first begins operation. The application assigns this instance handle to the
class by copying it to the hInstance field of the WNDCLASS structure.


Class Cursor

The class cursor defines the shape of the cursor when the cursor is in the
client area of a window in the class. Windows automatically sets the cursor
to the given shape as soon as the cursor enters the window's client area,
and ensures that the cursor keeps that shape while it remains in the client
area. To assign a cursor shape to a window class, an application typically
loads the shape from the application's resources by using the LoadCursor
function, and then assigns the returned cursor handle to the hCursor field
of the WNDCLASS structure.

Windows does not require a class cursor. If a class cursor is not defined,
Windows assumes that the window will set the cursor shape each time the
cursor moves into the window.


Class Icon

The class icon defines the shape of the icon used when the window of the
given class is minimized. To assign an icon to a window class, an
application typically loads the icon from the application's resources by
using the LoadIcon function, and then assigns the returned icon handle to
the hIcon field of the WNDCLASS structure.

Windows does not require a class icon. If a class icon is not defined,
Windows assumes the application will draw the icon whenever the window is
minimized. In this case, Windows sends appropriate messages to the window
procedure, requesting that the icon be painted.


Class Background Brush

A class background brush is the brush used to prepare the client area of a
window for subsequent drawing by the application. Windows uses the brush to
fill the client area with a solid color or pattern, thereby removing all
previous images from that location whether they belonged to the window or
not.

To assign a background brush to a class, an application typically creates a
brush by using the appropriate functions from GDI, and then assigns the
returned brush handle to the hbrBackground field of the WNDCLASS structure.


Instead of creating a brush, an application can use a standard system color
by setting the field to one of the following color values:


  ■   COLOR_ACTIVECAPTION

  ■   COLOR_APPWORKSPACE

  ■   COLOR_BACKGROUND

  ■   COLOR_BTNFACE

  ■   COLOR_BTNSHADOW

  ■   COLOR_BTNTEXT

  ■   COLOR_CAPTIONTEXT

  ■   COLOR_GRAYTEXT

  ■   COLOR_HIGHLIGHT

  ■   COLOR_HIGHLIGHTTEXT

  ■   COLOR_INACTIVECAPTION

  ■   COLOR_MENU

  ■   COLOR_MENUTEXT

  ■   COLOR_SCROLLBAR

  ■   COLOR_WINDOW

  ■   COLOR_WINDOWFRAME

  ■   COLOR_WINDOWTEXT



To use a standard system color, the application must increase the
background-color value by one. For example, COLOR_BACKGROUND + 1 is the
system background color.


Class Menu

A class menu defines the default menu to be used by the windows in the class
if no explicit menu is given when the windows are created. A menu is a list
of commands that appears at the top of a window, under the title bar, from
which a user can select actions for the application to carry out. To assign
a menu to a class, an application sets the lpszMenuName field of the
WNDCLASS structure to the address of a null-terminated string that contains
the resource name of the menu. The menu is assumed to be a resource in the
given application. Windows automatically loads the menu when it is needed.
Note that if the menu resource is identified by an integer and not by a
name, the lpszMenuName field can be set to that integer value by applying
the MAKEINTRESOURCE macro before assigning the value.

Windows does not require a class menu. If a menu is not given, Windows
assumes that the windows in the class have no menu bars. Even if no class
menu is given, an application can still define a menu bar for a window when
it creates the window.

Windows does not allow menu bars with child windows. If a menu is given and
a child window is created using the class, the menu is ignored.


1.2.8  Class Styles

The class styles define additional elements of the window class. Two or more
styles can be combined by using the bitwise OR operator. Table 1.2 lists the
class styles:

Table 1.2  Window Class Styles

Style                             Description
────────────────────────────────────────────────────────────────────────────
CS_BYTEALIGNCLIENT                Aligns the window's client area on a
                                  byte boundary (in the x direction).

CS_BYTEALIGNWINDOW                Aligns the window on a byte boundary (in
                                  the x direction).

CS_CLASSDC                        Allocates one display context to be
                                  shared by all windows in the class.

CS_DBLCLKS                        Sends double-click messages to the
                                  window function.


Table 1.2  Window Class Styles (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Style                             Description
────────────────────────────────────────────────────────────────────────────
CS_GLOBALCLASS                    Specifies that the window class is an
                                  application global class. An application
                                  global class is created by an
                                  application or library and is available
                                  to all applications. The class is
                                  destroyed when the application or
                                  library that created the class
Style                             Description
────────────────────────────────────────────────────────────────────────────
                                  library that created the class
                                  terminates;  it is essential, therefore,
                                  that all windows created with the
                                  application global class be closed
                                  before this occurs.

CS_HREDRAW                        Requests that the entire client area be
                                  redrawn if a movement or adjustment to
                                  the size changes the width of the client
                                  area.

CS_NOCLOSE                        Inhibits the close option on the System
                                  menu.

CS_OWNDC                          Allocates a unique display context for
                                  each window in the class.

CS_PARENTDC                       Gives the parent window's display
                                  context to the window class.
Style                             Description
────────────────────────────────────────────────────────────────────────────
                                  context to the window class.

CS_SAVEBITS                       Saves the portion of the screen image
                                  that is obscured by a window; Windows
                                  uses the saved bitmap to re-create the
                                  screen image when the window is removed.
                                  Windows displays the bitmap at its
                                  original location and does not send
                                  WM_PAINT messages to windows which had
                                  been obscured by the window if the
                                  memory used by the bitmap has not been
                                  discarded and if other screen actions
                                  have not invalidated the stored image.

CS_VREDRAW                        Requests that the entire client area be
                                  redrawn if a movement or adjustment to
                                  the size changes the height of the
                                  client area.

Style                             Description
────────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────



To assign a style to a window class, an application assigns the style value
to the style field of the WNDCLASS structure.


1.2.9  Internal Data Structures

Windows maintains internal data structures for each window class and window.
These structures are not directly accessible to applications but can be
examined and modified by using the following functions:


  ■   GetClassInfo

  ■   GetClassLong

  ■   GetClassName

  ■   GetClassWord

  ■   GetWindowLong

  ■   GetWindowWord

  ■   SetClassLong

  ■   SetClassWord

  ■   SetWindowLong

  ■   SetWindowWord


Section 1.2.10 describes some ways in which a window class or window can be
modified.


1.2.10  Window Subclassing

A subclass is a window or set of windows that belong to the same window
class, and whose messages are intercepted and processed by another window
function (or functions) before being passed to the class window function.

To create the subclass, the SetWindowLong function is used to change the
window function associated with a particular window, causing Windows to call
the new window function instead of the previous one. Any messages not
processed by the new window function must be passed to the previous window
function by calling the CallWindowProc function. This allows Windows to
create a chain of window functions. The address of the previous window
function can be retrieved by using the GetWindowLong function before using
SetWindowLong.

Similarly, the SetClassLong function changes the window function associated
with a window class. Any window that is subsequently created with that class
will be associated with the replacement window function for that class, as
will the window whose handle is passed to SetClassLong. Other existing
windows that were previously created with the class are not affected,
however.

When you subclass a window or class of windows, you must export the
replacement window procedure in your application's definition file, and you
must create the address of the procedure which you pass to SetWindowLong or
SetClassLong by calling the MakeProcInstance function.

────────────────────────────────────────────────────────────────────────────
NOTE
An application should not attempt to create a window subclass for standard
Windows controls such as combo boxes and buttons.
────────────────────────────────────────────────────────────────────────────


1.2.11  Redrawing the Client Area

When a window is moved, Windows automatically copies the contents of the
client area to the new location. This saves time because a window does not
have to recalculate and redraw the contents of the client area as part of
the move. If the window moves and changes size, Windows copies only as much
of the previous client area as is needed to fill the new location. If the
window increases in size, Windows copies the entire client area and sends a
WM_PAINT message to the window to fill in the newly exposed areas. When a
window is moved, Windows assumes the contents of the client area remain
valid and can be copied without modification to the new location.

For some windows, however, the contents of the client area are not valid
after a move, especially if the move includes a change in size. For example,
a clock application whose window must always contain the complete image of
the clock has to redraw the window anytime the window changes size, and has
to update the time after the move. To prevent the windows from copying the
previous contents of the client area, a window should specify the CS_VREDRAW
and CS_HREDRAW styles in the window class.


1.2.12  Class and Private Display Contexts

A display context is a special set of values that applications use for
drawing in the client area of their windows. Windows requires a display
context for each window on the system display, but allows some flexibility
in how that display context is stored and treated by the system.

If no explicit display-context style is given, Windows assumes that each
window will use a display context retrieved from a pool of contexts
maintained by Windows. In such cases, each window must retrieve and
initialize the display context before painting, and then free it after
painting.

In order not to retrieve a display context each time it wants to paint in a
window, an application can specify the CS_OWNDC style for the window class.
This class style directs Windows to create a private display context, that
is, to allocate a unique display context for each window in the class. The
application need only retrieve the context once, and then use it for all
subsequent painting. Although the CS_OWNDC style is convenient, it must be
used carefully because each display context occupies approximately 800 bytes
of memory in the GDI heap.

By specifying the CS_CLASSDC style, an application can have some of the
convenience of a private display context without allocating a separate
display context for each window. The CS_CLASSDC style directs Windows to
create a single class display context, that is, one display context to be
shared by all windows in the class. An application need only retrieve the
display context for a window; then as long as no other window in the class
retrieves that display context, the window can continue to use the context.


Similarly, by specifying the CS_PARENTDC style, an application can create
child windows that inherit the device context of their parent.


1.2.13  Window Function

A window function processes all messages sent to a window in a given class.
Windows sends messages to a window function when it receives input from the
user that is intended for the given window, or when it needs information or
the procedure to carry out some action on its window, such as painting in
the client area.

A window function receives input messages from the keyboard, mouse, and
timer. It receives requests for information, such as a request for the
window title. It receives reports of changes made to the system by other
windows, such as a change to the WIN.INI file. It receives messages that
give it an opportunity to modify the standard system response to certain
actions, such as an opportunity to adjust a menu before it is displayed. It
receives requests to carry out some action on its window or client area,
such as a request to update the client area. And a window function receives
information about its status in relation to other windows, such as losing
access to the keyboard or becoming the active window.

Most of the messages a window function receives are from Windows, but it can
also receive messages from other windows, including windows it owns. These
messages can be requests for information or notification that a given event
has occurred within another window.

A window function continues to receive messages from the system and possibly
other windows in the system until it, or the window function of a parent
window, or the system destroys the window. Even in the process of being
destroyed, the window function receives additional messages that give it the
opportunity to carry out any clean-up tasks before terminating. But once the
window is destroyed, no more messages are passed to the function for that
particular window. If there is more than one window of the class, however,
the window function continues to receive messages for the other windows
until they, too, are destroyed.

A window function defines how a given window actually behaves; that is, it
defines what response the window makes to commands from the user or system.
The messages the window function receives from the system contain
information that the function knows; for example, the user clicked the
scroll bar or selected the Open command in the File menu, or double-clicked
in the client area. The window function must examine these messages and
determine what action, if any, to take. For example, if the user clicks the
scroll bar, the window function may scroll the contents of the client area.
Windows provides detailed information about what happens and provides some
tools to carry out tasks, such as drawing and scrolling, but the window
function must carry out the actual task.

A window function can also choose not to respond to a given message. If it
does not respond, the function must give the system the opportunity to
respond by passing the message to the DefWindowProc function. This function
carries out default actions based on the given message and its parameters.
Many messages, especially nonclient-area messages, must be processed, so the
DefWindowProc function is required in all window functions.

A window function also receives messages that are really intended to be
processed by the system. These messages, called nonclient-area messages,
inform the function either that the user has carried out some action in a
nonclient area of the window, such as clicking the title bar, or that some
information about the window is required by the system to carry out an
action, such as for moving or adjusting the size of the window. Although
Windows passes these messages to the window function, the function should
pass them to the DefWindowProc function and not attempt to process them. In
any case, the window procedure must not ignore the message or return without
passing it to DefWindowProc.


Window Messages

A window message is a set of values that Windows sends to a window function
when it requests some action or informs the window of input. Every message
consists of four values: a handle that identifies the window, a message
identifier, a 16-bit message-specific value, and a 32-bit message-specific
value. These values are passed as individual parameters to the window
function. The window function then examines the message identifier to
determine what response to make and how to interpret the 16- and 32-bit
values.

Windows has a wide variety of messages that it or applications can send to a
window function. Most messages are sent to a window as a result of a given
function being executed or as input from the user.

To send a message to a window procedure, Windows expects the window function
to have four parameters and use the Pascal calling convention. The following
illustrates the window procedure syntax:

  LONG FAR PASCAL WndProc(hWnd, wMsg, wParam, lParam)
  HWND hWnd;
  WORD wMsg;
  WORD wParam;
  DWORD lParam;

The hWnd parameter identifies the window receiving the message; the wMsg
parameter is the message identifier; the wParam parameter is 16 bits of
additional message-specific information; and lParam is 32 bits of additional
information. The window procedure must return a 32-bit value that indicates
the result of message processing. The possible return values depend on the
actual message sent.

Windows expects to make an intersegment call to the window function, so the
function must be declared with the FAR attribute. The window-function name
must be exported by including it in an EXPORTS statement in the
application's module-definition file.


Default Window Function

The DefWindowProc function is the default message processor for window
functions that do not or cannot process some of the messages sent to them.
For most window functions, the DefWindowProc function carries out most, if
not all, processing of nonclient-area messages. Those are the messages that
signify actions to be carried out on parts of the window other than the
client area. Table 1.3 lists the messages DefWindowProc processes and the
default actions for each:

Table 1.3  Default Actions for Messages

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
WM_ACTIVATE                       Sets or kills the input focus.
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
WM_ACTIVATE                       Sets or kills the input focus.

WM_CANCELMODE                     Terminates internal processing of
                                  standard scroll bar input, terminates
                                  internal menu processing, and releases
                                  mouse capture.

WM_CLOSE                          Calls the DestroyWindow function.

WM_CTLCOLOR                       Sets the background and text color and
                                  returns a handle to the brush used to
                                  fill the control background.

WM_ERASEBKGND                     Fills the client area with the color and
                                  pattern specified by the class brush, if
                                  any.

WM_GETTEXT                        Copies the window title into a specified
                                  buffer.
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
                                  buffer.

WM_GETTEXTLENGTH                  Returns the length (in characters) of
                                  the window title.

WM_ICONERASEBKGND                 Fills the icon client area with the
                                  background brush of the parent window.

WM_NCACTIVATE                     Activates or deactivates the window and
                                  draws the icon or title bar to show the
                                  new state.

WM_NCCALCSIZE                     Computes the size of the client area.

WM_NCCREATE                       Initializes standard scroll bars, if any,
                                  and sets the default title for the
                                  window.

WM_NCDESTROY                      Frees any space internally allocated for
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
WM_NCDESTROY                      Frees any space internally allocated for
                                  the window title.



Table 1.3  Default Actions for Messages (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
WM_NCHITTEST                      Determines what part of the window the
                                  mouse is in.

WM_NCLBUTTONDBLCLK                Tests the given point to determine the
                                  location of the mouse and, if necessary,
                                  generates additional messages.

WM_NCLBUTTONDOWN                  Determines whether the left mouse button
                                  was pressed while the mouse was in the
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
                                  was pressed while the mouse was in the
                                  nonclient area of a window.

WM_NCLBUTTONUP                    Tests the given point to determine the
                                  location of the mouse and, if necessary,
                                  generates additional messages.

WM_NCMOUSEMOVE                    Tests the given point to determine the
                                  location of the mouse and, if necessary,
                                  generates additional messages.

WM_NCPAINT                        Paints the nonclient parts of the window.

WM_PAINT                          Validates the current update region, but
                                  does not paint the region.

WM_PAINTICON                      Draws the window class icon when a
                                  window is minimized.

Message                           Default Action
────────────────────────────────────────────────────────────────────────────

WM_QUERYENDSESSION                Returns TRUE.

WM_QUERYOPEN                      Returns TRUE.

WM_SETREDRAW                      Forces an immediate update of
                                  information about the clipping area of
                                  the complete window.

WM_SETTEXT                        Sets and displays the window title.

WM_SHOWWINDOW                     Opens or closes a window.

WM_SYSCHAR                        Generates a WM_SYSCOMMAND message for
                                  menu input.

WM_SYSCOMMAND                     Carries out the requested system command.

WM_SYSKEYDOWN                     Examines the given key and generates a
Message                           Default Action
────────────────────────────────────────────────────────────────────────────
WM_SYSKEYDOWN                     Examines the given key and generates a
                                  WM_SYSCOMMAND message if the key is
                                  either TAB or ENTER.

────────────────────────────────────────────────────────────────────────────




1.2.14  Window Styles

Windows provides several different window styles that can be combined to
form different kinds of windows. The styles are used in the CreateWindow
function when the window is created.


Overlapped Windows

An overlapped window is always a top-level window. In other words, an
overlapped window never has a parent window. It has a client area, a border,
and a title bar. It can also have a System menu, minimize/maximize boxes,
scroll bars, and a menu, if these items are specified when the window is
created. For windows used as a main interface, the System menu and
minimize/maximize boxes are strongly recommended.

Every overlapped window can have a corresponding icon that Windows displays
when the window is minimized. A minimized window is not destroyed. It can be
opened again by restoring the icon. An application minimizes a window to
save screen space when several windows are open at the same time.

You create an overlapped window by using the WS_OVERLAPPED or
WS_OVERLAPPEDWINDOW style with the CreateWindow function. An overlapped
window created with the WS_OVERLAPPED style always has a caption and a
border. The WS_OVERLAPPEDWINDOW style creates an overlapped window with a
caption, a thick-frame border, a system menu, and minimize and maximize
boxes.


Owned Windows

An owned window is a special type of overlapped window. Every owned window
has an owner. This owner must also be an overlapped window. Being owned
forces several constraints on a window:


  ■   An owned window will always be "above" its owner when the windows are
      ordered. Attempting to move the owner above the owned window will
      cause the owned window to also change position to ensure that it will
      always be above its owner.

  ■   Windows automatically destroys an owned window when it destroys the
      window's owner.

  ■   An owned window is hidden when its owner is minimized.


An application creates an owned window by specifying the owner's window
handle as the hWndParent parameter of the CreateWindow function when
creating a window that has the WS_OVERLAPPED style.

Dialog boxes are owned windows by default. The function that creates the
dialog box receives the handle of the owner window as its hWndParent
parameter.


Pop-up Windows

Pop-up windows are another special type of overlapped window. The main
difference between a pop-up window and an overlapped window is that an
overlapped window always has a caption, while the caption bar is optional
for a pop-up window. Like overlapped windows, pop-up windows can be owned.

You create a pop-up window by using the WS_POPUP window style with the
CreateWindow function. A pop-up window can be opened and closed by using the
ShowWindow function.


Child Windows

A child window is the window style used for windows that are confined to the
client area of a parent window. Child windows are typically used to divide
the client area of a parent window into different functional areas.

You create a child window by using the WS_CHILD window style with the
CreateWindow function. A child window can be shown and hidden by using the
ShowWindow function.

Every child window must have a parent window. The parent window can be an
overlapped window, a pop-up window, or even another child window. The parent
window relinquishes a portion of its client area to the child window, and
the child window receives all input from this area. The window class does
not have to be the same for each of the child windows in the parent window.
This means an application can fill a parent window with child windows that
look different and carry out different tasks.

A child window has a client area, but it does not have any other features
unless these are explicitly requested. An application can request a border,
title bar, minimize/maximize boxes, and scroll bars for a child window. In
most cases, the application designs its own features for the child window.

Although not required, every child window should have a unique integer
identifier. The identifier, given in the menu parameter of the CreateWindow
function in place of a menu, helps identify the child window when its parent
window has many other child windows. The child window should use this
identifier in any messages it sends to the parent window. This is the way a
parent window with several child windows can identify which child window is
sending the message.

Windows always positions the child window relative to the upper-left corner
of the parent window's client area. The coordinates are always client
coordinates. (For information about mapping, see Section 2.5, "Mapping
Functions.") If all or part of a child window is moved outside the visible
portion of the parent window's client area, the child window is clipped;
that is, the portion outside the parent window's client area is not
displayed.

A child window is an independent window that receives its own input and
other messages. Input intended for a child window goes directly to the child
window and is not passed through the parent window. The only exception is if
input to the child window has been disabled by the EnableWindow function. In
this case, Windows passes any input that would have gone to the child window
to the parent window instead. This gives the parent window an opportunity to
examine the input and enable the child window, if necessary.

Actions that affect the parent window can also affect the child window. The
following is a list of actions affecting parent windows that can affect
child windows:

Parent Window                     Child Window
────────────────────────────────────────────────────────────────────────────
Shown                             Shown after the parent window.

Hidden                            Hidden prior to the parent window being
                                  closed. A child window can be visible
                                  only when the parent window is visible.

Destroyed                         Destroyed prior to the parent window
                                  being destroyed.

Moved                             Moved with the parent window's client
                                  area. The child window is responsible
                                  for painting after the move.

Increased in size or              Paints any portions of the parent window
maximized                         that have been exposed as a result of
                                  the increased size of the client area.

Windows does not automatically clip a child window from the parent window's
client area. This means the parent window will draw over the child window if
it carries out any drawing in the same location as the child window. Windows
does clip the child window from the parent window's client area if the
parent window has a WS_CLIPCHILDREN style. If the child window is clipped,
the parent window cannot draw over it.

A child window can overlap other child windows in the same client area. Two
child windows of the same parent window may draw in each other's client area
unless one child window has a WS_CLIPSIBLINGS style. Sibling windows are
child windows that share the same parent window. If the application
specifies this style for a child window, any portion of that child's sibling
window that lies within this window will be clipped.

If a window has either the WS_CLIPCHILDREN or WS_CLIPSIBLINGS style, a
slight loss in performance occurs.


1.2.15  Multiple Document Interface Windows

Windows multiple document interface (MDI) provides applications with a
standard interface for displaying multiple documents within the same
instance of an application. An MDI application creates a frame window which
contains a client window in place of its client area. An application creates
an MDI client window by calling CreateWindow with the class MDICLIENT and
passing a CLIENTCREATESTRUCT data structure as the function's lpParam
parameter. This client window in turn can own multiple child windows, each
of which displays a separate document. An MDI application controls these
child windows by sending messages to its client window.

For more information on the multiple document interface, see the Guide to
Programming.


1.2.16  Title Bar

The title bar, a rectangle at the top of the window, provides space for the
window title or name. An application defines the window title when it
creates the window. It can also change this name anytime by using the
SetWindowText function. If a window has a title bar, Windows lets the user
use the mouse to move the window.


1.2.17  System Menu

The System menu, identified by an icon at the left end of the title bar, is
a pop-up menu that contains the system commands. The system commands are
commands selected by the user to direct Windows to carry out actions on the
window, such as moving and closing it.

If a System menu or close box is desired for a window, the WS_SYSMENU and
WS_CAPTION window styles must be specified when the window is created.


1.2.18  Scroll Bars

The horizontal and vertical scroll bars, bars on the right and lower sides
of a window, let a user scroll the contents of the client area. Windows
sends scroll requests to a window as WM_HSCROLL and WM_VSCROLL messages. If
the window permits scrolling, the window function must process these
messages.

A window can have one or both scroll bars. To create a window with a scroll
bar, the application must specify the WS_HSCROLL or WS_VSCROLL window style
when the window is created.


1.2.19  Menus

A menu is a list of commands from which the user can select using the mouse
or the keyboard. When the user selects an item, Windows sends a
corresponding message to the window function to indicate which command was
selected. Windows provides two types of menus: menu bars (sometimes called
static menus) and pop-up menus.

A menu bar is a horizontal menu that appears at the top of a window and
below the title bar, if one exists. Any window except a child window can
have a menu bar. If an application does not specify a menu when it creates a
window, the window receives the default menu bar (if any) defined by the
window class.

Pop-up menus contain a vertical list of items and are often displayed when a
user selects a menu-bar item. In turn, a pop-up menu item can display
another pop-up menu. Also, a pop-up menu can be "floating." A floating
pop-up menu can appear anywhere on the screen designated by the application.
An application creates an empty pop-up menu by calling the CreatePopupMenu
function, and then fills in the menu using the AppendMenu and InsertMenu
functions. It displays the pop-up menu by calling TrackPopupMenu.

Individual menu items can be created or modified with the MF_OWNERDRAW
style, indicating that the item is an owner-draw item. In this case, the
owner of the menu is responsible for drawing all visual aspects of the menu
item, including checked, grayed, and highlighted states. When the menu is
displayed for the first time, the window that owns the menu receives a
WM_MEASUREITEM message. The lParam parameter of this message points to a
MEASUREITEMSTRUCT data structure. The owner then fills in this data
structure with the dimensions of the item and returns. Windows uses the
information in the data structure to determine the size of the item so that
Windows can appropriately detect the user's interaction with the item.

Windows sends the WM_DRAWITEM message whenever the owner of the menu must
update the visual appearance of the item. Unlike other owner-draw controls,
however, the owner of the menu item does not receive the WM_DELETEITEM
message when the menu item is removed from the menu. A top-level menu item
cannot be an owner-draw item.

When the application calls AppendMenu, InsertMenu, or ModifyMenu to add an
owner-draw menu item to a menu or to change an existing menu item to be an
owner-draw menu item, the application can supply a 32-bit value as the
lpNewItem parameter to the function. The application can use this value to
maintain additional data associated with the item. This value is available
to the application as the itemData field of the structures pointed to by the
lParam parameter of the WM_MEASUREITEM and WM_DRAWITEM messages. For
example, if an application were to draw the text in a menu item using a
specific color, the 32-bit value could contain a pointer to a string. The
application could then set the text color before drawing the item when it
received the WM_DRAWITEM message.


1.2.20  Window State

The window state can be opened or closed (iconic), hidden or visible, and
enabled or disabled. The initial state of a window can be set by using the
following window styles:


  ■   WS_DISABLED

  ■   WS_MINIMIZE

  ■   WS_MAXIMIZE

  ■   WS_VISIBLE


Windows creates windows that are initially enabled for input, that is,
windows that can start receiving input messages immediately. In some cases,
an application may need to disable input to a new window. It can disable
input by specifying the WS_DISABLED window style.

A new window is not displayed until an application opens it by using the
ShowWindow function or specifies the WS_VISIBLE window style when it creates
the window. For overlapped windows, the WS_ICONIC window style creates a
window that is minimized initially.


1.2.21  Life Cycle of a Window

Because the purpose of any window is to let the user enter data or to let
the application display information, a window starts its life cycle when the
application has a need for input or output. A window continues its life
cycle until there is no longer a need for it, or the application is
terminated. Some windows, such as the window used for the application's main
user interface, last the life of the application. Other windows, such as a
window used as a dialog box, may last only a few seconds.

The first step in a window's life cycle is creation. Given a registered
window class with a corresponding window function, the application uses the
CreateWindow function to create the window. This function directs Windows to
prepare internal data structures for the window and to return a unique
integer value, called a window handle, that the application can use to
identify the window in subsequent function calls.

The first message most windows process is WM_CREATE, the window-creation
message. Again, the CreateWindow function sends this message to inform the
window function that it can now perform any initialization, such as
allocating memory and preparing data files. The wParam parameter is not
used, but the lParam parameter contains a long pointer to a CREATESTRUCT
data structure, whose fields correspond to the parameters passed to
CreateWindow.

Both the WM_CREATE and WM_NCCREATE messages are sent directly to the window
function, bypassing the application queue. This means an application will
create a window and process the WM_CREATE message before it enters the main
program loop.

After a window has been created, it must be opened (displayed) before it can
be used. An application can open the window in one of two ways: it can
specify the WS_VISIBLE window style in the CreateWindow function to open the
window immediately after creation, or it can wait until later and call the
ShowWindow function to open the window. When creating a main window, an
application should not specify WS_VISIBLE, but should call ShowWindow from
the WinMain function with the nCmdShow parameter set to the desired value.

When the window is no longer needed or the application is terminated, the
window must be destroyed. This is done by using the DestroyWindow function.
DestroyWindow removes the window from the system display and invalidates the
window handle. It also sends WM_DESTROY and WM_NCDESTROY messages to the
window function.

The WM_DESTROY message is usually the last message a window function
processes. This occurs when the DestroyWindow function is called or when a
WM_CLOSE message is processed by the DefWindowProc function. When a window
function receives a WM_DESTROY message, it should free any allocated memory
and close any open data files.

The window used as the application's main user interface should always be
the last window destroyed and should always cause the application to
terminate. When this window receives a WM_DESTROY message, it should call
the PostQuitMessage function. This function copies a WM_QUIT message to the
application's message queue as a signal for the application to terminate
when the message is read from the queue.


1.3  Display and Movement Functions

Display and movement functions show, hide, move, and obtain information
about the number and position of windows on the screen. The following list
briefly describes each display and movement function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ArrangeIconicWindows              Arranges minimized (iconic) child
                                  windows.

BeginDeferWindowPos               Initializes memory used by the
                                  DeferWindowPos function.

BringWindowToTop                  Brings a window to the top of a stack of
                                  overlapped windows.

CloseWindow                       Hides the specified window or minimizes
                                  it.

DeferWindowPos                    Records positioning information for a
                                  window to be moved or resized by the
                                  EndDeferWindowPos function.

EndDeferWindowPos                 Positions or sizes several windows
                                  simultaneously based on information
                                  recorded by the DeferWindowPos function.

GetClientRect                     Copies the coordinates of a window's
                                  client area.

GetWindowRect                     Copies the dimensions of an entire
                                  window.

GetWindowText                     Copies a window caption into a buffer.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetWindowTextLength               Returns the length (in characters) of
                                  the given window's caption or text.

IsIconic                          Specifies whether a window is open or
                                  closed (iconic).

IsWindowVisible                   Determines whether the given window is
                                  visible.

IsZoomed                          Determines whether a window is maximized.

MoveWindow                        Changes the size and position of a
                                  window.

OpenIcon                          Opens the specified window.

SetWindowPos                      Changes the size, position, and ordering
                                  of child or pop-up windows.

SetWindowText                     Sets the window caption or text.

ShowOwnedPopups                   Shows or hides all pop-up windows.

ShowWindow                        Displays or removes the given window.


1.4  Input Functions

Input functions disable input from system devices, take control of the
system devices, or define special actions that Windows takes when an
application receives input from a system device. (The system devices are the
mouse, the keyboard, and the timer.) The following list briefly describes
each input function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
EnableWindow                      Enables and disables mouse and keyboard
                                  input throughout the application.

GetActiveWindow                   Returns a handle to the active window.

GetCapture                        Returns a handle to the window with the
                                  mouse
                                  capture.

GetCurrentTime                    Retrieves the current Windows time.

GetDoubleClickTime                Retrieves the current double-click time
                                  for the mouse.

GetFocus                          Retrieves the handle of the window that
                                  currently owns the input focus.

GetTickCount                      Returns the number of timer ticks
                                  recorded since the system was booted.

Function                          Description
────────────────────────────────────────────────────────────────────────────
IsWindowEnabled                   Determines whether the specified window
                                  is enabled for mouse and keyboard input.

KillTimer                         Kills the specified timer event.

ReleaseCapture                    Releases mouse input and restores normal
                                  input
                                  processing.

SetActiveWindow                   Makes a window the active window.

SetCapture                        Causes mouse input to be sent to a
                                  specified window.

SetDoubleClickTime                Sets the double-click time for the mouse.

SetFocus                          Assigns the input focus to a specified
                                  window.

SetSysModalWindow                 Makes the specified window a system
                                  modal window.

SetTimer                          Creates a system-timer event.

SwapMouseButton                   Reverses the meaning of left and right
                                  mouse
                                  buttons.


1.5  Hardware Functions

Hardware functions alter the state of input devices and obtain state
information. Windows uses the mouse and the keyboard as input devices. The
following list briefly describes each hardware function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
EnableHardwareInput               Enables or disables mouse and keyboard
                                  input throughout the application.

GetAsyncKeyState                  Returns interrupt-level information
                                  about the key state.

GetInputState                     Returns TRUE if there is mouse or
                                  keyboard input.

GetKBCodePage                     Determines which OEM/ANSI tables are
                                  loaded.

GetKeyboardState                  Copies an array that contains the state
                                  of keyboard keys.

GetKeyNameText                    Retrieves a string containing the name
                                  of a key from a list maintained by the
                                  keyboard driver.

GetKeyState                       Retrieves the state of a virtual key.

Function                          Description
────────────────────────────────────────────────────────────────────────────
MapVirtualKey                     Accepts a virtual-key code or scan code
                                  for a key and returns the corresponding
                                  scan code, virtual-key code, or ASCII
                                  value.

OemKeyScan                        Maps OEM ASCII codes 0 through 0x0FF
                                  into the OEM scan codes and shift states.

SetKeyboardState                  Sets the state of keyboard keys by
                                  altering values in an array.

VkKeyScan                         Translates an ANSI character to the
                                  corresponding virtual-key code and shift
                                  state for the current
                                  keyboard.


1.6  Painting Functions

Painting functions prepare a window for painting and carry out some useful
general-purpose graphics operations. Although all the paint functions are
specifically intended for the system display, some can be used for other
output devices. The following list briefly describes each painting function:


Function                          Description
────────────────────────────────────────────────────────────────────────────
BeginPaint                        Prepares a window for painting.

DrawFocusRect                     Draws a rectangle in the style used to
                                  indicate focus.

DrawIcon                          Draws an icon.

DrawText                          Draws characters of a specified string.

EndPaint                          Marks the end of window repainting.

ExcludeUpdateRgn                  Prevents drawing within invalid areas of
                                  a window.

FillRect                          Fills a given rectangle by using the
                                  specified brush.

FrameRect                         Draws a border for the given rectangle.

GetDC                             Retrieves the display context for the
                                  client area.

GetUpdateRect                     Copies the dimensions of a window
                                  region's bounding rectangle.

GetUpdateRgn                      Copies a window's update region.

GetWindowDC                       Retrieves the display context for an
                                  entire window.

GrayString                        Writes the characters of a string using
                                  gray text.

InvalidateRect                    Marks a rectangle for repainting.

Function                          Description
────────────────────────────────────────────────────────────────────────────
InvalidateRgn                     Marks a region for repainting.

InvertRect                        Inverts the display bits of the
                                  specified rectangle.

ReleaseDC                         Releases a display context.

UpdateWindow                      Notifies the application when parts of a
                                  window need redrawing.

ValidateRect                      Releases the specified rectangle from
                                  repainting.

ValidateRgn                       Releases the specified region from
                                  repainting.


1.6.1  How Windows Manages the Display

The system display is the principal display device for all applications
running with Windows. All applications are free to display some form of
output on the system display, but since many applications can run at one
time, applications are not entitled to the entire system display. The
complete system display must be shared. Windows shares the system display by
carefully managing the access that applications have to it. Windows ensures
that applications have space to display output but do not draw in the space
reserved for other applications.

Windows manages the system display by using the display context type. The
display context is a special device context that treats each window as a
separate display surface. An application that retrieves a display context
for a specific window has complete control of the system display within that
window, but cannot access or paint over any part of the display outside the
window. With a display context, an application can use GDI painting
functions, as well as the output functions described in this section, to
draw in the given window.


1.6.2  Display Context Types

There are four types of display contexts: common, class, private, and
window. The common, class, and private display contexts permit drawing in
the client area of a given window. The window display context permits
drawing anywhere in the window. When a window is created, Windows assigns a
common, class, or private display context to it, based on the type of
display context specified in that window's class style.


Common Display Context

A common display context is the default context for all windows. Windows
assigns a common display context to the window if a display-context type is
not explicitly specified in the window's class style.

A common display context permits drawing in a window's client area, but it
is not immediately available for use by a window. A common display context
must be retrieved from a cache of display contexts before a window can carry
out any drawing in its client area. The GetDC or BeginPaint function
retrieves the display context and returns a handle to the context. The
handle can be used with GDI functions to draw in the client area of the
given window. After drawing is complete, the context must be returned to the
cache by using the ReleaseDC or EndPaint function. After the context is
released, drawing cannot occur until another display context is retrieved.

When a common display context is retrieved, Windows gives it default
selections for pen, brush, font, clipping area, and other attributes. These
attributes define the tools currently available to carry out the actual
drawing. Table 1.4 lists the default selections for a common display
context:

Table 1.4  Defaults for a Display Context

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Attribute                         Default
────────────────────────────────────────────────────────────────────────────
Background color                  White

Background mode                   OPAQUE
Attribute                         Default
────────────────────────────────────────────────────────────────────────────
Background mode                   OPAQUE

Bitmap                            No default.

Brush                             WHITE_BRUSH

Brush origin                      (0,0)

Clipping region                   Entire client area with the update
                                  region clipped as appropriate. Child and
                                  pop-up windows in the client area may
                                  also be clipped.

Color palette                     DEFAULT_PALETTE

Current pen position              (0,0)

Device origin                     Upper-left corner of client area.

Attribute                         Default
────────────────────────────────────────────────────────────────────────────

Drawing mode                      R2_COPYPEN

Font                              SYSTEM_FONT (SYSTEM_FIXED_FONT for
                                  applications written to run with Windows
                                  versions prior to 3.0)

Intercharacter spacing            0

Mapping mode                      MM_TEXT

Pen                               BLACK_PEN

Polygon-filling mode              ALTERNATE

Relative-absolute flag            ABSOLUTE

Stretching mode                   BLACKONWHITE

Attribute                         Default
────────────────────────────────────────────────────────────────────────────

Text color                        Black

Viewport extent                   (1,1)

Viewport origin                   (0,0)



Table 1.4  Defaults for a Display Context (continued)

Attribute                       Default
────────────────────────────────────────────────────────────────────────────
Window extents                  (1,1)
Window origin                   (0,0)
────────────────────────────────────────────────────────────────────────────

An application can modify the attributes of the display context by using the
selection functions and display-context attribute functions. For example,
applications typically change the selected pen, brush, and font.

When a common display context is released, the current selections, such as
mapping mode and clipping area, are lost. Windows does not preserve the
previous selections of a common display context since these contexts are
shared and Windows has no way to guarantee that the next window to use a
given common display context will be the last window to use that context.
Applications that modify the attributes of a common display context must do
so each time another context is retrieved.


Class Display Context

A window has a class display context if the window class specifies the
CS_CLASSDC style. A class display context is shared by all windows in a
given class. A class display context is not part of the display context
cache. Instead, Windows specifically allocates a class context for sole use
by the window class.

A class display context must be retrieved before it can be used, but it does
not have to be released after use. As long as only one window from the class
uses the context, the class display context can be kept and reused. If
another window in the class needs to use the context, that window must
retrieve it before any drawing occurs. Retrieving the context sets the
correct origin and clipping for the new window and ensures that the context
will be applied to the correct window. A handle to the class display context
can be retrieved by using the GetDC or BeginPaint function. The ReleaseDC
and EndPaint functions have no effect on the class display context.

A class display context is given the same default selections as a common
display context when the first window of the class is created (see Table
1.4, "Defaults for a Display Context"). These selections can be modified at
any time. Windows preserves all new selections made for the class display
context, except for the clipping region and device origin, which are
adjusted for the current window when the context is retrieved. Otherwise,
all other attributes remain unchanged. This means a change made by one
window applies to all windows that subsequently use the context.

────────────────────────────────────────────────────────────────────────────
NOTE

Changing the mapping mode of a class display context may have an undesirable
effect on how a window's background is erased. For more information, see
Section 1.6.7, "Window Background," and Section 2.5, "Mapping Functions."
────────────────────────────────────────────────────────────────────────────


Private Display Context

A window has a private display context if the window class specifies the
CS_OWNDC style. A private display context is used exclusively by a given
window. A private display context is not part of the display context cache.
Instead, Windows specifically allocates the context for sole use by the
window.

A private display context needs to be retrieved only once. Thereafter, it
can be kept and used any number of times by the window. Windows
automatically updates the context to reflect changes to the window, such as
moving or sizing. A handle to a private display context can be retrieved by
using the GetDC or BeginPaint function. The ReleaseDC and EndPaint functions
have no effect on the private display context.

A private display context is given the same default selections as a common
display context when the window is created (see Table 1.4, "Defaults for a
Display Context"). These selections can be modified at any time. Windows
preserves any new selections made for the context. New selections, such as
clipping region and brush, remain selected until the window specifically
makes a change.

────────────────────────────────────────────────────────────────────────────
NOTE

Changing the mapping mode of a private display context may have an
undesirable effect on how the window's background is erased. For more
information, see Section 1.6.7, "Window Background," and Section 2.5,
"Mapping Functions."
────────────────────────────────────────────────────────────────────────────


Window Display Context

A window display context permits painting anywhere in a window, including
the caption bar, menus, and scroll bars. Its origin is the upper-left corner
of the window, instead of the upper-left corner of the client area.

The GetWindowDC function retrieves a window display context from the same
cache as it does common display contexts. Therefore, a window that uses a
window display context must release it with the ReleaseDC function
immediately after drawing.

Windows always sets the current selections of a window display context to
the same default selections as a common display context and does not
preserve any change the window may have made to these selections (see Table
1.4, "Defaults for a Display Context"). Windows does not allow private or
class window display contexts, so CS_OWNDC and CS_CLASSDC class styles have
no effect on the window display context.

A window display context is intended to be used for special painting within
a window's nonclient area. Since painting in nonclient areas of overlapped
windows is not recommended, most applications reserve a display context for
designing custom child windows. For example, an application may use the
display context to draw a custom border around the window. In such cases,
the window usually processes the WM_NCPAINT message instead of passing it on
to the DefWindowProc function. For applications that do not process
WM_NCPAINT messages but still wish to paint in the nonclient area, the
GetSystemMetrics function can be used to retrieve the dimensions of various
parts of the nonclient area, such as the caption bar, menu bar, and scroll
bars.


1.6.3  Display-Context Cache

Windows maintains a cache of display contexts that it uses for common and
window display contexts. This cache contains five display contexts, which
means only five common display contexts can be active at any one time. To
prevent more than five from being retrieved, a window that uses a common or
window display context must release that context immediately after drawing.


If a window fails to release a common display context, all five display
contexts may eventually be active and unavailable for any other window. In
such a case, Windows ignores all subsequent requests for a common display
context. In the retail version of Windows, the system will appear to be
deadlocked, while the debugging version of Windows will undergo a fatal
exit, alerting the developer of a problem.

The ReleaseDC function releases a display context and returns it to the
cache. Class and private display contexts are individually allocated for
each class or window; they do not belong to the cache so they do not need to
be released after use.


1.6.4  Painting Sequence

Windows carries out many operations to manage the system display that affect
the content of the client area. If Windows moves, sizes, or alters the
appearance of the display, the change may affect a given window. If so,
Windows marks the area changed by the operation as ready for updating and,
at the next opportunity, sends a WM_PAINT message to the window so that it
can update the window in the update region. If a window paints in its client
area, it must call the BeginPaint function to retrieve a handle to a display
context, must update the changed area as defined by the update region, and
finally, must call the EndPaint function to complete the operation.

A window is free to paint in its client area at any time, that is, at times
other than in response to a WM_PAINT message. The only requirement is that
it retrieve a display context for the client area before carrying out any
operations.


1.6.5  WM_PAINT Message

The WM_PAINT message is a request from Windows to a given window to update
its display. Windows sends a WM_PAINT message to a window whenever it is
necessary to repaint a portion of an application's window. When a window
receives a WM_PAINT message, it should retrieve the update region by using
the BeginPaint function, and it should carry out whatever operations are
necessary to update that part of the client area.

The InvalidateRect and InvalidateRgn functions do not actually generate
WM_PAINT messages. Instead, Windows accumulates the changes made by these
functions and its own changes while a window processes other messages in its
application queue. Postponing the WM_PAINT message lets a window process all
changes at once instead of updating bits and pieces in time-consuming
individual steps.

A window can require Windows to send a WM_PAINT message by using the
UpdateWindow function. The UpdateWindow function sends the message directly
to the window, regardless of the number of other messages in the application
queue. UpdateWindow is typically used when a window wants to update its
client area immediately, such as just after the window is created.

Once a window receives a WM_PAINT message, it must call the BeginPaint
function to retrieve the display context for the client area and to retrieve
other information such as the update region and whether the background has
been erased.

Windows automatically selects the update region as the clipping region of
the display context. Since GDI discards (clips) drawing that extends outside
the clipping region, only drawing that is in the update region is actually
visible. For more information about the clipping region, see Section 2.8,
"Clipping Functions."

The BeginPaint function empties the update region to prevent the same region
from generating subsequent WM_PAINT messages.

After completing the painting operation, the window must call the EndPaint
function to release the display context.


1.6.6  Update Region

An update region defines the part of the client area that is marked for
painting on the next WM_PAINT message. The purpose of the update region is
to save some applications the time it takes to paint the entire contents of
the client area. If only the part that needs painting is added to the update
region, only that part is painted. For example, if a word changes in the
client area of a word-processing application, only the word needs to be
painted, not the entire line of text. This saves the time it takes the
application to draw the text, especially if there are many different sizes
and typefaces.

The InvalidateRect and InvalidateRgn functions add a given rectangle or
region to the update region. The rectangle or region must be given in client
coordinates. The update region itself is defined in client coordinates.
Windows adds its own rectangles and regions to a window's update region
after operations such as moving, sizing, and scrolling the window.

The ValidateRect and ValidateRgn functions remove a given rectangle or
region from the update region. These functions are typically used when the
window has updated a specific part of the display in the update region
before receiving the WM_PAINT message.

The GetUpdateRect and GetUpdateRgn functions retrieve the smallest rectangle
that encloses the entire update region. These functions can be used to
compute the current size of the update region to determine if painting is
required.


1.6.7  Window Background

The window background is the color or pattern the client area is filled with
before a window begins painting in the client area. Windows paints the
background for a window or gives the window the opportunity to do so by
sending a WM_ERASEBKGND message to the window when the application calls the
BeginPaint function.

The background is important since if not erased, the client area will
contain whatever was originally on the system display before the window was
moved there. Windows erases the background by filling it with the background
brush specified by the window's class.

Windows applications that use class or private display contexts should be
careful about erasing the background. Windows assumes the background is to
be computed by using the MM_TEXT mapping mode. If the display context has
any other mapping mode, the area erased may not be within the visible part
of the client area.


1.6.8  Brush Alignment

Brush alignment is particularly important on the system display where
scrolling and moving are commonplace. A brush is a pattern of bits with a
minimum size of 8-by-8 bits. GDI paints with a brush by repeating the
pattern again and again within a given rectangle or region. If the region is
moved by an arbitrary amount─for example, if the window is scrolled─and the
brush is used again to filled empty areas around the original area, there is
no guarantee that the original pattern and the new pattern will be aligned.
For example, if the scroll moves the original filled area up one pixel, the
intersection of the original area and any new painting will be out of
alignment by one pixel, or bit. Depending on the pattern, this may have a
undesirable visual effect.

To ensure that a brush is aligned after a window is moved, an application
must take the following steps:


  1.  Call the SelectObject function to select a different brush.

  2.  Call the SetBrushOrg function to realign the current brush.

  3.  Call the UnrealizeObject function to realign the origin of the
      original brush when it is selected next.

  4.  Call the SelectObject function to select the original brush.



1.6.9  Painting Rectangular Areas

The FillRect, FrameRect, and InvertRect functions provide an easy way to
carry out painting operations on rectangles in the client area.

The FillRect function fills a rectangle with the color and pattern of a
given brush. This function fills all parts of the rectangle, including the
edges or borders.

The FrameRect function uses a brush to draw a border around a rectangle. The
border width and height is one unit.

The InvertRect function inverts the contents of the given rectangle. On
monochrome displays, white pixels become black, and vice versa. On color
displays, the results depend on the method used by the display to generate
color. In either case, calling InvertRect twice with the same rectangle
restores the display to its original colors.


1.6.10  Drawing Icons

The DrawIcon function draws an icon at a given location in the client area.
An icon is a bitmap that a window uses as a symbol to represent an item or
concept, such as an application or a warning.

An icon can be created by using the SDKPaint program, added to an
application's resources by using the Resource Compiler, and loaded into
memory by using the LoadIcon function. Applications can also call the
CreateIcon function to create an icon and can modify a previously loaded or
created icon at any time. An icon resource is in global memory and its
handle is the handle to that memory. An application can free memory used to
store an icon created by CreateIcon by calling DeleteIcon.


1.6.11  Drawing Formatted Text

The DrawText function formats and draws text within a given rectangle in the
client area. This function provides simple text processing that most
applications, other than word processors, can use to display text. DrawText
output is similar to the output generated by a terminal, except it uses the
selected font and can clip the text if it extends outside a given rectangle.
DrawText provides many different formatting styles. Table 1.5 lists the
styles that are available:

Table 1.5  Text Formatting Styles

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Description
────────────────────────────────────────────────────────────────────────────
DT_BOTTOM                         Bottom-justified (single line only).

DT_CENTER                         Centered.

DT_EXPANDTABS                     Expands tab characters into spaces.
                                  Otherwise, tabs are treated as single
                                  characters. The number of spaces depends
                                  on the tab stop size specified by
                                  DT_TABSTOP. If DT_TABSTOP is not given,
                                  the default is eight spaces.

DT_EXTERNALLEADING                Includes the font external leading in
                                  line height. External leading is not
                                  included in the height of a line of text.
                                  (Leading is the space between lines of
                                  text.)  If DT_EXTERNALLEADING is not
                                  given, there is no spacing between lines
                                  of text. Depending on the selected font,
                                  this means that characters in different
Value                             Description
────────────────────────────────────────────────────────────────────────────
                                  this means that characters in different
                                  lines may touch or overlap.

DT_LEFT                           Left-justified. Default.

DT_NOCLIP                         Draws text without clipping. All text
                                  will be drawn even if it extends outside
                                  the specified rectangle. The DrawText
                                  function is somewhat faster when
                                  DT_NOCLIP is used.

DT_RIGHT                          Right-justified.

DT_SINGLELINE                     Single line only. Carriage returns and
                                  linefeeds do not break the line. Default
                                  is multiple-line formatting.

DT_TABSTOP                        Sets tab stops. The high-order byte of
                                  the wFormat parameter is the number of
Value                             Description
────────────────────────────────────────────────────────────────────────────
                                  the wFormat parameter is the number of
                                  characters for each tab. If DT_TABSTOP
                                  is not given, the default tab size is
                                  eight spaces.

DT_TOP                            Top-justified (single line only).
                                  Default.

DT_VCENTER                        Vertically centered (single line only).

DT_WORDBREAK                      Sets word breaks. Lines are
                                  automatically broken between words if a
                                  word would extend past the edge of the
                                  rectangle specified by the lpRect
                                  parameter. Carriage-return/linefeed
                                  sequence also causes a line break.
                                  Word-break characters are space, tab,
                                  carriage return, linefeed, and
                                  carriage-return/linefeed combinations.
Value                             Description
────────────────────────────────────────────────────────────────────────────
                                  carriage-return/linefeed combinations.
                                  Applies to multiple-line formatting only.

────────────────────────────────────────────────────────────────────────────



The DrawText function uses the selected font, so applications can draw
formatted text in other than the system font.

DrawText does not hyphenate, and although it can justify text to the left,
right, or center, it cannot combine justification styles. In other words, it
cannot justify both left and right.

DrawText recognizes a number of control characters and carries out special
actions when it encounters them. Table 1.6 lists the control characters and
the respective action:

Table 1.6  DrawText Control Characters

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Character (ANSI value)            Action
────────────────────────────────────────────────────────────────────────────
Carriage return(13)               Interpreted as a line-break character.
                                  The text is immediately broken and
                                  started on the next line down in the
                                  rectangle.

Linefeed(10)                      Interpreted as a line-break character.
                                  The text is immediately broken and
                                  started on the next line down in the
                                  rectangle.

                                  A carriage-return/linefeed character
                                  combination is interpreted as a single
                                  line-break character.

Space(32)                         Interpreted as a word-break character if
                                  the DT_WORDBREAK style is given. If the
                                  text is too long to fit on the current
Character (ANSI value)            Action
────────────────────────────────────────────────────────────────────────────
                                  text is too long to fit on the current
                                  line in the formatting rectangle, the
                                  line is broken at the closest word-break
                                  character to the end of the line.

Tab(9)                            Expanded into a given number of spaces
                                  if the DT_EXPANDTABS style is given. The
                                  number of spaces depends on what
                                  tab-stop value is given with the
                                  DT_TABSTOP style. The default is eight.

────────────────────────────────────────────────────────────────────────────




1.6.12  Drawing Gray Text

An application can draw gray text by calling the SetTextColor function to
set the current text color to the COLOR_GRAYTEXT, the solid gray system
color used to draw disabled text. However, if the curent display driver does
not support a solid gray color, this value is set to zero.

The GrayString function is a multiple-purpose function that gives
applications another way to gray text or carry out other customized
operations on text or bitmaps before drawing the result in a client area. To
gray text, the function creates a memory bitmap, draws the string in the
bitmap, and then grays the string by combining it with a gray brush. The
GrayString function finally copies the gray text to the display. An
application can intercept or modify each step of this process, however, to
carry out custom effects, such as changing the gray brush to a patterned
brush or drawing an icon instead of a string.

If GrayString is used to draw gray text only, GrayString uses the selected
font of the given display context. GrayString sets text color to black. It
creates a bitmap, and then uses the TextOut function to write a given string
to the bitmap. It then uses the PatBlt function and a gray brush to gray the
text, and uses the BitBlt function to copy the bitmap to the client area.

GrayString assumes that the display context for the client area has MM_TEXT
mapping mode. Other mapping modes cause undesirable results.

GrayString lets an application modify this graying procedure in three ways:
by defining an additional brush to be combined with the text before being
displayed, by replacing the call to the TextOut function with a call to an
application-supplied function, and by disabling the call to the PatBlt
function.

The additional brush is defined as a parameter. This brush is combined with
the text as the text is being copied to the client area by the BitBlt
function. The additional brush is intended to be used to give the text a
desired color, since the bitmap used to draw the text is a monochrome
bitmap.

The application-supplied function is also defined as a parameter. If a
non-NULL value is given for the function, GrayString automatically calls the
application-supplied function instead of the TextOut function and passes it
a handle to the display context for the memory bitmap as well as the long
pointer and count passed to GrayString. The function can carry out any
operation and interpret the long pointer and count in any way. For example,
a negative count could be used to indicate that the long pointer points to
an icon handle that signals the application-supplied function to draw the
icon and let GrayString gray and display it. No matter what type of drawing
the function carries out, GrayString assumes it is successful if the
application-supplied function returns TRUE.

GrayString suppresses graying if it receives an ncount parameter equal to -1
and the application-supplied function returns FALSE. This is a way to
combine custom patterns with the text without interference from the gray
brush.


1.6.13  Nonclient-Area Painting

Windows sends a WM_NCPAINT message to the window whenever the non-client
area of the window, such as the title bar, menu bar, and window frame, needs
painting. Processing this message is not recommended since a window that
does so must be able to paint all the required parts of the nonclient area
for the window. In other words, a window should pass this message on to the
DefWindowProc function for default processing unless the Windows application
is creating a custom nonclient area for a child window.


1.7  Dialog-Box Functions

Dialog-box functions create, alter, test, and destroy dialog boxes and
controls within dialog boxes. A dialog box is a temporary window that
Windows creates for special-purpose input, and then destroys immediately
after use. An application typically uses a dialog box to prompt the user for
additional information about a current command selection. The following list
briefly describes each dialog function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CheckDlgButton                    Places/removes a check, or changes the
                                  state of the three-state button.

CheckRadioButton                  Checks a specified button and removes
                                  checks from all others.

CreateDialog                      Creates a modeless dialog box.

CreateDialogIndirect              Creates a modeless dialog box from a
                                  template.

CreateDialogIndirectParam         Creates a modeless dialog box from a
                                  template and passes data to it when it
                                  is created.

CreateDialogParam                 Creates a modeless dialog box and passes
                                  data to it when it is created.

DefDlgProc                        Provides default processing for any
                                  Windows messages that a dialog box with
                                  a private window class does not process.

DialogBox                         Creates a modal dialog box.

DialogBoxIndirect                 Creates a modal dialog box from a
                                  template.

DialogBoxIndirectParam            Creates a modal dialog box from a
                                  template and passes data to it when it
                                  is created.

DialogBoxParam                    Creates a modal dialog box and passes
                                  data to it when it is created.

DlgDirList                        Fills the list box with names of files
                                  matching a path.

DlgDirListComboBox                Fills a combo box with names of files
                                  matching a path.

Function                          Description
────────────────────────────────────────────────────────────────────────────
DlgDirSelect                      Copies the current selection from a list
                                  box to a string.

DlgDirSelectComboBox              Copies the current selection from a
                                  combo box to a string.

EndDialog                         Frees resources and destroys windows
                                  associated with a modal dialog box.

GetDialogBaseUnits                Retrieves the base dialog units used by
                                  Windows when creating a dialog box.

GetDlgCtrlID                      Returns the ID value of a control window.

GetDlgItem                        Retrieves the handle of a dialog item
                                  from the given dialog box.

GetDlgItemInt                     Translates the control text of an item
                                  into an integer value.

GetDlgItemText                    Copies an item's control text into a
                                  string.

GetNextDlgGroupItem               Returns the window handle of the next
                                  item in a group.

GetNextDlgTabItem                 Returns the window handle of the next or
                                  previous item.

IsDialogMessage                   Determines whether a message is intended
                                  for the given dialog box.

IsDlgButtonChecked                Tests whether a button is checked.

MapDialogRect                     Converts the dialog-box coordinates to
                                  client coordinates.

SendDlgItemMessage                Sends a message to an item within a
                                  dialog box.

SetDlgItemInt                     Sets the caption or text of an item to a
                                  string that represents an integer.

SetDlgItemText                    Sets the caption or text of an item to a
                                  string.


1.7.1  Uses for Dialog Boxes

For convenience and to keep from introducing device-dependent values into
the application code, applications use dialog boxes instead of creating
their own windows. This device independence is maintained by using logical
coordinates in the dialog-box template. Dialog boxes are convenient to use
because all aspects of the dialog box, except how to carry out its tasks,
are predefined. Dialog boxes supply a window class and procedure, and create
the window for the dialog box automatically. The application supplies a
dialog function to carry out tasks and a dialog-box template that describes
the dialog style and content.


Modeless Dialog Box

A modeless dialog box allows the user to supply information to the dialog
box and return to the previous task without canceling or removing the dialog
box. Modeless dialog boxes are typically used as a way to let the user
continually supply information about the current task without having to
select a command from a menu each time. For example, modeless dialog boxes
are often used with a text-search command in word-processing applications.
The dialog box remains displayed while the search is carried out. The user
can then return to the dialog box and search for the same word again, or
change the entry in the dialog box and search for a new word.

An application with a modeless dialog box processes messages for that box by
using the IsDialogMessage function inside the main message loop. The dialog
function of a modeless dialog box must send a message to the parent window
when it has input for the parent window. It must also destroy the dialog box
when it is no longer needed. A modeless dialog box can be destroyed by using
the DestroyWindow function. An application must not call the EndDialog
function to destroy a modeless dialog box.


Modal Dialog Box

A modal dialog box requires the user to respond to a request before the
application continues. Typically, a modal dialog box is used when a chosen
command needs additional information before it can proceed. The user should
not be able to continue some other operation unless the command is canceled
or additional information is provided.

A modal dialog box disables its parent window, and it creates its own
message loop, temporarily taking control of the application queue from the
main loop of the program. A modal dialog box is displayed when the
application calls the  DialogBox function.

By default, a modal dialog box cannot be moved by the user. An application
can create a moveable dialog box by specifying the WS_CAPTION and,
optionally, the WS_SYSMENU window styles.

The dialog box is displayed until the dialog function calls the EndDialog
function, or until Windows is terminated. The parent window remains disabled
unless the dialog box enables it. Note that enabling the parent window is
not recommended since it defeats the purpose of the modal dialog box.


System-Modal Dialog Box

A system-modal dialog box is identical to a modal dialog box except that all
windows, not just the parent window, are disabled. System-modal dialog boxes
must be used with care since they effectively shut down the system until the
user supplies the required information.


1.7.2  Creating a Dialog Box

A dialog box is created by using either the CreateDialog or DialogBox
function. These functions load a dialog-box template from the application's
executable file, and then create a pop-up window that matches the template's
specifications. The dialog box belongs to the predefined dialog-box class
unless another class is explicitly defined. The DialogBox function creates a
modal dialog box; the CreateDialog function creates a modeless dialog box.

Use the WS_VISIBLE style for the dialog-box template if you want the dialog
box to appear upon creation.


Dialog-Box Template

The dialog-box template is a description of the dialog box: its height and
width, the controls it contains, its style, the type of border it uses, and
so on. A template is an application's resource and must be added to the
application's executable file by using the Resource Compiler.

Dialog boxes can be easily modified and are system independent, enabling an
application developer to change the template without changing the source
code.

The CreateDialog and DialogBox functions load the resource into memory when
they create the dialog box, and then use the information in the dialog
template to create the dialog box, position it, and create and position the
controls for the dialog box.

The Resource Compiler takes a text description of the template and converts
it to the required binary form. This binary form is added to the
application's executable file.


Dialog-Box Measurements

Dialog box and control dimensions and coordinates are device independent.
Since a dialog box may be displayed on system displays that have widely
varying pixel resolutions, dialog-box dimensions are specified in system
character widths and heights instead of pixels. Characters are guaranteed to
give the best possible appearance for a given display. One unit in the x
direction is equal to 1/4 of the dialog base width unit. One unit in the y
direction is equal to 1/8 of the dialog base height unit. The dialog base
units are computed from the height and width of the system font; the
GetDialogBaseUnits function returns the dialog base units for the current
display. Applications can convert these measurements to pixels by using the
MapDialogRect function.

Windows does not allow the height of a dialog box to exceed the height of a
full-screen window. The width of a dialog box is not allowed to be greater
than the width of the screen.


1.7.3  Return Values from a Dialog Box

The DialogBox function that creates a modal dialog box does not return until
the dialog function has called the EndDialog function to signal the end of
the dialog box. When control finally returns from the DialogBox function,
the return value is equal to the value specified in the EndDialog function.
This means a modal dialog box can return a value through the EndDialog
function.

Modeless dialog boxes cannot return values in this way since they do not use
the EndDialog function to terminate execution and do not return control in
the same way a modal dialog box does. Instead, modeless dialog boxes return
values to their parent windows by using the SendMessage function to send a
notification message to the parent window. Although Windows does not
explicitly define the content of a notification message, most applications
use a WM_COMMAND message with an integer value that identifies the dialog
box in the wParam parameter and the return value in the lParam parameter.
Modal dialog boxes may also use this technique to return values to their
parent windows before terminating.


1.7.4  Controls in a Dialog Box

A dialog box can contain any number and any type of controls. A control is a
child window that belongs to a predefined or application-defined window
class and that gives the user a method of supplying input to the
application. Examples of controls are push buttons and edit controls. Most
dialog boxes contain one or more controls of the predefined class. The
number of controls, the order in which they should be created, and the
location of each in the dialog box are defined by the control statements
given in the dialog-box template.


Control Identifiers

Every control in a dialog box needs a unique control identifier, or ID, to
distinguish it from other controls. Since all controls send information to
the dialog function through WM_COMMAND messages, the control identifiers are
essential for the dialog box to determine which control sent a given
message.

All identifiers for all controls in the dialog box must be unique. If a
dialog box has a menu bar, there must be no conflict between menu-item
identifiers and control identifiers. Since Windows sends menu input to a
dialog function as WM_COMMAND messages, conflicts with menu and control
identifiers can cause errors. Menus in dialog boxes are not recommended.

The dialog function usually identifies the dialog-box controls by using
their control identifier. Occasionally the dialog function requires the
window handle that was given to the control when it was created. The dialog
function can retrieve this window handle by using the GetDlgItem function.


General Control Styles

The WS_TABSTOP style specifies that the user can move the input focus to the
given control by pressing the TAB or SHIFT+TAB keys. Typically, every
control in the dialog box has this style, so the user can move the input
focus from one control to the other. If two or more controls are in the
dialog box, the TAB key moves the input focus to the controls in the order
in which they have been created. The SHIFT+TAB keys move the input focus in
reverse order. For modal dialog boxes, the TAB and SHIFT+TAB keys are
automatically enabled for moving the input focus. For modeless dialog boxes,
the IsDialogMessage function must be used to filter messages for the dialog
box and to process these key strokes. Otherwise, the keys have no special
meaning and the WS_TABSTOP style is ignored.

The WS_GROUP style specifies that the user can move the input focus to the
given control by using a DIRECTION key. Typically, the first and last
controls in a group of consecutive controls in the dialog box have this
style, so the user can move the input focus from one control to the other.
The DOWN and RIGHT keys move the input focus to controls in the order in
which they have been created. The UP and LEFT keys move the input focus in
reverse order. For modal dialog boxes, the DIRECTION keys are automatically
enabled for moving the input focus. For modeless dialog boxes, the
IsDialogMessage function must be used to filter messages for the dialog box
and to process these key strokes. Otherwise, the keys have no special
meaning and the WS_GROUP style is ignored.


Buttons

Button controls are the principal interface of a dialog box. Almost all
dialog boxes have at least one push-button control and most have one default
push button and one or more other push buttons. Many dialog boxes have
collections of radio buttons enclosed in group boxes, or lists of check
boxes.

Most modal or modeless dialog boxes that use the special keyboard interface
have a default push button whose control identifier is set to 1 so that the
action the dialog function takes when the button is clicked is identical to
the action taken when the ENTER key is pressed. There can be only one button
with the default style; however, an application can assign the default style
to any button at any time. These dialog boxes may also set the control
identifier of another push button to 2 so that the action of the ESCAPE key
is duplicated by clicking that button.

When a dialog box first starts, the dialog function can set the initial
state of the button controls by using the CheckDlgButton function, which
sets or clears the button state. This function is most useful when used to
set the state of radio buttons or check boxes. If the dialog box contains a
group of radio buttons in which only one button should be set at any given
time, the dialog function can use the CheckRadioButton function to set the
button and automatically clear any other radio button.

Before a dialog box terminates, the dialog function can check the state of
each button control by using the IsDlgButtonChecked function, which returns
the current state of the button. A dialog box typically saves this
information to initialize the buttons the next time the dialog box is
created.


Edit Controls

Many dialog boxes have edit controls that let the user supply text as input.
Most dialog functions initialize an edit control when the dialog box first
starts. For example, the function may place a proposed filename in the
control that the user can adapt or modify. The dialog function can set the
text in an edit control by using the SetDlgItemText function, which copies
text in a given buffer to the edit control. When the edit control receives
the input focus, the complete text will automatically be selected for
editing.

Since edit controls do not automatically return their text to the dialog
box, the dialog function must retrieve the text before terminating. It can
retrieve the text by using the GetDlgItemText function, which copies the
edit-control text to a buffer. The dialog function typically saves this text
to initialize the edit control later, or passes it on to the parent window
for processing.

Some dialog boxes use edit controls that let the user enter numbers. The
dialog function can retrieve a number from an edit control by using the
GetDlgItemInt function, which retrieves the text of the control and converts
the text to a decimal value. The user enters the number in decimal digits.
It can be either signed or unsigned. The dialog function can display an
integer by using the SetDlgItemInt function. It converts a signed or
unsigned integer to a string of decimal digits.


List Boxes and Directory Listings

Some dialog boxes display lists, such as filenames, from which the user can
select one or more names. Dialog boxes that display a list typically use
list-box controls. Dialog boxes that display a list of filenames typically
use a list-box control and the DlgDirList and DlgDirSelect functions. The
DlgDirList function automatically fills a list box with the filenames in the
current directory. The DlgDirSelect function retrieves the selected filename
from the list box. Together they provide a convenient way for a dialog box
to display a directory listing, and let the user select a file without
having to type in the name of the directory and file.


Combo Boxes

Another method for providing a list of items to a user is by means of a
combo box. A combo box consists of either a static text field or edit field
combined with a list box. The list box can be displayed at all times or
pulled down by the user. If the combo box contains a static text field, the
text field always displays the current selection (if any) in the list-box
portion of the combo box. If it uses an edit field, the user can type in the
desired selection; the list box highlights the first item (if any) which
matches what the user has entered in the edit field. The user can then
select the item highlighted in the list box to complete the choice.


Owner-Draw Dialog-Box Controls

List boxes, combo boxes, and buttons can be designated as owner-draw
controls by creating them with the appropriate style:

Style                             Meaning
────────────────────────────────────────────────────────────────────────────
LBS_OWNERDRAWFIXED                Creates an owner-draw list box with
                                  items that have the same, fixed height.

LBS_OWNERDRAWVARIABLE             Creates an owner-draw list box with
                                  items that have different heights.

CBS_OWNERDRAWFIXED                Creates an owner-draw combo box with
                                  items that have the same, fixed height.

CBS_OWNERDRAWVARIABLE             Creates an owner-draw combo box with
                                  items that have different heights.

BS_OWNERDRAW                      Creates an owner-draw button.


When a control has the owner-draw style, Windows handles the user's
interaction with the control as usual, such as detecting when a user has
clicked a button and notifying the button's owner of the event. However,
because it is an owner-draw control, the owner of the control is completely
responsible for the visual appearance of the control.

When Windows first creates a dialog box containing owner-draw controls, it
sends the owner a WM_MEASUREITEM message for each owner-draw control. The
lParam parameter of this message contains a pointer to a MEASUREITEMSTRUCT
data structure. When the owner receives the message for a control, the owner
fills in the appropriate fields of the structure and returns. This informs
Windows of the dimensions of the control or of its items so that Windows can
appropriately detect the user's interaction with the control. If a list box
or combo box is created with the LBS_OWNERDRAWVARIABLE or
CBS_OWNERDRAWVARIABLE style, this message is sent to the owner for each item
in the control, since each item can differ in height. Otherwise, this
message is sent once for the entire owner-draw control.

Whenever an owner-draw control needs to be redrawn, Windows sends the
WM_DRAWITEM message to the owner of the control. The lParam parameter of
this message contains a pointer to a DRAWITEMSTRUCT data structure that
contains information about the drawing required for the control. Similarly,
if an item is deleted from a list box or combo box, Windows sends the
WM_DELETEITEM message containing a pointer to a DELETEITEMSTRUCT data
structure that describes the deleted item.


Messages for Dialog-Box Controls

Many controls recognize predefined messages that, when sent to the control,
cause it to carry out some action. A dialog function can send a message to a
control by supplying the control identifier and using the SendDlgItemMessage
function, which is identical to the SendMessage function except that it uses
a control identifier instead of a window handle to identify the control that
is to receive the message.


1.7.5  Dialog-Box Keyboard Interface

Windows provides a special keyboard interface for modal dialog boxes and
modeless dialog boxes that use the IsDialogMessage function to filter
messages. This keyboard interface carries out special processing for several
keys and generates messages that correspond to certain buttons in the dialog
box or changes the input focus from one control to another. Table 1.7 lists
the keys used in this interface and the respective action:

Table 1.7  Dialog-Box Keyboard Interface

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Key                               Action
────────────────────────────────────────────────────────────────────────────
DOWN                              Moves the input focus to the next
                                  control that has the WS_GROUP style.

ENTER                             Sends a WM_COMMAND message to the dialog
                                  function. The wParam parameter is set to
Key                               Action
────────────────────────────────────────────────────────────────────────────
                                  function. The wParam parameter is set to
                                  1 or the default button.

ESCAPE                            Sends a WM_COMMAND message to the dialog
                                  function. The wParam parameter is set to
                                  2.

LEFT                              Same as UP.

RIGHT                             Same as DOWN.

SHIFT+TAB                         Moves the input focus to the previous
                                  control that has the WS_TABSTOP style.



Table 1.7  Dialog-Box Keyboard Interface (continued)

Key                               Action
────────────────────────────────────────────────────────────────────────────
TAB                               Moves the input focus to the next
                                  control that has the WS_TABSTOP style.

UP                                Moves the input focus to the previous
                                  control that has the WS_GROUP style.

────────────────────────────────────────────────────────────────────────────


The TAB and DIRECTION keys have no effect if the controls in the dialog box
do not have the WS_TABSTOP or WS_GROUP style. The keys have no effect in a
modeless dialog box if the IsDialogMessage function is not used to filter
messages for the dialog box.

────────────────────────────────────────────────────────────────────────────
NOTE

For applications that use accelerators and have modeless dialog boxes, the
IsDialogMessage function must be called before the TranslateAccelerator
function. Otherwise, the keyboard interface for the dialog box may not be
processed correctly.
────────────────────────────────────────────────────────────────────────────

Applications that have modeless dialog boxes and want those boxes to have
the special keyboard interface must filter all messages retrieved from the
application queue through the IsDialogMessage function before carrying out
any other processing. This means that the application must pass the message
to the function immediately after retrieving the message by using the
GetMessage or PeekMessage function. Most applications that have modeless
dialog boxes incorporate the IsDialogMessage function as part of the main
message loop in the WinMain function. The IsDialogMessage function
automatically processes any messages for the dialog box. This means that if
the function returns a nonzero value, the message does not require
additional processing and must not be passed to the TranslateMessage or
DispatchMessage function.

The IsDialogMessage function also processes the ALT+mnemonic sequence.


Scrolling in Dialog Boxes

In modal dialog boxes, the DIRECTION keys have specific functions that
depend on the controls in the box. For example, the keys move the input
focus from control to control in group boxes, move the cursor in edit
controls, and scroll the contents of list boxes. The DIRECTION keys cannot
be used to scroll the contents of any dialog box that has its own scroll
bars. If a dialog box has scroll bars, the application must provide an
appropriate keyboard interface for the scroll bars. Note that the mouse
interface for scrolling is available if the system has a mouse.


1.8  Scrolling Functions

Scrolling functions control the scrolling of a window's contents and control
the window's scroll bars. Scrolling is the movement of data in and out of
the client area at the request of the user. It is a way for the user to see
a document or graphic in parts if Windows cannot fit the entire document or
graphic inside the client area. A scroll bar allows the user to control
scrolling. The following list briefly describes each scrolling function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetScrollPos                      Retrieves the current position of the
                                  scroll-bar thumb.

GetScrollRange                    Copies the minimum and maximum
                                  scroll-bar positions for given
                                  scroll-bar positions for a specified
                                  scroll.

ScrollDC                          Scrolls a rectangle of bits horizontally
                                  and vertically.

ScrollWindow                      Moves the contents of the client area.

SetScrollPos                      Sets the scroll-bar thumb.

SetScrollRange                    Sets the minimum and maximum scroll-bar
                                  positions.

ShowScrollBar                     Displays or hides a scroll bar and its
                                  controls.


1.8.1  Standard Scroll Bars and Scroll-Bar Controls

A standard scroll bar is a part of the nonclient area of a window. It is
created with the window and displayed when the window is displayed. The sole
purpose of a standard scroll bar is to let users generate scrolling requests
for the window's client area. A window has standard scroll bars if it is
created with the WS_VSCROLL or WS_HSCROLL style. A standard scroll bar is
either vertical or horizontal. A vertical bar always appears at the right of
the client area; a horizontal bar always appears at the bottom. A standard
scroll bar always has the standard scroll-bar height and width as defined by
the SM_CXVSCROLL and SM_CYHSCROLL system metric values. (For more
information, see the GetSystemMetrics function in Chapter 4, "Functions
Directory.")

A scroll-bar control is a control window that looks and acts like a standard
scroll bar. But unlike a standard scroll bar, a scroll-bar control is not
part of any window. As a separate window, a scroll-bar control can receive
the input focus, and indicates this by displaying a flashing caret in the
thumb. When a scroll-bar control has the input focus, the user can use the
keyboard to direct the scrolling. Unlike standard scroll bars, a scroll-bar
control provides a built-in keyboard interface. Scroll-bar controls also can
be used for other purposes. For example, a scroll-bar control can be used to
select values from a range of values, such as a color from a rainbow of
colors.


1.8.2  Scroll-Bar Thumb

The scroll-bar thumb is the small rectangle in a scroll bar. It shows the
approximate location within the current document or file of the data
currently displayed in the client area. For example, the thumb is in the
middle of the scroll bar when page three of a five-page document is in the
client area.

The SetScrollPos function sets the thumb position in a scroll bar. Since
Windows does not automatically update the thumb position when an application
scrolls, SetScrollPos must be used to update the thumb position. The
GetScrollPos function retrieves the current position.

A thumb position is an integer. The position is relative to the left or
upper end of the scroll bar, depending on whether the scroll bar is
horizontal or vertical. The position must be within the scroll-bar range,
which is defined by minimum and maximum values. The positions are
distributed equally along the scroll bar. For example, if the range is 0 to
100, there are 100 positions along the scroll bar, each equally spaced so
that position 50 is in the middle of the scroll bar. The initial range
depends on the scroll bar. Standard scroll bars have an initial range of 0
to 100; scroll-bar controls have an empty range (both minimum and maximum
values are zero) if no explicit range is given when the control is created.
The SetScrollRange function sets new minimum and maximum values so that
applications can change the range at any time. The GetScrollRange function
retrieves the current minimum and maximum values. The minimum and maximum
values can be any integers. For example, a spreadsheet program with 255 rows
can set the vertical scroll range to 1 to 255.

If SetScrollPos specifies a position value that is less than the minimum or
more than the maximum, the minimum or maximum value is used instead.
SetScrollPos moves the thumb along the thumb positions.


1.8.3  Scrolling Requests

A user makes a scrolling request by clicking in a scroll bar. Windows sends
the request to the given window in the form of WM_HSCROLL and WM_VSCROLL
messages. The lParam parameter contains a position value and the handle of
the scroll-bar control that generated the message (lParam is zero if a
standard scroll bar generated the message). The wParam parameter specifies
the type of scroll, such as scroll up one line, scroll down a page, or
scroll to the bottom. The type of scroll is determined by which area of the
scroll bar the user clicks.

The user can also make a scrolling request by using the scroll-bar thumb,
the small rectangle inside the scroll bar. The user moves the thumb by
moving the mouse while holding the left mouse button down when the cursor is
in the thumb. The scroll bar sends SB_THUMBTRACK and SB_THUMBPOSITION flags
with a WM_HSCROLL or WM_VSCROLL message to an application as the user moves
the thumb. Each message specifies the current position of the thumb.


1.8.4  Processing Scroll Messages

A window that permits scrolling needs a standard scroll bar or a scroll-bar
control to let the user generate scrolling requests, and a window function
to process the WM_HSCROLL and WM_VSCROLL messages that represent the
scrolling requests. Although the result of a scrolling request is entirely
up to the window, a window typically carries out a scroll by moving in some
direction from the current location or to a known beginning or end, and by
displaying the data at the new location. For example, a word-processing
application can scroll to the next line, the next page, or to the end of the
document.


1.8.5  Scrolling the Client Area

The simplest way to scroll is to erase the current contents of the client
area, and then paint the new information. This is the method an application
is likely to use with SB_PAGEUP, SB_PAGEDOWN, SB_TOP, and SB_END requests
where completely new contents are required.

For some requests, such as SB_LINEUP and SB_LINEDOWN, not all the contents
need to be erased, since some will still be visible after the scroll. The
ScrollWindow function preserves a portion of the client area's contents,
moves the preserved portion the specified amount, and prepares the rest of
the client area for painting new information. ScrollWindow uses the BitBlt
function to move a specific part of the client area to a new location within
the client area. Any part of the client area that is uncovered (not in the
part to be preserved) is invalidated and will be erased and painted over at
the next WM_PAINT message.

ScrollWindow also lets an application clip a part of the client area from
the scroll. This is to keep items that have fixed positions in the client
area, such as child windows, from moving. This action automatically
invalidates the part of the client area that is to receive the new
information so that the application does not have to compute its own
clipping regions.


1.8.6  Hiding a Standard Scroll Bar

For standard scroll bars, if the minimum and maximum values are equal, the
scroll bar is considered disabled and is hidden. This is the way to
temporarily hide a scroll bar when it is not needed for the current contents
of the client area.

The SetScrollRange function hides and disables a standard scroll bar when it
sets the minimum and maximum values to equal values. No scrolling requests
can be made through the scroll bar when it is hidden. SetScrollRange enables
the scroll bar and shows it again when it sets the minimum and maximum
values to unequal values. The ShowScrollBar function can also be used to
hide or show a scroll bar. It does not affect the scroll bar's range or
thumb position.


1.9  Menu Functions

Menu functions create, modify, and destroy menus. A menu is an input tool in
a Windows application that offers users one or more choices, which they can
select with the mouse or keyboard. An item in a menu bar can display a
pop-up menu, and any item in a pop-up menu can display another pop-up menu.
In addition, a pop-up menu can appear anywhere on the screen. The following
list briefly describes each menu function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AppendMenu                        Appends a menu item to a menu.

CheckMenuItem                     Places or removes checkmarks next to
                                  pop-up menu items.

CreateMenu                        Creates an empty menu.

CreatePopupMenu                   Creates an empty pop-up menu.

DeleteMenu                        Removes a menu item and destroys any
                                  associated pop-up menus.

DestroyMenu                       Destroys the specified menu.

DrawMenuBar                       Redraws a menu bar.

EnableMenuItem                    Enables, disables, or grays a menu item.

GetMenu                           Retrieves a handle to the menu of a
                                  specified window.

GetMenuCheckMarkDimensions        Retrieves the dimensions of the default
                                  menu checkmark bitmap.

GetMenuItemCount                  Returns the count of items in a menu.

GetMenuItemID                     Returns the item's identification.

GetMenuState                      Obtains the status of a menu item.

GetMenuString                     Copies a menu label into a string.

GetSubMenu                        Retrieves the menu handle of a pop-up
                                  menu.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetSystemMenu                     Accesses the System menu for copying and
                                  modification.

HiliteMenuItem                    Highlights or removes the highlighting
                                  from a top-level (menu-bar) menu item.

InsertMenu                        Inserts a menu item in a menu.

LoadMenuIndirect                  Loads a menu resource.

ModifyMenu                        Changes a menu item.

RemoveMenu                        Removes an item from a menu but does not
                                  destroy it.

SetMenu                           Specifies a new menu for a window.

SetMenuItemBitmaps                Associates bitmaps with a menu item for
                                  display when an item is and is not
                                  checked.

TrackPopupMenu                    Displays a pop-up menu at a specified
                                  screen location and tracks user
                                  interaction with the menu.


1.10  Information Functions

Information functions obtain information about the number and position of
windows on the screen. The following list briefly describes each information
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AnyPopup                          Indicates whether any pop-up window
                                  exists.

ChildWindowFromPoint              Determines which child window contains a
                                  specific point.

EnumChildWindows                  Enumerates the child windows that belong
                                  to a specific parent window.

EnumTaskWindows                   Enumerates all windows associated with a
                                  given task.

EnumWindows                       Enumerates windows on the display.

FindWindow                        Returns the handle of a window with the
                                  given class and caption.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetNextWindow                     Returns a handle to the next or previous
                                  window.

GetParent                         Retrieves the handle of the specified
                                  window's parent window.

GetTopWindow                      Returns a handle to the top-level child
                                  window.

GetWindow                         Returns a handle from the window
                                  manager's list.

GetWindowTask                     Returns the handle of a task associated
                                  with a window.

IsChild                           Determines whether a window is the
                                  descendent of a specified window.

IsWindow                          Determines whether a window is a valid,
                                  existing window.

SetParent                         Changes the parent window of a child
                                  window.

WindowFromPoint                   Identifies the window containing a
                                  specified point.


1.11  System Functions

System functions return information about the system metrics, color, and
time. The following list briefly describes each system function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetCurrentTime                    Returns the time elapsed since the
                                  system was booted.

GetSysColor                       Retrieves the system color.

GetSystemMetrics                  Retrieves information about the system
                                  metrics.

SetSysColors                      Changes one or more system colors.


1.12  Clipboard Functions

Clipboard functions carry out data interchange between Windows applications.
The clipboard is the place for this interchange; it provides a place from
which applications can pass data handles to other applications. The
following list briefly describes each clipboard function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ChangeClipboardChain              Removes a window from the chain of
                                  clipboard viewers.

CloseClipboard                    Closes the clipboard.

EmptyClipboard                    Empties the clipboard and reassigns
                                  clipboard ownership.

EnumClipboardFormats              Enumerates the available clipboard
                                  formats.

GetClipboardData                  Retrieves data from the clipboard.

GetClipboardFormatName            Retrieves the clipboard format.

GetClipboardOwner                 Retrieves the window handle associated
                                  with the current clipboard owner.

GetClipboardViewer                Retrieves the handle of the first window
                                  in the clipboard viewer chain.

GetPriorityClipboardFormat        Retrieves data from the clipboard in the
                                  first format in a prioritized format
                                  list.

IsClipboardFormatAvailable        Returns TRUE if the data in the given
                                  format is available.

OpenClipboard                     Opens the clipboard.

RegisterClipboardFormat           Registers a new clipboard format.

SetClipboardData                  Copies a handle for data.

SetClipboardViewer                Adds a handle to the clipboard viewer
                                  chain.


1.13  Error Functions

Error functions display errors and prompt the user for a response. The
following list briefly describes each error function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
FlashWindow                       Flashes the window by inverting its
                                  active/inactive state.

MessageBeep                       Generates a beep on the system speaker.

MessageBox                        Creates a window with the given text and
                                  caption.


1.14  Caret Functions

Caret functions affect the Windows caret, which is a flashing line, block,
or bitmap that marks a location in a window's client area. The caret is
especially useful in word-processing applications to mark a location in text
for keyboard editing. These functions create, destroy, display, hide, and
alter the blink time of the caret. The following list briefly describes each
caret function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateCaret                       Creates a caret.

DestroyCaret                      Destroys the current caret.

GetCaretBlinkTime                 Returns the caret flash rate.

GetCaretPos                       Returns the current caret position.

HideCaret                         Removes a caret from a given window.

SetCaretBlinkTime                 Establishes the caret flash rate.

SetCaretPos                       Moves a caret to the specified position.

ShowCaret                         Displays the newly created caret or
                                  redisplays a hidden caret.


1.14.1  Creating and Displaying a Caret

Windows forms a caret by inverting the pixel color within the rectangle
given by the caret's position and its width and height. Windows flashes the
caret by alternately inverting the display, and then restoring it to its
previous appearance. The caret blink time (in milliseconds) defines the
elapsed time between inverting and restoring the display. A complete flash
(on-off-on) takes twice the blink time.

The CreateCaret function creates the caret shape and assigns ownership of
the caret to the given window. The caret can be solid or gray, or, for
bitmap carets, any desired pattern. The caret can have any shape, but
typical shapes are a line, a solid block, a gray block, and a pattern, as
shown in Figure 1.1:

(This figure may be found in the printed book.)

Windows displays a solid caret by inverting everything in the rectangle
defined by the caret's width and height. For a gray caret, Windows inverts
every other pixel. For a pattern, Windows inverts only the white bits of the
bitmap that defines the pattern. The width and height of a caret are given
in logical units, which means they are subject to the window's mapping mode.



1.14.2  Sharing the Caret

There is only one caret, so only one caret shape can be active at a time.
Applications must cooperatively share the caret to prevent undesired
effects. Windows does not inform an application when a caret is created or
destroyed, so to be cooperative a window should create, move, show, and hide
a caret only when it has the input focus or is active. A window should
destroy the caret before losing the input focus or becoming inactive.

Bitmaps for the caret can be created by using the CreateBitmap function, or
loaded from the application's resources by using the LoadBitmap function.
Bitmaps loaded from resources can be created by using the SDKPaint program
and added to an application's resources by using the Resource Compiler. (For
more information about the Resource Compiler, see Tools.)


1.15  Cursor Functions

Cursor functions set, move, show, hide, and confine the cursor. The cursor
is a bitmap, displayed on the display screen, that shows a current location.
The following list briefly describes each cursor function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ClipCursor                        Restricts the cursor to a given
                                  rectangle.

CreateCursor                      Creates a cursor from two bit masks.

DestroyCursor                     Destroys a cursor created by the
                                  CreateCursor function.

GetCursorPos                      Stores the cursor position (in screen
                                  coordinates).

LoadCursor                        Loads a cursor from the resource file.

SetCursor                         Sets the cursor shape.

SetCursorPos                      Sets the position of the cursor.

ShowCursor                        Increases or decreases the cursor
                                  display count.


1.15.1  Pointing Devices and the Cursor

When a system has a mouse (or any other type of pointing device), the cursor
shows the current location of the mouse. Windows automatically displays and
moves the cursor when the mouse is moved. If a system does not have a mouse,
Windows does not automatically display or move the cursor. Applications can
use the cursor functions to display or move the cursor when a system does
not have a mouse.


1.15.2  Displaying and Hiding the Cursor

In a system without a mouse, Windows does not display or move the cursor
unless the user chooses certain system commands, such as commands for sizing
and moving. This means that after a call to SetCursor, the cursor remains on
the screen until a subsequent call to SetCursor with a NULL parameter
removes the cursor, or until a system command is carried out. Applications
that wish to use the cursor without a mouse usually simulate mouse input by
using keyboard keys, such as the DIRECTION keys, and display and move the
cursor by using the cursor functions.

The ShowCursor function shows or hides the cursor. It is used to temporarily
hide the cursor, and then restore it without changing the current cursor
shape. This function actually sets an internal counter that determines
whether the cursor should be drawn. Hiding and showing are accumulative, so
hiding the cursor five times requires that it be shown five times before the
cursor will be drawn.


1.15.3  Positioning the Cursor

The SetCursorPos and GetCursorPos functions set and retrieve the current
screen coordinates of the cursor. Although the cursor can be set at a
location other than the current mouse location, if the system has a mouse,
the next mouse movement will redraw the cursor at the mouse location. The
SetCursorPos and GetCursorPos functions are most often used in applications
that use the keyboard and specified key strokes to move the cursor. Notice
that screen coordinates are not affected by the mapping mode in a window's
client area.


1.15.4  The Cursor Hotspot and Confining the Cursor

A cursor has a hotspot. When Windows draws the cursor, it always places the
hotspot over the point on the display screen that represents the current
position of the mouse or keyboard DIRECTION key. For example, the hotspot on
the pointer is the point at the tip of the arrow.

The ClipCursor function confines the cursor to a given rectangle on the
display screen. The cursor can move to the edge of the rectangle but cannot
move out of it. ClipCursor is typically used to restrict the cursor to a
given window such as a dialog box that contains a warning about a serious
error. The rectangle is always given in screen coordinates and does not have
to be within the window of the currently running application.


1.15.5  Creating a Custom Cursor

The SetCursor function sets the cursor shape and draws the cursor. When a
system has a mouse, Windows automatically changes the shape of the cursor
when it crosses a window border or enters a different part of a window, such
as a title or menu bar. It uses standard cursor shapes for the different
parts of the screen, such as a pointer in a title bar. The SetCursor
function lets an application delete the standard cursor and draw its own
custom cursor. The cursor keeps its new shape until the mouse moves or a
system command is carried out.


1.16  Hook Functions

Hook functions manage system hooks, which are shared resources that install
a specific type of filter function. A filter function is an
application-supplied callback function, specified by the SetWindowsHook
function, that processes events before they reach any application's message
loop. Windows sends messages generated by a specific type of event to filter
functions installed by the same type of hook. The following list briefly
describes each hook function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CallMsgFilter                     Passes a message and other data to the
                                  current message-filter function.

DefHookProc                       Calls the next filter function in a
                                  filter-function chain.

Function                          Description
────────────────────────────────────────────────────────────────────────────
SetWindowsHook                    Installs a system and/or application
                                  filter function.

UnhookWindowsHook                 Removes a Windows filter function from a
                                  filter-function chain.


1.16.1  Filter-Function Chain

A filter-function chain is a series of connected filter functions for a
particular system hook. For example, all keyboard filter functions are
installed by WH_KEYBOARD and all journaling-record filter functions are
installed by WH_JOURNALRECORD. Applications pass these filter functions to
the system hooks with calls to the SetWindowsHook function. Each call adds a
new filter function to the beginning of the chain. Whenever an application
passes a filter function to a system hook, it must reserve space for the
address of the next filter function in the chain. SetWindowsHook returns
this address.

Once each filter function completes its task, it must call the DefHookProc
function. DefHookProc uses the address stored in the location reserved by
the application to access the next filter function in the chain.

To remove a filter function from a filter chain, an application must call
the UnhookWindowsHook function with the type of hook and a pointer to the
function.

There are five types of standard window hooks and two types of debugging
hooks. Table 1.8 lists each type and describes its purpose:

Table 1.8  System Hooks

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Type                              Purpose
────────────────────────────────────────────────────────────────────────────
WH_CALLWNDPROC                    Installs a window function filter.
Type                              Purpose
────────────────────────────────────────────────────────────────────────────
WH_CALLWNDPROC                    Installs a window function filter.

WH_GETMESSAGE                     Installs a message filter (on debugging
                                  versions only).

WH_JOURNALPLAYBACK                Installs a journaling playback filter.

WH_JOURNALRECORD                  Installs a journaling record filter.

WH_KEYBOARD                       Installs a keyboard filter.

WH_MSGFILTER                      Installs a message filter.

WH_SYSMSGFILTER                   Installs a system-wide message filter.

────────────────────────────────────────────────────────────────────────────



────────────────────────────────────────────────────────────────────────────
NOTE

The WH_CALLWNDPROC and WH_GETMESSAGE hooks will affect system performance.
They are supplied for debugging purposes only.
────────────────────────────────────────────────────────────────────────────


1.16.2  Installing a Filter Function

To install a filter function, an application must do the following:


  1.  Export the function in its module definition file.

  2.  Obtain the function's address by using the MakeProcInstance function.

  3.  Call the SetWindowsHook function, specifying the type of hook function
      (see Table 1.8, "System Hooks") and the address of the function
      (returned by MakeProcInstance).

  4.  Store the return value from SetWindowsHook in a reserved location.
      This value is the address of the previous filter function.

      NOTE  Filter functions and the return value from SetWindowsHook must
      reside in fixed library code and data. This allows these hooks to
      operate in a large-frame EMS environment.



1.17  Property Functions

Property functions create and access a window's property list. A property
list is a storage area that contains handles for data that the application
wishes to associate with a window. The following list briefly describes each
property function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
EnumProps                         Passes the properties of a window to an
                                  enumeration function.

GetProp                           Retrieves a handle associated with a
                                  string from the window property list.

RemoveProp                        Removes a string from the property list.

SetProp                           Copies a string and a data handle to a
                                  window's property list.


1.17.1


Using Property Lists

Once a data handle is in a window's property list, any application can
access the handle if it can also access the window. This makes the property
list a convenient way to make data (for example, alternate captions or menus
for the window) available to the application when it wishes to modify the
window.

Every window has its own property list. When the window is created, the list
is empty. The SetProp function adds entries to the list. Each entry contains
a unique ANSI string and a data handle. The ANSI string identifies the
handle; the handle identifies the data associated with the window, as
illustrated in Figure 1.2:

(This figure may be found in the printed book.)

The data handle can identify any object or memory block that the application
wishes to associate with the window. The GetProp function retrieves the data
handle of an entry from the list without removing the entry. The handle can
then be used to retrieve or use the data. The RemoveProp function removes an
entry from the list when it is no longer needed.

Although the purpose of the property list is to associate data with a window
for use by the application that owns the window, the handles in a property
list are actually accessible to any application that has access to the
window. This means an application can retrieve and use a data handle from
the property list of a window created by another application. But using
another application's data handles must be done with care. Only shared,
global memory objects, such as GDI drawing objects, can be used by other
applications. If a property list contains local or global memory handles or
resource handles, only the application that has created the window may use
them. Global memory handles can be shared with other applications by using
the Windows clipboard. (For more information, see Section 1.12, "Clipboard
Functions.") Local memory handles cannot be shared.

The contents of a property list can be enumerated by using the EnumProps
function. The function passes the string and data handle of each entry in
the list to an application-supplied function. The application-supplied
function can carry out any task.

The data handles in a property list always belong to the application that
created them. The property list itself, like other window-related data,
belongs to Windows. A window's property list is actually allocated in the
the USER heap, the local heap of the USER library. Although there is no
defined limit to the number of entries in a property list, the actual number
of entries depends on how much room is available in the USER heap. This
depends on how many windows, window classes, and other window-related
objects have been created.

The application creates the entries in a property list. Before a window is
destroyed or the application that owns the window terminates, all entries in
the property list must be removed by using the RemoveProp function. Failure
to remove the entries leaves the property list in the USER heap and makes
the space it occupies unusable for subsequent applications. This can
ultimately cause an overflow of the USER heap. Entries in the property list
can be removed at any time by using the RemoveProp function. If there are
entries in the property list when the WM_DESTROY message is received for the
window, the entries must be removed at that time. To ensure that all entries
are removed, use the EnumProps function to enumerate all entries in the
property list. An application should remove only those properties that it
added to the property list. Windows adds properties for its own use and
disposes of them automatically. An application must not remove properties
which Windows has added to the list.


1.18  Rectangle Functions

Rectangle functions alter and obtain information about rectangles in a
window's client area. In Windows, a rectangle is defined by a RECT data
structure. The structure contains two points: the upper-left and lower-right
corners of the rectangle. The sides of a rectangle extend from these two
points and are parallel to the xand y-axes. The following list briefly
describes each rectangle function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CopyRect                          Makes a copy of an existing rectangle.

EqualRect                         Determines whether two rectangles are
                                  equal.

InflateRect                       Expands or shrinks the specified
                                  rectangle.

IntersectRect                     Finds the intersection of two rectangles.

OffsetRect                        Moves a given rectangle.

PtInRect                          Indicates whether a specified point lies
                                  within a given rectangle.

SetRectEmpty                      Sets a rectangle to an empty rectangle.

UnionRect                         Stores the union of two rectangles.


1.18.1  Using Rectangles in a Windows Application

Rectangles are used to specify rectangular areas on the display or in a
window, such as the cursor clipping area, the client repaint area, a
formatting area for formatted text, and the scroll area. Rectangles are also
used to fill, frame, or invert an area in the client area with a given
brush, and to retrieve the coordinates of a window or a window's client
area.

Since rectangles are used for many different purposes, the rectangle
functions do not use an explicit unit of measure. Instead, all rectangle
coordinates and dimensions are given in signed, logical values. The actual
units are determined by the function in which the rectangle is used.


1.18.2  Rectangle Coordinates

Coordinate values for a rectangle can be within the range -32,768 to 32,767.
Widths and heights, which must be positive, are within the range 0 to
32,767. This means that a rectangle whose left and right sides or whose top
and bottom are further apart than 32,768 units is not valid. Figure 1.3
shows a rectangle whose upper-left corner is left of the origin, but whose
width is less than 32,767:

(This figure may be found in the printed book.)


1.18.3  Creating and Manipulating Rectangles

The SetRect function creates a rectangle, the CopyRect function makes a copy
of a given rectangle, and the SetRectEmpty function creates an empty
rectangle. An empty rectangle is any rectangle that has zero width, zero
height, or both.

The InflateRect function increases or decreases the width and height of a
rectangle. It adds or removes width from both ends of the rectangle, or adds
or removes height from both the top and bottom of the rectangle.

The OffsetRect function moves the rectangle by a given amount. It moves the
corners of the rectangle by adding the given x and y amounts to the corner
coordinates.

The PtInRect function determines whether a given point lies within a given
rectangle. The point is in the rectangle if it lies on the left or top side
or is completely within the rectangle.

The IsRectEmpty function determines whether the given rectangle is empty.

The IntersectRect function creates a new rectangle that is the intersection
of two existing rectangles. The intersection is the largest rectangle
contained in both existing rectangles. The intersection of two rectangles is
shown in Figure 1.4:

(This figure may be found in the printed book.)

The UnionRect function creates a new rectangle that is the union of two
existing rectangles. The union is the smallest rectangle that contains both
existing rectangles. The union of two rectangles is shown in Figure 1.5:

(This figure may be found in the printed book.)

For information about functions that draw ellipses and polygons, see Section
2.10, "Ellipse and Polygon Functions."


1.19  Summary

Window manager interface functions process messages, create, move, or alter
a window, or create system output. For more information on topics related to
window manager interface functions, see the following:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
Function descriptions                 Reference, Volume 1: Chapter 4,
                                      "Functions Directory"

Windows messages                      Reference, Volume 1: Chapter 5,
                                      "Messages Overview," and Chapter 6,
                                      "Messages Directory"

Topic                                 Reference
────────────────────────────────────────────────────────────────────────────

Windows data types and structures     Reference, Volume 2: Chapter 7,
                                      "Data Types and Structures"

Using the Resource                    Reference, Volume 2: Chapter 8,
Compiler                              "Resource Script Statements"

                                      Tools: Chapter 3, "Compiling
                                      Resources: The Resource Compiler"

General information on Windows        Guide to Programming: Chapter 1, "An
programming                           Overview of the Windows Environment"

Creating and managing a window        Guide to Programming: Chapter 2, "A
                                      Generic Windows Application"

Handling input                        Guide to Programming: Chapter 4,
                                      "Keyboard and Mouse Input," and
                                      Chapter 6, "The Cursor, the Mouse,
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
                                      Chapter 6, "The Cursor, the Mouse,
                                      and the
                                      Keyboard"

Icons                                 Guide to Programming: Chapter 5,
                                      "Icons"

Menus                                 Guide to Programming: Chapter 7,
                                      "Menus"

Controls and dialog boxes             Guide to Programming: Chapter 8,
                                      "Controls," and Chapter 9, "Dialog
                                      Boxes"

Creating icons and cursors            Tools: Chapter 4, "Designing Images:
                                      SDKPaint"

Designing dialog boxes                Tools: Chapter 5, "Designing Dialog
                                      Boxes: The Dialog Editor"
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
                                      Boxes: The Dialog Editor"








Chapter 2  Graphics Device Interface Functions
────────────────────────────────────────────────────────────────────────────

This chapter describes the functions that perform device-independent
graphics operations within a Windows application, including creating a wide
variety of line, text, and bitmap output on many output devices. These
functions constitute the Windows graphics device interface (GDI).

The chapter covers the following function categories:


  ■   Device-context functions

  ■   Drawing-tool functions

  ■   Color-palette functions

  ■   Drawing-attribute functions

  ■   Mapping functions

  ■   Coordinate functions

  ■   Region functions

  ■   Clipping functions

  ■   Line-output functions

  ■   Ellipse and polygon functions

  ■   Bitmap functions

  ■   Text functions

  ■   Font functions

  ■   Metafile functions

  ■   Printer-control functions

  ■   Printer-escape function

  ■   Environment functions



2.1  Device-Context Functions

Device-context functions create, delete, and restore device contexts (DC). A
device context is a link between a Windows application, a device driver, and
an output device, such as a printer or plotter.

Figure 2.1 shows the flow of information from a Windows application through
a device context and a device driver to an output device:

(This figure may be found in the printed book.)

Any Windows application can use GDI functions to access an output device.
GDI passes calls (which are device independent) from the application to the
device driver. The device driver then translates the calls into
device-dependent operations.

The following list briefly describes each device-context function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateCompatibleDC                Creates a memory device context.

CreateDC                          Creates a device context.

CreateIC                          Creates an information context.

DeleteDC                          Deletes a device context.

GetDCOrg                          Retrieves the origin of a specified
                                  device context.

RestoreDC                         Restores a device context.

SaveDC                            Saves the current state of the device
                                  context.


2.1.1  Device-Context Attributes

Device-context attributes describe selected drawing objects (pens and
brushes), the selected font and its color, the way in which objects are
drawn (or mapped) to the device, the area on the device available for output
(clipping region), and other important information. The data structure that
contains these attributes is called the DC data block.

Table 2.1 lists the default device-context attributes and the GDI functions
that affect or use these attributes:

Table 2.1  Default Device-Context Attributes and Related GDI

╓┌─────────────────────┌────────────────┌────────────────────────────────────╖
Attribute             Default          GDI Functions
────────────────────────────────────────────────────────────────────────────
Background color      White            SetBkColor

Background mode       OPAQUE           SetBkMode

Bitmap                No default       CreateBitmap
                                       CreateBitmapIndirect
                                       CreateCompatibleBitmap
                                       SelectObject

Brush                 WHITE_BRUSH      CreateBrushIndirect
                                       CreateDIBPatternBrush
                                       CreateHatchBrush
                                       CreatePatternBrush
                                       CreateSolidBrush
                                       SelectObject
Attribute             Default          GDI Functions
────────────────────────────────────────────────────────────────────────────
                                       SelectObject

Brush origin          (0,0)            SetBrushOrg
                                       UnrealizeObject

Clipping region       Display surface  ExcludeClipRect
                                       IntersectClipRect
                                       OffsetClipRgn
                                       SelectClipRgn

Color palette         DEFAULT_PALETTE  CreatePalette
                                       RealizePalette
                                       SelectPalette

Current pen position  (0,0)            MoveTo

Drawing mode          R2_COPYPEN       SetROP2

Font                  SYSTEM_FONT      CreateFont
Attribute             Default          GDI Functions
────────────────────────────────────────────────────────────────────────────
Font                  SYSTEM_FONT      CreateFont
                                       CreateFontIndirect
                                       SelectObject



Table 2.1  Default Device-Context Attributes and Related GDI

╓┌───────────────────────┌─────────────┌─────────────────────────────────────╖
Attribute               Default       GDI Functions
────────────────────────────────────────────────────────────────────────────
Intercharacter spacing  0             SetTextCharacterExtra

Mapping mode            MM_TEXT       SetMapMode

Pen                     BLACK_PEN     CreatePen
                                      CreatePenIndirect
                                      SelectObject

Attribute               Default       GDI Functions
────────────────────────────────────────────────────────────────────────────

Polygon-filling mode    ALTERNATE     SetPolyFillMode

Stretching mode         BLACKONWHITE  SetStretchBltMode

Text color              Black         SetTextColor

Viewport extent         (1,1)         SetViewportExt

Viewport origin         (0,0)         SetViewportOrg

Window extent           (1,1)         SetWindowExt

Window origin           (0,0)         SetWindowOrg

────────────────────────────────────────────────────────────────────────────




2.1.2  Saving a Device Context

Occasionally, it is necessary to save a device context so that the original
attributes will be available at a later time. For example, a Windows
application may need to save its original clipping region so that it can
restore the client area's original state after a series of alterations
occur. The SaveDC and RestoreDC functions make this possible.


2.1.3  Deleting a Device Context

The DeleteDC function deletes a device context and ensures that shared
resources are not removed until the last context is deleted. The device
driver is a shared resource.


2.1.4  Compatible Device Contexts

The CreateCompatibleDC function causes Windows to treat a portion of memory
as a virtual device. This means that Windows prepares a device context that
has the same attributes as the device for which it was created, but the
device context has no connected output device. To use the compatible device
context, the application creates a compatible bitmap and selects it into the
device context. Any output it sends to the device is drawn in the selected
bitmap. Since the device context is compatible with some actual device, the
context of the bitmap can be copied directly to the actual device, or vice
versa. This also means that the application can send output to memory (prior
to sending it to the device). Note that the CreateCompatibleDC function
works only for devices that have BitBlt capabilities.


2.1.5  Information Contexts

The CreateIC function creates an information context for a device. An
information context is a device context with limited capabilities; it cannot
be used to write to the device. An application uses an information context
to gather information about the selected device. Information contexts are
useful in large applications that require memory conservation.

By using an information context and the GetDeviceCaps function, you can
obtain the following device information:


  ■   Device technology

  ■   Physical display size

  ■   Color capabilities of the device

  ■   Color-palette capabilities of the device

  ■   Drawing objects available on the device

  ■   Clipping capabilities of the device

  ■   Raster capabilities of the device

  ■   Curve-drawing capabilities of the device

  ■   Line-drawing capabilities of the device

  ■   Polygon-drawing capabilities of the device

  ■   Text capabilities of the device



2.2  Drawing-Tool Functions

Drawing-tool functions create and delete the drawing tools that GDI uses
when it creates output on a device or display surface. The following list
briefly describes each drawing-tool function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateBrushIndirect               Creates a logical brush.

CreateDIBPatternBrush             Creates a logical brush that has a
                                  pattern defined by a device-independent
                                  bitmap (DIB).

CreateHatchBrush                  Creates a logical brush that has a
                                  hatched pattern.

Function                          Description
────────────────────────────────────────────────────────────────────────────
CreatePatternBrush                Creates a logical brush that has a
                                  pattern defined by a memory bitmap.

CreatePen                         Creates a logical pen.

CreatePenIndirect                 Creates a logical pen.

CreateSolidBrush                  Creates a logical brush.

DeleteObject                      Deletes a logical pen, brush, font,
                                  bitmap, or region.

EnumObjects                       Enumerates the available pens or brushes.

GetBrushOrg                       Retrieves the current brush origin for a
                                  device context.

GetObject                         Copies the bytes of logical data that
                                  define an object.

GetStockObject                    Retrieves a handle to one of the
                                  predefined stock pens, brushes, fonts,
                                  or color palettes.

SelectObject                      Selects an object as the current object.

SetBrushOrg                       Sets the origin of all brushes selected
                                  into a given device context.

UnrealizeObject                   Directs GDI to reset the origin of the
                                  given brush.


2.2.1  Drawing-Tool Uses

A Windows application can use any of three tools when it creates output: a
bitmap, a brush, or a pen. An application can use the pen and brush
together, outlining a region or object with the pen and filling the region's
or object's interior with the brush. GDI allows the application to create
pens with solid colors, bitmaps with solid or combination colors, and
brushes with solid or combination colors. (The available colors and color
combinations depend on the capabilities of the intended output device.)


Brushes

There are seven predefined brushes available in GDI; an application selects
any one of them by using the GetStockObject function. The following list
describes these brushes:


  ■   Black

  ■   Dark-Gray

  ■   Gray

  ■   Hollow

  ■   Light-Gray

  ■   Null

  ■   White


There are six hatched brush patterns; an application can select any one of
these patterns by using the CreateHatchBrush function. (A hatch line is a
thin line that appears at regular intervals on a solid background.) The
following list describes these hatch patterns:


  ■   Backward Diagonal

  ■   Cross

  ■   Diagonal Cross

  ■   Forward Diagonal

  ■   Horizontal

  ■   Vertical


Figure 2.2 shows each hatched brush pattern. A simple Windows application
created this figure:

(This figure may be found in the printed book.)


Pens

There are three predefined pens available in GDI; an application selects any
one of them by using the GetStockObject function. The following list
describes these pens:


  ■   Black

  ■   Null

  ■   White


In addition to selecting a stock pen, an application creates an original pen
by using the GDI CreatePen function. This function allows the application to
select one of six pen styles, a pen width, and a pen color (if the device
has color capabilities). The pen style can be solid, dashed, dotted, a
combination of dots and dashes, or null. The pen width is the number of
logical units GDI maps to a certain number of pixels (this number is
dependent on the current mapping mode if the pen is selected into a device
context). The pen color is an RGB color value.

Figure 2.3 shows a variety of pen patterns obtained from calls to the
CreatePen function. A simple Windows application created this figure:

(This figure may be found in the printed book.)


2.2.2  Color

Many of the GDI functions that create pens and brushes require that the
calling application specify a color in the form of a COLORREF value. A
COLORREF value specifies color in one of three ways:


  ■   As an explicit RGB value

  ■   As an index to a logical-palette entry

  ■   As a palette-relative RGB value


The second and third methods require the application to create a logical
palette. Section 2.3, "Color Palette Functions," describes Windows color
palettes and the functions used by an application to exploit their
capabilities.

An explicit RGB COLORREF value is a long integer that contains a red, a
green, and a blue color field. The first (low-order) byte contains the red
field, the second byte contains the green field, and the third byte contains
the blue field; the fourth (high-order) byte must be zero. Each field
specifies the intensity of the color; zero indicates the lowest intensity
and 255 indicates the highest. For example, 0x00FF0000 specifies pure blue,
and 0x0000FF00 specifies pure green. The RGB macro accepts values for the
relative intensities of the three colors and returns an explicit RGB
COLORREF value. When GDI receives the RGB value as a function parameter, it
passes the RGB color value directly to the output device driver, which
selects the closest available color on the device. The GetNearestColor
function returns the closest logical color to a specified logical color that
a given device can represent.

If the device is a plotter, the driver converts the RGB value to a single
color that matches one of the pens on the device.

If the device uses color raster technology and the RGB value specifies a
color for a pen, the driver will select a solid color. If the device uses
color raster technology and the RGB value specifies a color for a brush, the
driver will select from a variety of available color combinations. Since
many color devices can display only a few colors, the actual color is
simulated by "dithering," that is, mixing pixels of the colors which the
display can actually render.

If the device is monochrome (black-and-white), the driver will select black,
white, or a shade of gray, depending on the RGB value. If the sum of the RGB
values is zero, the driver selects a black brush. If the sum of the RGB
values is 765, the driver selects a white brush. If the sum of the RGB
values is between zero and 765, the driver selects one of the gray patterns
available.

The GetRValue, GetGValue, and GetBValue functions extract the values for
red, green, and blue from an explicit RGB COLORREF value.


2.3  Color-Palette Functions

Many color graphic displays are capable of displaying a wide range of
colors. In most cases, however, the actual number of colors which the
display can render at any given time is more limited. For example, a display
that is potentially able to produce over 262,000 different colors may be
able to show only 256 of those colors at a time because of hardware
limitations. In such cases, the display device often maintains a palette of
colors; when an application requests a color that is not currently
displayed, the display device adds the requested color to the palette.
However, when the number of requested colors exceeds the maximum number for
the device, it must replace an existing color with the requested color. As a
result, if the total number of colors requested by one or more windows
exceeds the number available on the display, many of the actual colors
displayed will be incorrect.

Windows color palettes act as a buffer between color-intensive applications
and the system, allowing an application to use as many colors as needed
without interfering with its own color display or colors displayed by other
windows. When a window has input focus, Windows ensures that the window will
display all the colors it requests, up to the maximum number simultaneously
available on the display, and displays additional colors by matching them to
available colors. In addition, Windows matches the colors requested by
inactive windows as closely as possible to the available colors. This
significantly reduces undesirable changes in the colors displayed in
inactive windows.

The following list briefly describes the functions an application calls to
use color palettes:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AnimatePalette                    Replaces entries in a logical palette;
                                  Windows maps the new entries into the
                                  system palette immediately.

CreatePalette                     Creates a logical palette.

GetNearestPaletteIndex            Retrieves the index of a logical palette
                                  entry most nearly matching a specified
                                  RGB value.

GetPaletteEntries                 Retrieves entries from a logical palette.

GetSystemPaletteEntries           Retrieves a range of palette entries
                                  from the system palette.

GetSystemPaletteUse               Determines whether an application has
                                  access to the full system palette.

RealizePalette                    Maps entries in a logical palette to the
                                  system palette.

SelectPalette                     Selects a logical palette into a device
                                  context.

SetPaletteEntries                 Sets new palette entries in a logical
                                  palette; Windows does not map the new
                                  entries to the system palette until the
                                  application realizes the logical palette.

SetSystemPaletteUse               Allows an application to use the full
                                  system palette.

UpdateColors                      Performs a pixel-by-pixel translation of
                                  each pixel's current color to the system
                                  palette. This allows an inactive window
                                  to correct its colors without redrawing
                                  its client area.


2.3.1  How Color Palettes Work

Color palettes provide a device-independent method for accessing the color
capabilities of a display device by managing the device's physical (or
system) palette, if one is available. Typically, devices that can display at
least 256 colors use a physical palette.

An application employs the system palette by creating and using one or more
logical palettes. Each entry in the palette contains a specific color. Then,
instead of specifying an explicit value for a color when performing graphics
operations, the application indicates which color is to be displayed by
supplying an index into its logical palette.

Since more than one application can use logical palettes, it is possible
that the total number of colors requested for display can exceed the
capacity of the display device. Windows acts as a mediator among these
applications.

When a window requests that its logical palette be given its requested
colors (a process known as realizing its palette), Windows first exactly
matches entries in the logical palette to current entries in the system
palette.

If an exact match for a given logical-palette entry is not possible, Windows
sets the entry in the logical palette into an unused entry in the system
palette.

Finally, when all entries in the system palette have been used, Windows
takes these logical palette entries that do not exactly match and matches
them as closely as possible to entries already in the system palette. To
further aid this color matching, Windows sets aside 20 static colors (called
the "default palette") in the system palette to which it can match entries
in a background palette.

Windows always satisfies the color requests of the foreground window first;
this ensures that the active window will have the best color display
possible. For the remaining windows, Windows satisfies the color requests of
the window which most recently received input focus, the window which was
active before that one, and so on.

(This figure may be found in the printed book.)

Figure 2.4 illustrates this process. In this figure, a hypothetical display
has a system palette capable of containing 12 colors. The application that
created Logical Palette 1 owns the active window and was the first to
realize its logical palette, which consists of 8 colors. Logical Palette 2
is owned by a window which realized its logical palette while it was
inactive.

Because the active window was active when it realized its palette, Windows
mapped all of the colors in Logical Palette 1 directly to the system
palette.

Three of the colors (1, 3, and 5) in Logical Palette 2 are identical to
colors in the system palette; to save space in the palette, then, Windows
simply matched those colors to the existing system colors when the second
application realized its palette. Colors 0, 2, 4, and 6 were not already in
the system palette, however, and so Windows mapped those colors into the
system palette.

Because the system palette is now full, Windows was not able to map the
remaining two colors (which do not exactly match existing colors in the
system palette) into the system palette. Instead, it matched them to the
closest colors in the system palette.


2.3.2  Using a Color Palette

Before drawing to the display device using a color palette, an application
must first create a logical palette by calling the CreatePalette function
and then call SelectPalette to select the palette for the device context
(DC) for the output device for which it will be used. An application cannot
select a palette into a device context using the SelectObject function.

All functions which accept a color parameter accept an index to an entry in
the logical palette. The palette-index specifier is a long integer value
with the first bit in its high-order byte set to 1 and the palette index in
the two low-order bytes. For example, 0x01000005 would specify the palette
entry with an index of 5. The PALETTEINDEX macro accepts an integer value
representing the index of a logical-palette entry and returns a
palette-index COLORREF value which an application can use as a parameter for
GDI functions that require a color.

An application can also specify a palette index indirectly by using a
palette-relative RGB COLORREF value. If the target display device supports
logical palettes, Windows matches the palette-relative RGB COLORREF value to
the closest palette entry; if the target device does not support palettes,
then the RGB value is used as though it were an explicit RGB COLORREF value.
The palette-relative RGB COLORREF value is identical to an explicit RGB
COLORREF value except that the second bit of the high-order byte is set to
1. For example, 0x02FF0000 would specify a palette-relative RGB COLORREF
value for pure blue. The PALETTERGB macro accepts values for red, green and
blue, and returns a palette-relative RGB COLORREF value which an application
can use as a parameter for GDI functions that require a color.

If an application does specify an RGB value instead of a palette entry,
Windows will use the closest matching color in the default palette of 20
static colors.

────────────────────────────────────────────────────────────────────────────
NOTE

If the source and destination device contexts have selected and realized
different palettes, the BitBlt function does not properly move bitmap bits
to or from a memory device context. In this case, you must call the
GetDIBits with the wUsage parameter set to DIB_RGB_COLORS to retrieve the
bitmap bits from the source bitmap in a device-independent format. You then
use the SetDIBits function to set the retrieved bits in the destination
bitmap. This ensures that Windows will properly match colors between the two
device contexts.

BitBlt can successfully move bitmap bits between two screen display
contexts, even if they have selected and realized different palettes. The
StretchBlt function properly moves bitmap bits between device contexts
whether or not they use different palettes.
────────────────────────────────────────────────────────────────────────────


2.4  Drawing-Attribute Functions

Drawing-attribute functions affect the appearance of Windows output, which
has four forms: line, brush, bitmap, and text. The following list describes
each drawing-attribute function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetBkColor                        Returns the current background color.

GetBkMode                         Returns the current background mode.

GetPolyFillMode                   Retrieves the current polygon-filling
                                  mode.

GetROP2                           Retrieves the current drawing mode.

GetStretchBltMode                 Retrieves the current stretching mode.

GetTextColor                      Retrieves the current text color.

SetBkColor                        Sets the background color.

SetBkMode                         Sets the background mode.

SetPolyFillMode                   Sets the polygon-filling mode.

SetROP2                           Sets the current drawing mode.

SetStretchBltMode                 Sets the stretching mode.

SetTextColor                      Sets the text color.


2.4.1  Background Mode and Background Color

Line output can be solid or broken (dashed, dotted, or a combination of the
two). If it is broken, the space between the breaks can be filled by setting
the background mode to OPAQUE and selecting a color. By setting the
background mode to TRANSPARENT, the space between breaks is left in its
original state. The SetBkMode and SetBkColor functions accomplish this task.


Brush output is solid, patterned, or hatched. The space between hatch marks
can be filled by setting the background mode to OPAQUE and selecting a
color. When Windows creates brush output on a display, it combines the
existing color on the display surface with the brush color to yield a new
and final color; this is a binary raster operation. If the default raster
operation is not appropriate, a new one is chosen by using the SetROP2
function.


2.4.2  Stretch Mode

If an application copies a bitmap to a device and it is necessary to shrink
or expand the bitmap before drawing, the effects of the StretchBlt and
StretchDIBits functions can be controlled by calling SetStretchBltMode to
set the current stretch mode for a device context. The stretch mode
determines how lines eliminated from the bitmap are combined.


2.4.3  Text Color

The appearance of text output is limited only by the number of available
fonts and the color capabilities of the output device. The SetBkColor
function sets the color of the text background (the unused portion of each
character's cell) and the SetTextColor function sets the color of the
character itself.


2.5  Mapping Functions

Mapping functions alter and retrieve information about the GDI mapping
modes. In order to maintain device independence, GDI creates output in a
logical space and maps it to the display. The mapping mode defines the
relationship between units in the logical space and pixels on a device. The
following list briefly describes each mapping function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetMapMode                        Retrieves the current mapping mode.

GetViewportExt                    Retrieves a device context's viewport
                                  extents.

GetViewportOrg                    Retrieves a device context's viewport
                                  origin.

GetWindowExt                      Retrieves a device context's window
                                  extents.

GetWindowOrg                      Retrieves a device context's window
                                  origin.

OffsetViewportOrg                 Modifies a viewport origin.

OffsetWindowOrg                   Modifies a window origin.

ScaleViewportExt                  Modifies the viewport extents.

ScaleWindowExt                    Modifies the window extents.

SetMapMode                        Sets the mapping mode of a specified
                                  device context.

SetViewportExt                    Sets a device context's viewport extents.

SetViewportOrg                    Sets a device context's viewport origin.

SetWindowExt                      Sets a device context's window extents.

SetWindowOrg                      Sets a device context's window origin.

There are eight different mapping modes: MM_ANISOTROPIC, MM_HIENGLISH,
MM_HIMETRIC, MM_ISOTROPIC, MM_LOENGLISH, MM_LOMETRIC, MM_TEXT, and MM_TWIPS.
Each mode has a specific use in a Windows application. Table 2.2 summarizes
the eight GDI mapping modes:

Table 2.2  GDI Mapping Modes

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Mapping Mode                      Intended Use
────────────────────────────────────────────────────────────────────────────
MM_ANISOTROPIC                    Used in applications that map one
                                  logical unit to an arbitrary physical
                                  unit. The x- and y-axes are arbitrarily
                                  scaled.

MM_HIENGLISH                      Used in applications that map one
                                  logical unit to 0.001 inch. Positive y
                                  extends upward.

MM_HIMETRIC                       Used in applications that map one
                                  logical unit to 0.01 millimeter.
                                  Positive y extends upward.

MM_ISOTROPIC                      Used in applications that map one
Mapping Mode                      Intended Use
────────────────────────────────────────────────────────────────────────────
MM_ISOTROPIC                      Used in applications that map one
                                  logical unit to an arbitrary physical
                                  unit. One unit along the x-axis is
                                  always equal to one unit along the y
                                  -axis.

MM_LOENGLISH                      Used in applications that map one
                                  logical unit to 0.01 inch. Positive y
                                  extends upward.

MM_LOMETRIC                       Used in applications that map one
                                  logical unit to 0.1 millimeter. Positive
                                  y extends upward.

MM_TEXT                           Used in applications that map one
                                  logical unit to one pixel. Positive y
                                  extends downward.

MM_TWIPS                          Used in applications that map one
Mapping Mode                      Intended Use
────────────────────────────────────────────────────────────────────────────
MM_TWIPS                          Used in applications that map one
                                  logical unit to 1/1440 inch (1/20 of a
                                  printer's point). Positive y extends
                                  upward.

────────────────────────────────────────────────────────────────────────────




2.5.1  Constrained Mapping Modes

GDI classifies six of the mapping modes as constrained mapping modes:
MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, MM_TEXT, and MM_TWIPS.
In each of these modes, one logical unit is mapped to a predefined physical
unit. For instance, the MM_TEXT mode maps one logical unit to one device
pixel, and the MM_LOENGLISH mode maps one logical unit to 0.01 inch on the
device. These mapping modes are constrained because the scaling factor is
fixed, so an application cannot change the number of logical units that
Windows maps to a physical unit. Table 2.3 shows the number of logical units
in various mapping modes that result in a certain physical unit:

Table 2.3  Logical/Physical Conversion Table

╓┌─────────────┌─────────────┌───────────────────────────────────────────────╖
Mapping       Logical       Physical
Mode          Units         Unit
────────────────────────────────────────────────────────────────────────────
MM_HIENGLISH  1000          1 inch

MM_HIMETRIC   100           1 millimeter

MM_LOENGLISH  100           1 inch

MM_LOMETRIC   10            1 millimeter

MM_TEXT       1             Device pixel

MM_TWIPS      1440          1 inch

Mapping       Logical       Physical
Mode          Units         Unit
────────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────




2.5.2  Partially Constrained and Unconstrained Mapping Modes

The unconstrained mapping modes, MM_ISOTROPIC and MM_ANISOTROPIC, use two
rectangular regions to derive a scaling factor and an orientation: the
window and the viewport. The window lies within the logical-coordinate space
and the viewport lies within the physical-coordinate space. Both possess an
origin, an x-extent, and a y-extent. The origin may be any one of the four
corners. The x-extent is the horizontal distance from the origin to its
opposing corner. The y-extent is the vertical distance from the origin to
its opposing corner. Windows creates a horizontal scaling factor by dividing
the viewport's x-extent by the window's x-extent and creates a vertical
scaling factor by dividing the viewport's y-extent by the window's y-extent.
These scaling factors determine the number of logical units that Windows
maps to a number of pixels. In addition to determining scaling factors, the
window and viewport determine the orientation of an object. Windows always
maps the window origin to the viewport origin, the window x-extent to the
viewport x-extent, and the window y-extent to the viewport y-extent.


Partially Constrained Mapping Mode

An application creates output with equally scaled axes by using the
MM_ISOTROPIC mapping mode. This means that Windows will map a symmetrical
object (for example, a square or a circle) in the logical space as a
symmetrical object in the physical space. In order to maintain this
symmetry, GDI shrinks one of the viewport extents. The amount of shrinkage
depends on the requested extents and the aspect ratio of the device. This
mapping mode is called partially constrained because the application does
not have complete control in altering the scaling factor.


Unconstrained Mapping Mode

An application can completely alter the horizontal and vertical scaling
factors by using the MM_ANISOTROPIC mapping mode and setting the window and
viewport extents to any value after selecting this mapping mode. Windows
will not alter either scaling factor in this mode.


2.5.3  Transformation Equations

GDI uses the following equations to transform logical points to device
points, and device points to logical points:


  ■   Transforming logical points to device points:

      Dx = (Lx - xWO) x xVE/xWE + xVO Dy = (Ly - yWO) x yVE/yWE + yVO

  ■   Transforming device points to logical points:

      Lx = (Dx - xVO) x xWE/xVE + xWO Ly = (Dy - yVO) x yWE/yVE + yWO


The following list describes the variables used in these transformation
equations:

Variable                          Description
────────────────────────────────────────────────────────────────────────────
xWO                               Window origin x-coordinate

yWO                               Window origin y-coordinate

xWE                               Window extent x-coordinate

yWE                               Window extent y-coordinate

xVO                               Viewport origin x-coordinate

yVO                               Viewport origin y-coordinate

xVE                               Viewport extent x-coordinate

yVE                               Viewport extent y-coordinate

Lx                                Logical-coordinate system x-coordinate

Ly                                Logical-coordinate system y-coordinate

Dx                                Device x-coordinate

Dy                                Device y-coordinate

The following four ratios are scaling factors:

xVE/xWE

yVE/yWE

xWE/xVE

yWE/yVE

They are used to determine the necessary stretching or compressing of
logical units. The subtraction and addition of viewport and window origins
is referred to as the translational component of the equation.


2.5.4  Example: MM_TEXT

The default mapping mode is MM_TEXT. In this mapping mode, one logical unit
is mapped to one pixel on the device or display.

A simple Windows application created three rectangles as they appear in the
logical and physical coordinate spaces when MM_TEXT is the mapping mode, as
shown in Figure 2.5. The drawing on the left illustrates the logical space;
the drawing on the right illustrates the device, or physical, space. The
rectangles appear vertically elongated in the physical space because pixels
on the chosen display are longer than they are wide. The rectangles appear
to be upside-down because positive y extends downward in the
physical-coordinate system.

(This figure may be found in the printed book.)


2.5.5  Example: MM_LOENGLISH

A Windows application created three rectangles and mapped them from the
logical space to the physical space by using the MM_LOENGLISH mapping mode,
as shown in Figure 2.6. The drawing on the left illustrates how the
rectangles appear in relation to the xand y-axes in the logical coordinate
system. The drawing on the right illustrates how the rectangles appear in
relation to the x- and y-axes in the physical coordinate system.

(This figure may be found in the printed book.)


2.6  Coordinate Functions

Coordinate functions convert client coordinates to screen coordinates (or
vice versa), and determine the location of a specific point. These functions
are useful in graphics-intensive applications. The following list briefly
describes each coordinate function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ChildWindowFromPoint              Determines which child window contains a
                                  specified point.

ClientToScreen                    Converts client coordinates into screen
                                  coordinates.

DPtoLP                            Converts device points (that is, points
                                  relative to the window origin) into
                                  logical points.

LPtoDP                            Converts logical points into device
                                  points.

ScreenToClient                    Converts screen coordinates into client
                                  coordinates.

WindowFromPoint                   Determines which window contains a
                                  specified point.


2.7  Region Functions

Region functions create, alter, and retrieve information about regions. A
region is an elliptical or polygonal area within a window that can be filled
with graphical output. An application uses these functions in conjunction
with the clipping functions to create clipping regions. For more information
about clipping functions, see Section 2.8, "Clipping Functions." The
following list briefly describes each region function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CombineRgn                        Combines two existing regions into a new
                                  region.

CreateEllipticRgn                 Creates an elliptical region.

CreateEllipticRgnIndirect         Creates an elliptical region.

CreatePolygonRgn                  Creates a polygonal region.

CreatePolyPolygonRgn              Creates a region consisting of a series
                                  of closed polygons that are filled as
                                  though they were a single polygon.

CreateRectRgn                     Creates a rectangular region.

CreateRectRgnIndirect             Creates a rectangular region.

CreateRoundRectRgn                Creates a rounded rectangular region.

EqualRgn                          Determines whether two regions are
                                  identical.

FillRgn                           Fills the given region with a brush
                                  pattern.

FrameRgn                          Draws a border for a given region.

GetRgnBox                         Retrieves the coordinates of the
                                  bounding rectangle of a region.

InvertRgn                         Inverts the colors in a region.

OffsetRgn                         Moves the given region.

PaintRgn                          Fills the region with the selected brush
                                  pattern.

PtInRegion                        Tests whether a point is within a region.

Function                          Description
────────────────────────────────────────────────────────────────────────────
RectInRegion                      Tests whether any part of a rectangle is
                                  within a region.

SetRectRgn                        Creates a rectangular region.


2.8  Clipping Functions

Clipping functions create, test, and alter clipping regions. A clipping
region is the portion of a window's client area where GDI creates output;
any output sent to that portion of the client area which is outside the
clipping region will not be visible. Clipping regions are useful in any
Windows application that needs to save one part of the client area and
simultaneously send output to another. The following list briefly describes
each clipping function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ExcludeClipRect                   Excludes a rectangle from the clipping
                                  region.

GetClipBox                        Copies the dimensions of a bounding
                                  rectangle.

IntersectClipRect                 Forms the intersection of a clipping
                                  region and a rectangle.

OffsetClipRgn                     Moves a clipping region.

PtVisible                         Tests whether a point lies in a region.

RectVisible                       Determines whether part of a rectangle
                                  lies in a region.

SelectClipRgn                     Selects a clipping region.


2.9  Line-Output Functions

Line-output functions create simple and complex line output with the
selected pen. The following list briefly describes each line-output
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
Arc                               Draws an arc.

LineDDA                           Computes successive points on a line.

LineTo                            Draws a line with the selected pen.

MoveTo                            Moves the current position to the
                                  specified point.

Polyline                          Draws a set of line segments.

Figure 2.7 shows an arc created by using the Arc function. The upper portion
of the illustration shows the arc as it would appear on a display; the lower
portion shows the arc suspended in its bounding rectangle, which GDI uses to
determine the size and shape of the arc:

(This figure may be found in the printed book.)


2.9.1  Function Coordinates

Line-output functions require coordinates in logical units, which GDI uses
to draw a line in logical space. The use of logical units ensures device
independence in Windows. GDI maps this line from the logical space to the
physical space on the device. The number of logical units that GDI maps to a
pixel depends on the current mapping mode. When GDI draws a line, it
excludes the last specified point. For example, if the LineTo function is
given the arguments (X1, Y1) and (X2, Y2), the line will be drawn from (X1,
Y1) to (X2 - 1, Y2 - 1).


2.9.2  Pen Styles, Colors, Widths

If an application draws lines and does not create a new pen, GDI uses the
default pen. This pen is black and is one pixel wide when the mapping mode
is MM_TEXT. An application can create a new pen of a different width, style,
and color by using the CreatePen function. The new color is dependent on the
color capabilities of the output device. The new style can be solid, dotted,
dashed, or a combination of dotted and dashed. Once an application creates a
new pen, it can select it into a display context by using the SelectObject
function.

Figure 2.8 shows simple line output created by the LineTo and MoveTo
functions. The application created the rectangle on the left by using a
styled pen and the rectangle on the right by using a solid pen:

(This figure may be found in the printed book.)


2.10  Ellipse and Polygon Functions

Ellipse and polygon functions draw ellipses and polygons. GDI draws the
perimeter of each object with the selected pen and fills the interior by
using the selected brush. These functions are particularly useful in drawing
and charting applications. The following list briefly describes each ellipse
and polygon function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
Chord                             Draws a chord.

DrawFocusRect                     Draws a rectangle in the style used to
                                  indicate focus.

Ellipse                           Draws an ellipse.

Pie                               Draws a pie.

Polygon                           Draws a polygon.

PolyPolygon                       Draws a series of closed polygons that
                                  are filled as though they were a single
                                  polygon.

Rectangle                         Draws a rectangle.

RoundRect                         Draws a rounded rectangle.


2.10.1  Function Coordinates

Ellipse and polygon functions require coordinates in logical units, which
GDI uses to determine the location and size of an object in logical space.
The use of logical units ensures device independence in Windows. GDI uses a
mapping function to map logical units to pixels on the device. The number of
logical units that Windows maps to a pixel depends on the current mapping
mode. The default mapping mode, MM_TEXT, maps one logical unit to one pixel.


When GDI draws a rectangle, it uses four arguments. The first two arguments
specify the rectangle's upper-left corner. The last two arguments do not
actually specify part of the rectangle; they specify the point adjacent to
the lower-right corner. For example, if the first point is specified by (X1,
Y1) and the second point is specified by (X2, Y2), the rectangle's
upper-left corner will be (X1, Y1) and the lower-right corner will be (X2 -
1, Y2 - 1).


2.10.2  Bounding Rectangles

Instead of requiring a radius or circumference measurement, the Chord,
Ellipse, and Pie functions use a bounding rectangle to define the size of
the object they create. The bounding rectangle is hidden; GDI uses it only
to describe the object's location and size.

For information about functions that alter or obtain information about
rectangles in a window's client area, see Section 1.18, "Rectangle
Functions."


2.11  Bitmap Functions

Bitmap functions display bitmaps. A bitmap is a matrix of memory bits that,
when copied to a device, defines the color and pattern of a corresponding
matrix of pixels on the device's display surface. Bitmaps are useful in
drawing, charting, and word-processing applications because they let you
prepare images in memory and then quickly copy them to the display. The
following list briefly describes each bitmap function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
BitBlt                            Copies a bitmap from a source to a
                                  destination device.

CreateBitmap                      Creates a bitmap.

CreateBitmapIndirect              Creates a bitmap described in a data
                                  structure.

CreateCompatibleBitmap            Creates a bitmap that is compatible with
                                  a specified device.

CreateDiscardableBitmap           Creates a discardable bitmap that is
                                  compatible with a specified device.

ExtFloodFill                      Fills the display surface within a
                                  border or over an area of a given color.

FloodFill                         Fills the display surface within a
                                  border.

GetBitmapBits                     Retrieves the bits in memory for a
                                  specific bitmap.

GetBitmapDimension                Retrieves the dimensions of a bitmap.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetPixel                          Retrieves the RGB value for a pixel.

LoadBitmap                        Loads a bitmap from a resource file.

PatBlt                            Creates a bit pattern.

SetBitmapBits                     Sets the bits of a bitmap.

SetBitmapDimension                Sets the height and width of a bitmap.

SetPixel                          Sets the RGB value for a pixel.

StretchBlt                        Copies a bitmap from a source to a
                                  destination device (compresses or
                                  stretches, if necessary).


2.11.1  Bitmaps and Devices

The relationship between bitmap bits in memory and pixels on a device is
device-dependent. On a monochrome device, the correspondence is usually
one-to-one, where one bit in memory corresponds to one pixel on the device.



2.11.2  Device-Independent Bitmap Functions

Microsoft Windows version 3.0 provides a set of functions that define and
manipulate color bitmaps which can be appropriately displayed on any device
with a given resolution, regardless of the method by which the display
represents color in memory. These functions translate a device-independent
bitmap specification into the device-specific format used by the current
display. The following is a list of these functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateDIBitmap                    Creates a device-specific memory bitmap
                                  from a device-independent bitmap (DIB)
                                  specification and optionally initializes
                                  bits in the bitmap. This function is
                                  similar to CreateBitmap.

GetDIBits                         Retrieves the bits in memory for a
                                  specific bitmap in device-independent
                                  form. This function is similar to
                                  GetBitmapBits.

SetDIBits                         Sets a memory bitmap's bits from a DIB.
                                  This function is similar to
                                  SetBitmapBits.

SetDIBitsToDevice                 Sets bits on a device surface directly
                                  from a DIB.

Function                          Description
────────────────────────────────────────────────────────────────────────────
StretchDIBits                     Moves a device-independent bitmap (DIB)
                                  from a source rectangle into a
                                  destination rectangle, stretching or
                                  compressing the bitmap as required.

A device-independent bitmap specification consists of two parts:


  1.  A BITMAPINFO data structure that defines the format of the bitmap and
      optionally supplies a table of colors used by the bitmap

  2.  An array of bytes that contain the bitmap bit values


Depending on the values contained in the bitmap information data structure,
the bitmap bit values can specify explicit color (RGB) values or indexes
into the color table. In addition, the color table can consist of indexes
into the currently realized logical palette instead of explicit RGB color
values. It is important to note that the coordinate-system origin for DIBs
is the lower-left corner, not the Windows default upper-left corner.


2.12  Text Functions

Text functions retrieve text information, alter text alignment, alter text
justification, and write text on a device or display surface. GDI uses the
current font for text output. The following list briefly describes each text
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ExtTextOut                        Writes a character string, within a
                                  rectangular region, using the currently
                                  selected font. The rectangular region
                                  can be opaque (filled with the current
                                  background color) and it can be a
                                  clipping region.

GetTabbedTextExtent               Computes the width and height of a line
                                  of text containing tab characters.

GetTextAlign                      Returns a mask of the text alignment
                                  flags.

GetTextExtent                     Uses the current font to compute the
                                  width and height of text.

GetTextFace                       Copies the current font name to a buffer.

GetTextMetrics                    Fills the buffer with metrics for the
                                  selected font.

SetTextAlign                      Positions a string of text on a display
                                  or device.

SetTextJustification              Justifies a text line.

Function                          Description
────────────────────────────────────────────────────────────────────────────
TabbedTextOut                     Writes a character string with expanded
                                  tabs, using the current font.

TextOut                           Writes a character string using the
                                  current font.


2.13  Font Functions

Font functions select, create, remove, and retrieve information about fonts.
A font is a subset of a particular typeface, which is a set of characters
that share a similar fundamental design.

The following list briefly describes each font function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AddFontResource                   Adds a font resource in the specified
                                  file to the system font table.

CreateFont                        Creates a logical font that has the
                                  specified characteristics.

CreateFontIndirect                Creates a logical font that has the
                                  specified characteristics.

EnumFonts                         Enumerates the fonts available on a
                                  given device.

GetCharWidth                      Retrieves the widths of individual
                                  characters.

RemoveFontResource                Removes a font resource from the font
                                  table.

SetMapperFlags                    Alters the algorithm the font mapper
                                  uses.

A font family is a group of typefaces that have similar stroke-width and
serif characteristics. A typeface is a set of characters (letters, numerals,
punctuation marks, symbols) that share a common design. Font characters
share very specific characteristics, such as point size and weight.

Note that the terms GDI uses to describe fonts, typefaces, and families of
fonts do not necessarily correspond to traditional typographic terms.

The Helv typeface is an example of a familiar typeface. Available fonts
within this typeface include 8-point Helv bold and 10-point Helv italic.

Figure 2.9 shows several fonts from the Helv and Courier typefaces:

(This figure may be found in the printed book.)


2.13.1  Font Family

GDI organizes fonts by family; each family consists of typefaces and fonts
that share a common design. The families are divided by stroke width and
serif characteristics. The term stroke, which means a horizontal or vertical
line, comes from handwritten characters composed of one or more pen strokes.
The horizontal stroke is called a cross-stroke. The main vertical line is
called a stem. Figure 2.10 shows a lowercase f composed of a cross-stroke
and a stem with a loop at the top:

(This figure may be found in the printed book.)

Serifs are short cross-lines drawn at the ends of the main strokes of a
letter. If a typeface does not have serifs, it is generally called a
sans-serif (without serif) typeface. Figure 2.11 shows serifs:

(This figure may be found in the printed book.)

GDI uses five distinct family names to categorize typefaces and fonts. A
sixth name is used for generic cases. Note that GDI's family names do not
correspond to traditional typographic categories. Table 2.4 lists the
font-family names and briefly describes each family:

Table 2.4  Font Families

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Name                              Description
────────────────────────────────────────────────────────────────────────────
Dontcare                          Generic family name. Used when
                                  information about a font does not exist
Name                              Description
────────────────────────────────────────────────────────────────────────────
                                  information about a font does not exist
                                  or does not matter.

Decorative                        Novelty fonts.

Modern                            Constant stroke width (fixed-pitch),
                                  with or without serifs. Fixed-pitch
                                  fonts are usually modern.

Roman                             Variable stroke width (proportionally
                                  spaced), with serifs.

Script                            Designed to look like handwriting.

Swiss                             Variable stroke width (proportionally
                                  spaced), without serifs.

────────────────────────────────────────────────────────────────────────────

Name                              Description
────────────────────────────────────────────────────────────────────────────




2.13.2  Character Cells

A character is the basic element in a font. In GDI, each character is
contained within a rectangular region known as a character cell. This
rectangular region consists of a specific number of rows and columns, and
possesses six points of measurement: ascent, baseline, descent, height,
origin, and width. The following list describes these measurements:

Measurement                       Description
────────────────────────────────────────────────────────────────────────────
Ascent                            Specifies the distance in character-cell
                                  rows from the character-cell baseline to
                                  the top of the character cell.

Baseline                          Serves as the base on which all
                                  characters stand (some lowercase letters
                                  have descenders, such as the tail of the
                                  g or y, that descend below the baseline).

Descent                           Specifies the distance in character-cell
                                  rows from the character-cell baseline to
                                  the bottom of the character cell.

Height                            Specifies the height of a character-cell
                                  row.

Measurement                       Description
────────────────────────────────────────────────────────────────────────────
Origin                            Used as a point of reference when the
                                  character is written on a device or a
                                  display surface. The origin is the
                                  upper-left corner of the character cell.

Width                             Specifies the width of a character-cell
                                  column.

Figure 2.12 shows a character cell that contains an uppercase A. The
baseline appears at the top of the second row. Note that the uppercase A
uses the baseline as its starting point. Also note that the width and height
values refer to the character-cell width and height, not the width and
height of the individual character:

(This figure may be found in the printed book.)


2.13.3  Altering Characters

Characters exist in many sizes and shapes. The following sections describe
how characters are altered in GDI to produce a particular font.


Italic

For an italic font, GDI skews the characters so that they appear slanted.
When italicized, the base of the character remains intact while the upper
portion shifts to the right. The greatest amount of shifting occurs at the
top of the character, the least amount at the base. Figure 2.13 shows
characters before and after being italicized:

(This figure may be found in the printed book.)


Bold

A font is made bold by increasing its weight, which refers to the thickness
of the lines or strokes that compose a character. Fonts with a heavy weight
are referred to as bold. Figure 2.14 shows normal and bold characters:

(This figure may be found in the printed book.)


Underline

An underline font has a line under each character. When a character is
underlined, a solid line appears directly below the baseline of the
character cell. Figure 2.15 shows underlined characters:

(This figure may be found in the printed book.)


Strikeout

A strikeout font has a solid horizontal line drawn through each character.
The position of this line within each character cell is constant for a given
font. Figure 2.16 shows characters that are struck out:

(This figure may be found in the printed book.)


2.13.4  Leading

Leading is the distance from baseline to baseline of two adjacent rows of
text. When font designers develop a font, they specify that a given amount
of space should appear between rows. The addition of this space ensures that
a character is not obscured by part of another character in an adjacent row.
There are two ways of adding this additional space: by inserting it within
the character cells of a font (internal leading) or by inserting it between
rows of text as they are printed on a device (external leading).


Internal Leading

Internal leading refers to the space inserted within character cells of a
particular font. Only marks such as accents, umlauts, and tildes in foreign
character sets appear within the space allocated for internal leading.
Figure 2.17 shows two rows of text that use internal leading:

(This figure may be found in the printed book.)


External Leading

External leading is space inserted between the top and bottom of character
cells in adjacent rows of text. The font designer must specify the amount of
external leading necessary to produce easily readable text from a particular
font. External leading is not built into a font; you must add it before you
print text on a device. Figure 2.18 shows external leading:

(This figure may be found in the printed book.)


2.13.5  Character Set

All fonts use a character set. A character set contains punctuation marks,
numerals, uppercase and lowercase letters, and all other printable
characters. The designer of a character set assigns a numeric value to each
element in the set. You use this number to access an element within the set.


Most character sets used in Windows are supersets of the U.S. ASCII
character set, which defines characters for the 96 numeric values from 32 to
127. There are four major groups of character sets:


  ■   ANSI

  ■   OEM

  ■   Symbol

  ■   Vendor specific



ANSI Character Set

The ANSI character set is the most commonly used character set. The blank
character is the first character in the ANSI character set. It has a
hexadecimal value of 0x20, which is equivalent to the decimal value 32. The
last character in the ANSI character set has a hexadecimal value of 0xFF,
which is equivalent to the decimal value 255.

Many fonts specify a default character. Whenever a request is made for a
character not in the set, this default character is given. Most fonts using
the ANSI character set specify the period (.) as the default character. The
hexadecimal value for the period is 0x2E, or decimal 46 in the ANSI
character set.

Fonts use a break character to separate words and justify text. Most fonts
using the ANSI character set specify the blank character, whose hexadecimal
value is 0x20, decimal 32.


OEM Character Set

Windows supports a second character set, referred to as the OEM character
set. This is generally the character set used internally by DOS for screen
display. Characters 32 to 127 of the OEM set are usually identical to the
same characters in the U.S. ASCII set, which are also in the ANSI set. The
remaining characters in the OEM set (0 to 31, and 128 to 255) correspond to
the characters which may be shown on the computer's DOS display, and
generally differ from ANSI characters.


Symbol Character Set

The symbol character set contains special characters typically used to
represent mathematical and scientific formulas.


Vendor-Specific Character Sets

Many printers and other output devices contain fonts based on character sets
which differ from the ANSI and OEM sets, such as the EBCDIC character set.
In such cases, the printer driver must translate from the ANSI character set
to one or more of the sets provided by the printer or other device.


2.13.6  Pitch

The term pitch traditionally refers to the number of characters from a
particular font that will fit in a single inch. GDI, however, uses this term
differently. The term fixed-pitch refers to a font whose character-cell size
is constant for each character. The term variable-pitch refers to a font
whose character cells vary in size, depending on the actual width of the
characters.


Average Character Width

Variable-pitch fonts use the average character width to specify the average
width of character cells in the font. Since there is no variance in
character-cell width for fixed-pitch fonts, the average character width
specifies the character width of any character in the fixed-pitch font.


Maximum Character Width

Variable-pitch fonts use the maximum character width to specify the maximum
width of any character cell in the font. Since there is no variance in
character width for fixed-pitch fonts, the maximum character width is
equivalent to the average character width in the fixed-pitch font.


Digitized Aspect

When raster fonts are created, they are designed with one particular aspect
ratio in mind. The aspect ratio is the ratio of the width and height of a
device's pixel. GDI maintains a record of the ideal x-aspect and y-aspect
for individual fonts. The ideal x-aspect is the width value from the aspect
ratio of the device. The ideal y-aspect is the height value from the aspect
ratio of the device. These values are called the digitized aspects for x and
y. The GetAspectRatioFilter function retrieves the setting for the current
aspect-ratio filter. Windows provides a special filter, the aspect-ratio
filter, to select fonts designed for a particular aspect ratio from all of
the available fonts. The filter uses the aspect ratio specified by the
SetMapperFlags function.


Overhang

When a particular font is not available on a device, GDI sometimes
synthesizes that font. The process of synthesizing may add width or height
to an existing font. Whenever GDI synthesizes an italic or bold font from a
normal font, extra columns are added to individual character cells in that
font. The difference in width (the extra columns) between a string created
with the normal font and a string created with the synthesized font is
called the overhang.


2.13.7  Selecting Fonts with GDI

GDI maintains a collection of fonts from different typefaces. In addition to
this collection, some devices maintain a collection of hardware fonts in
their ROM. GDI lets you describe a font and then selects the closest
matching available font from your description.

GDI requires you to describe the font you want to use to create text. The
font you describe is a logical font (it may or may not actually exist). GDI
compares this logical font to the available physical fonts and selects the
closest match.

The process of selecting the physical font that bears the closest
resemblance to the specified logical font is known as font mapping. GDI also
maintains a font table. Each entry in the font table describes a physical
font and its attributes. Included in each entry is a pointer to a
corresponding font resource. Figure 2.19 shows a font table that contains
fonts X, Y, and Z:

(This figure may be found in the printed book.)


Font-Mapping Scheme

GDI cannot guarantee that a physical font exists that exactly matches a
requested logical font, so GDI attempts to pick a font that has the fewest
differences from the requested logical font. Since fonts have many different
attributes, the GDI font mapper assigns penalties to physical fonts whose
characteristics do not match the characteristics of the specified logical
font. The physical font with the fewest penalties assigned is the one that
GDI selects.

To begin the mapping, GDI transforms the requested height and width of the
logical font to device units. This transformation depends on the current
mapping mode and window and viewport extents. GDI then asks the device to
realize the physical font. A device can realize a font if it can create it
or a font very close to it.

If the device can realized a physical font, GDI compares this font with its
own set of fonts. If GDI has a font that more closely matches the logical
font, GDI uses it. But if the device signals that it can take
device-realized fonts only, GDI uses the realized font.

If the device cannot realize a font, GDI searches its own fonts for a match.


To determine how good a match a given physical font is to the requested
logical font, the mapper takes the logical font and compares it one
attribute at a time with each physical font in the system.

Table 2.5 lists the characteristics that are penalized by GDI's font mapper.
The characteristics are grouped according to penalty weights, with the
heaviest penalty assigned to the CharSet characteristic and the lightest
penalty assigned to the Weight, Slant, Underline, and StrikeOut
characteristics.

Table 2.5  Font-Mapping Characteristics

╓┌───────────────┌────────────────────────────────────────────────────────┌──╖
Characteristic  Penalty Scheme
────────────────────────────────────────────────────────────────────────────
CharSet         If the character set does not match, the candidate font  4
                is penalized heavily. Fonts with the wrong character
                set are very rarely selected as the physical font.
                There is no default character set. This means a logical
                font must alway specify the desired set.

Pitch           The wrong pitch is penalized heavily. If the requested   3
                pitch is fixed, a wrong pitch is assessed a greater
Characteristic  Penalty Scheme
────────────────────────────────────────────────────────────────────────────
CharSet         If the character set does not match, the candidate font  4
                pitch is fixed, a wrong pitch is assessed a greater
                penalty since an application that handles fixed pitches
                may not be able to handle variable-pitch fonts.

Family          If the font families do not match, the candidate font    3
                is penalized heavily. If a default font family is
                requested, no penalties are assessed.

FaceName        If the font typeface names do not match, the candidate   3
                font is penalized heavily. If a default font facename
                is requested, no penalties are assessed.

Height          The wrong height is penalized. GDI always chooses or     2
                synthesizes a shorter font if the exact height is not
                available. GDI can synthesize a font by expanding a
                font's character bitmaps by an integer multiple. GDI
                will expand a font up to eight times. If a default
                height is requested, GDI arbitrarily searches for a
Characteristic  Penalty Scheme
────────────────────────────────────────────────────────────────────────────
CharSet         If the character set does not match, the candidate font  4
                height is requested, GDI arbitrarily searches for a
                twelve-point font.

Width           The wrong width is penalized. GDI always chooses or      2
                synthesizes a narrower font if the exact width is not
                available. If a default width is requested, GDI
                assesses a penalty for any difference between the
                aspect ratio of the device and the aspect ratio of the
                font. The mapper can give unexpected results if there
                are no fonts for the given aspect ratio.

Weight          Although GDI can synthesize bold, an actual bold font    1
                is preferred. The mapper penalizes for synthesizing.

Slant           Although GDI can synthesize italics, an actual italic    1
                font is preferred. The mapper penalizes for
                synthesizing.

Characteristic  Penalty Scheme
────────────────────────────────────────────────────────────────────────────
CharSet         If the character set does not match, the candidate font  4



Table 2.5  Font-Mapping Characteristics (continued)

Characteristic  Penalty Scheme
────────────────────────────────────────────────────────────────────────────
Underline       Although GDI can synthesize underlining, an actual       1
                underline font is preferred. The mapper penalizes for
                synthesizing.

StrikeOut       Although GDI can synthesize strikeouts, an actual        1
                strikeout font is preferred. The mapper penalizes for
                synthesizing.

────────────────────────────────────────────────────────────────────────────


If GDI synthesizes a font, the mapper assesses a penalty that depends on the
number of times the font was replicated. Furthermore, a penalty is added if
the font was synthesized in both directions and the synthesizing was uneven,
that is, if the font was stretched more in one direction than the other.

When the mapper has compared all the fonts in the system, it picks the one
with the smallest penalty. The application should retrieve the metrics of
the font to find out the characteristics of the font it received.

The penalty weights listed in Table 2.5 are the default penalties used by
GDI.


Example of Font Selection

For the purpose of this example, assume that the system font table lists
only the three fonts shown in Figure 2.19, "A GDI Font Table," fonts X, Y,
and Z. Suppose you need to use a specific font, font Q, to create text on an
output device. You will need to describe font Q so that GDI can choose the
physical font (X, Y, or Z) that bears the closest resemblance to Q.

To describe font Q, you use the CreateFont or CreateFontIndirect GDI
function. These functions create a logical font which is a description of
the desired physical font.

Use the SelectObject function to select the physical font that most closely
matches logical font Q. (The SelectObject function requires that you pass a
handle to font Q.) Once a call to the SelectObject function occurs, GDI will
initiate the selection process.

Table 2.6 shows the physical fonts in the font table and the penalties that
GDI assigns to each as it tries to find a font that will match font Q. The
left column shows the font attributes that GDI compares; the second column
gives the attributes of font Q, the desired font. The attributes of fonts X,
Y, and Z─the fonts that are actually in the system font table─are followed
by the penalty values that GDI gives to each one. The bottom row of the
table gives the penalty totals for each font:

Table 2.6  Sample Font Selection Ratings

╓┌───────────┌──────────┌──────────┌───────────────┌──────────┌──┌──────────┌►
─────────────────────────────────────────────────────────────────────────────
─────────────────────────────────────────────────────────────────────────────
            Desired               Available
                                  Fonts/Penalty
                                  Score

Attributes   Q            X                          Y             Z

─────────────────────────────────────────────────────────────────────────────

CharSet     ANSI       OEM        4               OEM        4  ANSI       0

Pitch       Fixed      Variable   3               Fixed      0  Variable   3

Family      Roman      Modern     3               Roman      0  Modern     3

FaceName    Tms Rmn    Pica       3               Tms Rmn    0  Elite      3

Height      8          10         2               10         2  8          0

Width       4          6          2               6          2  4          0

─────────────────────────────────────────────────────────────────────────────

Slant       None       None       0               None       0  None       0

Underline   None       None       0               None       0  None       0

StrikeOut   None       None       0               None       0  None       0

─────────────────────────────────────────────────────────────────────────────

Penalty                           17                         8             9
Total

─────────────────────────────────────────────────────────────────────────────



The penalty totals show that font Y has the lowest penalty score and
therefore resembles font Q most closely. In this example, GDI would select
font Y as the physical font on the output device.


2.13.8  Font Files and Font Resources

GDI stores information about the physical font in font files. The font file
consists of a header and a bitmap. The font-file header contains a detailed
description of the font. If the font file is a raster file, the font-file
bitmap contains actual representations of the font characters. If the font
file is a vector file, the font-file bitmap contains character strokes for
the font characters. A font resource is a collection of one or more of these
physical-font files.


2.14  Metafile Functions

Metafile functions close, copy, create, delete, retrieve, play, and return
information about metafiles. A metafile is a collection of GDI commands that
creates desired text or images.

Metafiles provide a convenient method of storing graphics commands that
create text or images. Metafiles are especially useful in applications that
use specific text or a particular image repeatedly. They are also
device-independent; by creating text or images with GDI commands and then
placing the commands in a metafile, an application can re-create the text or
images repeatedly on a variety of devices. Metafiles are also useful in
applications that need to pass graphics information to other applications.

The following list briefly describes each metafile function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CloseMetaFile                     Closes a metafile and creates a metafile
                                  handle.

CopyMetaFile                      Copies a source metafile to a file.

CreateMetaFile                    Creates a metafile display context.

DeleteMetaFile                    Deletes a metafile from memory.

EnumMetaFile                      Enumerates the GDI calls within a
                                  metafile.

GetMetaFile                       Creates a handle to a metafile.

GetMetaFileBits                   Stores a metafile as a collection of
                                  bits in a global memory block.

PlayMetaFile                      Plays the contents of a specified
                                  metafile.

PlayMetaFileRecord                Plays a metafile record.

SetMetaFileBits                   Creates a memory metafile.


2.14.1  Creating a Metafile

A Windows application must create a metafile in a special device context. It
cannot use the device contexts that the CreateDC or GetDC functions return;
instead, it must use the device context that the CreateMetaFile function
returns.

Windows allows an application to use a subset of the GDI functions to create
a metafile. This subset is the set of all GDI functions that create output
(it is not necessary to use those functions that provide state information,
such as the GetDeviceCaps or GetEnvironment functions). The following is a
list of GDI functions an application can use in a metafile:

AnimatePalette           OffsetViewportOrg        SetBkMode
Arc                      OffsetWindowOrg          SetDIBitsToDevice
BitBlt                   PatBlt                   SetMapMode
Chord                    Pie                      SetMapperFlags
CreateBrushIndirect      Polygon                  SetPixel
CreateDIBPatternBrush    Polyline                 SetPolyFillMode
CreateFontIndirect       PolyPolygon              SetROP2
CreatePatternBrush       RealizePalette           SetStretchBltMode
CreatePenIndirect        Rectangle                SetTextAlign
CreateRegion             ResizePalette            SetTextCharExtra
DrawText                 RestoreDC                SetTextColor
Ellipse                  RoundRect                SetTextJustification
Escape                   SaveDC                   SetViewportExt
ExcludeClipRect          ScaleViewportExt         SetViewportOrg
ExtTextOut               ScaleWindowExt           SetWindowExt
FloodFill                SelectClipRegion         SetWindowOrg
IntersectClipRect        SelectObject             StretchBlt
LineTo                   SelectPalette            StretchDIBits
MoveTo                   SetBkColor               TextOut
OffsetClipRgn

To create output with a metafile, an application must follow four steps:


  1.  Create a special device context by using the CreateMetaFile function.

  2.  Send GDI commands to the metafile by using the special device context.

  3.  Close the metafile by calling the CloseMetaFile function. This
      function returns a metafile handle.

  4.  Display the image or text on a device by using the PlayMetaFile
      function, passing to the function the metafile handle obtained from
      CloseMetaFile and a device-context handle for the device to which the
      metafile is to be played.


The device context which CreateMetaFile creates does not have default
attributes of its own. Whatever device-context attributes are in effect for
the output device when an application plays a metafile will be the defaults
for the metafile. The metafile can change these attributes while it is
playing. If the application needs to retain the same device-context
attributes after the metafile has finished playing, it should save the
output device context by calling the SaveDC function before calling
PlayMetaFile. Then, when PlayMetaFile returns, the application can call the
RestoreDC function (with -1 as the nSavedDC parameter) to restore the
original device-context attributes.

Although the maximum size of a metafile is 232 bytes or records, the actual
size of a metafile is limited by the amount of memory or disk space
available.


2.14.2  Storing a Metafile in Memory or on Disk

An application can store a metafile in system memory or in a disk file.

To store the metafile in memory, an application calls CreateMetafile and
passes NULL as the function parameter.

There are two ways of storing a metafile in a disk file:


  ■   When the application calls CreateMetaFile to open a metafile, it
      passes a filename as the function parameter; the metafile will then be
      recorded in a disk file.

  ■   After the application has created a metafile in memory, it calls the
      CopyMetaFile function. This function accepts the handle of a memory
      metafile and the filename of the disk file which is to save the
      metafile.


The GetMetaFile function opens a metafile stored in a disk file and makes it
available for replay or modification. This function accepts the filename of
a metafile stored on disk and returns a metafile handle.


2.14.3  Deleting a Metafile

An application frees the memory which Windows uses to store the metafile by
calling the DeleteMetafile function. This function removes a metafile from
memory and invalidates its handle. It has no effect on disk files.


2.14.4  Changing How Windows Plays a Metafile

A metafile does not have to be played back in its entirety or exactly in the
form in which it was recorded. An application can use the EnumMetaFile
function to locate a specific metafile record. EnumMetaFile calls an
application-supplied callback function and passes it the following:


  ■   The metafile device context

  ■   A pointer to the metafile handle table

  ■   A pointer to a metafile record

  ■   The number of associated objects with handles in the handle table

  ■   A pointer to application-supplied data


The callback function can then use this information to play a single record,
to query it, copy it, or modify it. The PlayMetaFileRecord function plays a
single metafile record.

Chapter 9, "File Formats," in Reference, Volume 2, shows the formats of the
various metafile records and describes their contents.

When Windows plays or enumerates the records in a metafile, it identifies
each object with an index into a handle table. Functions that select objects
(such as SelectObject and SelectPalette) identify the object by means of the
object handle which the application passes to the function.

Objects are added to the table in the order in which they are created. For
example, if a brush is the first object created in a metafile, the brush is
given index zero. If the second object is a pen, it is given index 1, and so
on. See the description of the HANDLETABLE data structure in Chapter 7,
"Data Types and Structures," in Reference, Volume 2, for information on the
format of the handle table.


2.15  Printer-Control Functions

Printer-control functions retrieve information about a printer and modify
its initialization state. The printer driver, rather than GDI itself,
provides these functions. The following list briefly describes each
printer-control function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
DeviceCapabilities                Retrieves capabilities of a printer
                                  device driver.

DeviceMode                        Sets the current printing modes for a
                                  device by prompting the user with a
                                  dialog box.

ExtDeviceMode                     Retrieves or modifies device
                                  initialization information for a given
                                  printer driver or displays a
                                  driver-supplied dialog box for
                                  configuring the driver.


2.16  Printer-Escape Function

The Escape function allows an application to access facilities of a
particular device that are not directly available through GDI. The nEscape
parameter of this function specifies the escape function to be performed.
When an application calls Escape for a printer device context, the escape
functions regulate the flow of printer output from Windows applications,
retrieve information about a printer, and alter the settings of a printer.


2.16.1  Creating Output on a Printer

Windows applications use only the standard Windows functions to access
system memory, the output device, the keyboard, and the mouse. Each
application interacts with the user through one or more windows that are
created and maintained by the user. GDI assists an application in creating
output by passing device-independent function calls from the application to
the device driver. The device driver first translates these
device-independent function calls into device-dependent operations that
create images on a device's display surface, and then sends them to Print
Manager (the spooler). Print Manager serves two purposes: it collects
translated commands from one application and stores them in a corresponding
job, and it passes a complete job to the device for output. Figure 2.20
shows the path of output from a Windows application to a device:

(This figure may be found in the printed book.)

If only one Windows application were allowed to run at any given time, Print
Manager and many of the escape functions would be unnecessary. However,
Windows allows several applications to run at once. If two or more of these
applications send output simultaneously, each application's output must be
separated and remain separated during printing or plotting. Print Manager
maintains this separation. The printer-escape functions affect the way Print
Manager handles this separation task.


2.16.2  Banding Output

The model used by GDI states that any point on an output device can be
written to at any time. This model is easily implemented on vector devices
but poses a problem on many dot-matrix devices that cannot scroll backward.
Banding provides a solution to this problem.

Banding involves several steps:


  1.  The application creates a metafile and uses it as an intermediate
      storage device for the output.

  2.  Beginning at the top of the metafile, GDI translates a rectangular
      region (band) of output into device-specific commands, and then sends
      it to a corresponding job.

  3.  The application repeats this process until the entire metafile has
      been converted to bands and the output from these bands has been
      translated into device-specific commands and stored in a job.

  4.  The application sends the job to the output device.


When creating a device context, GDI verifies whether the device has banding
capabilities. If it does, GDI creates the metafile that will be used during
the banding process. To implement banding, you call the necessary output
functions and the NEXTBAND escape. The NEXTBAND escape requires a long
pointer to a RECT data structure as its output parameter. The device driver
copies the coordinates of the next band into this structure. When the entire
metafile has been converted into device-specific commands, the driver
returns four zeros (0,0,0,0) in the RECT structure.

GDI does the banding for you if your output device has banding capabilities
and you call the NEWFRAME escape. Although NEWFRAME requires more memory and
is slower, it does simplify the output process. After the application
creates each page of output, it calls the NEWFRAME escape. If the device is
capable of banding, GDI copies output to a metafile and calls the NEXTBAND
escape for you. As discussed earlier, the NEXTBAND escape causes the
contents of the metafile to be converted into device-specific commands and
to be copied to a corresponding job. If a memory problem occurs or the user
terminates a job, the NEWFRAME escape returns a message that defines the
error or abort message.


2.16.3  Starting and Ending a Print Job

The STARTDOC escape informs the device driver that an application is
beginning a new print job. After the STARTDOC call is issued, Print Manager
queues all output from a particular application in a corresponding job until
an ENDDOC escape is issued. (Note that you cannot use the ENDDOC escape to
terminate a job.)


2.16.4  Terminating a Print Job

If you send output to a device with the NEWFRAME escape, you are required to
write a termination procedure and supply it with the application. The
SETABORTPROC escape sets a pointer to this procedure; it should be called
prior to the STARTDOC escape. The ABORTDOC escape terminates print jobs if
it is called before the first call to NEWFRAME. It should also be used to
terminate jobs that use the NEXTBAND escape.


2.16.5  Information Escapes

Four of the escape functions are used to retrieve information about the
selected device and its settings. The GETPHYSPAGESIZE escape retrieves the
physical page size of the output device (in device units), the smallest
addressable units on the device. For example, one-fortieth of a millimeter
is the smallest addressable unit on some vector devices. A pixel is the
smallest addressable unit on a dot-matrix device. The GETPRINTINGOFFSET
escape retrieves the distance (in device units) from the upper-left corner
of the page to the point at which printing begins. The GETSCALINGFACTOR
escape retrieves the scaling factors for the x- and y-axes of a device. The
scaling factor expresses the number of logical units that are mapped to a
device unit. The QUERYESCSUPPORT escape determines whether a particular
escape function is implemented on a device driver. If the escape in question
is implemented, QUERYESCSUPPORT returns a nonzero value. If the escape is
not implemented, QUERYESCSUPPORT returns zero.


2.16.6  Additional Escape Calls

There are two additional escapes that alter the state of the device: the
FLUSHOUTPUT and DRAFTMODE escapes. The FLUSHOUTPUT escape flushes the output
in the device's buffer (the device stores device operations in the buffer
before sending them to Print Manager). The DRAFTMODE escape turns on the
device's draft mode. This means that the device will use one of its own
fonts instead of using a GDI font. It also means that calls to the
text-justification functions that alter interword and intercharacter spacing
are ignored. For a detailed description of the functions that alter
interword and intercharacter spacing, see Sections 2.12, "Text Functions,"
and 2.13, "Font Functions."


2.17  Environment Functions

Environment functions alter and retrieve information about the environment
associated with an output device. The following list briefly describes the
two enviornment functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetEnvironment                    Copies environment information into a
                                  buffer.

SetEnvironment                    Copies data to the environment
                                  associated with an attached device.


2.18  Summary

Graphics device interface (GDI) functions perform device-independent
graphics operations within a Windows application. For more information on
topics related to GDI functions, see the following:

╓┌─────────────────────────────────────┌─────────────────────────────────────╖
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
Function descriptions                 Reference, Volume 1: Chapter 4,
                                      "Functions Directory"

Windows data types and structures     Reference, Volume 2: Chapter 7,
                                      "Data Types and Structures"

Metafile formats                      Reference, Volume 2: Chapter 9,
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
Metafile formats                      Reference, Volume 2: Chapter 9,
                                      "File
                                      Formats"

Raster operations                     Reference, Volume 2: Chapter 11,
                                      "Binary and Ternary Raster-Operation
                                      Codes"

Printer escapes                       Reference, Volume 2: Chapter 12,
                                      "Printer Escapes"

Drawing text and graphics in a        Guide to Programming: Chapter 3,
window                                "Output to a Window"

Drawing bitmaps                       Guide to Programming: Chapter 11,
                                      "Bitmaps"

Sending output to a printer           Guide to Programming: Chapter 12,
                                      "Printing," and Chapter 17, "Print
Topic                                 Reference
────────────────────────────────────────────────────────────────────────────
                                      "Printing," and Chapter 17, "Print
                                      Settings"

Text fonts                            Guide to Programming: Chapter 18,
                                      "Fonts"

Color palettes                        Guide to Programming: Chapter 19,
                                      "Color Palettes"








Chapter 3  System Services Interface Functions
────────────────────────────────────────────────────────────────────────────

This chapter describes the system services interface functions. These
functions access code and data in modules, allocate and manage both local
and global memory, manage tasks, load program resources, translate strings
from one character set to another, alter the Microsoft 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.

This chapter lists the following categories of functions:


  ■   Module-management functions

  ■   Memory-management functions

  ■   Segment functions

  ■   Operating-system interrupt functions

  ■   Task functions

  ■   Resource-management functions

  ■   String-manipulation functions

  ■   Atom-management functions

  ■   Initialization-file functions

  ■   Communication functions

  ■   Sound functions

  ■   Utility macros and functions

  ■   File I/O functions

  ■   Debugging functions

  ■   Optimization-tool functions

  ■   Application-execution functions



3.1  Module-Management Functions

Module-management functions alter and retrieve information about Windows
modules, which are loadable, executable units of code and data. The
following list briefly describes each module-management function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
FreeLibrary                       Decreases the reference count of a
                                  library by one and removes it from
                                  memory if the reference count is zero.

FreeModule                        Decreases the reference count of a
                                  module by one and removes it from memory
                                  if the reference count is zero.

FreeProcInstance                  Removes a function instance entry at an
                                  address.

GetCodeHandle                     Determines which code segment contains a
                                  specified function.

GetInstanceData                   Copies data from an offset in one
                                  instance to an offset in another
                                  instance.

GetModuleFileName                 Copies a module filename.

GetModuleHandle                   Returns the module handle of a module.

GetModuleUsage                    Returns the reference count of a module.

GetProcAddress                    Returns the address of a function in a
                                  module.

GetVersion                        Returns the current version number of
                                  Windows.

LoadLibrary                       Loads a library module.

MakeProcInstance                  Returns a function-instance address.


3.2  Memory-Management Functions

Memory-management functions manage system memory. There are two categories
of functions: those that manage global memory and those that manage local
memory. Global memory is all memory in the system that has not been
allocated by an application or reserved by the system. Local memory is the
memory within a Windows application's data segment. The following list
briefly describes each memory-management function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
DefineHandleTable                 Creates a private handle table in an
                                  application's default data segment.

GetFreeSpace                      Retrieves the number of bytes available
                                  in the global heap.

GetWinFlags                       Retrieves information about the system
                                  memory configuration.

GlobalAlloc                       Allocates memory from the global heap.

GlobalCompact                     Compacts global memory to generate free
                                  bytes.

GlobalDiscard                     Discards a global memory block if the
                                  lock count is zero, but does not
                                  invalidate the handle of the memory
                                  block.

GlobalDosAlloc                    Allocates global memory that can be
                                  accessed by DOS running in real or
                                  protected mode.

GlobalDosFree                     Frees global memory previously allocated
                                  by the GlobalDosAlloc function.

GlobalFlags                       Returns the flags and lock count of a
                                  global memory block.

GlobalFree                        Removes a global memory block and
                                  invalidates the handle of the memory
                                  block.

GlobalHandle                      Retrieves the handle of a global memory
                                  object.

GlobalLock                        Retrieves a pointer to a global memory
                                  block specified by a handle. Except for
                                  nondiscardable objects in protected
                                  (standard or 386 enhanced) mode, the
                                  block is locked into memory at the given
                                  address and its lock count is increased
                                  by one.

GlobalLRUNewest                   Moves a global memory object to the
                                  newest least-recently-used (LRU)
                                  position.

GlobalLRUOldest                   Moves a global memory object to the
                                  oldest least-recently-used (LRU)
                                  position.

GlobalNotify                      Installs a notification procedure for
                                  the current task.

GlobalReAlloc                     Reallocates a global memory block.

GlobalSize                        Returns the size (in bytes) of a global
                                  memory block.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GlobalUnlock                      Invalidates the pointer to a global
                                  memory block previously retrieved by the
                                  GlobalLock function. In real mode, or if
                                  the block is discardable, GlobalUnlock
                                  decreases the block's lock count by one.

GlobalUnwire                      Decreases the lock count set by the
                                  GlobalWire function, and unlocks the
                                  memory block if the count is zero.

GlobalWire                        Moves an object to low memory and
                                  increases the lock count.

LimitEMSPages                     Limits the amount of expanded memory
                                  that Windows will assign to an
                                  application.

LocalAlloc                        Allocates memory from the local heap.

LocalCompact                      Compacts local memory.

LocalDiscard                      Discards a local memory block if the
                                  lock count is zero, but does not
                                  invalidate the handle of the memory
                                  block.

LocalFlags                        Returns the memory type of a local
                                  memory block.

LocalFree                         Frees a local memory block from memory
                                  if the lock count is zero and
                                  invalidates the handle of the memory
                                  block.

LocalHandle                       Retrieves the handle of a local memory
                                  object.

LocalInit                         Initializes a local heap in the
                                  specified segment.

LocalLock                         Locks a block of local memory by
                                  increasing its lock count.

LocalReAlloc                      Reallocates a local memory block.

LocalShrink                       Shrinks the local heap.

LocalSize                         Returns the size (in bytes) of a local
                                  memory block.

LocalUnlock                       Unlocks a local memory block.

LockData                          Locks the current data segment in memory.

LockSegment                       Locks a specified data segment in memory.

SetSwapAreaSize                   Increases the amount of memory that an
                                  application reserves for code segments.

Function                          Description
────────────────────────────────────────────────────────────────────────────
SwitchStackBack                   Returns the stack of the current task to
                                  the task's data segment after it had
                                  been previously redirected by the
                                  SwitchTasksBack function.

SwitchStackTo                     Changes the stack of the current task to
                                  the specified data segment, such as the
                                  data segment of a dynamic-link library
                                  (DLL).

UnlockData                        Unlocks the current data segment.

UnLockSegment                     Unlocks a specified data segment.


3.3  Segment Functions

Segment functions allocate, free, and convert selectors; lock and unlock
memory blocks referenced by selectors; and retrieve information about
segments. The following list briefly describes each selector function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AllocDStoCSAlias                  Accepts a data-segment selector and
                                  returns a code-segment selector that can
                                  be used to execute code in a data
                                  segment.

AllocSelector                     Allocates a new selector.

ChangeSelector                    Generates a temporary code selector that
                                  corresponds to a given data selector, or
                                  a temporary data selector that
                                  corresponds to a given code selector.

DefineHandleTable                 Creates a private handle table which
                                  Windows updates automatically.

FreeSelector                      Frees a selector originally allocated by
                                  the AllocSelector or AllocDStoCSAlias
                                  functions.

GetCodeInfo                       Retrieves information about a code
                                  segment.

GlobalFix                         Prevents a global memory block from
                                  moving in linear memory.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GlobalPageLock                    Page-locks the memory associated with
                                  the specified global selector and
                                  increments its page-lock count. Memory
                                  that is page-locked cannot be moved or
                                  paged out to disk.

GlobalPageUnlock                  Decrements the page-lock count for a
                                  block of memory. If the page-lock count
                                  reaches zero, the memory can be moved
                                  and paged out to disk.

GlobalUnfix                       Unlocks a global memory block previously
                                  fixed by the GlobalFix function.

LockSegment                       Locks a segment in memory.

UnlockSegment                     Unlocks a segment previously locked by
                                  the LockSegment function.

────────────────────────────────────────────────────────────────────────────
NOTE

An application should not use these functions unless it is absolutely
necessary. Use of these functions violates preferred Windows programming
practices.
────────────────────────────────────────────────────────────────────────────


3.4  Operating-System Interrupt Functions

Operating-system interrupt functions allow an assembly-language application
to perform certain DOS and NETBIOS interrupts without directly coding the
interrupt. This ensures compatibility with future Microsoft products.

The following list briefly describes these functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
DOS3Call                          Issues a DOS 21H (function-request)
                                  interrupt.

NetBIOSCall                       Issues a NETBIOS 5CH interrupt.


3.5  Task Functions

Task functions alter the execution status of tasks, return information
associated with a task, and retrieve information about the environment in
which the task is executing. A task is a single Windows application call.
The following list briefly describes each task function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
Catch                             Copies the current execution environment
                                  to a buffer.

ExitWindows                       Initiates the standard Windows shutdown
                                  procedure.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetCurrentPDB                     Returns the current DOS Program Data
                                  Base (PDB), also known as the Program
                                  Segment Prefix (PSP).

GetCurrentTask                    Returns the task handle of the current
                                  task.

GetDOSEnvironment                 Retrieves the environment string of the
                                  currently running task.

GetNumTasks                       Returns the number of tasks currently
                                  executing in the system.

SetErrorMode                      Controls whether Windows handles DOS
                                  Function 24H errors or allows the
                                  calling application to handle them.

Throw                             Restores the execution environment to
                                  the specified values.

Yield                             Halts the current task and starts any
                                  waiting task.


3.6  Resource-Management Functions

Resource-management functions find and load application resources from a
Windows executable file. A resource can be a cursor, icon, bitmap, string,
or font. The following list briefly describes each resource-management
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AccessResource                    Opens the specified resource.

AllocResource                     Allocates uninitialized memory for a
                                  resource.

FindResource                      Determines the location of a resource.

FreeResource                      Removes a loaded resource from memory.

LoadAccelerators                  Loads an accelerator table.

LoadBitmap                        Loads a bitmap resource.

LoadCursor                        Loads a cursor resource.

LoadIcon                          Loads an icon resource.

LoadMenu                          Loads a menu resource.

LoadResource                      Loads a resource.

LoadString                        Loads a string resource.

LockResource                      Retrieves the absolute memory address of
                                  a resource.

Function                          Description
────────────────────────────────────────────────────────────────────────────
SetResourceHandler                Sets up a function to load resources.

SizeofResource                    Supplies the size (in bytes) of a
                                  resource.

UnlockResource                    Unlocks a resource.


3.7  String-Manipulation Functions

String-manipulation functions translate strings from one character set to
another, determine and convert the case of strings, determine whether a
character is alphabetic or alphanumeric, find adjacent characters in a
string, and perform other string manipulation. The following list briefly
describes each string-translation function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AnsiLower                         Converts a character string to lowercase.

AnsiLowerBuff                     Converts a character string in a buffer
                                  to lowercase.

AnsiNext                          Returns a long pointer to the next
                                  character in a string.

AnsiPrev                          Returns a long pointer to the previous
                                  character in a string.

AnsiToOem                         Converts an ANSI string to an OEM
                                  character string.

AnsiToOemBuff                     Converts an ANSI string in a buffer to
                                  an OEM character string.

AnsiUpper                         Converts a character string to uppercase.

AnsiUpperBuff                     Converts a character string in a buffer
                                  to uppercase.

IsCharAlpha                       Determines whether a character is
                                  alphabetical.

IsCharAlphaNumeric                Determines whether a character is
                                  alphanumeric.

IsCharLower                       Determines whether a character is
                                  lowercase.

IsCharUpper                       Determines whether a character is
                                  uppercase.

lstrcat                           Concatenates two strings identified by
                                  long pointers.

lstrcmp                           Performs a case-sensitive comparison of
                                  two strings identified by long pointers.

lstrcmpi                          Performs a case-insensitive comparison
                                  of two strings identified by long
                                  pointers.

Function                          Description
────────────────────────────────────────────────────────────────────────────
lstrcpy                           Copies one string to another; both
                                  strings are identified by long pointers.

lstrlen                           Determines the length of a string
                                  identified by a long pointer.

OemToAnsi                         Converts an OEM character string to an
                                  ANSI string.

OemToAnsiBuff                     Converts an OEM character string in a
                                  buffer to an ANSI string.

ToAscii                           Translates a virtual-key code to the
                                  corresponding ANSI character or
                                  characters.

wsprintf                          Formats and stores a series of
                                  characters and values in a buffer.
                                  Format arguments are passed separately.

wvsprintf                         Formats and stores a series of
                                  characters and values in a buffer.
                                  Format arguments are passed through an
                                  array.


3.8  Atom-Management Functions

Atom-management functions create and manipulate atoms. Atoms are integers
that uniquely identify character strings. They are useful in applications
that use many character strings and in applications that need to conserve
memory. Windows stores atoms in atom tables. A local atom table is allocated
in an application's data segment; it cannot be accessed by other
applications. The global atom table can be shared, and is useful in
applications that use dynamic data exchange (DDE). The following list
briefly describes each atom-management function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AddAtom                           Creates an atom for a character string.

DeleteAtom                        Deletes an atom if the reference count
                                  is zero.

FindAtom                          Retrieves an atom associated with a
                                  character string.

GetAtomHandle                     Retrieves a handle (relative to the
                                  local heap) of the string that
                                  corresponds to a specified atom.

GetAtomName                       Copies the character string associated
                                  with an atom.

GlobalAddAtom                     Creates a global atom for a character
                                  string.

GlobalDeleteAtom                  Deletes a global atom if the reference
                                  count is zero.

Function                          Description
────────────────────────────────────────────────────────────────────────────
GlobalFindAtom                    Retrieves a global atom associated with
                                  a character string.

GlobalGetAtomName                 Copies the character string associated
                                  with a global atom.

InitAtomTable                     Initializes an atom hash table.

MAKEINTATOM                       Casts an integer for use as a function
                                  argument.


3.9  Initialization-File Functions

Initialization-file functions obtain information from and copy information
to the Windows initialization file WIN.INI and private initialization files.
A Windows initialization file is a special ASCII file that contains
key-name-value pairs that represent run-time options for applications. The
following list briefly describes each initialization-file function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetPrivateProfileInt              Returns an integer value in a section
                                  from a private initialization file.

GetPrivateProfileString           Returns a character string in a section
                                  from a private initialization file.

GetProfileInt                     Returns an integer value in a section
                                  from the WIN.INI file.

GetProfileString                  Returns a character string in a section
                                  from the WIN.INI file.

WritePrivateProfileString         Copies a character string to a private
                                  initialization file, or deletes one or
                                  more lines in a private initialization
                                  file.

WriteProfileString                Copies a character string to the WIN.INI
                                  file, or deletes one or more lines from
                                  WIN.INI.

An application should use a private (application-specific) initialization
file to record information which affects only that application. This
improves both the performance of the application and Windows itself by
reducing the amount of information that Windows must read when it accesses
the initialization file. An application should record information in WIN.INI
only if it affects the Windows environment or other applications; in such
cases, the application should send the WM_WININICHANGE message to all
top-level windows.

The files WININI.TXT and SYSINI.TXT supplied with the retail version of
Windows describe the contents of WIN.INI and SYSTEM.INI, respectively.


3.10  Communication Functions

Communication functions carry out communications through the system's serial
and parallel I/O ports. The following list briefly describes each
communication function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
BuildCommDCB                      Fills a device control block with
                                  control codes.

ClearCommBreak                    Clears the communication break state
                                  from a communication device.

CloseComm                         Closes a communication device after
                                  transmitting the current buffer.

EscapeCommFunction                Directs a device to carry out an
                                  extended function.

FlushComm                         Flushes characters from a communication
                                  device.

GetCommError                      Fills a buffer with the communication
                                  status.

GetCommEventMask                  Retrieves, then clears, an event mask.

GetCommState                      Fills a buffer with a device control
                                  block.

OpenComm                          Opens a communication device.

ReadComm                          Reads the bytes from a communication
                                  device into a buffer.

SetCommBreak                      Sets a break state on the communication
                                  device.

SetCommEventMask                  Retrieves and then sets an event mask on
                                  the communication device.

SetCommState                      Sets a communication device to the state
                                  specified by the device control block.

TransmitCommChar                  Places a character at the head of the
                                  transmit queue.

UngetCommChar                     Specifies which character will be the
                                  next character to be read.

WriteComm                         Writes the bytes from a buffer to a
                                  communication device.


3.11  Sound Functions

Sound functions create sound and music for the system's sound generator. The
following list briefly describes each sound function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
CloseSound                        Closes the play device after flushing
                                  the voice queues and freeing the buffers.

CountVoiceNotes                   Returns the number of notes in the
                                  specified queue.

GetThresholdEvent                 Returns a long pointer to a threshold
                                  flag.

GetThresholdStatus                Returns the threshold-event status for
                                  each voice.

OpenSound                         Opens the play device for exclusive use.

SetSoundNoise                     Sets the source and duration of a noise
                                  from the play device.

SetVoiceAccent                    Places an accent in the voice queue.

SetVoiceEnvelope                  Places the voice envelope in the voice
                                  queue.

SetVoiceNote                      Places a note in the specified voice
                                  queue.

SetVoiceQueueSize                 Allocates a specified number of bytes
                                  for the voice queue.

SetVoiceSound                     Places the specified sound frequency and
                                  durations in a voice queue.

SetVoiceThreshold                 Sets the threshold level for a given
                                  voice.

StartSound                        Starts playing each voice queue.

StopSound                         Stops playing all voice queues and
                                  flushes their contents.

SyncAllVoices                     Places a sync mark in each voice queue.

WaitSoundState                    Waits until the play driver enters the
                                  specified state.


3.12  Utility Macros and Functions

Utility macros and functions return contents of words and bytes, create
unsigned long integers and data structures, and perform specialized
arithmetic. The following list briefly describes each utility macro or
function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
HIBYTE                            Returns the high-order byte of an
                                  integer.

HIWORD                            Returns the high-order word of a long
                                  integer.

LOBYTE                            Returns the low-order byte of an integer.

LOWORD                            Returns the low-order word of a long
                                  integer.

MAKEINTATOM                       Casts an integer for use as a function
                                  argument.

MAKEINTRESOURCE                   Converts an integer value into a long
                                  pointer to a string, with the high-order
                                  word of the long pointer set to zero.

MAKELONG                          Creates an unsigned long integer.

MAKEPOINT                         Converts a long value that contains the
                                  x- and y-coordinates of a point into a
                                  POINT data structure.

MulDiv                            Multiplies two word-length values and
                                  then divides the result by a third
                                  word-length value, returning the result
                                  rounded to the nearest integer.

PALETTEINDEX                      Converts an integer into a palette-index
                                  COLORREF value.

PALETTERGB                        Converts three values for red, green,
                                  and blue into a palette-relative RGB
                                  COLORREF value.

RGB                               Converts three values for red, green,
                                  and blue into an explicit RGB COLORREF
                                  value.


3.13  File I/O Functions

File I/O functions create, open, read from, write to, and close files. The
following list briefly describes each file I/O function:

Function                          Description
────────────────────────────────────────────────────────────────────────────
GetDriveType                      Determines whether a disk drive is
                                  removeable, fixed, or remote.

GetSystemDirectory                Retrieves the pathname of the Windows
                                  system subdirectory.

GetTempDrive                      Returns the letter of the optimal drive
                                  for temporary file storage.

GetTempFileName                   Creates a temporary filename.

GetWindowsDirectory               Retrieves the pathname of the Windows
                                  directory.

Function                          Description
────────────────────────────────────────────────────────────────────────────
_lclose                           Closes a file.

_lcreat                           Creates a new file or opens and
                                  truncates an existing file.

_llseek                           Positions the pointer to a file.

_lopen                            Opens an existing file.

_lread                            Reads data from a file.

_lwrite                           Writes data in a file.

OpenFile                          Creates, opens, reopens, or deletes the
                                  specified file.

SetHandleCount                    Changes the number of file handles
                                  available to a task.


3.14  Debugging Functions

Debugging functions help locate programming errors in an application or
library. The following briefly describes these functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
DebugBreak                        Forces a break to the debugger.

FatalAppExit                      Displays a message box and then
                                  terminates the application.

FatalExit                         Displays the current state of Windows
                                  and prompts for instructions on how to
                                  proceed.

OutputDebugString                 Sends a debugging message to the
                                  debugger if present, or to the AUX
                                  device if the debugger is not present.

ValidateCodeSegments              Determines whether any code segments
                                  have been altered by random memory
                                  overwrites.

ValidateFreeSpaces                Checks free segments in memory for valid
                                  contents.


3.15  Optimization-Tool Functions

Optimization-tool functions control how the Windows Profiler and Swap
software development tools interact with an application being developed. The
following list briefly describes these functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
ProfClear                         Discards all samples in the Profiler
                                  sampling buffer.

ProfFinish                        Stops sampling by Profiler and flushes
                                  the buffer to disk.

ProfFlush                         Flushes the Profiler sampling buffer to
                                  disk.

ProfInsChk                        Determines if Profiler is installed.

ProfSampRate                      Sets the rate of code sampling by
                                  Profiler.

ProfSetup                         Sets up the Profiler sampling buffer and
                                  recording rate.

ProfStart                         Starts sampling by Profiler.

ProfStop                          Stops sampling by Profiler.

SwapRecording                     Begins or ends analyzing by Swap of the
                                  application's swapping behavior.


3.16  Application-Execution Functions

Application-execution tasks permit one application to execute another
program. The following list briefly describe these functions:

Function                          Description
────────────────────────────────────────────────────────────────────────────
LoadModule                        Executes a separate application.

WinExec                           Executes a separate application.

WinHelp                           Runs the Windows Help application and
                                  passes context or topic information to
                                  Help.

The WinExec function provides a high-level method for executing any Windows
or standard DOS application. The calling application supplies a string
containing the name of the executable file to be run and any command
parameters, and specifies the initial state of the application's window.

The LoadModule function is similar, but provides more control over the
environment in which the application is executed. The calling application
supplies the name of the executable file and a DOS Function 4BH, Code 00H,
parameter block.

The WinHelp function executes the Windows Help application and optionally
passes data to it indicating the nature of the help requested by the
application. This data is either an integer which specifies a context
identifier in the help file or a string containing a key word in the help
file.


3.17  Summary

System services interface functions access code and data in modules,
allocate and manage both local and global memory, 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. For more information on
topics related to system services interface functions, see the following:

╓┌──────────────────────────────────┌────────────────────────────────────────╖
Topic                              Reference
────────────────────────────────────────────────────────────────────────────
Topic                              Reference
────────────────────────────────────────────────────────────────────────────
Function descriptions              Reference, Volume 1: Chapter 4,
                                   "Functions Directory"

Windows data types and structures  Reference, Volume 2: Chapter 7, "Data
                                   Types and Structures"

Initialization-file formats        Reference, Volume 2: Chapter 9, "File
                                   Formats"

Diagnostic messages for            Reference, Volume 2: Appendix C,
debugging                          "Windows Debugging Messages"

Writing and reading from files     Guide to Programming: Chapter 10, "File
                                   Input and Output"

Managing memory                    Guide to Programming: Chapter 15,
                                   "Memory Management," and Chapter 16,
                                   "More Memory Management"

Topic                              Reference
────────────────────────────────────────────────────────────────────────────

Libraries                          Guide to Programming: Chapter 20,
                                   "Dynamic-Link Libraries"

Using Profiler                     Tools: Chapter 13, "Analyzing CPU Time:
                                   Profiler"

Using Swap                         Tools: Chapter 14, "Analyzing Swaps:
                                   Swap"








Chapter 4  Functions Directory
────────────────────────────────────────────────────────────────────────────

This chapter contains an alphabetical list of functions from the Microsoft
Windows application programming interface (API). The documentation for each
function contains a line illustrating correct syntax, a statement about the
function's purpose, a description of its input parameters, and a description
of its return value. The documentation for some functions contains
additional, important information that an application developer needs in
order to use the function.



AccessResource
────────────────────────────────────────────────────────────────────────────


Syntax

  int   AccessResource(hInstance, hResInfo)

This function opens the specified resource file and moves the file pointer
to the beginning of the specified resource, letting an application read the
resource from the file. The AccessResource function supplies a DOS file
handle that can be used in subsequent file-read calls to load the resource.
The file is opened for reading only.

Applications that use this function must close the resource file by calling
the _lclose function after reading the resource.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies the instance of the
                                  module whose executable file contains
                                  the resource.

hResInfo                          HANDLE  Identifies the desired resource.
                                  This handle should be created by using
                                  the FindResource function.



Return Value

The return value specifies a DOS file handle to the designated resource
file. It is -1 if the resource cannot be found.


Comments

AccessResource can exhaust available DOS file handles and cause errors if
the opened file is not closed after the resource is accessed.


AddAtom
────────────────────────────────────────────────────────────────────────────


Syntax

  ATOM   AddAtom(lpString)

This function adds the character string pointed to by the lpString parameter
to the atom table and creates a new atom that uniquely identifies the
string. The atom can be used in a subsequent GetAtomName function to
retrieve the string from the atom table.

The AddAtom function stores no more than one copy of a given string in the
atom table. If the string is already in the table, the function returns the
existing atom value and increases the string's reference count by one.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to the character string to
                                  be added to the table. The string must
                                  be a null-terminated character string.



Return Value

The return value specifies the newly created atom if the function is
successful. Otherwise, it is NULL.


Comments

The atom values returned by AddAtom range from 0xC000 to 0xFFFF. Atoms are
case insensitive.


AddFontResource
────────────────────────────────────────────────────────────────────────────


Syntax

  int   AddFontResource(lpFilename)

This function adds the font resource from the file named by the lpFilename
parameter to the Windows font table. The font can subsequently be used by
any application.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpFilename                        LPSTR  Points to a character string that
                                  names the font-resource file or contains
                                  a handle to a loaded module. If
                                  lpFilename points to the font-resource
                                  filename, the string must be
                                  null-terminated, have the DOS filename
                                  format, and include the extension. If
                                  lpFilename contains a handle, the handle
                                  is in the low-order word and the
                                  high-order word is zero.



Return Value

The return value specifies the number of fonts added. The return value is
zero if no fonts are loaded.


Comments

Any application that adds or removes fonts from the Windows font table
should notify other windows of the change by using the SendMessage function
with the hWnd parameter set to -1 to send a WM_FONTCHANGE message to all
top-level windows in the system.

It is good practice to remove any font resource an application has added
once the application is through with the resource.

For a description of font resources, see the Guide to Programming.


AdjustWindowRect
────────────────────────────────────────────────────────────────────────────


Syntax

  void  AdjustWindowRect(lpRect, dwStyle, bMenu)

This function computes the required size of the window rectangle based on
the desired client-rectangle size. The window rectangle can then be passed
to the CreateWindow function to create a window whose client area is the
desired size. A client rectangle is the smallest rectangle that completely
encloses a client area. A window rectangle is the smallest rectangle that
completely encloses the window. The dimensions of the resulting window
rectangle depend on the window styles and on whether the window has a menu.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the coordinates of the
                                  client rectangle.

dwStyle                           DWORD  Specifies the window styles of
                                  the window whose client rectangle is to
                                  be converted.

bMenu                             BOOL  Specifies whether the window has a
                                  menu.



Return Value

None.


Comments

This function assumes a single menu row. If the menu bar wraps to two or
more rows, the coordinates are incorrect.


AdjustWindowRectEx
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  AdjustWindowRectEx(lpRect, dwStyle, bMenu, dwExStyle)

This function computes the required size of the rectangle of a window with
extended style based on the desired client-rectangle size. The window
rectangle can then be passed to the CreateWindowEx function to create a
window whose client area is the desired size.

A client rectangle is the smallest rectangle that completely encloses a
client area. A window rectangle is the smallest rectangle that completely
encloses the window. The dimensions of the resulting window rectangle
depends on the window styles and on whether the window has a menu.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the coordinates of the
                                  client rectangle.

dwStyle                           DWORD  Specifies the window styles of
                                  the window whose client rectangle is to
                                  be converted.

bMenu                             BOOL  Specifies whether the window has a
                                  menu.

dwExStyle                         DWORD  Specifies the extended style of
                                  the window being created.



Return Value

None.


Comments

This function assumes a single menu row. If the menu bar wraps to two or
more rows, the coordinates are incorrect.


AllocDStoCSAlias
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  AllocDStoCSAlias(wSelector)

This function accepts a data-segment selector and returns a code-segment
selector that can be used to execute code in the data segment. When in
protected mode, attempting to execute code directly in a data segment will
cause a general protection violation. AllocDStoCSAlias allows an application
to execute code which the application had created in its own stack segment.


The application must free the new selector by calling the FreeSelector
function.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
wSelector        WORD  Specifies the data-segment selector.


Return Value

The return value is the code-segment selector corresponding to the
data-segment selector. If the function cannot allocate a new selector, the
return value is zero.


Comments

Windows does not track segment movements. Consequently, the data segment
must be fixed and nondiscardable; otherwise, the data segment might move,
invalidating the code-segment selector.

The ChangeSelector function provides another method of obtaining a code
selector corresponding to a data selector.

An application should not use this function unless it is absolutely
necessary. Use of this function violates preferred Windows programming
practices.


AllocResource
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  AllocResource(hInstance, hResInfo, dwSize)

This function allocates uninitialized memory for the passed resource. All
resources must be initially allocated by using the AllocResource function.
The LoadResource function calls this function before loading the resource.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies the instance of the
                                  module whose executable file contains
                                  the resource.

hResInfo                          HANDLE  Identifies the desired resource.
                                  It is assumed that this handle was
                                  created by using the FindResource
                                  function.

dwSize                            DWORD  Specifies an override size in
                                  bytes to allocate for the resource. The
                                  override is ignored if the size is zero.



Return Value

The return value identifies the global memory block allocated for the
resource.


AllocSelector
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  AllocSelector(wSelector)

This function allocates a new selector. If the wSelector parameter is a
valid selector, AllocSelector returns a new selector which is an exact copy
of the one specified by wSelector. If wSelector is NULL, AllocSelector
returns a new, uninitialized selector.

The application must free the new selector by calling the FreeSelector
function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wSelector                         WORD  Specifies the selector to be
                                  copied, or NULL if AllocSelector is to
                                  allocate a new, uninitialized selector.



Return Value

The return value is either a selector that is a copy of an existing
selector, or a new, uninitialized selector. If the function could not
allocate a new selector, the return value is zero.


Comments

An application can call AllocSelector to allocate a selector that it can
pass to the ChangeSelector function.

An application should not use this function unless it is absolutely
necessary. Use of this function violates preferred Windows programming
practices.


AnimatePalette
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  AnimatePalette(hPalette, wStartIndex, wNumEntries, lpPaletteColors)

This function replaces entries in the logical palette identified by the
hPalette parameter. When an application calls AnimatePalette, it does not
have to update its client area because Windows maps the new entries into the
system palette immediately.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hPalette                          HPALETTE  Identifies the logical palette.

wStartIndex                       WORD  Specifies the first entry in the
                                  palette to be animated.

wNumEntries                       WORD  Specifies the number of entries in
                                  the palette to be animated.

lpPaletteColors                   LPPALETTEENTRY  Points to the first
                                  member of an array of PALETTEENTRY data
                                  structures to replace the palette
                                  entries identified by wStartIndex and
                                  wNumEntries.



Return Value

None.


Comments

AnimatePalette will only change entries with the PC_RESERVED flag set in the
corresponding palPaletteEntry field of the LOGPALETTE data structure that
defines the current logical palette. The CreatePalette function creates a
logical palette.


AnsiLower
────────────────────────────────────────────────────────────────────────────


Syntax

  LPSTR  AnsiLower(lpString)

This function converts the given character string to lowercase. The
conversion is made by the language driver based on the criteria of the
current language selected by the user at setup or with the Control Panel.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to a null-terminated
                                  character string or specifies single
                                  character. If lpString specifies single
                                  character, that character is in the
                                  low-order byte of the low-order word,
                                  and the high-order word is zero.



Return Value

The return value points to a converted character string if the function
parameter is a character string. Otherwise, it is a 32-bit value that
contains the converted character in the low-order byte of the low-order
word.


AnsiLowerBuff
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  AnsiLowerBuff(lpString, nLength)

This function converts character string in a buffer to lowercase. The
conversion is made by the language driver based on the criteria of the
current language selected by the user at setup or with the Control Panel.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to a buffer containing one
                                  or more characters.

nLength                           WORD  Specifies the number of characters
                                  in the buffer identified by the lpString
                                  parameter. If nLength is zero, the
                                  length is 64K (65,536).



Return Value

The return value specifies the length of the converted string.


AnsiNext
────────────────────────────────────────────────────────────────────────────


Syntax

  LPSTR  AnsiNext(lpCurrentChar)

This function moves to the next character in a string.

Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
lpCurrentChar   LPSTR  Points to a character in a null-terminated string.


Return Value

The return value points to the next character in the string, or, if there is
no next character, to the null character at the end of the string.


Comments

The AnsiNext function is used to move through strings whose characters are
two or more bytes each (for example, strings that contain characters from a
Japanese character set).


AnsiPrev
────────────────────────────────────────────────────────────────────────────


Syntax

  LPSTR  AnsiPrev(lpStart, lpCurrentChar)

This function moves to the previous character in a string.

Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
lpStart         LPSTR  Points to the beginning of the string.
lpCurrentChar   LPSTR  Points to a character in a null-terminated string.


Return Value

The return value points to the previous character in the string, or to the
first character in the string if the lpCurrentChar parameter is equal to the
lpStart parameter.


Comments

The AnsiPrev function is used to move through strings whose characters are
two or more bytes each (for example, strings that contain characters from a
Japanese character set).


AnsiToOem
────────────────────────────────────────────────────────────────────────────


Syntax

  int  AnsiToOem(lpAnsiStr, lpOemStr)

This function translates the string pointed to by the lpAnsiStr parameter
from the ANSI character set into the OEM-defined character set. The string
can be greater than 64K in length.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpAnsiStr                         LPSTR  Points to a null-terminated
                                  string of characters from the ANSI
                                  character set.

lpOemStr                          LPSTR  Points to the location where the
                                  translated string is to be copied. The
                                  lpOemStr parameter can be the same as
                                  lpAnsiStr to translate the string in
                                  place.



Return Value

The return value is always -1.


AnsiToOemBuff
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  AnsiToOemBuff(lpAnsiStr, lpOemStr, nLength)

This function translates the string in the buffer pointed to by the
lpAnsiStr parameter from the ANSI character set into the OEM-defined
character set.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpAnsiStr                         LPSTR  Points to a buffer containing one
                                  or more characters from the ANSI
                                  character set.

lpOemStr                          LPSTR  Points to the location where the
                                  translated string is to be copied. The
                                  lpOemStr parameter can be the same as
                                  lpAnsiStr to translate the string in
                                  place.

nLength                           WORD  Specifies the number of characters
                                  in the buffer identified by the
                                  lpAnsiStr parameter. If nLength is zero,
                                  the length is 64K (65,536).



Return Value

None.


AnsiUpper
────────────────────────────────────────────────────────────────────────────


Syntax

  LPSTR AnsiUpper(lpString)

This function converts the given character string to uppercase. The
conversion is made by the language driver based on the criteria of the
current language selected by the user at setup or with the Control Panel.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to a null-terminated
                                  character string or specifies single
                                  character. If  lpString specifies a
                                  single character, that character is in
                                  the low-order byte of the low-order word,
                                  and the high-order word is zero.



Return Value

The return value points to a converted character string if the function
parameter is a character string; otherwise, it is a 32-bit value that
contains the converted character in the low-order byte of the low-order
word.


AnsiUpperBuff
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  AnsiUpperBuff(lpString, nLength)

This function converts a character string in a buffer to uppercase. The
conversion is made by the language driver based on the criteria of the
current language selected by the user at setup or with the Control Panel.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to a buffer containing one
                                  or more characters.

nLength                           WORD  Specifies the number of characters
                                  in the buffer identified by the lpString
                                  parameter. If nLength is zero, the
                                  length is 64K (65,536).



Return Value

The return value specifies the length of the converted string.


AnyPopup
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL AnyPopup( )

This function indicates whether a pop-up window exists on the screen. It
searches the entire Windows screen, not just the caller's client area. The
AnyPopup function returns nonzero even if a pop-up window is completely
covered by another window.

This function has no parameters.


Return Value

The return value is nonzero if a pop-up window exists. Otherwise, it is
zero.


AppendMenu
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  AppendMenu(hMenu, wFlags, wIDNewItem, lpNewItem)

This function appends a new item to the end of a menu. The application can
specify the state of the menu item by setting values in the wFlags
parameter.

╓┌────────────┌──────────────────────────────┌───────────────────────────────╖
Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu        HMENU  Identifies the menu to
             be changed.

wFlags       WORD  Specifies information
             about the state of the new
             menu item when it is added to
             the menu. It consists of one
             or more values listed in the
             following "Comments" section.

wIDNewItem   WORD  Specifies either the
             command ID of the new menu
             item or, if wFlags is set to
             MF_POPUP, the menu handle of
Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
             MF_POPUP, the menu handle of
             the pop-up menu.

lpNewItem    LPSTR  Specifies the content
             of the new menu item. The
             interpretation of the
             lpNewItem parameter depends
             upon the setting of the
             wFlags parameter.

             If wFlags is                   lpNewItem

             MF_STRING                      Contains a long pointer to a
                                            null-terminated character
                                            string.

             MF_BITMAP                      Contains a bitmap handle
                                            HBITMAP in its low-order word.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────

             MF_OWNERDRAW                   Contains an
                                            application-supplied 32-bit
                                            value which the application
                                            can use to maintain additional
                                            data associated with the menu
                                            item. This 32-bit value is
                                            available to the application
                                            in the itemData field of the
                                            structure pointed to by the
                                            lParam parameter of the
                                            WM_MEASUREITEM and WM_DRAWITEM
                                            messages sent when the menu
                                            item is initially displayed or
                                            is changed.




Return Value

The return value specifies the outcome of the function. It is TRUE if the
function is successful. Otherwise, it is FALSE.


Comments

Whenever a menu changes (whether or not the menu resides in a window that is
displayed), the application should call DrawMenuBar.

Each of the following groups lists flags that are mutually exclusive and
should not be used together:


  ■   MF_BYCOMMAND and MF_BYPOSITION

  ■   MF_DISABLED, MF_ENABLED, and MF_GRAYED

  ■   MF_BITMAP, MF_STRING, and MF_OWNERDRAW

  ■   MF_MENUBARBREAK and MF_MENUBREAK

  ■   MF_CHECKED and MF_UNCHECKED


The following list describes the flags which may be set in the wFlags
parameter:

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
MF_BITMAP                         Uses a bitmap as the item. The low-order
                                  word of the lpNewItem parameter contains
                                  the handle of the bitmap.

MF_CHECKED                        Places a checkmark next to the item. If
                                  the application has supplied checkmark
                                  bitmaps (see SetMenuItemBitmaps),
                                  setting this flag displays the
                                  "checkmark on" bitmap next to the menu
                                  item.
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  item.

MF_DISABLED                       Disables the menu item so that it cannot
                                  be selected, but does not gray it.

MF_ENABLED                        Enables the menu item so that it can be
                                  selected and restores it from its grayed
                                  state.

MF_GRAYED                         Disables the menu item so that it cannot
                                  be selected and grays it.

MF_MENUBARBREAK                   Same as MF_MENUBREAK except that for
                                  pop-up menus, separates the new column
                                  from the old column with a vertical line.

MF_MENUBREAK                      Places the item on a new line for static
                                  menu-bar items. For pop-up menus, places
                                  the item in a new column, with no
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the item in a new column, with no
                                  dividing line between the columns.

MF_OWNERDRAW                      Specifies that the item is an owner-draw
                                  item. The window that owns the menu
                                  receives a WM_MEASUREITEM message when
                                  the menu is displayed for the first time
                                  to retrieve the height and width of the
                                  menu item. The WM_DRAWITEM message is
                                  then sent whenever the owner must update
                                  the visual appearance of the menu item.
                                  This option is not valid for a top-level
                                  menu item.

MF_POPUP                          Specifies that the menu item has a
                                  pop-up menu associated with it. The
                                  wIDNewItem parameter specifies a handle
                                  to a pop-up menu to be associated with
                                  the item. This is used for adding either
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the item. This is used for adding either
                                  a top-level pop-up menu or adding a
                                  hierarchical pop-up menu to a pop-up
                                  menu item.

MF_SEPARATOR                      Draws a horizontal dividing line. Can
                                  only be used in a pop-up menu. This line
                                  cannot be grayed, disabled, or
                                  highlighted. The lpNewItem and
                                  wIDNewItem parameters are ignored.

MF_STRING                         Specifies that the menu item is a
                                  character string; the lpNewItem
                                  parameter points to the string for the
                                  menu item.

MF_UNCHECKED                      Does not place a checkmark next to the
                                  item (default). If the application has
                                  supplied checkmark bitmaps (see
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  supplied checkmark bitmaps (see
                                  SetMenuItemBitmaps), setting this flag
                                  displays the "checkmark off" bitmap next
                                  to the menu item.




Arc
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  Arc(hDC, X1, Y1, X2, Y2, X3, Y3, X4, Y4)

This function draws an elliptical arc. The center of the arc is the center
of the bounding rectangle specified by the points (X1, Y1) and (X2, Y2). The
arc starts at the point (X3, Y3) and ends at the point (X4, Y4). The arc is
drawn using the selected pen and moving in a counterclockwise direction.
Since an arc does not define a closed area, it is not filled.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X1                                int  Specifies the logical x-coordinate
                                  of the upper-left corner of the bounding
                                  rectangle.

Y1                                int  Specifies the logical y-coordinate
                                  of the upper-left corner of the bounding
                                  rectangle.

X2                                int  Specifies the logical x-coordinate
                                  of the lower-right corner of the
                                  bounding rectangle.

Y2                                int  Specifies the logical y-coordinate
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
Y2                                int  Specifies the logical y-coordinate
                                  of the lower-right corner of the
                                  bounding rectangle.

X3                                int  Specifies the logical x-coordinate
                                  of the arc's starting point. This point
                                  does not have to lie exactly on the arc.

Y3                                int  Specifies the logical y-coordinate
                                  of the arc's starting point. This point
                                  does not have to lie exactly on the arc.

X4                                int  Specifies the logical x-coordinate
                                  of the arc's endpoint. This point does
                                  not have to lie exactly on the arc.

Y4                                int  Specifies the logical y-coordinate
                                  of the arc's endpoint. This point does
                                  not have to lie exactly on the arc.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  not have to lie exactly on the arc.




Return Value

The return value specifies whether the arc is drawn. It is nonzero if the
arc is drawn. Otherwise, it is zero.


Comments

The width of the rectangle specified by the absolute value of X2 - X1 must
not exceed 32,767 units. This limit applies to the height of the rectangle
as well.


ArrangeIconicWindows
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  ArrangeIconicWindows(hWnd)

This function arranges all the minimized (iconic) child windows of the
window specified by the hWnd parameter.

Parameter            Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                 HWND  Identifies the window.


Return Value

The return value is the height of one row of icons, or zero if there were no
icons.


Comments

Applications that maintain their own iconic child windows call this function
to arrange icons in a client window. This function also arranges icons on
the desktop window, which covers the entire screen. The GetDesktopWindow
function retrieves the window handle of the desktop window.

To arrange iconic MDI child windows in an MDI client window, an application
sends the WM_MDIICONARRANGE message to the MDI client window.





BeginDeferWindowPos
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HANDLE  BeginDeferWindowPos(nNumWindows)

This function allocates memory to contain a multiple window-position data
structure and returns a handle to the structure. The DeferWindowPos function
fills this data structure with information about the target position for a
window that is about to be moved. The EndDeferWindowPos function accepts
this data structure and instantaneously repositions the windows using the
information stored in the structure.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nNumWindows                       int  Specifies the initial number of
                                  windows for which position information
                                  is to be stored in the data structure.
                                  The Defer-
                                  WindowPos function increases the size of
                                  the structure if needed.



Return Value

The return value identifies the multiple window-position data structure. The
return value is NULL if system resources are not available to allocate the
structure.


BeginPaint
────────────────────────────────────────────────────────────────────────────


Syntax

  HDC  BeginPaint(hWnd, lpPaint)

This function prepares the given window for painting and fills the paint
structure pointed to by the lpPaint parameter with information about the
painting.

The paint structure contains a handle to the device context for the window,
a RECT data structure that contains the smallest rectangle that completely
encloses the update region, and a flag that specifies whether or not the
background has been erased.

The BeginPaint function automatically sets the clipping region of the device
context to exclude any area outside the update region. The update region is
set by the InvalidateRect or InvalidateRgn functions and by the system after
sizing, moving, creating, scrolling, or any other operation that affects the
client area. If the update region is marked for erasing, BeginPaint sends a
WM_ERASEBKGND message to the window.

An application should not call the BeginPaint function except in response to
a WM_PAINT message. Each BeginPaint call must have a matching call to the
EndPaint function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window to be
                                  repainted.

lpPaint                           LPPAINTSTRUCT  Points to the PAINTSTRUCT
                                  data structure that is to receive
                                  painting information, such as the device
                                  context for the window and the update
                                  rectangle.



Return Value

The return value identifies the device context for the specified window.


Comments

If the caret is in the area to be painted, the BeginPaint function
automatically hides the caret to prevent it from being erased.


BitBlt
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  BitBlt(hDestDC, X, Y, nWidth, nHeight, hSrcDC, XSrc, YSrc, dwRop)

This function moves a bitmap from the source device given by the hSrcDC
parameter to the destination device given by the hDestDC parameter. The XSrc
and YSrc parameters specify the origin on the source device of the bitmap
that is to be moved. The X, Y, nWidth, and nHeight parameters specify the
origin, width, and height of the rectangle on the destination device that is
to be filled by the bitmap. The dwRop parameter (raster operation) defines
how the bits of the source and destination are combined.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDestDC                           HDC  Identifies the device context that
                                  is to receive the bitmap.

X                                 int  Specifies the logical x-coordinate
                                  of the upper-left corner of the
                                  destination rectangle.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  destination rectangle.

Y                                 int  Specifies the logical y-coordinate
                                  of the upper-left corner of the
                                  destination rectangle.

nWidth                            int  Specifies the width (in logical
                                  units) of the destination rectangle and
                                  source bitmap.

nHeight                           int  Specifies the height (in logical
                                  units) of the destination rectangle and
                                  source bitmap.

hSrcDC                            HDC  Identifies the device context from
                                  which the bitmap will be copied. It must
                                  be NULL if the dwRop parameter specifies
                                  a raster operation that does not include
                                  a source.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  a source.

XSrc                              int  Specifies the logical x-coordinate
                                  of the upper-left corner of the source
                                  bitmap.

YSrc                              int  Specifies the logical y-coordinate
                                  of the upper-left corner of the source
                                  bitmap.

dwRop                             DWORD  Specifies the raster operation to
                                  be performed. Raster-operation codes
                                  define how the graphics device interface
                                  (GDI) combines colors in output
                                  operations that involve a current brush,
                                  a possible source bitmap, and a
                                  destination bitmap. For a list of
                                  raster-operation codes, see Table .1,
                                  "Raster Operations."
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  "Raster Operations."




Return Value

The return value specifies whether the bitmap is drawn. It is nonzero if the
bitmap is drawn. Otherwise, it is zero.


Comments

GDI transforms the nWidth and nHeight parameters, once by using the
destination display context, and once by using the source display context.
If the resulting extents do not match, GDI uses the StretchBlt function to
compress or stretch the source bitmap as necessary. If destination, source,
and pattern bitmaps do not have the same color format, the BitBlt function
converts the source and pattern bitmaps to match the destination. The
foreground and background colors of the destination are used in the
conversion.

If BitBlt converts monochrome bitmaps to color, it sets white bits (1) to
the background color and black bits (0) to the foreground color. The
foreground and background colors of the destination device context are used.
To convert color to monochrome, BitBlt sets pixels that match the background
color to white (1), and sets all other pixels to black (0). The foreground
and background colors of the color-source device context are used.

The foreground color is the current text color for the specified device
context, and the background color is the current background color for the
specified device context.

Not all devices support the BitBlt function. For more information, see the
RC_BITBLT raster capability in the GetDeviceCaps function, later in this
chapter.

Table  lists the various raster-operation codes for the dwRop parameter:

Table   Raster Operations

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Code                              Description
────────────────────────────────────────────────────────────────────────────
BLACKNESS                         Turns all output black.

DSTINVERT                         Inverts the destination bitmap.

MERGECOPY                         Combines the pattern and the source
                                  bitmap using the Boolean AND operator.

MERGEPAINT                        Combines the inverted source bitmap with
                                  the destination bitmap using the Boolean
                                  OR operator.

NOTSRCCOPY                        Copies the inverted source bitmap to the
                                  destination.

NOTSRCERASE                       Inverts the result of combining the
                                  destination and source bitmaps using the
                                  Boolean OR operator.
Code                              Description
────────────────────────────────────────────────────────────────────────────
                                  Boolean OR operator.

PATCOPY                           Copies the pattern to the destination
                                  bitmap.

PATINVERT                         Combines the destination bitmap with the
                                  pattern using the Boolean XOR operator.

PATPAINT                          Combines the inverted source bitmap with
                                  the pattern using the Boolean OR
                                  operator. Combines the result of this
                                  operation with the destination bitmap
                                  using the Boolean OR operator.

SRCAND                            Combines pixels of the destination and
                                  source bitmaps using the Boolean AND
                                  operator.

SRCCOPY                           Copies the source bitmap to the
Code                              Description
────────────────────────────────────────────────────────────────────────────
SRCCOPY                           Copies the source bitmap to the
                                  destination bitmap.

SRCERASE                          Inverts the destination bitmap and
                                  combines the result with the source
                                  bitmap using the Boolean AND operator.

SRCINVERT                         Combines pixels of the destination and
                                  source bitmaps using the Boolean XOR
                                  operator.

SRCPAINT                          Combines pixels of the destination and
                                  source bitmaps using the Boolean OR
                                  operator.

WHITENESS                         Turns all output white.

────────────────────────────────────────────────────────────────────────────

Code                              Description
────────────────────────────────────────────────────────────────────────────



For a complete list of the raster-operation codes, see Chapter 11, "Binary
and Ternary Raster-Operation Codes," in Reference, Volume 2.


BringWindowToTop
────────────────────────────────────────────────────────────────────────────


Syntax

  void  BringWindowToTop(hWnd)

This function brings a pop-up or child window to the top of a stack of
overlapping windows. In addition, it activates pop-up and top-level windows.
The BringWindowToTop function should be used to uncover any window that is
partially or completely obscured by any overlapping windows.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the pop-up or child
                                  window that is to be brought to the top.



Return Value

None.


BuildCommDCB
────────────────────────────────────────────────────────────────────────────


Syntax

  int  BuildCommDCB(lpDef, lpDCB)

This function translates the definition string specified by the lpDef
parameter into appropriate device-control block codes and places these codes
into the block pointed to by the lpDCB parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpDef                             LPSTR  Points to a null-terminated
                                  character string that specifies the
                                  device-control information for a device.
                                  The string must have the same form as
                                  the DOS MODE command-line parameter.

lpDCB                             DCB FAR * Points to the DCB data
                                  structure that is to receive the
                                  translated string. The structure defines
                                  the control setting for the
                                  serial-communication device.



Return Value

The return value specifies the result of the function. It is zero if the
string is translated. It is negative if an error occurs.


Comments

The BuildCommDCB function only fills the buffer. An application should call
SetCommState to apply these settings to the port. Also, by default,
BuildCommDCB specifies Xon/Xoff and hardware flow control as disabled. An
application should set the appropriate fields in the DCB data structure to
enable flow control.





CallMsgFilter
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  CallMsgFilter(lpMsg, nCode)

This function passes the given message and code to the current message
filter function. The message filter function is an application-specified
function that examines and modifies all messages. An application specifies
the function by using the SetWindowsHook function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpMsg                             LPMSG  Points to an MSG data structure
                                  that contains the message to be filtered.

nCode                             int  Specifies a code used by the filter
                                  function to determine how to process the
                                  message.



Return Value

The return value specifies the state of message processing. It is FALSE if
the message should be processed. It is TRUE if the message should not be
processed further.


Comments

The CallMsgFilter function is usually called by Windows to let applications
examine and control the flow of messages during internal processing in menus
and scroll bars or when moving or sizing a window.

Values given for the nCode parameter must not conflict with any of the MSGF_
and HC_ values passed by Windows to the message filter function.


CallWindowProc
────────────────────────────────────────────────────────────────────────────


Syntax

  LONG  CallWindowProc(lpPrevWndFunc, hWnd, wMsg, wParam, lParam)

This function passes message information to the function specified by the
lpPrevWndFunc parameter. The CallWindowProc function is used for window
subclassing. Normally, all windows with the same class share the same window
function. A subclass is a window or set of windows belonging to the same
window class whose messages are intercepted and processed by another
function (or functions) before being passed to the window function of that
class.

The SetWindowLong function creates the subclass by changing the window
function associated with a particular window, causing Windows to call the
new window function instead of the previous one. Any messages not processed
by the new window function must be passed to the previous window function by
calling CallWindowProc. This allows a chain of window functions to be
created.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPrevWndFunc                     FARPROC  Is the procedure-instance
                                  address of the previous window function.

hWnd                              HWND  Identifies the window that
                                  receives the message.

wMsg                              WORD  Specifies the message number.

wParam                            WORD  Specifies additional
                                  message-dependent information.

lParam                            DWORD  Specifies additional
                                  message-dependent information.



Return Value

The return value specifies the result of the message processing. The
possible return values depend on the message sent.


Catch
────────────────────────────────────────────────────────────────────────────


Syntax

  int  Catch(lpCatchBuf)

This function catches the current execution environment and copies it to the
buffer pointed to by the lpCatchBuf parameter. The execution environment is
the state of all system registers and the instruction counter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpCatchBuf                        LPCATCHBUF  Points to the CATCHBUF
                                  structure that will receive the
                                  execution environment.



Return Value

The return value specifies whether the execution environment is copied to
the buffer. It is zero if the environment is copied to the buffer.


Comments

The Throw function uses the buffer to restore the execution environment to
its previous values.

The Catch function is similar to the C run-time setjmp function (which is
incompatible with the Windows environment).


ChangeClipboardChain
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  ChangeClipboardChain(hWnd, hWndNext)

This function removes the window specified by the hWnd parameter from the
chain of clipboard viewers and makes the window specified by the hWndNext
parameter the descendant of the hWnd parameter's ancestor in the chain.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window that is to
                                  be removed from the chain. The handle
                                  must previously have been passed to the
                                  SetClipboardViewer function.

hWndNext                          HWND  Identifies the window that follows
                                  hWnd in the clipboard-viewer chain (this
                                  is the handle returned by the
                                  SetClipboardViewer function, unless the
                                  sequence was changed in response to a
                                  WM_CHANGECBCHAIN message).



Return Value

The return value specifies the status of the hWnd window. It is nonzero if
the window is found and removed. Otherwise, it is zero.


ChangeMenu
────────────────────────────────────────────────────────────────────────────

The Microsoft Windows version 3.0 SDK has replaced this function with five
specialized functions. These new functions are:

Function                          Description
────────────────────────────────────────────────────────────────────────────
AppendMenu                        Appends a menu item to the end of a menu.

DeleteMenu                        Deletes a menu item from a menu,
                                  destroying the menu item.

InsertMenu                        Inserts a menu item into a menu.

ModifyMenu                        Modifies a menu item in a menu.

RemoveMenu                        Removes a menu item from a menu but does
                                  not destroy the menu item.


Applications written for SDK versions 2.1 and earlier may continue to call
ChangeMenu as previously documented. New applications should call the new
functions listed above.


ChangeSelector
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  ChangeSelector(wDestSelector, wSourceSelector)

This function generates a code selector that corresponds to a given data
selector, or a data selector that corresponds to a given code selector.

The wSourceSelector parameter specifies the selector to be copied and
converted; the wDestSelector parameter is a selector previously allocated by
a call to the AllocSelector function. ChangeSelector modifies the
destination selector to have the same properties as the source selector, but
with the opposite code or data attribute. This function changes only the
attributes of the selector, not the value of the selector.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wDestSelector                     WORD  Specifies a selector previously
                                  allocated by AllocSelector that receives
                                  the converted selector.

wSourceSelector                   WORD  Specifies the selector to be
                                  converted.



Return Value

The return value is the copied and converted selector. It is zero if the
function failed.


Comments

Windows does not attempt to track changes to the source selector.
Consequently, the application should use the converted destination selector
immediately after it is returned by this function before any movement of
memory can occur.

An application should not use this function unless it is absolutely
necessary. Use of this function violates preferred Windows programming
practices.


CheckDlgButton
────────────────────────────────────────────────────────────────────────────


Syntax

  void  CheckDlgButton(hDlg, nIDButton, wCheck)

This function places a checkmark next to or removes a checkmark from a
button control, or changes the state of a three-state button. The
CheckDlgButton function sends a BM_SETCHECK message to the button control
that has the specified ID in the given dialog box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the button.

nIDButton                         int  Specifies the button control to be
                                  modified.

wCheck                            WORD  Specifies the action to take. If
                                  the wCheck parameter is nonzero, the
                                  CheckDlgButton function places a
                                  checkmark next to the button; if zero,
                                  the checkmark is removed. For
                                  three-state buttons, if wCheck is 2, the
                                  button is grayed; if wCheck is 1, it is
                                  checked; if wCheck is 0, the checkmark
                                  is removed.



Return Value

None.


CheckMenuItem
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  CheckMenuItem(hMenu, wIDCheckItem, wCheck)

This function places checkmarks next to or removes checkmarks from menu
items in the pop-up menu specified by the hMenu parameter. The wIDCheckItem
parameter specifies the item to be modified.

╓┌──────────────┌─────────────────────────────┌──────────────────────────────╖
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu          HMENU  Identifies the menu.

wIDCheckItem   WORD  Specifies the menu
               item to be checked.

wCheck         WORD  Specifies how to check
               the menu item and how to
               determine the item's
               position in the menu. The
               wCheck parameter can be a
               combination of the
               MF_CHECKED or MF_UNCHECKED
               with MF_BYPOSITION or
               MF_BYCOMMAND flags. These
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
               MF_BYCOMMAND flags. These
               flags can be combined by
               using the bitwise OR
               operator. They have the
               following meanings:

               MF_BYCOMMAND                  Specifies that the
                                             wIDCheckItem  parameter gives
                                             the menu-item ID
                                             (MF_BYCOMMAND is the default).


               MF_BYPOSITION                 Specifies that the
                                             wIDCheckItem  parameter gives
                                             the position of the menu item
                                             (the first item is at
                                             position zero).

               MF_CHECKED                    Adds checkmark.
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
               MF_CHECKED                    Adds checkmark.

               MF_UNCHECKED                  Removes checkmark.




Return Value

The return value specifies the previous state of the item. It is either
MF_CHECKED or MF_UNCHECKED. The return value is -1 if the menu item does not
exist.


Comments

The wIDCheckItem parameter may identify a pop-up menu item as well as a menu
item. No special steps are required to check a pop-up menu item.

Top-level menu items cannot be checked.

A pop-up menu item should be checked by position since it does not have a
menu-item identifier associated with it.


CheckRadioButton
────────────────────────────────────────────────────────────────────────────


Syntax

  void  CheckRadioButton(hDlg, nIDFirstButton, nIDLastButton,
  nIDCheckButton)

This function checks the radio button specified by the nIDCheckButton
parameter and removes the checkmark from all other radio buttons in the
group of buttons specified by the nIDFirstButton and nIDLastButton
parameters. The CheckRadioButton function sends a BM_SETCHECK message to the
radio-button control that has the specified ID in the given dialog box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box.

nIDFirstButton                    int  Specifies the integer identifier of
                                  the first radio button in the group.

nIDLastButton                     int  Specifies the integer identifier of
                                  the last radio button in the group.

nIDCheckButton                    int  Specifies the integer identifier of
                                  the radio button to be checked.



Return Value

None.


ChildWindowFromPoint
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND ChildWindowFromPoint(hWndParent, Point)

This function determines which, if any, of the child windows belonging to
the given parent window contains the specified point.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWndParent                        HWND  Identifies the parent window.

Point                             POINT  Specifies the client coordinates
                                  of the point to be tested.



Return Value

The return value identifies the child window that contains the point. It is
NULL if the given point lies outside the parent window. If the point is
within the parent window but is not contained within any child window, the
handle of the parent window is returned.


Chord
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  Chord(hDC, X1, Y1, X2, Y2, X3, Y3, X4, Y4)

This function draws a chord (a region bounded by the intersection of an
ellipse and a line segment). The (X1, Y1) and (X2, Y2) parameters specify
the upper-left and lower-right corners, respectively, of a rectangle
bounding the ellipse that is part of the chord. The (X3, Y3) and (X4, Y4)
parameters specify the endpoints of a line that intersects the ellipse. The
chord is drawn by using the selected pen and filled by using the selected
brush.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context in
                                  which the chord will appear.

X1                                int  Specifies the x-coordinate of the
                                  bounding rectangle's upper-left corner.

Y1                                int  Specifies the y-coordinate of the
                                  bounding rectangle's upper-left corner.

X2                                int  Specifies the x-coordinate of the
                                  bounding rectangle's lower-right corner.

Y2                                int  Specifies the y-coordinate of the
                                  bounding rectangle's lower-right corner.

X3                                int  Specifies the x-coordinate of one
                                  end of the line segment.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  end of the line segment.

Y3                                int  Specifies the y-coordinate of one
                                  end of the line segment.

X4                                int  Specifies the x-coordinate of one
                                  end of the line segment.

Y4                                int  Specifies the y-coordinate of one
                                  end of the line segment.




Return Value

The return value specifies whether or not the arc is drawn. It is nonzero if
the arc is drawn. Otherwise, it is zero.


ClearCommBreak
────────────────────────────────────────────────────────────────────────────


Syntax

  int ClearCommBreak(nCid)

This function restores character transmission and places the transmission
line in a nonbreak state.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int  Specifies the communication device
                                  to be restored. The OpenComm function
                                  returns this value.



Return Value

The return value specifies the result of the function. It is zero if the
function is successful. It is negative if the nCid parameter is not a valid
device.


ClientToScreen
────────────────────────────────────────────────────────────────────────────


Syntax

  void  ClientToScreen(hWnd, lpPoint)

This function converts the client coordinates of a given point on the
display to screen coordinates. The ClientToScreen function uses the client
coordinates in the POINT data structure, pointed to by the lpPoint
parameter, to compute new screen coordinates; it then replaces the
coordinates in the structure with the new coordinates. The new screen
coordinates are relative to the upper-left corner of the system display.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window whose client
                                  area will be used for the conversion.

lpPoint                           LPPOINT  Points to a POINT data
                                  structure that contains the client
                                  coordinates to be converted.



Return Value

None.


Comments

The ClientToScreen function assumes that the given point is in client
coordinates and is relative to the given window.


ClipCursor
────────────────────────────────────────────────────────────────────────────


Syntax

  void  ClipCursor(lpRect)

This function confines the cursor to the rectangle on the display screen
given by the lpRect parameter. If a subsequent cursor position, given with
the SetCursorPos function or the mouse, lies outside the rectangle, Windows
automatically adjusts the position to keep the cursor inside. If lpRect is
NULL, the cursor is free to move anywhere on the display screen.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the screen coordinates of
                                  the upper-left and lower-right corners
                                  of the confining rectangle.



Return Value

None.


Comments

The cursor is a shared resource. An application that has confined the cursor
to a given rectangle must free it before relinquishing control to another
application.


CloseClipboard
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  CloseClipboard( )

This function closes the clipboard. The CloseClipboard function should be
called when a window has finished examining or changing the clipboard. It
lets other applications access the clipboard.

This function has no parameters.


Return Value

The return value specifies whether the clipboard is closed. It is nonzero if
the clipboard is closed. Otherwise, it is zero.


CloseComm
────────────────────────────────────────────────────────────────────────────


Syntax

  int  CloseComm(nCid)

This function closes the communication device specified by the nCid
parameter and frees any memory allocated for the device's transmit and
receive queues. All characters in the output queue are sent before the
communication device is closed.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int  Specifies the device to be closed.
                                  The OpenComm function returns this value.



Return Value

The return value specifies the result of the function. It is zero if the
device is closed. It is negative if an error occurred.


CloseMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  CloseMetaFile(hDC)

This function closes the metafile device context and creates a metafile
handle that can be used to play the metafile by using the PlayMetaFile
function.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hDC         HANDLE  Identifies the metafile device context to be closed.


Return Value

The return value identifies the metafile if the function is successful.
Otherwise, it is NULL.


CloseSound
────────────────────────────────────────────────────────────────────────────


Syntax

  void  CloseSound( )

This function closes access to the play device and frees the device for
opening by other applications. The CloseSound function flushes all voice
queues and frees any buffers allocated for these queues.

This function has no parameters.


Return Value

None.


CloseWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  void  CloseWindow(hWnd)

This function minimizes the specified window. If the window is an overlapped
window, it is minimized by removing the client area and caption of the open
window from the display screen and moving the window's icon into the icon
area of the screen.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd             HWND  Identifies the window to be minimized.


Return Value

None.


Comments

This function has no effect if the hWnd parameter is a handle to a pop-up or
child window.


CombineRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  int  CombineRgn(hDestRgn, hSrcRgn1, hSrcRgn2, nCombineMode)

This function creates a new region by combining two existing regions. The
method used to combine the regions is specified by the nCombineMode
parameter.

╓┌──────────────┌─────────────────────────────┌──────────────────────────────╖
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
hDestRgn       HRGN  Identifies an existing
               region that will be replaced
               by the new region.

hSrcRgn1       HRGN  Identifies an existing
               region.

hSrcRgn2       HRGN  Identifies an existing
               region.

nCombineMode   int  Specifies the operation
               to be performed on the two
               existing regions. It can be
               any one of the following
               values:

               RGN_AND                       Uses overlapping areas of
                                             both regions (intersection).

Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────

               RGN_COPY                      Creates a copy of region 1
                                             (identified by hSrcRgn1).

               RGN_DIFF                      Saves the areas of region 1
                                             (identified by the hSrcRgn1
                                             parameter) that are not part
                                             of region 2 (identified by
                                             the hSrcRgn2 parameter).

               RGN_OR                        Combines all of both regions
                                             (union).

               RGN_XOR                       Combines both regions but
                                             removes overlapping areas.




Return Value

The return value specifies the type of the resulting region. It can be any
one of the following values:

Value                Meaning
────────────────────────────────────────────────────────────────────────────
COMPLEXREGION        New region has overlapping borders.
ERROR                No new region created.
NULLREGION           New region is empty.
SIMPLEREGION         New region has no overlapping borders.


Comments

If the hDestRgn parameter does not identify an existing region, the
application must pass a far pointer to a previously allocated HRGN as the
hDestRgn parameter.


CopyMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  CopyMetaFile(hSrcMetaFile, lpFilename)

This function copies the source metafile to the file pointed to by the
lpFilename parameter and returns a handle to the new metafile. If lpFilename
is NULL, the source is copied to a memory metafile.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hSrcMetaFile                      HANDLE  Identifies the source metafile.

lpFilename                        LPSTR  Points to a null-terminated
                                  character string that specifies the file
                                  that is to receive the metafile.



Return Value

The return value identifies the new metafile.


CopyRect
────────────────────────────────────────────────────────────────────────────


Syntax

  int  CopyRect(lpDestRect, lpSourceRect)

This function copies the rectangle pointed to by the lpSourceRect parameter
to the RECT data structure pointed to by the lpDestRect parameter.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
lpDestRect          LPRECT  Points to a RECT data structure.
lpSourceRect        LPRECT  Points to a RECT data structure.


Return Value

Although the CopyRect function return type is an integer, the return value
is not used and has no meaning.


CountClipboardFormats
────────────────────────────────────────────────────────────────────────────


Syntax

  int CountClipboardFormats( )

This function retrieves a count of the number of formats the clipboard can
render.

This function has no parameters.


Return Value

The return value specifies the number of data formats in the clipboard.


CountVoiceNotes
────────────────────────────────────────────────────────────────────────────


Syntax

  int  CountVoiceNotes(nVoice)

This function retrieves a count of the number of notes in the specified
queue. Only those queue entries that result from calls to the SetVoiceNote
function are counted.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nVoice                            int  Specifies the voice queue to be
                                  counted. The first voice queue is
                                  numbered 1.



Return Value

The return value specifies the number of notes in the given queue.


CreateBitmap
────────────────────────────────────────────────────────────────────────────


Syntax

  HBITMAP  CreateBitmap(nWidth, nHeight, nPlanes,
  nBitCount, lpBits)

This function creates a device-dependent memory bitmap that has the
specified width, height, and bit pattern. The bitmap can subsequently be
selected as the current bitmap for a memory display by using the
SelectObject function.

Although a bitmap cannot be copied directly to a display device, the BitBlt
function can copy it from a memory display context (in which it is the
current bitmap) to any compatible device.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nWidth                            int  Specifies the width (in pixels) of
                                  the bitmap.

nHeight                           int  Specifies the height (in pixels) of
                                  the bitmap.

nPlanes                           BYTE  Specifies the number of color
                                  planes in the bitmap. Each plane has
                                  nWidth x nHeight x nBitCount bits.

nBitCount                         BYTE  Specifies the number of color bits
                                  per display pixel.

lpBits                            LPSTR  Points to a short-integer array
                                  that contains the initial bitmap bit
                                  values. If it is NULL, the new bitmap is
                                  left uninitialized. For more information,
                                  see the description of the bmBits field
                                  in the BITMAP data structure in Chapter
                                  7, "Data Types and Structures," in
                                  Reference, Volume 2.



Return Value

The return value identifies a bitmap if the function is successful.
Otherwise, it is NULL.


CreateBitmapIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HBITMAP  CreateBitmapIndirect(lpBitmap)

This function creates a bitmap that has the width, height, and bit pattern
given in the data structure pointed to by the lpBitmap parameter. Although a
bitmap cannot be directly selected for a display device, it can be selected
as the current bitmap for a memory display and copied to any compatible
display device by using the BitBlt function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpBitmap                          BITMAP FAR *  Points to a BITMAP data
                                  structure that contains information
                                  about the bitmap.



Return Value

The return value identifies a bitmap if the function is successful.
Otherwise, it is NULL.


CreateBrushIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HBRUSH  CreateBrushIndirect(lpLogBrush)

This function creates a logical brush that has the style, color, and pattern
given in the data structure pointed to by the lpLogBrush parameter. The
brush can subsequently be selected as the current brush for any device.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpLogBrush                        LOGBRUSH FAR *  Points to a LOGBRUSH
                                  data structure that contains information
                                  about the brush.



Return Value

The return value identifies a logical brush if the function is successful.
Otherwise, it is NULL.


Comments

A brush created using a monochrome (one plane, one bit per pixel) bitmap is
drawn using the current text and background colors. Pixels represented by a
bit set to 0 will be drawn with the current text color, and pixels
represented by a bit set to 1 will be drawn with the current background
color.


CreateCaret
────────────────────────────────────────────────────────────────────────────


Syntax

  void  CreateCaret(hWnd, hBitmap, nWidth, nHeight)

This function creates a new shape for the system caret and assigns ownership
of the caret to the given window. The caret shape can be a line, block, or
bitmap as defined by the hBitmap parameter. If hBitmap is a bitmap handle,
the nWidth and nHeight parameters are ignored; the bitmap defines its own
width and height. (The bitmap handle must have been previously created by
using the CreateBitmap, CreateDIBitmap, or LoadBitmap function.) If hBitmap
is NULL or 1, nWidth and nHeight give the caret's width and height (in
logical units); the exact width and height (in pixels) depend on the
window's mapping mode.

If nWidth or nHeight is zero, the caret width or height is set to the
system's window-border width or height. Using the window-border width or
height guarantees that the caret will be visible on a high-resolution
display.

The CreateCaret function automatically destroys the previous caret shape, if
any, regardless of which window owns the caret. Once created, the caret is
initially hidden. To show the caret, the ShowCaret function must be called.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window that owns
                                  the new caret.

hBitmap                           HBITMAP  Identifies the bitmap that
                                  defines the caret shape. If hBitmap is
                                  NULL, the caret is solid; if hBitmap is
                                  1, the caret is gray.

nWidth                            int  Specifies the width of the caret
                                  (in logical units).

nHeight                           int  Specifies the height of the caret
                                  (in logical units).



Return Value

None.


Comments

The system caret is a shared resource. A window should create a caret only
when it has the input focus or is active. It should destroy the caret before
losing the input focus or becoming inactive.

The system's window-border width or height can be retrieved by using the
GetSystemMetrics function with the SM_CXBORDER and SM_CYBORDER indexes.


CreateCompatibleBitmap
────────────────────────────────────────────────────────────────────────────


Syntax

  HBITMAP  CreateCompatibleBitmap(hDC, nWidth, nHeight)

This function creates a bitmap that is compatible with the device specified
by the hDC parameter. The bitmap has the same number of color planes or the
same bits-per-pixel format as the specified device. It can be selected as
the current bitmap for any memory device that is compatible with the one
specified by hDC.

If hDC is a memory device context, the bitmap returned has the same format
as the currently selected bitmap in that device context. A memory device
context is a block of memory that represents a display surface. It can be
used to prepare images in memory before copying them to the actual display
surface of the compatible device.

When a memory device context is created, GDI automatically selects a
monochrome stock bitmap for it.

Since a color memory device context can have either color or monochrome
bitmaps selected, the format of the bitmap returned by the
CreateCompatibleBitmap function is not always the same; however, the format
of a compatible bitmap for a nonmemory device context is always in the
format of the device.

Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
hDC            HDC  Identifies the device context.
nWidth         int  Specifies the width (in bits) of the bitmap.
nHeight        int  Specifies the height (in bits) of the bitmap.


Return Value

The return value identifies a bitmap if the function is successful.
Otherwise, it is NULL.


CreateCompatibleDC
────────────────────────────────────────────────────────────────────────────


Syntax

  HDC CreateCompatibleDC(hDC)

This function creates a memory device context that is compatible with the
device specified by the hDC parameter. A memory device context is a block of
memory that represents a display surface. It can be used to prepare images
in memory before copying them to the actual device surface of the compatible
device.

When a memory device context is created, GDI automatically selects a 1-by-1
monochrome stock bitmap for it.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context. If
                                  hDC is NULL, the function creates a
                                  memory device context that is compatible
                                  with the system display.



Return Value

The return value identifies the new memory device context if the function is
successful. Otherwise, it is NULL.


Comments

This function can only be used to create compatible device contexts for
devices that support raster operations. For more information, see the
RC_BITBLT raster capability in the GetDeviceCaps function, later in this
chapter.

GDI output functions can be used with a memory device context only if a
bitmap has been created and selected into that context.

When the application no longer requires the device context, it should free
it by calling the DeleteDC function.


CreateCursor
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HCURSOR  CreateCursor(hInstance, nXhotspot,
  nYhotspot, nWidth, nHeight, lpANDbitPlane, lpXORbitPlane)

This function creates a cursor that has specified width, height, and bit
patterns.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module creating the cursor.

nXhotspot                         int  Specifies the horizontal position
                                  of the cursor hotspot.

nYhotspot                         int  Specifies the vertical position of
                                  the cursor hotspot.

nWidth                            int  Specifies the width in pixels of
                                  the cursor.

nHeight                           int  Specifies the height in pixels of
                                  the cursor.

lpANDbitPlane                     LPSTR  Points to an array of bytes
                                  containing the bit values for the AND
                                  mask of the cursor. This can be the bits
                                  of a device-dependent monochrome bitmap.

lpXORbitPlane                     LPSTR  Points to an array of bytes
                                  containing the bit values for the XOR
                                  mask of the cursor. This can be the bits
                                  of a device-dependent monochrome bitmap.


Return Value

The return value identifies the cursor if the function was successful.
Otherwise, it is NULL.


CreateDC
────────────────────────────────────────────────────────────────────────────


Syntax

  HDC  CreateDC(lpDriverName, lpDeviceName, lpOutput, lpInitData)

This function creates a device context for the specified device. The
lpDriverName, lpDeviceName, and lpOutput parameters specify the device
driver, device name, and physical output medium (file or port),
respectively.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpDriverName                      LPSTR  Points to a null-terminated
                                  character string that specifies the DOS
                                  filename (without extension) of the
                                  device driver (for example, Epson (R)).

lpDeviceName                      LPSTR  Points to a null-terminated
                                  character string that specifies the name
                                  of the specific device to be supported
                                  (for example, Epson FX-80). The
                                  lpDeviceName parameter is used if the
                                  module supports more than one device.

lpOutput                          LPSTR  Points to a null-terminated
                                  character string that specifies the DOS
                                  file or device name for the physical
                                  output medium (file or output port).

lpInitData                        LPDEVMODE  Points to a DEVMODE data
                                  structure containing device-specific
                                  initialization data for the device
                                  driver. The ExtDeviceMode retrieves this
                                  structure filled in for a given device.
                                  The lpInitData parameter must be NULL if
                                  the device driver is to use the default
                                  initialization (if any) specified by the
                                  user through the Control Panel.



Return Value

The return value identifies a device context for the specified device if the
function is successful. Otherwise, it is NULL.


Comments

DOS device names follow DOS conventions; an ending colon (:) is recommended,
but optional. Windows strips the terminating colon so that a device name
ending with a colon is mapped to the same port as the same name without a
colon. The driver and port names must not contain leading or trailing
spaces.


CreateDialog
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  CreateDialog(hInstance, lpTemplateName,
  hWndParent, lpDialogFunc)

This function creates a modeless dialog box that has the size, style, and
controls defined by the dialog-box template given by the lpTemplateName
parameter. The hWndParent parameter identifies the application window that
owns the dialog box. The dialog function pointed to by the lpDialogFunc
parameter processes any messages received by the dialog box.

The CreateDialog function sends a WM_INITDIALOG message to the dialog
function before displaying the dialog box. This message allows the dialog
function to initialize the dialog-box controls.

CreateDialog returns immediately after creating the dialog box. It does not
wait for the dialog box to begin processing input.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpTemplateName                    LPSTR  Points to a character string that
                                  names the dialog-box template. The
                                  string must be a null-terminated
                                  character string.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address for the dialog function. See the
                                  following "Comments" section for details.



Return Value

The return value is the window handle of the dialog box. It is NULL if the
function cannot create the dialog box.


Comments

Use the WS_VISIBLE style for the dialog-box template if the dialog box
should appear in the parent window upon creation.

Use the DestroyWindow function to destroy a dialog box created by the
CreateDialog function.

A dialog box can contain up to 255 controls.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  BOOL FAR PASCAL DialogFunc(hDlg, wMsg,
  wParam, lParam)
  HWND hDlg;
  WORD wMsg;
  WORD wParam;
  DWORD lParam;

DialogFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Definition
────────────────────────────────────────────────────────────────────────────
hDlg                              Identifies the dialog box that receives
                                  the message.

wMsg                              Specifies the message number.

wParam                            Specifies 16 bits of additional
                                  message-dependent information.

lParam                            Specifies 32 bits of additional
                                  message-dependent information.



Return Value

Except in response to the WM_INITDIALOG message, the dialog function should
return nonzero if the function processes the message, and zero if it does
not. In response to a WM_INITDIALOG message, the dialog function should
return zero if it calls the SetFocus function to set the focus to one of the
controls in the dialog box. Otherwise, it should return nonzero, in which
case Windows will set the focus to the first control in the dialog box that
can be given the focus.


Comments

The dialog function is used only if the dialog class is used for the dialog
box. This is the default class and is used if no explicit class is given in
the dialog-box template. Although the dialog function is similar to a window
function, it must not call the DefWindowProc function to process unwanted
messages. Unwanted messages are processed internally by the dialog-class
window function.

The dialog-function address, passed as the lpDialogFunc parameter, must be
created by using the MakeProcInstance function.


CreateDialogIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  CreateDialogIndirect(hInstance, lpDialogTemplate,
  hWndParent, lpDialogFunc)

This function creates a modeless dialog box that has the size, style, and
controls defined by the dialog-box template given by the lpDialogTemplate
parameter. The hWndParent parameter identifies the application window that
owns the dialog box. The dialog function pointed to by the lpDialogFunc
parameter processes any messages received by the dialog box.

The CreateDialogIndirect function sends a WM_INITDIALOG message to the
dialog function before displaying the dialog box. This message allows the
dialog function to initialize the dialog-box controls.

CreateDialogIndirect returns immediately after creating the dialog box. It
does not wait for the dialog box to begin processing input.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpDialogTemplate                  LPSTR  Points to a block of  memory that
                                  contains a DLGTEMPLATE data structure.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. See the
                                  following "Comments" section for details.



Return Value

The return value is the window handle of the dialog box. It is NULL if the
function cannot create either the dialog box or any controls in the dialog
box.


Comments

Use the WS_VISIBLE style in the dialog-box template if the dialog box should
appear in the parent window upon creation.

A dialog box can contain up to 255 controls.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  BOOL FAR PASCAL DialogFunc(hDlg, wMsg,
  wParam, lParam)
  HWND hDlg;
  WORD wMsg;
  WORD wParam;
  DWORD lParam;

DialogFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Definition
────────────────────────────────────────────────────────────────────────────
hDlg                              Identifies the dialog box that receives
                                  the message.

wMsg                              Specifies the message number.

wParam                            Specifies 16 bits of additional
                                  message-dependent information.

lParam                            Specifies 32 bits of additional
                                  message-dependent information.



Return Value

Except in response to the WM_INITDIALOG message, the dialog function should
return nonzero if the function processes the message, and zero if it does
not. In response to a WM_INITDIALOG message, the dialog function should
return zero if it calls the SetFocus function to set the focus to one of the
controls in the dialog box. Otherwise, it should return nonzero, in which
case Windows will set the focus to the first control in the dialog box that
can be given the focus.


Comments

The dialog function is used only if the dialog class is used for the dialog
box. This is the default class and is used if no explicit class is given in
the dialog-box template. Although the dialog function is similar to a window
function, it must not call the DefWindowProc function to process unwanted
messages. Unwanted messages are processed internally by the dialog-class
window function.

The dialog-function address, passed as the lpDialogFunc parameter, must be
created by using the MakeProcInstance function.


CreateDialogIndirectParam
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HWND  CreateDialogIndirectParam(hInstance, lpDialogTemplate,
  hWndParent, lpDialogFunc, dwInitParam)

This function creates a modeless dialog box, sends a WM_INITDIALOG message
to the dialog function before displaying the dialog box, and passes
dwInitParam as the message lParam. This message allows the dialog function
to initialize the dialog-box controls. Otherwise, this function is identical
to the CreateDialogIndirect function.

For more information on creating a modeless dialog box, see the description
of the CreateDialogIndirect function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpDialogTemplate                  LPSTR  Points to a block of  memory that
                                  contains a DLGTEMPLATE data structure.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. For
                                  details, see the "Comments" section in
                                  the description of the
                                  CreateDialogIndirect function.

dwInitParam                       DWORD  Is a 32-bit value which
                                  CreateDialogIndirectParam passes to the
                                  dialog function when it creates the
                                  dialog box.



Return Value

The return value is the window handle of the dialog box. It is NULL if the
function cannot create either the dialog box or any controls in the dialog
box.


CreateDialogParam
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HWND  CreateDialogParam(hInstance, lpTemplateName,
  hWndParent, lpDialogFunc, dwInitParam)

This function creates a modeless dialog box, sends a WM_INITDIALOG message
to the dialog function before displaying the dialog box, and passes
dwInitParam as the message lParam. This message allows the dialog function
to initialize the dialog-box controls. Otherwise, this function is identical
to the CreateDialog function.

For more information on creating a modeless dialog box, see the description
of the CreateDialog function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpTemplateName                    LPSTR  Points to a character string that
                                  names the dialog-box template. The
                                  string must be a null-terminated
                                  character string.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address for the dialog function. For
                                  details, see the "Comments" section of
                                  the CreateDialog function.

dwInitParam                       DWORD  Is a 32-bit value which
                                  CreateDialogParam passes to the dialog
                                  function when it creates the dialog box.



Return Value

The return value is the window handle of the dialog box. It is -1 if the
function cannot create the dialog box.


CreateDIBitmap
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HBITMAP  CreateDIBitmap(hDC, lpInfoHeader, dwUsage,
  lpInitBits, lpInitInfo, wUsage)

This function creates a device-specific memory bitmap from a
device-independent bitmap (DIB) specification and optionally sets bits in
the bitmap.

╓┌──────────────┌─────────────────────────────┌──────────────────────────────╖
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
hDC            HDC  Identifies the device
               context.

lpInfoHeader   LPBITMAPINFOHEADER  Points
               to a BITMAPINFOHEADER
               structure that describes the
               size and format of the
               device-independent bitmap.

dwUsage        DWORD  Indicates whether the
               memory bitmap is to be
               initialized. If dwUsage is
               set to CBM_INIT,
               CreateDIBitmap will
               initialize the bitmap with
               the bits specified by
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
               the bits specified by
               lpInitBits and lpInitInfo.

lpInitBits     LPSTR  Points to a byte
               array that contains the
               initial bitmap values. The
               format of the bitmap values
               depends on the biBitCount
               field of the BITMAPINFO
               structure identified by
               lpInitInfo. See the
               description of the
               BITMAPINFO data structure in
               Chapter 7, "Data Types and
               Structures," in Reference,
               Volume 2, for more
               information.

lpInitInfo     LPBITMAPINFO  Points to a
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
lpInitInfo     LPBITMAPINFO  Points to a
               BITMAPINFO data structure
               that describes the
               dimensions and color format
               of lpInitBits.

wUsage         WORD  Specifies whether the
               bmiColors[ ] fields of the
               lpInitInfo data structure
               contain explicit RGB values
               or indexes into the
               currently realized logical
               palette. The wUsage
               parameter must be one of the
               following values:

               DIB_PAL_COLORS                The color table consists of
                                             an array of 16-bit indexes
                                             into the currently realized
Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
                                             into the currently realized
                                             logical palette.

               DIB_RGB_COLORS                The color table contains
                                             literal RGB values.




Return Value

The return value identifies a bitmap if the function is successful.
Otherwise, it is NULL.


Comments

This function also accepts a device-independent bitmap specification
formatted for Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 if
the lpInfoHeader points to a BITMAPCOREHEADER data structure and the
lpInitInfo parameter points to a BITMAPCOREINFO data structure.


CreateDIBPatternBrush
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HBRUSH  CreateDIBPatternBrush(hPackedDIB, wUsage)

This function creates a logical brush that has the pattern specified by the
device-independent bitmap (DIB) defined by the the hPackedDIB parameter. The
brush can subsequently be selected for any device that supports raster
operations. For more information, see the RC_BITBLT raster capability in the
GetDeviceCaps function, later in this chapter.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hPackedDIB  GLOBALHANDLE  Identifies a
            global memory object
            containing a packed
            device-independent bitmap. To
            obtain this handle, an
            application calls the
            GlobalAlloc function to
            allocate a block of global
            memory and then fills the
            memory with the packed DIB. A
            packed DIB consists of a
            BITMAPINFO data structure
            immediately followed by the
            array of bytes which define
            the pixels of the bitmap.

wUsage      WORD  Specifies whether the
            bmiColors[ ] fields of the
            BITMAPINFO data structure
            contain explicit RGB values or
            indexes into the currently
            realized logical palette. The
            wUsage parameter must be one
            of the following values:

            DIB_PAL_COLORS                  The color table contains
                                            literal RGB values. into the
                                            currently realized logical
                                            palette.

            DIB_RGB_COLORS                  The color table consists of an
                                            array of 16-bit indexes.



Return Value

The return value identifies a logical brush if the function is successful.
Otherwise, it is NULL.


CreateDiscardableBitmap
────────────────────────────────────────────────────────────────────────────


Syntax

  HBITMAP  CreateDiscardableBitmap(hDC, nWidth, nHeight)

This function creates a discardable bitmap that is compatible with the
device identified by the hDC parameter. The bitmap has the same number of
color planes or the same bits-per-pixel format as the specified device. An
application can select this bitmap as the current bitmap for a memory device
that is compatible with the one specified by the hDC parameter.

Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
hDC            HDC  Identifies a device context.
nWidth         int  Specifies the width (in bits) of the bitmap.
nHeight        int  Specifies the height (in bits) of the bitmap.


Return Value

The return value identifies a bitmap if the function is successful.
Otherwise, it is NULL.


Comments

Windows can discard a bitmap created by this function only if an application
has not selected it into a display context. If Windows discards the bitmap
when it is not selected and the application later attempts to select it, the
SelectObject function will return zero. When this occurs, the application
should remove the handle to the bitmap by using DeleteObject.


CreateEllipticRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  HRGN  CreateEllipticRgn(X1, Y1, X2, Y2)

This function creates an elliptical region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
X1                                int  Specifies the x-coordinate of the
                                  upper-left corner of the bounding
                                  rectangle of the ellipse.

Y1                                int  Specifies the y-coordinate of the
                                  upper-left corner of the bounding
                                  rectangle of the ellipse.

X2                                int  Specifies the x-coordinate of the
                                  lower-right corner of the bounding
                                  rectangle of the ellipse.

Y2                                int  Specifies the y-coordinate of the
                                  lower-right corner of the bounding
                                  rectangle of the ellipse.



Return Value

The return value identifies a new region if the function is successful.
Otherwise, it is NULL.


Comments

The width of the rectangle, specified by the absolute value of X2 - X1, must
not exceed 32,767 units. This limit also applies to the height of the
rectangle.


CreateEllipticRgnIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HRGN  CreateEllipticRgnIndirect(lpRect)

This function creates an elliptical region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the coordinates of the
                                  upper-left and lower-right corners of
                                  the bounding rectangle of the ellipse.



Return Value

The return value identifies a new region if the function is successful.
Otherwise, it is NULL.


Comments

The width of the rectangle must not exceed 32,767 units. This limit applies
to the height of the rectangle as well.


CreateFont
────────────────────────────────────────────────────────────────────────────


Syntax

  HFONT CreateFont(nHeight, nWidth, nEscapement,
  nOrientation, nWeight, cItalic, cUnderline,
  cStrikeOut, cCharSet, cOutputPrecision, cClipPrecision,
  cQuality, cPitchAndFamily, lpFacename)

This function creates a logical font that has the specified characteristics.
The logical font can subsequently be selected as the font for any device.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nHeight                           int  Specifies the desired height (in
                                  logical units) of the font. The font
                                  height can be specified in three ways:
                                  If nHeight is greater than zero, it is
                                  transformed into device units and
                                  matched against the cell height of the
                                  available fonts. If it is zero, a
                                  reasonable default size is used. If it
                                  is less than zero, it is transformed
                                  into device units and the absolute value
                                  is matched against the character height
                                  of the available fonts. For all height
                                  comparisons, the font mapper looks for
                                  the largest font that does not exceed
                                  the requested size, and, if there is no
                                  such font, looks for the smallest font
                                  available.

nWidth                            int  Specifies the average width (in
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nWidth                            int  Specifies the average width (in
                                  logical units) of characters in the font.
                                  If nWidth is zero, the aspect ratio of
                                  the device will be matched against the
                                  digitization aspect ratio of the
                                  available fonts to find the closest
                                  match, determined by the absolute value
                                  of the difference.

nEscapement                       int    Specifies the angle (in tenths of
                                  degrees) of each line of text written in
                                  the font (relative to the bottom of the
                                  page).

nOrientation                      int  Specifies the angle (in tenths of
                                  degrees) of each character's baseline
                                  (relative to the bottom of the page).

nWeight                           int  Specifies the desired weight of the
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nWeight                           int  Specifies the desired weight of the
                                  font in the range 0 to 1000 (for example,
                                  400 is normal, 700 is bold). If nWeight
                                  is zero, a default weight is used.

cItalic                           BYTE  Specifies whether the font is
                                  italic.

cUnderline                        BYTE  Specifies whether the font is
                                  underlined.

cStrikeOut                        BYTE  Specifies whether characters in
                                  the font are struck out.

cCharSet                          BYTE  Specifies the desired character
                                  set. The following values are
                                  predefined:

                                  ANSI_CHARSET
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  ANSI_CHARSET
                                  OEM_CHARSET
                                  SYMBOL_CHARSET

                                  The OEM character set is
                                  system-dependent.

                                  Fonts with other character sets may
                                  exist in the system. If an application
                                  uses a font with an unknown character
                                  set, it should not attempt to translate
                                  or interpret strings that are to be
                                  rendered with that font. Instead, the
                                  strings should be passed directly to the
                                  output device driver.

cOutputPrecision                  BYTE  Specifies the desired output
                                  precision. The output precision defines
                                  how closely the output must match the
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  how closely the output must match the
                                  requested font's height, width,
                                  character orientation, escapement, and
                                  pitch. It can be any one of the
                                  following values:

                                  OUT_CHARACTER_PRECIS
                                  OUT_DEFAULT_PRECIS
                                  OUT_STRING_PRECIS
                                  OUT_STROKE_PRECIS

cClipPrecision                    BYTE  Specifies the desired clipping
                                  precision. The clipping precision
                                  defines how to clip characters that are
                                  partially outside the clipping region.
                                  It can be any one of the following
                                  values:

                                  CLIP_CHARACTER_PRECIS
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  CLIP_CHARACTER_PRECIS
                                  CLIP_DEFAULT_PRECIS
                                  CLIP_STROKE_PRECIS

cQuality                          BYTE  Specifies the desired output
                                  quality. The output quality defines how
                                  carefully GDI must attempt to match the
                                  logical-font attributes to those of an
                                  actual physical font. It can be any one
                                  of the following values:

                                  DEFAULT_QUALITY
                                  DRAFT_QUALITY
                                  PROOF_QUALITY

cPitchAndFamily                   BYTE  Specifies the pitch and family of
                                  the font. The two low-order bits specify
                                  the pitch of the font and can be any one
                                  of the following values:
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  of the following values:

                                  DEFAULT_PITCH
                                  FIXED_PITCH
                                  VARIABLE_PITCH

                                  The four high-order bits of the field
                                  specify the font family and can be any
                                  one of the following values:

                                  FF_DECORATIVE
                                  FF_DONTCARE
                                  FF_MODERN
                                  FF_ROMAN
                                  FF_SCRIPT
                                  FF_SWISS

lpFacename                        LPSTR  Points to a null-terminated
                                  character string that specifies the
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  character string that specifies the
                                  typeface name of the font. The length of
                                  this string must not exceed 30
                                  characters. The EnumFonts function can
                                  be used to enumerate the typeface names
                                  of all currently available fonts.




Return Value

The return value identifies a logical font if the function is successful.
Otherwise, it is NULL.


Comments

The CreateFont function does not create a new font. It merely selects the
closest match from the fonts available in GDI's pool of physical fonts.


CreateFontIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HFONT CreateFontIndirect(lpLogFont)

This function creates a logical font that has the characteristics given in
the data structure pointed to by the lpLogFont parameter. The font can
subsequently be selected as the current font for any device.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpLogFont                         LOGFONT FAR *  Points to a LOGFONT data
                                  structure that defines the
                                  characteristics of the logical font.



Return Value

The return value identifies a logical font if the function is successful.
Otherwise, it is NULL.


Comments

The CreateFontIndirect function creates a logical font that has all the
specified characteristics. When the font is selected by using the
SelectObject function, GDI's font mapper attempts to match the logical font
with an existing physical font. If it fails to find an exact font, it
provides an alternate whose characteristics match as many of the requested
characteristics as possible. For a description of the font mapper, see
Chapter 2, "Graphics Device Interface Functions."


CreateHatchBrush
────────────────────────────────────────────────────────────────────────────


Syntax

  HBRUSH CreateHatchBrush(nIndex, crColor)

This function creates a logical brush that has the specified hatched pattern
and color. The brush can subsequently be selected as the current brush for
any device.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nIndex      int  Specifies the hatch style
            of the brush. It can be any
            one of the following values:

            HS_BDIAGONAL                    45-degree downward hatch (left
                                            to right)

            HS_CROSS                        Horizontal and vertical
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            HS_CROSS                        Horizontal and vertical
                                            crosshatch

            HS_DIAGCROSS                    45-degree crosshatch

            HS_FDIAGONAL                    45-degree upward hatch (left
                                            to right)

            HS_HORIZONTAL                   Horizontal hatch

            HS_VERTICAL                     Vertical hatch

crColor     COLORREF  Specifies the
            foreground color of the brush
            (the color of the hatches).




Return Value

The return value identifies a logical brush if the function is successful.
Otherwise, it is NULL.


CreateIC
────────────────────────────────────────────────────────────────────────────


Syntax

  HDC CreateIC(lpDriverName, lpDeviceName, lpOutput, lpInitData)

This function creates an information context for the specified device. The
information context provides a fast way to get information about the device
without creating a device context.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpDriverName                      LPSTR  Points to a null-terminated
                                  character string that specifies the DOS
                                  filename (without extension) of the
                                  device driver (for example, EPSON).

lpDeviceName                      LPSTR  Points to a null-terminated
                                  character string that specifies the name
                                  of the specific device to be supported
                                  (for example, EPSON FX-80). The
                                  lpDeviceName parameter is used if the
                                  module supports more than one device.

lpOutput                          LPSTR  Points to a null-terminated
                                  character string that specifies the DOS
                                  file or device name for the physical
                                  output medium (file or port).

lpInitData                        LPSTR  Points to device-specific
                                  initialization data for the device
                                  driver. The lpInitData parameter must be
                                  NULL if the device driver is to use the
                                  default initialization (if any)
                                  specified by the user through the
                                  Control Panel.



Return Value

The return value identifies an information context for the specified device
if the function is successful. Otherwise, it is NULL.


Comments

DOS device names follow DOS conventions; an ending colon (:) is recommended,
but optional. Windows strips the terminating colon so that a device name
ending with a colon is mapped to the same port as the same name without a
colon.

The driver and port names must not contain leading or trailing spaces.

GDI output functions cannot be used with information contexts.


CreateIcon
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HICON  CreateIcon(hInstance, nWidth, nHeight,
  nPlanes, nBitsPixel, lpANDbits, lpXORbits)

This function creates an icon that has specified width, height, colors, and
bit patterns.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module creating the icon.

nWidth                            int  Specifies the width in pixels of
                                  the icon.

nHeight                           int  Specifies the height in pixels of
                                  the icon.

nPlanes                           BYTE  Specifies the number of planes in
                                  the XOR mask of the icon.

nBitsPixel                        BYTE  Specifies the number of bits per
                                  pixel in the XOR mask of the icon.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpANDbits                         LPSTR  Points to an array of bytes that
                                  contains the bit values for the AND mask
                                  of the icon. This array must specify a
                                  monochrome mask.

lpXORbits                         LPSTR  Points to an array of bytes that
                                  contains the bit values for the XOR mask
                                  of the icon. This can be the bits of a
                                  monochrome or device-dependent color
                                  bitmap.


Return Value

The return value identifies an icon if the function is successful.
Otherwise, it is NULL.


CreateMenu
────────────────────────────────────────────────────────────────────────────


Syntax

  HMENU CreateMenu( )

This function creates a menu. The menu is initially empty, but can be filled
with menu items by using the AppendMenu or InsertMenu function.

This function has no parameters.


Return Value

The return value identifies the newly created menu. It is NULL if the menu
cannot be created.


CreateMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE CreateMetaFile(lpFilename)

This function creates a metafile device context.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpFilename                        LPSTR  Points to a null-terminated
                                  character string that specifies the name
                                  of the metafile. If the lpFilename
                                  parameter is NULL, a device context for
                                  a memory metafile is returned.



Return Value

The return value identifies a metafile device context if the function is
successful. Otherwise, it is NULL.


CreatePalette
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HPALETTE  CreatePalette(lpLogPalette)

This function creates a logical color palette.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpLogPalette                      LPLOGPALETTE  Points to a LOGPALETTE
                                  data structure that contains information
                                  about the colors in the logical palette.



Return Value

The return value identifies a logical palette if the function was
successful. Otherwise, it is NULL.


CreatePatternBrush
────────────────────────────────────────────────────────────────────────────


Syntax

  HBRUSH CreatePatternBrush(hBitmap)

This function creates a logical brush that has the pattern specified by the
hBitmap parameter. The brush can subsequently be selected for any device
that supports raster operations. For more information, see the RC_BITBLT
raster capability in the GetDeviceCaps function, later in this chapter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hBitmap                           HBITMAP  Identifies the bitmap. It is
                                  assumed to have been created by using
                                  the CreateBitmap, CreateBitmapIndirect,
                                  LoadBitmap, or CreateCompatibleBitmap
                                  function. The minimum size for a bitmap
                                  to be used in a fill pattern is 8-by-8.



Return Value

The return value identifies a logical brush if the function is successful.
Otherwise, it is NULL.


Comments

A pattern brush can be deleted without affecting the associated bitmap by
using the DeleteObject function. This means the bitmap can be used to create
any number of pattern brushes.

A brush created using a monochrome (one plane, one bit per pixel) bitmap is
drawn using the current text and background colors. Pixels represented by a
bit set to 0 will be drawn with the current text color, and pixels
represented by a bit set to 1 will be drawn with the current background
color.


CreatePen
────────────────────────────────────────────────────────────────────────────


Syntax

  HPEN CreatePen(nPenStyle, nWidth, crColor)

This function creates a logical pen having the specified style, width, and
color. The pen can be subsequently selected as the current pen for any
device.

╓┌───────────┌──────────────────────────────────────────────────────────┌────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nPenStyle   int  Specifies the pen style. It can be any one of the
            following values:

            PS_SOLID                                                   0

            PS_DASH                                                    1

            PS_DOT                                                     2
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            PS_DOT                                                     2

            PS_DASHDOT                                                 3

            PS_DASHDOTDOT                                              4

            PS_NULL                                                    5

            PS_INSIDEFRAME                                             6

            If the width of the pen is greater than 1 and the pen
            style is PS_INSIDEFRAME, the line is drawn inside the
            frame of all primitives except polygons and polylines;
            the pen is drawn with a logical (dithered) color if the
            pen color does not match an available RGB value. The
            PS_INSIDEFRAME style is identical to PS_SOLID if the pen
            width is less than or equal to 1.

nWidth      int  Specifies the width of the pen (in logical units).
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nWidth      int  Specifies the width of the pen (in logical units).

crColor     COLORREF  Specifies the color of the pen.




Return Value

The return value identifies a logical pen if the function is successful.
Otherwise, it is NULL.


Comments

Pens with a physical width greater than one pixel will always have either
null or solid style or will be dithered if the pen style is PS_INSIDEFRAME.



CreatePenIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HPEN CreatePenIndirect(lpLogPen)

This function creates a logical pen that has the style, width, and color
given in the data structure pointed to by the lpLogPen parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpLogPen                          LOGPEN FAR *  Points to the LOGPEN data
                                  structure that contains information
                                  about the logical pen.



Return Value

The return value identifies a logical pen object if the function is
successful. Otherwise, it is NULL.


Comments

Pens with a physical width greater than one pixel will always have either
null or solid style or will be dithered if the pen style is PS_INSIDEFRAME.



CreatePolygonRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  HRGN CreatePolygonRgn(lpPoints, nCount, nPolyFillMode)

This function creates a polygonal region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPoints                          LPPOINT  Points to an array of POINT
                                  data structures. Each point specifies
                                  the x- and y-coordinates of one vertex
                                  of the polygon.

nCount                            int  Specifies the number of points in
                                  the array.

nPolyFillMode                     int  Specifies the polygon-filling mode
                                  to be used for filling the region. It
                                  can be ALTERNATE or WINDING (for an
                                  explanation of these modes, see the
                                  SetPolyFillMode function, later in this
                                  chapter).



Return Value

The return value identifies a new region if the function is successful.
Otherwise, it is NULL.


CreatePolyPolygonRgn
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HRGN  CreatePolyPolygonRgn(lpPoints, lpPolyCounts,
  nCount, nPolyFillMode)

This function creates a region consisting of a series of closed polygons.
The region is filled using the mode specified by the nPolyFillMode
parameter. The polygons may overlap, but they do not have to overlap.

╓┌───────────────┌─────────────────────────────┌─────────────────────────────╖
Parameter       Type/Description
Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
lpPoints        LPPOINT  Points to an array
                of POINT data structures
                that define the vertices of
                the polygons. Each polygon
                must be a closed polygon.
                The polygons are not
                automatically closed. The
                polygons are specified
                consecutively.

lpPolyCounts    LPINT  Points to an array of
                integers, each of which
                specifies the number of
                points in one of the
                polygons in the lpPoints
                array.

nCount          int  Specifies the total
                number of integers in the
Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
                number of integers in the
                lpPolyCounts array.

nPolyFillMode   int  Specifies the filling
                mode for the region. The
                nPolyFillMode parameter may
                be either of the following
                values:

                ALTERNATE                     Selects alternate mode.

                WINDING                       Selects winding number mode.





Return Value

The return value identifies the region if the function was successfull.
Otherwise, it is NULL.


Comments

In general, the polygon fill modes differ only in cases where a complex,
overlapping polygon must be filled (for example, a five-sided polygon that
forms a five-pointed star with a pentagon in the center). In such cases,
ALTERNATE mode fills every other enclosed region within the polygon (that
is, the points of the star), but WINDING mode fills all regions (that is,
the points and the pentagon).

When the filling mode is ALTERNATE, GDI fills the area between odd-numbered
and even-numbered polygon sides on each scan line. That is, GDI fills the
area between the first and second side, between the third and fourth side,
and so on.

To fill all parts of the region, WINDING mode causes GDI to compute and draw
a border that encloses the region but does not overlap. For example, in
WINDING mode, the five-sided polygon that forms the star is computed as a
ten-sided polygon with no overlapping sides; the resulting star is filled.


CreatePopupMenu
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HMENU  CreatePopupMenu()

This function creates and returns a handle to an empty pop-up menu.

An application adds items to the pop-up menu by calling InsertMenu and
AppendMenu. The application can add the pop-up menu to an existing menu or
pop-up menu, or it may display and track selections on the pop-up menu by
calling TrackPopupMenu.

This function has no parameters.


Return Value

The return value identifies the newly created menu. It is NULL if the menu
cannot be created.


CreateRectRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  HRGN CreateRectRgn(X1, Y1, X2, Y2)

This function creates a rectangular region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
X1                                int  Specifies the x-coordinate of the
                                  upper-left corner of the region.

Y1                                int  Specifies the y-coordinate of the
                                  upper-left corner of the region.

X2                                int  Specifies the x-coordinate of the
                                  lower-right corner of the region.

Y2                                int  Specifies the y-coordinate of the
                                  lower-right corner of the region.



Return Value

The return value identifies a new region if the function is successful.
Otherwise, it is NULL.


Comments

The width of the rectangle, specified by the absolute value of X2 - X1, must
not exceed 32,767 units. This limit applies to the height of the rectangle
as well.


CreateRectRgnIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  HRGN CreateRectRgnIndirect(lpRect)

This function creates a rectangular region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the coordinates of the
                                  upper-left and lower-right corners of
                                  the region.



Return Value

The return value identifies a new region if the function is successful.
Otherwise, it is NULL.


Comments

The width of the rectangle must not exceed 32,767 units. This limit applies
to the height of the rectangle as well.


CreateRoundRectRgn
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HRGN  CreateRoundRectRgn(X1, Y1, X2, Y2, X3, Y3)

This function creates a rectangular region with rounded corners.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
X1                                int  Specifies the x-coordinate of the
                                  upper-left corner of the region.

Y1                                int  Specifies the y-coordinate of the
                                  upper-left corner of the region.

X2                                int  Specifies the x-coordinate of the
                                  lower-right corner of the region.

Y2                                int  Specifies the y-coordinate of the
                                  lower-right corner of the region.

X3                                int  Specifies the width of the ellipse
                                  used to create the rounded corners.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  used to create the rounded corners.

Y3                                int  Specifies the height of the ellipse
                                  used to create the rounded corners.




Return Value

The return value identifies a new region if the function was successful.
Otherwise, it is NULL.


Comments

The width of the rectangle, specified by the absolute value of X2 - X1, must
not exceed 32,767 units. This limit applies to the height of the rectangle
as well.


CreateSolidBrush
────────────────────────────────────────────────────────────────────────────


Syntax

  HBRUSH CreateSolidBrush(crColor)

This function creates a logical brush that has the specified solid color.
The brush can subsequently be selected as the current brush for any device.


Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
crColor          COLORREF  Specifies the color of the brush.


Return Value

The return value identifies a logical brush if the function is successful.
Otherwise, it is NULL.


CreateWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND CreateWindow(lpClassName, lpWindowName, dwStyle,
  X, Y, nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam)

This function creates an overlapped, pop-up, or child window. The
CreateWindow function specifies the window class, window title, window
style, and (optionally) initial position and size of the window. The
CreateWindow function also specifies the window's parent (if any) and menu.


For overlapped, pop-up, and child windows, the CreateWindow function sends
WM_CREATE, WM_GETMINMAXINFO, and WM_NCCREATE messages to the window. The
lParam parameter of the WM_CREATE message contains a pointer to a
CREATESTRUCT data structure. If WS_VISIBLE style is given, CreateWindow
sends the window all the messages required to activate and show the window.


If the window style specifies a title bar, the window title pointed to by
the lpWindowName parameter is displayed in the title bar. When using
CreateWindow to create controls such as buttons, check boxes, and text
controls, the lpWindowName parameter specifies the text of the control.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpClassName                       LPSTR  Points to a null-terminated
                                  character string that names the window
                                  class. The class name can be any name
                                  registered with the RegisterClass
                                  function or any of the predefined
                                  control-class names specified in Table
                                  .2, "Control Classes."

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────

lpWindowName                      LPSTR  Points to a null-terminated
                                  character string that represents the
                                  window name.

dwStyle                           DWORD  Specifies the style of window
                                  being created. It can be any combination
                                  of the styles given in Table .3, "Window
                                  Styles," the control styles given in
                                  Table 4.4, "Control Styles," or a
                                  combination of styles created by using
                                  the bitwise OR operator.

X                                 int  Specifies the initial x-position of
                                  the window. For an overlapped or pop-up
                                  window, the X parameter is the initial x
                                  -coordinate of the window's upper-left
                                  corner (in screen coordinates). If this
                                  value is CW_USEDEFAULT, Windows selects
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  value is CW_USEDEFAULT, Windows selects
                                  the default position for the window's
                                  upper-left corner. For a child window, X
                                  is the x-coordinate of the upper-left
                                  corner of the window in the client area
                                  of its parent window.

Y                                 int  Specifies the initial y-position of
                                  the window. For an overlapped window,
                                  the Y parameter is the initial y
                                  -coordinate of the window's upper-left
                                  corner. For a pop-up window, Y is the y
                                  -coordinate (in screen coordinates) of
                                  the upper-left corner of the pop-up
                                  window. For list-box controls, Y is the
                                  y-coordinate of the upper-left corner of
                                  the control's client area. For a child
                                  window, Y is the y-coordinate of the
                                  upper-left corner of the child window.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  upper-left corner of the child window.
                                  All of these coordinates are for the
                                  window, not the window's client area.

nWidth                            int  Specifies the width (in device
                                  units) of the window. For overlapped
                                  windows, the nWidth parameter is either
                                  the window's width (in screen
                                  coordinates) or CW_USEDEFAULT. If nWidth
                                  is CW_USEDEFAULT, Windows selects a
                                  default width and height for the window
                                  (the default width extends from the
                                  initial x-position to the right edge of
                                  the screen, and the default height
                                  extends from the initial y-position to
                                  the top of the icon area).

nHeight                           int  Specifies the height (in device
                                  units) of the window. For overlapped
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  units) of the window. For overlapped
                                  windows, the nHeight parameter is the
                                  window's height in screen coordinates.
                                  If the nWidth parameter is CW_USEDEFAULT,
                                  Windows ignores nHeight.

hWndParent                        HWND  Identifies the parent or owner
                                  window of the window being created. A
                                  valid window handle must be supplied
                                  when creating a child window or an owned
                                  window. An owned window is an overlapped
                                  window that is destroyed when its owner
                                  window is destroyed, hidden when its
                                  owner is made iconic, and which is
                                  always displayed on top of its owner
                                  window. For pop-up windows, a handle can
                                  be supplied, but is not required. If the
                                  window does not have a parent or is not
                                  owned by another window, the hWndParent
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  owned by another window, the hWndParent
                                  parameter must be set to NULL.

hMenu                             HMENU  Identifies a menu or a
                                  child-window identifier. The meaning
                                  depends on the window style. For
                                  overlapped or pop-up windows, the hMenu
                                  parameter identifies the menu to be used
                                  with the window. It can be NULL, if the
                                  class menu is to be used. For child
                                  windows, hMenu specifies the
                                  child-window identifier, an integer
                                  value that is used by a dialog-box
                                  control to notify its parent of events
                                  (such as the EN_HSCROLL message). The
                                  child-window identifier is determined by
                                  the application and should be unique for
                                  all child windows with the same parent
                                  window.
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  window.

hInstance                         HANDLE  Identifies the instance of the
                                  module to be associated with the window.

lpParam                           LPSTR  Points to a value that is passed
                                  to the window through the CREATESTRUCT
                                  data structure referenced by the lParam
                                  parameter of the WM_CREATE message. If
                                  an application is calling CreateWindow
                                  to create a multiple document interface
                                  (MDI) client window, lpParam must point
                                  to a CLIENTCREATESTRUCT data structure.




Return Value

The return value identifies the new window. It is NULL if the window is not
created.


Comments

For overlapped windows where the X parameter is CW_USEDEFAULT, the Y
parameter can be one of the show-style parameters described with the
ShowWindow function, or, for the first overlapped window to be created by
the application, it can be the nCmdShow parameter passed to the WinMain
function.

Table  lists the window control classes; Table  lists the window styles;
Table  lists the control styles:

Table   Control Classes

Class                             Meaning
────────────────────────────────────────────────────────────────────────────
BUTTON                            Designates a small rectangular child
                                  window that represents a button the user
                                  can turn on or off by clicking it.
                                  Button controls can be used alone or in
                                  groups, and can either be labeled or
                                  appear without text. Button controls
                                  typically change appearance when the
                                  user clicks them.

COMBOBOX                          Designates a control consisting of a
                                  selection field similar to an edit
                                  control plus a list box. The list box
                                  may be displayed at all times or may be
                                  dropped down when the user selects a
                                  "pop box" next to the selection field.

                                  Depending on the style of the combo box,
                                  the user can or cannot edit the contents
                                  of the selection field. If the list box
                                  is visible, typing characters into the
                                  selection box will cause the first list
                                  box entry that matches the characters
                                  typed to be highlighted. Conversely,
                                  selecting an item in the list box
                                  displays the selected text in the
                                  selection field.

EDIT                              Designates a rectangular child window in
                                  which the user can enter text from the
                                  keyboard. The user selects the control,
                                  and gives it the input focus by clicking
                                  it or moving to it by using the TAB key.
                                  The user can enter text when the control
                                  displays a flashing caret. The mouse can
                                  be used to move the cursor and select
                                  characters to be replaced, or to
                                  position the cursor for inserting
                                  characters. The BACKSPACE key can be
                                  used to delete characters.

                                  Edit controls use the variable-pitch
                                  system font and display ANSI characters.
                                  Applications compiled to run with
                                  previous versions of Windows display
                                  text with a fixed-pitch system font
                                  unless they have been marked by the
                                  Windows 3.0 MARK utility with the MEMORY
                                  FONT option. An application can also
                                  send the WM_SETFONT message to the edit
                                  control to change the default font.


Table   Control Classes (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Class                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  Edit controls expand tab characters into
                                  as many space characters as are required
                                  to move the cursor to the next tab stop.
                                  Tab stops are assumed to be at every
                                  eighth character position.

LISTBOX                           Designates a list of character strings.
                                  This control is used whenever an
Class                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  This control is used whenever an
                                  application needs to present a list of
                                  names, such as filenames, that the user
                                  can view and select. The user can select
                                  a string by pointing to it and clicking.
                                  When a string is selected, it is
                                  highlighted and a notification message
                                  is passed to the parent window. A
                                  vertical or horizontal scroll bar can be
                                  used with a list-box control to scroll
                                  lists that are too long for the control
                                  window. The list box automatically hides
                                  or shows the scroll bar as needed.

MDICLIENT                         Designates an MDI client window. The MDI
                                  client window receives messages which
                                  control the MDI application's child
                                  windows. The recommended style bits are
                                  WS_CLIPCHILDREN and WS_CHILD. To create
Class                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  WS_CLIPCHILDREN and WS_CHILD. To create
                                  a scrollable MDI client window which
                                  allows the user to scroll MDI child
                                  windows into view, an application can
                                  also use the WS_HSCROLL and WS_VSCROLL
                                  styles.

SCROLLBAR                         Designates a rectangle that contains a
                                  thumb and has direction arrows at both
                                  ends. The scroll bar sends a
                                  notification message to its parent
                                  window whenever the user clicks the
                                  control. The parent window is
                                  responsible for updating the thumb
                                  position, if necessary. Scroll-bar
                                  controls have the same appearance and
                                  function as scroll bars used in ordinary
                                  windows. Unlike scroll bars, scroll-bar
                                  controls can be positioned anywhere in a
Class                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  controls can be positioned anywhere in a
                                  window and used whenever needed to
                                  provide scrolling input for a window.

                                  The scroll-bar class also includes
                                  size-box controls. A size-box control is
                                  a small rectangle that the user can
                                  expand to change the size of the window.

STATIC                            Designates a simple text field, box, or
                                  rectangle that can be used to label, box,
                                  or separate other controls. Static
                                  controls take no input and provide no
                                  output.

────────────────────────────────────────────────────────────────────────────



Table   Window Styles

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
DS_LOCALEDIT                      Specifies that edit controls in the
                                  dialog box will use memory in the
                                  application's data segment. By default,
                                  all edit controls in dialog boxes use
                                  memory outside the application's data
                                  segment. This feature may be suppressed
                                  by adding the DS_LOCALEDIT flag to the
                                  STYLE command for the dialog box. If
                                  this flag is not used, EM_GETHANDLE and
                                  EM_SETHANDLE messages must not be used
                                  since the storage for the control is not
                                  in the application's data segment. This
                                  feature does not affect edit controls
                                  created outside of dialog boxes.

DS_MODALFRAME                     Creates a dialog box with a modal
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
DS_MODALFRAME                     Creates a dialog box with a modal
                                  dialog-box frame that can be combined
                                  with a title bar and System menu by
                                  specifying the WS_CAPTION and WS_SYSMENU
                                  styles.

DS_NOIDLEMSG                      Suppresses WM_ENTERIDLE messages that
                                  Windows would otherwise send to the
                                  owner of the dialog box while the dialog
                                  box is displayed.

DS_SYSMODAL                       Creates a system-modal dialog box.

WS_BORDER                         Creates a window that has a border.

WS_CAPTION                        Creates a window that has a title bar
                                  (implies the WS_BORDER style). This
                                  style cannot be used with the
                                  WS_DLGFRAME style.
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  WS_DLGFRAME style.

WS_CHILD                          Creates a child window. Cannot be used
                                  with the WS_POPUP style.

WS_CHILDWINDOW                    Creates a child window that has the
                                  WS_CHILD style.

WS_CLIPCHILDREN                   Excludes the area occupied by child
                                  windows when drawing within the parent
                                  window. Used when creating the parent
                                  window.

WS_CLIPSIBLINGS                   Clips child windows relative to each
                                  other; that is, when a particular child
                                  window receives a paint message, the
                                  WS_CLIPSIBLINGS style clips all other
                                  overlapped child windows out of the
                                  region of the child window to be updated.
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  region of the child window to be updated.
                                  (If WS_CLIPSIBLINGS is not given and
                                  child windows overlap, it is possible,
                                  when drawing within the client area of a
                                  child window, to draw within the client
                                  area of a neighboring child window.) For
                                  use with the WS_CHILD style only.



Table   Window Styles (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_DISABLED                       Creates a window that is initially
                                  disabled.

WS_DLGFRAME                       Creates a window with a double border
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_DLGFRAME                       Creates a window with a double border
                                  but no title.

WS_GROUP                          Specifies the first control of a group
                                  of controls in which the user can move
                                  from one control to the next by using
                                  the DIRECTION keys. All controls defined
                                  with the WS_GROUP style after the first
                                  control belong to the same group. The
                                  next control with the WS_GROUP style
                                  ends the style group and starts the next
                                  group (that is, one group ends where the
                                  next begins). Only dialog boxes use this
                                  style.

WS_HSCROLL                        Creates a window that has a horizontal
                                  scroll bar.

WS_ICONIC                         Creates a window that is initially
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_ICONIC                         Creates a window that is initially
                                  iconic. For use with the WS_OVERLAPPED
                                  style only.

WS_MAXIMIZE                       Creates a window of maximum size.

WS_MAXIMIZEBOX                    Creates a window that has a maximize box.


WS_MINIMIZE                       Creates a window of minimum size.

WS_MINIMIZEBOX                    Creates a window that has a minimize box.


WS_OVERLAPPED                     Creates an overlapped window. An
                                  overlapped window has a caption and a
                                  border.

WS_OVERLAPPEDWINDOW               Creates an overlapped window having the
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_OVERLAPPEDWINDOW               Creates an overlapped window having the
                                  WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU,
                                  WS_THICKFRAME, WS_MINIMIZEBOX, and
                                  WS_MAXIMIZEBOX styles.

WS_POPUP                          Creates a pop-up window. Cannot be used
                                  with the WS_CHILD style.

WS_POPUPWINDOW                    Creates a pop-up window that has the
                                  WS_BORDER, WS_POPUP, and WS_SYSMENU
                                  styles. The WS_CAPTION style must be
                                  combined with the WS_POPUPWINDOW style
                                  to make the system menu visible.

WS_SYSMENU                        Creates a window that has a System-menu
                                  box in its title bar. Used only for
                                  windows with title bars.

WS_TABSTOP                        Specifies one of any number of controls
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_TABSTOP                        Specifies one of any number of controls
                                  through which the user can move by using
                                  the TAB key. The TAB key moves the user
                                  to the next control specified by the
                                  WS_TABSTOP style. Only dialog boxes use
                                  this style.

WS_THICKFRAME                     Creates a window with a thick frame that
                                  can be used to size the window.

WS_VISIBLE                        Creates a window that is initially
                                  visible. This applies to overlapped and
                                  pop-up windows. For overlapped windows,
                                  the Y parameter is used as a ShowWindow
                                  function parameter.

WS_VSCROLL                        Creates a window that has a vertical
                                  scroll bar.

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

────────────────────────────────────────────────────────────────────────────



Table   Control Styles

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
BUTTON Class

────────────────────────────────────────────────────────────────────────────

BS_AUTOCHECKBOX                   Identical to BS_CHECKBOX, except that
                                  the button automatically toggles its
                                  state whenever the user clicks it.

BS_AUTORADIOBUTTON                Identical to BS_RADIOBUTTON, except that
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
BS_AUTORADIOBUTTON                Identical to BS_RADIOBUTTON, except that
                                  the button is checked, the application
                                  is notified by BN_CLICKED, and the
                                  checkmarks are removed from all other
                                  radio buttons in the group.

BS_AUTO3STATE                     Identical to BS_3STATE, except that the
                                  button automatically toggles its state
                                  when the user clicks it.

BS_CHECKBOX                       Designates a small rectangular button
                                  that may be checked; its border is bold
                                  when the user clicks the button. Any
                                  text appears to the right of the button.


BS_DEFPUSHBUTTON                  Designates a button with a bold border.
                                  This button represents the default user
                                  response. Any text is displayed within
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  response. Any text is displayed within
                                  the button. Windows sends a message to
                                  the parent window when the user clicks
                                  the button.

BS_GROUPBOX                       Designates a rectangle into which other
                                  buttons are grouped. Any text is
                                  displayed in the rectangle's upper-left
                                  corner.

BS_LEFTTEXT                       Causes text to appear on the left side
                                  of the radio button or check-box button.
                                  Use this style with the BS_CHECKBOX,
                                  BS_RADIOBUTTON, or BS_3STATE styles.



Table   Control Styles (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
BS_OWNERDRAW                      Designates an owner-draw button. The
                                  parent window is notified when the
                                  button is clicked. Notification includes
                                  a request to paint, invert, and disable
                                  the button.

BS_PUSHBUTTON                     Designates a button that contains the
                                  given text. The control sends a message
                                  to its parent window whenever the user
                                  clicks the button.

BS_RADIOBUTTON                    Designates a small circular button that
                                  can be checked; its border is bold when
                                  the user clicks the button. Any text
                                  appears to the right of the button.
                                  Typically, two or more radio buttons are
                                  grouped together to represent mutually
                                  exclusive choices, so no more than one
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  exclusive choices, so no more than one
                                  button in the group is checked at any
                                  time.

BS_3STATE                         Identical to BS_CHECKBOX, except that a
                                  button can be grayed as well as checked.
                                  The grayed state typically is used to
                                  show that a check box has been disabled.


────────────────────────────────────────────────────────────────────────────

COMBOBOX Class

────────────────────────────────────────────────────────────────────────────

CBS_AUTOHSCROLL                   Automatically scrolls the text in the
                                  edit control to the right when the user
                                  types a character at the end of the line.
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  types a character at the end of the line.
                                  If this style is not set, only text
                                  which fits within the rectangular
                                  boundary is allowed.

CBS_DROPDOWN                      Similar to CBS_SIMPLE, except that the
                                  list box is not displayed unless the
                                  user selects an icon next to the
                                  selection field.

CBS_DROPDOWNLIST                  Similar to CBS_DROPDOWN, except that the
                                  edit control is replaced by a static
                                  text item which displays the current
                                  selection in the list box.

CBS_HASSTRINGS                    An owner-draw combo box contains items
                                  consisting of strings. The combo box
                                  maintains the memory and pointers for
                                  the strings so the application can use
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the strings so the application can use
                                  the LB_GETTEXT message to retrieve the
                                  text for a particular item.

CBS_OEMCONVERT                    Text entered in the combo box edit
                                  control is converted from the ANSI
                                  character set to the OEM character set
                                  and then back to ANSI. This ensures
                                  proper character conversion when the
                                  application calls the AnsiToOem function
                                  to convert an ANSI string in the combo
                                  box to OEM characters. This style is
                                  most useful for combo boxes that contain
                                  filenames and applies only to combo
                                  boxes created with the CBS_SIMPLE or
                                  CBS_DROPDOWN styles.

CBS_OWNERDRAWFIXED                The owner of the list box is responsible
                                  for drawing its contents; the items in
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  for drawing its contents; the items in
                                  the list box are all the same height.

CBS_OWNERDRAWVARIABLE             The owner of the list box is responsible
                                  for drawing its contents; the items in
                                  the list box are variable in height.

CBS_SIMPLE                        The list box is displayed at all times.
                                  The current selection in the list box is
                                  displayed in the edit control.

CBS_SORT                          Automatically sorts strings entered into
                                  the list box.

────────────────────────────────────────────────────────────────────────────

EDIT Class

────────────────────────────────────────────────────────────────────────────
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────────────

ES_AUTOHSCROLL                    Automatically scrolls text to the right
                                  by 10 characters when the user types a
                                  character at the end of the line. When
                                  the user presses the ENTER key, the
                                  control scrolls all text back to
                                  position zero.

ES_AUTOVSCROLL                    Automatically scrolls text up one page
                                  when the user presses ENTER  on the last
                                  line.

ES_CENTER                         Centers text in a multiline edit control.


ES_LEFT                           Aligns text flush-left.

ES_LOWERCASE                      Converts all characters to lowercase as
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
ES_LOWERCASE                      Converts all characters to lowercase as
                                  they are typed into the edit control.

ES_MULTILINE                      Designates multiple-line edit control.
                                  (The default is single-line.) If the
                                  ES_AUTOVSCROLL style is specified, the
                                  edit control shows as many lines as
                                  possible and scrolls vertically when the
                                  user presses the ENTER key. If
                                  ES_AUTOVSCROLL is not given, the edit
                                  control shows as many lines as possible
                                  and beeps if ENTER is pressed when no
                                  more lines can be displayed.

                                  If the ES_AUTOHSCROLL style is specified,
                                  the multiple-line edit control
                                  automatically scrolls horizontally when
                                  the caret goes past the right edge of
                                  the control. To start a new line, the
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the control. To start a new line, the
                                  user must press ENTER. If ES_AUTOHSCROLL
                                  is not given, the control automatically
                                  wraps words to the beginning of the next
                                  line when necessary; a new line is also
                                  started if ENTER is pressed. The
                                  position of the wordwrap is determined
                                  by the window size. If the window size
                                  changes, the wordwrap position changes,
                                  and the text is redisplayed.

                                  Multiple-line edit controls can have
                                  scroll bars. An edit control with scroll
                                  bars processes its own scroll-bar
                                  messages. Edit controls without scroll
                                  bars scroll as described above, and
                                  process any scroll messages sent by the
                                  parent window.

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

ES_NOHIDESEL                      Normally, an edit control hides the
                                  selection when the control loses the
                                  input focus, and inverts the selection
                                  when the control receives the input
                                  focus. Specifying ES_NOHIDESEL deletes
                                  this default action.

ES_OEMCONVERT                     Text entered in the edit control is
                                  converted from the ANSI character set to
                                  the OEM character set and then back to
                                  ANSI. This ensures proper character
                                  conversion when the application calls
                                  the AnsiToOem function to convert an
                                  ANSI string in the edit control to OEM
                                  characters. This style is most useful
                                  for edit controls that contain
                                  filenames.

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

ES_PASSWORD                       Displays all characters as an asterisk
                                  (*) as they are typed into the edit
                                  control. An application can use the
                                  EM_SETPASSWORDCHAR message to change the
                                  character that is displayed.

ES_RIGHT                          Aligns text flush-right in a multiline
                                  edit control.

ES_UPPERCASE                      Converts all characters to uppercase as
                                  they are typed into the edit control.

────────────────────────────────────────────────────────────────────────────

LISTBOX Class

────────────────────────────────────────────────────────────────────────────

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

LBS_EXTENDEDSEL                   The user can select multiple items using
                                  the SHIFT key and the mouse or special
                                  key combinations.

LBS_HASSTRINGS                    Specifies an owner-draw list box which
                                  contains items consisting of strings.
                                  The list box maintains the memory and
                                  pointers for the strings so the
                                  application can use the LB_GETTEXT
                                  message to retrieve the text for a
                                  particular item.

LBS_MULTICOLUMN                   Specifies a multicolumn list box that is
                                  scrolled horizontally. The
                                  LB_SETCOLUMNWIDTH message sets the width
                                  of the columns.

LBS_MULTIPLESEL                   String selection is toggled each time
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
LBS_MULTIPLESEL                   String selection is toggled each time
                                  the user clicks or double-clicks the
                                  string. Any number of strings can be
                                  selected.

LBS_NOINTEGRALHEIGHT              The size of the list box is exactly the
                                  size specified by the application when
                                  it created the list box. Normally,
                                  Windows sizes a list box so that the
                                  list box does not display partial items.

LBS_NOREDRAW                      List-box display is not updated when
                                  changes are made. This style can be
                                  changed at any time by sending a
                                  WM_SETREDRAW message.

LBS_NOTIFY                        Parent window receives an input message
                                  whenever the user clicks or
                                  double-clicks a string.
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  double-clicks a string.

LBS_OWNERDRAWFIXED                The owner of the list box is responsible
                                  for drawing its contents; the items in
                                  the list box are the same height.

LBS_OWNERDRAWVARIABLE             The owner of the list box is responsible
                                  for drawing its contents; the items in
                                  the list box are variable in height.

LBS_SORT                          Strings in the list box are sorted
                                  alphabetically.

LBS_STANDARD                      Strings in the list box are sorted
                                  alphabetically and the parent window
                                  receives an input message whenever the
                                  user clicks or double-clicks a string.
                                  The list box contains borders on all
                                  sides.
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  sides.

LBS_USETABSTOPS                   Allows a list box to recognize and
                                  expand tab characters when drawing its
                                  strings. The default tab positions are
                                  32 dialog units. (A dialog unit is a
                                  horizontal or vertical distance. One
                                  horizontal dialog unit is equal to 1/4
                                  of the current dialog base width unit.
                                  The dialog base units are computed based
                                  on the height and width of the current
                                  system font. The GetDialogBaseUnits
                                  function returns the current dialog base
                                  units in pixels.)

LBS_WANTKEYBOARDINPUT             The owner of the list box receives
                                  WM_VKEYTOITEM or WM_CHARTOITEM messages
                                  whenever the user presses a key when the
                                  list box has input focus. This allows an
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  list box has input focus. This allows an
                                  application to perform special
                                  processing on the keyboard input.

────────────────────────────────────────────────────────────────────────────

SCROLLBAR Class

────────────────────────────────────────────────────────────────────────────

SBS_BOTTOMALIGN                   Used with the SBS_HORZ style. The bottom
                                  edge of the scroll bar is aligned with
                                  the bottom edge of the rectangle
                                  specified by the X, Y, nWidth, and
                                  nHeight parameters given in the
                                  CreateWindow function. The scroll bar
                                  has the default height for system scroll
                                  bars.

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

SBS_HORZ                          Designates a horizontal scroll bar. If
                                  neither the SBS_BOTTOMALIGN nor
                                  SBS_TOPALIGN style is specified, the
                                  scroll bar has the height, width, and
                                  position given in the CreateWindow
                                  function.

SBS_LEFTALIGN                     Used with the SBS_VERT style. The left
                                  edge of the scroll bar is aligned with
                                  the left edge of the rectangle specified
                                  by the X, Y, nWidth, and nHeight
                                  parameters given in the CreateWindow
                                  function. The scroll bar has the default
                                  width for system scroll bars.

SBS_RIGHTALIGN                    Used with the SBS_VERT style. The right
                                  edge of the scroll bar is aligned with
                                  the right edge of the rectangle
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the right edge of the rectangle
                                  specified by the X, Y, nWidth, and
                                  nHeight parameters given in the
                                  CreateWindow function. The scroll bar
                                  has the default width for system scroll
                                  bars.

SBS_SIZEBOX                       Designates a size box. If neither the
                                  SBS_SIZEBOXBOTTOMRIGHTALIGN nor
                                  SBS_SIZEBOXTOPLEFTALIGN style is
                                  specified, the size box has the height,
                                  width, and position given in the
                                  CreateWindow function.

SBS_SIZEBOXBOTTOMRIGHTALIGN       Used with the SBS_SIZEBOX style. The
                                  lower-right corner of the size box is
                                  aligned with the lower-right corner of
                                  the rectangle specified by the X, Y,
                                  nWidth, and nHeight parameters given in
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  nWidth, and nHeight parameters given in
                                  the CreateWindow function. The size box
                                  has the default size for system size
                                  boxes.

SBS_SIZEBOXTOPLEFTALIGN           Used with the SBS_SIZEBOX style. The
                                  upper-left corner of the size box is
                                  aligned with the upper-left corner of
                                  the rectangle specified by the X, Y,
                                  nWidth, and nHeight parameters given in
                                  the CreateWindow function. The size box
                                  has the default size for system size
                                  boxes.

SBS_TOPALIGN                      Used with the SBS_HORZ style. The top
                                  edge of the scroll bar is aligned with
                                  the top edge of the rectangle specified
                                  by the X, Y, nWidth, and nHeight
                                  parameters given in the CreateWindow
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  parameters given in the CreateWindow
                                  function. The scroll bar has the default
                                  height for system scroll bars.

SBS_VERT                          Designates a vertical scroll bar. If
                                  neither the SBS_RIGHTALIGN nor
                                  SBS_LEFTALIGN style is specified, the
                                  scroll bar has the height, width, and
                                  position given in the CreateWindow
                                  function.

────────────────────────────────────────────────────────────────────────────

STATIC Class

────────────────────────────────────────────────────────────────────────────

SS_BLACKFRAME                     Specifies a box with a frame drawn with
                                  the same color as window frames. This
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the same color as window frames. This
                                  color is black in the default Windows
                                  color scheme.

SS_BLACKRECT                      Specifies a rectangle filled with the
                                  color used to draw window frames. This
                                  color is black in the default Windows
                                  color scheme.

SS_CENTER                         Designates a simple rectangle and
                                  displays the given text centered in the
                                  rectangle. The text is formatted before
                                  it is displayed. Words that would extend
                                  past the end of a line are automatically
                                  wrapped to the beginning of the next
                                  centered line.

SS_GRAYFRAME                      Specifies a box with a frame drawn with
                                  the same color as the screen background
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  the same color as the screen background
                                  (desktop). This color is gray in the
                                  default Windows color scheme.

SS_GRAYRECT                       Specifies a rectangle filled with the
                                  color used to fill the screen background.
                                  This color is gray in the default
                                  Windows color scheme.

SS_ICON                           Designates an icon displayed in the
                                  dialog box. The given text is the name
                                  of an icon (not a filename) defined
                                  elsewhere in the resource file. The
                                  nWidth and nHeight parameters are
                                  ignored; the icon automatically sizes
                                  itself.

SS_LEFT                           Designates a simple rectangle and
                                  displays the given text flush-left in
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  displays the given text flush-left in
                                  the rectangle. The text is formatted
                                  before it is displayed. Words that would
                                  extend past the end of a line are
                                  automatically wrapped to the beginning
                                  of the next flush-left line.

SS_LEFTNOWORDWRAP                 Designates a simple rectangle and
                                  displays the given text flush-left in
                                  the rectangle. Tabs are expanded, but
                                  words are not wrapped. Text that extends
                                  past the end of a line is clipped.

SS_NOPREFIX                       Unless this style is specified, windows
                                  will interpret any "&" characters in the
                                  control's text to be accelerator prefix
                                  characters. In this case, the "&" is
                                  removed and the next character in the
                                  string is underlined. If a static
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  string is underlined. If a static
                                  control is to contain text where this
                                  feature is not wanted, SS_NOPREFIX may
                                  be added. This static-control style may
                                  be included with any of the defined
                                  static controls.

                                  You can combine SS_NOPREFIX with other
                                  styles by using the bitwise OR operator.
                                  This is most often used when filenames
                                  or other strings that may contain an "&"
                                  need to be displayed in a static control
                                  in a dialog box.

SS_RIGHT                          Designates a simple rectangle and
                                  displays the given text flush-right in
                                  the rectangle. The text is formatted
                                  before it is displayed. Words that would
                                  extend past the end of a line are
Style                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  extend past the end of a line are
                                  automatically wrapped to the beginning
                                  of the next flush-right line.

SS_SIMPLE                         Designates a simple rectangle and
                                  displays a single line of text
                                  flush-left in the rectangle. The line of
                                  text cannot be shortened or altered in
                                  any way. (The control's parent window or
                                  dialog box must not process the
                                  WM_CTLCOLOR message.)

SS_USERITEM                       Specifies a user-defined item.

SS_WHITEFRAME                     Specifies a box with a frame drawn with
                                  the same color as window backgrounds.
                                  This color is white in the default
                                  Windows color scheme.

Style                             Meaning
────────────────────────────────────────────────────────────────────────────

SS_WHITERECT                      Specifies a rectangle filled with the
                                  color used to fill window backgrounds.
                                  This color is white in the default
                                  Windows color scheme.




CreateWindowEx
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HWND  CreateWindowEx(dwExStyle, lpClassName,
  lpWindowName, dwStyle, X, Y, nWidth,
  nHeight, hWndParent, hMenu, hInstance, lpParam)

This function creates an overlapped, pop-up, or child window with an
extended style specified in the dwExStyle parameter. Otherwise, this
function is identical to the CreateWindow function. See the description of
the CreateWindow function for more information on creating a window and for
a full descriptions of the other parameters of CreateWindowEx.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
dwExStyle                         DWORD  Specifies the extended style of
                                  the window being created. Table .5,
                                  "Extended Window Styles," lists the
                                  extended window styles.

lpClassName                       LPSTR  Points to a null-terminated
                                  character string that names the window
                                  class.

lpWindowName                      LPSTR  Points to a null-terminated
                                  character string that represents the
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  character string that represents the
                                  window name.

dwStyle                           DWORD  Specifies the style of window
                                  being created.

X                                 int  Specifies the initial x-position of
                                  the window.

Y                                 int  Specifies the initial y-position of
                                  the window.

nWidth                            int  Specifies the width (in device
                                  units) of the window.

nHeight                           int  Specifies the height (in device
                                  units) of the window.

hWndParent                        HWND  Identifies the parent or owner
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWndParent                        HWND  Identifies the parent or owner
                                  window of the window being created.

hMenu                             HMENU  Identifies a menu or a
                                  child-window identifier. The meaning
                                  depends on the window style.

hInstance                         HANDLE  Identifies the instance of the
                                  module to be associated with the window.

lpParam                           LPSTR  Points to a value that is passed
                                  to the window through the CREATESTRUCT
                                  data structure referenced by the lParam
                                  parameter of the WM_CREATE message.




Return Value

The return value identifies the new window. It is NULL if the window is not
created.


Comments

Table  lists the extended window styles.

Table   Extended Window Styles

Style                             Meaning
────────────────────────────────────────────────────────────────────────────
WS_EX_DLGMODALFRAME               Designates a window with a double border
                                  that may optionally be created with a
                                  title bar by specifying the WS_CAPTION
                                  style flag in the dwStyle parameter.

WS_EX_NOPARENTNOTIFY              Specifies that a child window created
                                  with this style will not send the
                                  WM_PARENTNOTIFY message to its parent
                                  window when the child window is created
                                  or destroyed.

────────────────────────────────────────────────────────────────────────────


Table , "Control Classes," lists the window control classes. Table , "Window
Styles," lists the window styles. Table , "Control Styles," lists the
control styles. See the description of the CreateWindow function for these
tables.





DebugBreak
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void   DebugBreak( )

This function forces a break to the debugger.

This function has no parameters.


Return Value

None.


DefDlgProc
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  LONG  DefDlgProc(hDlg, wMsg, wParam, lParam)

This function provides default processing for any Windows messages that a
dialog box with a private window class does not process.

All window messages that are not explicitly processed by the window function
must be passed to the DefDlgProc function, not the DefWindowProc function.
This ensures that all messages not handled by their private window procedure
will be handled properly.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box.

wMsg                              WORD  Specifies the message number.

wParam                            WORD  Specifies 16 bits of additional
                                  message-dependent information.

lParam                            DWORD  Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The return value specifies the result of the message processing and depends
on the actual message sent.


Comments

The source code for the DefDlgProc function is provided on the SDK disks.

An application creates a dialog box by calling one of the following
functions:

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateDialog                      Creates a modeless dialog box.

CreateDialogIndirect              Creates a modeless dialog box.
Function                          Description
────────────────────────────────────────────────────────────────────────────
CreateDialogIndirect              Creates a modeless dialog box.

CreateDialogIndirectParam         Creates a modeless dialog box and passes
                                  data to it when it is created.

CreateDialogParam                 Creates a modeless dialog box and passes
                                  data to it when it is created.

DialogBox                         Creates a modal dialog box.

DialogBoxIndirect                 Creates a modal dialog box.

DialogBoxIndirectParam            Creates a modal dialog box and passes
                                  data to it when it is created.

DialogBoxParam                    Creates a modal dialog box and passes
                                  data to it when it is created.




DeferWindowPos
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HANDLE  DeferWindowPos(hWinPosInfo, hWnd, hWndInsertAfter,
  x, y, cx, cy, wFlags)

This function updates the multiple window-position data structure identified
by the hWinPosInfo parameter for the window identified by hWnd parameter and
returns the handle of the updated structure. The EndDeferWindowPos function
uses the information in this structure to change the position and size of a
number of windows simultaneously. The BeginDeferWindowPos function creates
the multiple window-position data structure used by this function.

The x and y parameters specify the new position of the window, and the cx
and cy parameters specify the new size of the window.

╓┌────────────────┌────────────────────────────┌─────────────────────────────╖
Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hWinPosInfo      HANDLE  Identifies a
                 multiple window-position
                 data structure that
                 contains size and position
                 information for one or more
                 windows. This structure is
                 returned by the
                 BeginDeferWindowPos
                 function or the most recent
                 call to the DeferWindowPos
                 function.

hWnd             HWND  Identifies the window
                 for which update
                 information is to be stored
                 in the data structure.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────

hWndInsertAfter  HWND  Identifies the window
                 following which the window
                 identified by the hWnd
                 parameter is to be updated.

x                int  Specifies the x-
                 coordinate of the window's
                 upper-left corner.

y                int  Specifies the y-
                 coordinate of the window's
                 upper-left corner.

cx               int  Specifies the window's
                 new width.

cy               int  Specifies the window's
                 new height.
Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
                 new height.

wFlags           WORD  Specifies one of
                 eight possible 16-bit
                 values that affect the size
                 and position of the window.
                 It must be one of the
                 following values:

                 Value                        Meaning

                 SWP_DRAWFRAME                Draws a frame (defined in
                                              the window's class
                                              description) around the
                                              window.

                 SWP_HIDEWINDOW               Hides the window.

                 SWP_NOACTIVATE               Does not activate the window.
Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
                 SWP_NOACTIVATE               Does not activate the window.


                 SWP_NOMOVE                   Retains current position
                                              (ignores the x and y
                                              parameters).

                 SWP_NOREDRAW                 Does not redraw changes.

                 SWP_NOSIZE                   Retains current size
                                              (ignores the cx and cy
                                              parameters).

                 SWP_NOZORDER                 Retains current ordering
                                              (ignores the hWndInsertAfter
                                              parameter).

                 SWP_SHOWWINDOW               Displays the window.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────




Return Value

The return value identifies the updated multiple window-position data
structure. The handle returned by this function may differ from the handle
passed to the function as the hWinPosInfo parameter. The new handle returned
by this function should be passed to the next call to DeferWindowPos or the
EndDeferWindowPos function.

The return value is NULL if insufficient system resources are available for
the function to complete successfully.


Comments

If the SWP_NOZORDER flag is not specified, Windows places the window
identified by the hWnd parameter in the position following the window
identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL,
Windows places the window identified by hWnd at the top of the list. If
hWndInsertAfter is set to 1, Windows places the window identified by hWnd at
the bottom of the list.

If the SWP_SHOWWINDOW or the SWP_HIDEWINDOW flags are set, scrolling and
moving cannot be done simultaneously.

All coordinates for child windows are relative to the upper-left corner of
the parent window's client area.


DefFrameProc
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  LONG  DefFrameProc(hWnd, hWndMDIClient, wMsg,
  wParam, lParam)

This function provides default processing for any Windows messages that the
window function of a multiple document interface (MDI) frame window does not
process. All window messages that are not explicitly processed by the window
function must be passed to the DefFrameProc function, not the DefWindowProc
function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the MDI frame window.

hWndMDIClient                     HWND  Identifies the MDI client window.

wMsg                              WORD  Specifies the message number.

wParam                            WORD  Specifies 16 bits of additional
                                  message-dependent information.

lParam                            DWORD  Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The return value specifies the result of the message processing and depends
on the actual message sent. If the hWndMDIClient parameter is NULL, the
return value is the same as for the DefWindowProc function.


Comments

Normally, when an application's window procedure does not handle a message,
it passes the message to the DefWindowProc function, which processes the
message. MDI applications use the DefFrameProc and DefMDIChildProc functions
instead of DefWindowProc to provide default message processing. All messages
that an application would normally pass to DefWindowProc (such as nonclient
messages and WM_SETTEXT) should be passed to DefFrameProc instead. In
addition to these, DefFrameProc also handles the following messages:

Message                           Default Processing by DefFrameProc
────────────────────────────────────────────────────────────────────────────
WM_COMMAND                        The frame window of an MDI application
                                  receives the WM_COMMAND message to
                                  activate a particular MDI child window.
                                  The window ID accompanying this message
                                  will be the ID of the MDI child window
                                  assigned by Windows, starting with the
                                  first ID specified by the application
                                  when it created the MDI client window.
                                  This value of the first ID must not
                                  conflict with menu-item IDs.

WM_MENUCHAR                       When the ALT+HYPHEN key is pressed, the
                                  control menu of the active MDI child
                                  window will be selected.

WM_NEXTMENU                       This message causes the control menu of
                                  the active MDI child window to be
                                  selected.

WM_SETFOCUS                       DefFrameProc passes focus on to the MDI
                                  client, which in turn passes the focus
                                  on to the active MDI child window.

WM_SIZE                           If the frame window procedure passes
                                  this message to DefFrameProc, the MDI
                                  client window will be resized to fit in
                                  the new client area. If the frame window
                                  procedure sizes the MDI client to a
                                  different size, it should not pass the
                                  message to DefWindowProc.



DefHookProc
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD DefHookProc(code, wParam, lParam, lplpfnNextHook)

This function calls the next function in a chain of hook functions. A hook
function is a function that processes events before they are sent to an
application's message-processing loop in the WinMain function. When an
application defines more than one hook function by using the SetWindowsHook
function, Windows forms a linked list or hook chain. Windows places
functions of the same type in a chain.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
code                              int  Specifies a code used by the
                                  Windows hook function (also called the
                                  message filter function) to determine
                                  how to process the message.

wParam                            WORD  Specifies the word parameter of
                                  the message that the hook function is
                                  processing.

lParam                            DWORD  Specifies the long parameter of
                                  the message that the hook function is
                                  processing.

lplpfnNextHook                    FARPROC FAR *  Points to a memory
                                  location that contains the FARPROC
                                  structure returned by the SetWindowsHook
                                  function. Windows changes the value at
                                  this location after an application calls
                                  the UnhookWindowsHook function.



Return Value

The return value specifies a value that is directly related to the code
parameter.


DefineHandleTable
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  DefineHandleTable(wOffset)

This function creates a private handle table in an application's default
data segment. The application stores in the table the segment addresses of
global memory objects returned by the GlobalLock function. In real mode,
Windows updates the corresponding address in the private handle table when
it moves a global memory object. When Windows discards an object with a
corresponding table entry, Windows replaces the address of the object in the
table with the object's handle. Windows does not update addresses in the
private handle table in protected (standard or 386 enhanced) mode.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wOffset                           WORD  Specifies the offset from the
                                  beginning of the data segment to the
                                  beginning of the private handle table.
                                  If wOffset is zero, Windows no longer
                                  updates the private handle table.



Return Value

The return value is nonzero if the function was successful. Otherwise, it is
zero.


Comments

The private handle table has the following format:

  Count
  Clear_Number
  Entry[0]
  .
  .
  .
  Entry[Count-1]

The first WORD (Count) in the table specifies the number of entries in the
table. The second WORD (Clear_Number) specifies the number of entries (from
the beginning of the table) which Windows will set to zero when Windows
updates its least-recently-used (LRU) memory list. The remainder of the
table consists of an array of addresses returned by GlobalLock.

The application must initialize the Count field in the table before calling
DefineHandleTable. The application can change either the Count or
Clearn_Number fields at any time.


DefMDIChildProc
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  LONG  DefMDIChildProc(hWnd, wMsg, wParam, lParam)

This function provides default processing for any Windows messages that the
window function of a multiple document interface (MDI) child window does not
process. All window messages that are not explicitly processed by the window
function must be passed to the DefMDIChildProc function, not the
DefWindowProc function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the MDI child window.

wMsg                              WORD  Specifies the message number.

wParam                            WORD  Specifies 16 bits of additional
                                  message-dependent information.

lParam                            DWORD  Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The return value specifies the result of the message processing and depends
on the actual message sent.


Comments

This function assumes that the parent of the window identified by the hWnd
parameter was created with the MDICLIENT class.

Normally, when an application's window procedure does not handle a message,
it passes the message to the DefWindowProc function, which processes the
message. MDI applications use the DefFrameProc and DefMDIChildProc functions
instead of DefWindowProc to provide default message processing. All messages
that an application would normally pass to DefWindowProc (such as nonclient
messages and WM_SETTEXT) should be passed to DefMDIChildProc instead. In
addition to these, DefMDIChildProc also handles the following messages:

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Message                           Default Processing by DefMDIChildProc
────────────────────────────────────────────────────────────────────────────
WM_CHILDACTIVATE                  Performs activation processing when
                                  child windows are sized, moved, or shown.
Message                           Default Processing by DefMDIChildProc
────────────────────────────────────────────────────────────────────────────
                                  child windows are sized, moved, or shown.
                                  This message must be passed.

WM_GETMINMAXINFO                  Calculates the size of a maximized MDI
                                  child window based on the current size
                                  of the MDI client window.

WM_MENUCHAR                       Sends the key to the frame window.

WM_MOVE                           Recalculates MDI client scroll bars, if
                                  they are present.

WM_NEXTMENU                       Wraps back to the frame menu bar or
                                  frame control menu.

WM_SETFOCUS                       Activates the child window if it is not
                                  the active MDI child.

WM_SIZE                           Performs necessary operations when
Message                           Default Processing by DefMDIChildProc
────────────────────────────────────────────────────────────────────────────
WM_SIZE                           Performs necessary operations when
                                  changing the size of a window,
                                  especially when maximizing or restoring
                                  an MDI child window. Failing to pass
                                  this message to DefMDIChildProc will
                                  produce highly undesirable results.

WM_SYSCOMMAND                     Also handles the "next window" command.




DefWindowProc
────────────────────────────────────────────────────────────────────────────


Syntax

  LONG DefWindowProc(hWnd, wMsg, wParam, lParam)

This function provides default processing for any Windows messages that a
given application does not process. All window messages that are not
explicitly processed by the class window function must be passed to the
DefWindowProc function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window that passes
                                  the message.

wMsg                              WORD  Specifies the message number.

wParam                            WORD  Specifies 16 bits of additional
                                  message-dependent information.

lParam                            DWORD  Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The return value specifies the result of the message processing and depends
on the actual message sent.


Comments

The source code for the DefWindowProc function is provided on the SDK disks.



DeleteAtom
────────────────────────────────────────────────────────────────────────────


Syntax

  ATOM DeleteAtom(nAtom)

This function deletes an atom and, if the atom's reference count is zero,
removes the associated string from the atom table.

An atom's reference count specifies the number of times the atom has been
added to the atom table. The AddAtom function increases the count on each
call; the DeleteAtom function decreases the count on each call. DeleteAtom
removes the string only if the atom's reference count is zero.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nAtom       ATOM  Identifies the atom and character string to be deleted.


Return Value

The return value specifies the outcome of the function. It is NULL if the
function is successful. It is equal to the nAtom parameter if the function
failed and the atom has not been deleted.


DeleteDC
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DeleteDC(hDC)

This function deletes the specified device context. If the hDC parameter is
the last device context for a given device, the device is notified and all
storage and system resources used by the device are released.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC  Identifies the device context.


Return Value

The return value specifies whether the device context is deleted. It is
nonzero if the device context is successfully deleted (regardless of whether
the deleted device context is the last context for the device). If an error
occurs, the return value is zero.


Comments

An application must not delete a device context whose handle was obtained by
calling the GetDC function. Instead, it must call the ReleaseDC function to
free the device context.


DeleteMenu
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  DeleteMenu(hMenu, nPosition, wFlags)

This function deletes an item from the menu identified by the hMenu
parameter; if the menu item has an associated pop-up menu, DeleteMenu
destroys the handle by the pop-up menu and frees the memory used by the
pop-up menu.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu                             HMENU  Identifies the menu to be changed.

nPosition                         WORD  Specifies the menu item which is
                                  to be deleted. If wFlags is set to
                                  MF_BYPOSITION, nPosition specifies the
                                  position of the menu item; the first
                                  item in the menu is at position 0. If
                                  wFlags is set to MF_BYCOMMAND, then
                                  nPosition specifies the command ID of
                                  the existing menu item.

wFlags                            WORD  Specifies how the nPosition
                                  parameter is interpreted. It may be set
                                  to either MF_BYCOMMAND (the default) or
                                  MF_BYPOSITION.



Return Value

The return value specifies the outcome of the function. It is TRUE if the
function is successful. Otherwise, it is FALSE.


Comments

Whenever a menu changes (whether or not the menu resides in a window that is
displayed), the application should call DrawMenuBar.


DeleteMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DeleteMetaFile(hMF)

This function deletes access to a metafile by freeing the system resources
associated with that metafile. It does not destroy the metafile itself, but
it invalidates the metafile handle, hMF. Access to the metafile can be
reestablished by retrieving a new handle by using the GetMetaFile function.


Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
hMF             HANDLE Identifies the metafile to be deleted.


Return Value

The return value specifies whether the metafile handle is invalidated. It is
nonzero if the metafile's system resources are deleted. It is zero if the
hMF parameter is not a valid handle.


DeleteObject
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DeleteObject(hObject)

This function deletes a logical pen, brush, font, bitmap, region, or palette
from memory by freeing all system storage associated with the object. After
the object is deleted, the hObject handle is no longer valid.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hObject                           HANDLE Identifies a handle to a logical
                                  pen, brush, font, bitmap, region, or
                                  palette.



Return Value

The return value specifies whether the specified object is deleted. It is
nonzero if the object is deleted. It is zero if the hObject parameter is not
a valid handle or is currently selected into a device context.


Comments

The object to be deleted should not be currently selected into a device
context.

When a pattern brush is deleted, the bitmap associated with the brush is not
deleted. The bitmap must be deleted independently.

An application must not delete a stock object.


DestroyCaret
────────────────────────────────────────────────────────────────────────────


Syntax

  void DestroyCaret( )

This function destroys the current caret shape, frees the caret from the
window that currently owns it, and removes the caret from the screen if it
is visible. The DestroyCaret function checks the ownership of the caret and
destroys the caret only if a window in the current task owns it.

If the caret shape was previously a bitmap, DestroyCaret does not free the
bitmap.

This function has no parameters.


Return Value

None.


Comments

The caret is a shared resource. If a window has created a caret shape, it
destroys that shape before it loses the input focus or becomes inactive.


DestroyCursor
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  DestroyCursor(hCursor)

This function destroys a cursor that was previously created by the
CreateCursor function and frees any memory that the cursor occupied. It
should not be used to destroy any cursor that was not created with the
CreateCursor function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hCursor                           HCURSOR  Identifies the cursor to be
                                  destroyed. The cursor must not be in
                                  current use.


Return Value

The return value is nonzero if the function was successful. It is zero if
the function failed.


DestroyIcon
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  DestroyIcon(hIcon)

This function destroys an icon that was previously created by the CreateIcon
function and frees any memory that the icon occupied. It should not be used
to destroy any icon that was not created with the CreateIcon function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hIcon                             HICON  Identifies the icon to be
                                  destroyed. The icon must not be in
                                  current use.


Return Value

The return value is nonzero if the function was successful. It is zero if
the function failed.


DestroyMenu
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DestroyMenu(hMenu)

This function destroys the menu specified by the hMenu parameter and frees
any memory that the menu occupied.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu            HMENU  Identifies the menu to be destroyed.


Return Value

The return value specifies whether or not the specified menu is destroyed.
It is nonzero if the menu is destroyed. Otherwise, it is zero.


DestroyWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DestroyWindow(hWnd)

This function destroys the specified window. The DestroyWindow function
hides or permanently closes the window, sending the appropriate messages to
the window to deactivate it and remove the input focus. It also destroys the
window menu, flushes the application queue, destroys outstanding timers,
removes clipboard ownership, and breaks the clipboard-viewer chain, if the
window is at the top of the viewer chain. It sends WM_DESTROY and
WM_NCDESTROY messages to the window.

If the given window is the parent of any windows, these child windows are
automatically destroyed when the parent window is destroyed. DestroyWindow
destroys child windows first, and then the window itself.

DestroyWindow also destroys modeless dialog boxes created by the
CreateDialog function.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd             HWND  Identifies the window to be destroyed.


Return Value

The return value specifies whether or not the specified window is destroyed.
It is nonzero if the window is destroyed. Otherwise, it is zero.


DeviceCapabilities
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  DWORD  DeviceCapabilities(lpDeviceName, lpPort,
  nIndex, lpOutput, lpDevMode)

This function retrieves the capabilities of the printer device driver.

Parameter      Type/Description
────────────────────────────────────────────────────────────────────────────
lpDeviceName   LPSTR  Points to a
               null-terminated character
               string that contains the
               name of the printer device,
               such as "PCL/HP LaserJet."

lpPort         LPSTR  Points to a
               null-terminated character
               string that contains the
               name of the port to which
               the device is connected,
               such as LPT1:.

nIndex         WORD  Specifies the
               capabilities to query. It
               can be any one of the
               following values:

               DC_BINNAMES                   Copies a structure identical
                                             to that returned by the
                                             ENUMPAPERBINS escape. A
                                             printer driver does not need
                                             to support this index if it
                                             has only bins corresponding
                                             to predefined indexes, in
                                             which case no data is copied
                                             and the return value is 0. If
                                             the index is supported, the
                                             return value is the number of
                                             bins copied. If lpOutput is
                                             NULL, the return value is the
                                             number of bin entries
                                             required.

               DC_BINS                       Retrieves a list of available
                                             bins. The function copies the
                                             list to lpOutput as a WORD
                                             array. If lpOutput is NULL,
                                             the function returns the
                                             number of supported bins to
                                             allow the application the
                                             opportunity to allocate a
                                             buffer with the correct size.
                                             See the description of the
                                             dmDefaultSource field of the
                                             DEVMODE data structure for
                                             information on these values.
                                             An application can determine
                                             the name of device-specific
                                             bins by using the
                                             ENUMPAPERBINS escape.


╓┌───────────┌─────────────────┌─────────────────────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            Value             Meaning

            DC_DRIVER         Returns the printer driver version number.

            DC_DUPLEX         Returns the level of duplex support. The
                              function returns 1 if the printer is capable
                              of duplex printing. Otherwise, the return
                              value is zero.
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                              value is zero.

            DC_EXTRA          Returns the number of bytes required for the
                              device-specific portion of the DEVMODE data
                              structure for the printer driver.

            DC_FIELDS         Returns the dmFields field of the printer
                              driver's DEVMODE data structure. The
                              dmFields bitfield indicates which fields in
                              the device-independent portion of the
                              structure are supported by the printer
                              driver.

            DC_MAXEXTENT      Returns a POINT data structure containing
                              the maximum paper size that the
                              dmPaperLength and dmPaperWidth fields of the
                              printer driver's DEVMODE data structure can
                              specify.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────

            DC_MINEXTENT      Returns a POINT data structure containing
                              the minimum paper size that the
                              dmPaperLength and dmPaperWidth fields of the
                              printer driver's DEVMODE data structure can
                              specify.



╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            Value                           Meaning

            DC_PAPERS                       Retrieves a list of supported
                                            paper sizes. The function
                                            copies the list to lpOutput as
                                            a WORD array and returns the
                                            number of entries in the array.
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            number of entries in the array.
                                            If lpOutput is NULL, the
                                            function returns the number of
                                            supported paper sizes to allow
                                            the application the
                                            opportunity to allocate a
                                            buffer with the correct size.
                                            See the description of the
                                            dmPaperSize field of the
                                            DEVMODE data structure for
                                            information on these values.

            DC_PAPERSIZE                    Copies the dimensions of
                                            supported paper sizes in
                                            tenths of a millimeter to an
                                            array of POINT structures in
                                            lpOutput. This allows an
                                            application to obtain
                                            information about nonstandard
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            information about nonstandard
                                            paper sizes.

            DC_SIZE                         Returns the dmSize field of
                                            the printer driver's DEVMODE
                                            data structure.

            DC_VERSION                      Returns the specification
                                            version to which the printer
                                            driver conforms.

lpOutput    LPSTR  Points to an array of
            bytes. The actual format of
            the array depends on the
            setting of nIndex. If set to
            zero, DeviceCapabilities
            returns the number of bytes
            required for the output data.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────

lpDevMode   DEVMODE FAR *  Points to a
            DEVMODE data structure. If
            lpDevMode is NULL, this
            function retrieves the current
            default initialization values
            for the specified printer
            driver. Otherwise, the
            function retrieves the values
            contained in the structure to
            which lpDevMode points.




Return Value

The return value depends on the setting of the nIndex parameter; see the
description of that parameter for details.


Comments

This function is supplied by the printer driver. An application must include
the DRIVINIT.H file and call the LoadLibrary and GetProcAddress functions to
call the DeviceCapabilities function.


DeviceMode
────────────────────────────────────────────────────────────────────────────


Syntax

  void  DeviceMode(hWnd, hModule, lpDeviceName, lpOutput)

This function sets the current printing modes for the device identified by
the lpDestDevType by prompting for those modes using a dialog box. An
application calls the DeviceMode function to allow the user to change the
printing modes of the corresponding device. The function copies the mode
information to the environment block associated with the device and
maintained by GDI.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window that will
                                  own the dialog box.

hModule                           HANDLE  Identifies the printer-driver
                                  module. The application should retrieve
                                  this handle by calling either the
                                  GetModuleHandle or LoadLibrary function.

lpDeviceName                      LPSTR  Points to a null-terminated
                                  character string that specifies the name
                                  of the specific device to be supported
                                  (for example, Epson FX-80). The device
                                  name is the same as the name passed to
                                  the CreateDC function.

lpOutput                          LPSTR  Points to a null-terminated
                                  character string that specifies the DOS
                                  file or device name for the physical
                                  output medium (file or output port). The
                                  output name is the same as the name
                                  passed to the CreateDC function.



Return Value

None.


Comments

The DeviceMode function is actually part of the printer's device driver, and
not part of GDI. To call this function, the application must load the
printer device driver by calling LoadLibrary and retrieve the address of the
function by using the GetProcAddress function. The application can then use
the address to set up the printer.


DialogBox
────────────────────────────────────────────────────────────────────────────


Syntax

  int DialogBox(hInstance, lpTemplateName, hWndParent,
  lpDialogFunc)

This function creates a modal dialog box that has the size, style, and
controls specified by the dialog-box template given by the lpTemplateName
parameter. The hWndParent parameter identifies the application window that
owns the dialog box. The callback function pointed to by the lpDialogFunc
parameter processes any messages received by the dialog box.

The DialogBox function does not return control until the callback function
terminates the modal dialog box by calling the EndDialog function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpTemplateName                    LPSTR  Points to a character string that
                                  names the dialog-box template. The
                                  string must be a null-terminated
                                  character string.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. See the
                                  following "Comments" section for details.



Return Value

The return value specifies the value of the nResult parameter in the
EndDialog function that is used to terminate the dialog box. Values returned
by the application's dialog box are processed by Windows and are not
returned to the application. The return value is -1 if the function could
not create the dialog box.


Comments

The DialogBox function calls the GetDC function in order to obtain a
display-context. Problems will result if all the display contexts in the
Windows display-context cache have been retrieved by GetDC and DialogBox
attempts to access another display context.

A dialog box can contain up to 255 controls.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  int FAR PASCAL DialogFunc(hDlg, wMsg,
  wParam, lParam)
  HWND hDlg;
  WORD wMsg;
  WORD wParam;
  DWORD lParam;

DialogFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hDlg                              Identifies the dialog box that receives
                                  the message.

wMsg                              Specifies the message number.

wParam                            Specifies 16 bits of additional
                                  message-dependent information.

lParam                            Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The callback function should return nonzero if the function processes the
message and zero if it does not.


Comments

Although the callback function is similar to a window function, it must not
call the DefWindowProc function to process unwanted messages. Unwanted
messages are processed internally by the dialog-class window function.

The callback-function address, passed as the lpDialogFunc parameter, must be
created by using the MakeProcInstance function.


DialogBoxIndirect
────────────────────────────────────────────────────────────────────────────


Syntax

  int DialogBoxIndirect(hInstance, hDialogTemplate,
  hWndParent, lpDialogFunc)

This function creates an application's modal dialog box that has the size,
style, and controls specified by the dialog-box template associated with the
hDialogTemplate parameter. The hWndParent parameter identifies the
application window that owns the dialog box. The callback function pointed
to by lpDialogFunc processes any messages received by the dialog box.

The DialogBoxIndirect function does not return control until the callback
function terminates the modal dialog box by calling the EndDialog function.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

hDialogTemplate                   HANDLE  Identifies a block of global
                                  memory that contains a DLGTEMPLATE data
                                  structure.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. See the
                                  following "Comments" section for details.



Return Value

The return value specifies the value of the wResult parameter specified in
the EndDialog function that is used to terminate the dialog box. Values
returned by the application's dialog box are processed by Windows and are
not returned to the application. The return value is -1 if the function
could not create the dialog box.


Comments

A dialog box can contain up to 255 controls.

The callback function must use the Pascal calling convention and be declared
FAR.


Callback Function

  BOOL FAR PASCAL DialogFunc(hDlg, wMsg,
  wParam, lParam)
  HWND hDlg;
  WORD wMsg;
  WORD wParam;
  DWORD lParam;

DialogFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hDlg                              Identifies the dialog box that receives
                                  the message.

wMsg                              Specifies the message number.

wParam                            Specifies 16 bits of additional
                                  message-dependent information.

lParam                            Specifies 32 bits of additional
                                  message-dependent information.



Return Value

The callback function should return nonzero if the function processes the
message and zero if it does not.


Comments

Although the callback function is similar to a window function, it must not
call the DefWindowProc function to process unwanted messages. Unwanted
messages are processed internally by the dialog-class window function.

The callback-function address, passed as the lpDialogFunc parameter, must be
created by using the MakeProcInstance function.


DialogBoxIndirectParam
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  DialogBoxIndirectParam(hInstance, hDialogTemplate,
  hWndParent, lpDialogFunc, dwInitParam)

This function creates an application's modal dialog box, sends a
WM_INITDIALOG message to the dialog function before displaying the dialog
box and passes dwInitParam as the message lParam. This message allows the
dialog function to initialize the dialog-box controls.

For more information on creating an application modal dialog box, see the
description of the DialogBoxIndirect function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

hDialogTemplate                   HANDLE  Identifies a block of global
                                  memory that contains a DLGTEMPLATE data
                                  structure.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. For
                                  details, see the "Comments" section in
                                  the description of the DialogBoxIndirect
                                  function.

dwInitParam                       DWORD  Is a 32-bit value which
                                  DialogBoxIndirectParam passes to the
                                  dialog function when it creates the
                                  dialog box.



Return Value

The return value specifies the value of the wResult parameter specified in
the EndDialog function that is used to terminate the dialog box. Values
returned by the application's dialog box are processed by Windows and are
not returned to the application. The return value is -1 if the function
could not create the dialog box.


DialogBoxParam
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  DialogBoxParam(hInstance, lpTemplateName,
  hWndParent, lpDialogFunc, dwInitParam)

This function creates a modal dialog box, sends a WM_INITDIALOG message to
the dialog function before displaying the dialog box, and passes dwInitParam
as the message lParam. This message allows the dialog function to initialize
the dialog-box controls.

For more information on creating a modal dialog box, see the description of
the DialogBox function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies an instance of the
                                  module whose executable file contains
                                  the dialog-box template.

lpTemplateName                    LPSTR  Points to a character string that
                                  names the dialog-box template. The
                                  string must be a null-terminated
                                  character string.

hWndParent                        HWND  Identifies the window that owns
                                  the dialog box.

lpDialogFunc                      FARPROC  Is the procedure-instance
                                  address of the dialog function. For
                                  details, see the "Comments" section of
                                  the description of the DialogBox
                                  function.

dwInitParam                       DWORD  Is a 32-bit value which
                                  DialogBoxParam passes to the dialog
                                  function when it creates the dialog box.



Return Value

The return value specifies the value of the nResult parameter in the
EndDialog function that is used to terminate the dialog box. Values returned
by the application's dialog box are processed by Windows and are not
returned to the application. The return value is -1 if the function could
not create the dialog box.


DispatchMessage
────────────────────────────────────────────────────────────────────────────


Syntax

  LONG  DispatchMessage(lpMsg)

This function passes the message in the MSG structure pointed to by the
lpMsg parameter to the window function of the specified window.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpMsg                             LPMSG  Points to an MSG data structure
                                  that contains message information from
                                  the Windows application queue.

                                  The structure must contain valid message
                                  values. If lpMsg points to a WM_TIMER
                                  message and the lParam parameter of the
                                  WM_TIMER message is not NULL, then the
                                  lParam parameter is the address of a
                                  function that is called instead of the
                                  window function.



Return Value

The return value specifies the value returned by the window function. Its
meaning depends on the message being dispatched, but generally the return
value is ignored.


DlgDirList
────────────────────────────────────────────────────────────────────────────


Syntax

  int DlgDirList(hDlg, lpPathSpec, nIDListBox,
  nIDStaticPath, wFiletype)

This function fills a list-box control with a file or directory listing. It
fills the list box specified by the nIDListBox parameter with the names of
all files matching the pathname given by the lpPathSpec parameter.

The DlgDirList function shows subdirectories enclosed in square brackets ([
]), and shows drives in the form [-x-], where x is the drive letter.

The lpPathSpec parameter has the following form:

  «drive:» « «\»directory«\directory»...\»
  «filename»

In this example, drive is a drive letter, directory is a valid directory
name, and filename is a valid filename that must contain at least one
wildcard character. The wildcard characters are a question mark (?), meaning
"match any character," and an asterisk (*), meaning "match any number of
characters."

If the lpPathSpec parameter includes a drive and/or directory name, the
current drive and directory are changed to the designated drive and
directory before the list box is filled. The text control identified by the
nIDStaticPath parameter is also updated with the new drive and/or directory
name.

After the list box is filled, lpPathSpec is updated by removing the drive
and/or directory portion of the pathname.

DlgDirList sends LB_RESETCONTENT and LB_DIR messages to the list box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the list box.

lpPathSpec                        LPSTR  Points to a pathname string. The
                                  string must be a null-terminated
                                  character string.

nIDListBox                        int  Specifies the identifier of a
                                  list-box control. If nIDListBox is zero,
                                  DlgDirList assumes that no list box
                                  exists and does not attempt to fill it.

nIDStaticPath                     int  Specifies the identifier of the
                                  static-text control used for displaying
                                  the current drive and directory. If
                                  nIDStaticPath is zero, DlgDirList
                                  assumes that no such text control is
                                  present.

wFiletype                         WORD  Specifies DOS file attributes of
                                  the files to be displayed. It can be any
                                  combination of the values given in Table
                                  .6, "DOS File Attributes." Values can be
                                  combined by using the bitwise OR
                                  operator.



Return Value

The return value specifies the outcome of the function. It is nonzero if a
listing was made, even an empty listing. A zero return value implies that
the input string did not contain a valid search path.

The wFiletype parameter specifies the DOS attributes of the files to be
listed. Table 4.6 describes these attributes.

Table   DOS File Attributes

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
Attribute Value   Meaning
────────────────────────────────────────────────────────────────────────────
0x0000            Read/write data files with no additional attributes
0x0001            Read-only files
0x0002            Hidden files
0x0004            System files
0x0010            Subdirectories
0x0020            Archives
0x2000            LB_DIR flag(1)
0x4000            Drives
0x8000            Exclusive bit(2)
────────────────────────────────────────────────────────────────────────────


(1)  If the LB_DIR flag is set, Windows places the messages generated by
DlgDirList in the application's queue; otherwise they are sent directly to
the dialog function.
(2)  If the exclusive bit is set, only files of the specified type are
listed. Otherwise, files of the specified type are listed in addition to
normal files.



DlgDirListComboBox
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int DlgDirListComboBox(hDlg, lpPathSpec, nIDComboBox,
  nIDStaticPath, wFiletype)

This function fills the list box of a combo-box control with a file or
directory listing. It fills the list box of the combo box specified by the
nIDComboBox parameter with the names of all files matching the pathname
given by the lpPathSpec parameter.

The DlgDirListComboBox function shows subdirectories enclosed in square
brackets ([ ]), and shows drives in the form [-x-], where x is the drive
letter.

The lpPathSpec parameter has the following form:

  «drive:» « «\»directory«\directory»...\»
  «filename»

In this example, drive is a drive letter, directory is a valid directory
name, and filename is a valid filename that must contain at least one
wildcard character. The wildcard characters are a question mark (?), meaning
"match any character," and an asterisk (*), meaning "match any number of
characters."

If the lpPathSpec parameter includes a drive and/or directory name, the
current drive and directory are changed to the designated drive and
directory before the list box is filled. The text control identified by the
nIDStaticPath parameter is also updated with the new drive and/or directory
name.

After the combo-box list box is filled, lpPathSpec is updated by removing
the drive and/or directory portion of the pathname.

DlgDirListComboBox sends CB_RESETCONTENT and CB_DIR messages to the combo
box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the combo box.

lpPathSpec                        LPSTR  Points to a pathname string. The
                                  string must be a null-terminated
                                  character string.

nIDComboBox                       int  Specifies the identifier of a
                                  combo-box control in a dialog box. If
                                  nIDComboBox is zero, DlgDirListComboBox
                                  assumes that no combo box exists and
                                  does not attempt to fill it.

nIDStaticPath                     int  Specifies the identifier of the
                                  static-text control used for displaying
                                  the current drive and directory. If
                                  nIDStaticPath is zero,
                                  DlgDirListComboBox assumes that no such
                                  text control is present.

wFiletype                         WORD  Specifies DOS file attributes of
                                  the files to be displayed. It can be any
                                  combination of the values given in Table
                                  .6, "DOS File Attributes." Refer to the
                                  description of the DlgDirList function
                                  for this table. Values can be combined
                                  by using the bitwise OR operator.



Return Value

The return value specifies the outcome of the function. It is nonzero if a
listing was made, even an empty listing. A zero return value implies that
the input string did not contain a valid search path.


DlgDirSelect
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DlgDirSelect(hDlg, lpString, nIDListBox)

This function retrieves the current selection from a list box. It assumes
that the list box has been filled by the DlgDirList function and that the
selection is a drive letter, a file, or a directory name.

The DlgDirSelect function copies the selection to the buffer given by the
lpString parameter. If the current selection is a directory name or drive
letter, DlgDirSelect removes the enclosing square brackets (and hyphens, for
drive letters) so that the name or letter is ready to be inserted into a new
pathname. If there is no selection, lpString does not change.

DlgDirSelect sends LB_GETCURSEL and LB_GETTEXT messages to the list box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the list box.

lpString                          LPSTR  Points to a buffer that is to
                                  receive the selected pathname.

nIDListBox                        int  Specifies the integer ID of a
                                  list-box control in the dialog box.



Return Value

The return value specifies the status of the current list-box selection. It
is nonzero if the current selection is a directory name. Otherwise, it is
zero.


Comments

The DlgDirSelect function does not allow more than one filename to be
returned from a list box.

The list box must not be a multiple-selection list box. If it is, this
function will not return a zero value and lpString will remain unchanged.


DlgDirSelectComboBox
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL DlgDirSelectComboBox(hDlg, lpString, nIDComboBox)

This function retrieves the current selection from the list box of a combo
box. It assumes that the list box has been filled by the DlgDirListComboBox
function and that the selection is a drive letter, a file, or a directory
name.

The DlgDirSelectComboBox function copies the selection to the buffer given
by the lpString parameter. If the current selection is a directory name or
drive letter, DlgDirSelectComboBox removes the enclosing square brackets
(and hyphens, for drive letters) so that the name or letter is ready to be
inserted into a new pathname. If there is no selection, lpString does not
change.

DlgDirSelectComboBox sends CB_GETCURSEL and CB_GETLBTEXT messages to the
combo box.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the combo box.

lpString                          LPSTR  Points to a buffer that is to
                                  receive the selected pathname.

nIDComboBox                       int  Specifies the integer ID of the
                                  combo-box control in the dialog box.



Return Value

The return value specifies the status of the current combo-box selection. It
is nonzero if the current selection is a directory name. Otherwise, it is
zero.


Comments

The DlgDirSelectComboBox function does not allow more than one filename to
be returned from a combo box.


DOS3Call
────────────────────────────────────────────────────────────────────────────

 Version 3.0 
This function allows an application to issue a DOS function-request
interrupt 21H. An application can use this function instead of a directly
coded DOS 21H interrupt. The DOS3Call function executes somewhat faster than
the equivalent DOS 21H software interrupt under Windows.

An application can call this function only from an assembly-language
routine. It is exported from KERNEL.EXE and is not defined in any Windows
include files.

To use this function call, an application should declare it in an
assembly-language program as shown:

  extrn    DOS3Call    :far

If the application includes CMACROS.INC, the application declares it as
shown:

  extrnFP  Dos3Call

Before calling DOS3Call, all registers must be set as for an actual INT 21H.
All registers at the function's exit are the same as for the corresponding
INT 21H function.

This function has no parameters and returns the registers of the DOS
function.

The following is an example of using DOS3Call:

  extrn DOS3Call : far
    .
    .
    .
   ; set registers
   mov ah, DOSFUNC
   cCall DOS3Call


DPtoLP
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DPtoLP(hDC, lpPoints, nCount)

This function converts device points into logical points. The function maps
the coordinates of each point specified by the lpPoints parameter from the
device coordinate system into GDI's logical coordinate system. The
conversion depends on the current mapping mode and the settings of the
origins and extents for the device's window and viewport.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

lpPoints                          LPPOINT  Points to an array of points.
                                  Each point must be a POINT data
                                  structure.

nCount                            int  Specifies the number of points in
                                  the array.



Return Value

The return value specifies whether the conversion has taken place. It is
nonzero if all points are converted. Otherwise, it is zero.


DrawFocusRect
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  DrawFocusRect(hDC, lpRect)

This function draws a rectangle in the style used to indicate focus.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

lpRect                            LPRECT  Points to a RECT data structure
                                  that specifies the coordinates of the
                                  rectangle to be drawn.



Return Value

None.


Comments

Since this is an XOR function, calling this function a second time with the
same rectangle removes the rectangle from the display.

The rectangle drawn by this function cannot be scrolled. To scroll an area
containing a rectangle drawn by this function, call DrawFocusRect to remove
the rectangle from the display, scroll the area, and then call DrawFocusRect
to draw the rectangle in the new position.


DrawIcon
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL DrawIcon(hDC, X, Y, hIcon)

This function draws an icon on the specified device. The DrawIcon function
places the icon's upper-left corner at the location specified by the X and Y
parameters. The location is subject to the current mapping mode of the
device context.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context for a
                                  window.

X                                 int  Specifies the logical x-coordinate
                                  of the upper-left corner of the icon.

Y                                 int  Specifies the logical y-coordinate
                                  of the upper-left corner of the icon.

hIcon                             HICON  Identifies the icon to be drawn.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. Otherwise, it is zero.


Comments

The icon resource must have been previously loaded by using the LoadIcon
function. The MM_TEXT mapping mode must be selected prior to using this
function.


DrawMenuBar
────────────────────────────────────────────────────────────────────────────


Syntax

  void  DrawMenuBar(hWnd)

This function redraws the menu bar. If a menu bar is changed after Windows
has created the window, this function should be called to draw the changed
menu bar.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd         HWND  Identifies the window whose menu needs redrawing.


Return Value

None.


DrawText
────────────────────────────────────────────────────────────────────────────


Syntax

  int  DrawText(hDC, lpString, nCount, lpRect, wFormat)

This function draws formatted text in the rectangle specified by the lpRect
parameter. It formats text by expanding tabs into appropriate spaces,
justifying text to the left, right, or center of the given rectangle, and
breaking text into lines that fit within the given rectangle. The type of
formatting is specified by the wFormat parameter.

The DrawText function uses the device context's selected font, text color,
and background color to draw the text. Unless the DT_NOCLIP format is used,
DrawText clips the text so that the text does not appear outside the given
rectangle. All formatting is assumed to have multiple lines unless the
DT_SINGLELINE format is given.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

lpString                          LPSTR  Points to the string to be drawn.
                                  If the nCount parameter is -1, the
                                  string must be null-terminated.

nCount                            int  Specifies the number of bytes in
                                  the string. If nCount is -1, then
                                  lpString is assumed to be a long pointer
                                  to a null-terminated string and DrawText
                                  computes the character count
                                  automatically.

lpRect                            LPRECT  Points to a RECT data structure
                                  that contains the rectangle (in logical
                                  coordinates) in which the text is to be
                                  formatted.

wFormat                           WORD  Specifies the method of formatting
                                  the text. It can be a combination of the
                                  values given in Table .7, "DrawText
                                  Formats."



Return Value

The return value specifies the height of the text.


Comments

If the selected font is too large for the specified rectangle, the DrawText
function does not attempt to substitute a smaller font.

Table 4.7 lists the values for the wFormat parameter. These values can be
combined by using the bitwise OR operator. Note that the DT_CALCRECT,
DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be
used with the DT_TABSTOP value:

Table   DrawText Formats

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
DT_BOTTOM                         Specifies bottom-justified text. This
                                  value must be combined with
                                  DT_SINGLELINE.

DT_CALCRECT                       Determines the width and height of the
                                  rectangle. If there are multiple lines
                                  of text, DrawText will use the width of
                                  the rectangle pointed to by the lpRect
                                  parameter and extend the base of the
                                  rectangle to bound the last line of text.
                                  If there is only one line of text,
                                  DrawText will modify the right side of
                                  the rectangle so that it bounds the last
                                  character in the line. In either case,
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  character in the line. In either case,
                                  DrawText returns the height of the
                                  formatted text but does not draw the
                                  text.

DT_CENTER                         Centers text horizontally.

DT_EXPANDTABS                     Expands tab characters. The default
                                  number of characters per tab is eight.

DT_EXTERNALLEADING                Includes the font external leading in
                                  line height. Normally, external leading
                                  is not included in the height of a line
                                  of text.

DT_LEFT                           Aligns text flush-left.

DT_NOCLIP                         Draws without clipping. DrawText is
                                  somewhat faster when DT_NOCLIP is used.
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  somewhat faster when DT_NOCLIP is used.



Table   DrawText Formats (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
DT_NOPREFIX                       Turns off processing of prefix
                                  characters. Normally, DrawText
                                  interprets the mnemonic-prefix character
                                  "&" as a directive to underscore the
                                  character that follows, and the
                                  mnemonic-prefix characters "&&" as a
                                  directive to print a single "&". By
                                  specifying DT_NOPREFIX, this processing
                                  is turned off.

Value                             Meaning
────────────────────────────────────────────────────────────────────────────

DT_RIGHT                          Aligns text flush-right.

DT_SINGLELINE                     Specifies single line only. Carriage
                                  returns and linefeeds do not break the
                                  line.

DT_TABSTOP                        Sets tab stops. The high-order byte of
                                  the wFormat parameter is the number of
                                  characters for each tab. The default
                                  number of characters per tab is eight.

DT_TOP                            Specifies top-justified text (single
                                  line only).

DT_VCENTER                        Specifies vertically centered text
                                  (single line only).

DT_WORDBREAK                      Specifies word breaking. Lines are
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
DT_WORDBREAK                      Specifies word breaking. Lines are
                                  automatically broken between words if a
                                  word would extend past the edge of the
                                  rectangle specified by the lpRect
                                  parameter. A carriage return/line
                                  sequence will also break the line.

────────────────────────────────────────────────────────────────────────────







Ellipse
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL Ellipse(hDC, X1, Y1, X2, Y2)

This function draws an ellipse. The center of the ellipse is the center of
the bounding rectangle specified by the X1, Y1, X2, and Y2 parameters. The
ellipse border is drawn with the current pen, and the interior is filled
with the current brush.

If the bounding rectangle is empty, nothing is drawn.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X1                                int  Specifies the logical x-coordinate
                                  of the upper-left corner of the bounding
                                  rectangle.

Y1                                int  Specifies the logical y-coordinate
                                  of the upper-left corner of the bounding
                                  rectangle.

X2                                int  Specifies the logical x-coordinate
                                  of the lower-right corner of the
                                  bounding rectangle.

Y2                                int  Specifies the logical y-coordinate
                                  of the lower-right corner of the
                                  bounding rectangle.



Return Value

The return value specifies whether the ellipse is drawn. It is nonzero if
the ellipse is drawn. Otherwise, it is zero.


Comments

The width of the rectangle, specified by the absolute value of X2 - X1, must
not exceed 32,767 units. This limit applies to the height of the rectangle
as well.

The current position is neither used nor updated by this function.


EmptyClipboard
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EmptyClipboard( )

This function empties the clipboard and frees handles to data in the
clipboard. It then assigns ownership of the clipboard to the window that
currently has the clipboard open.

This function has no parameters.


Return Value

The return value specifies the status of the clipboard. It is nonzero if the
clipboard is emptied. It is zero if an error occurs.


Comments

The clipboard must be open when the EmptyClipboard function is called.


EnableHardwareInput
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnableHardwareInput(bEnableInput)

This function disables mouse and keyboard input. The input is saved if the
bEnableInput parameter is TRUE and discarded if it is FALSE.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
bEnableInput                      BOOL  Specifies that the function should
                                  save input if the bEnableInput parameter
                                  is set to a nonzero value; specifies
                                  that the function should discard input
                                  if the bEnableInput parameter is set to
                                  zero.



Return Value

The return value specifies whether mouse and keyboard input is disabled. It
is nonzero if input was previously enabled. Otherwise, it is zero. The
default return value is nonzero (TRUE).


EnableMenuItem
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnableMenuItem(hMenu, wIDEnableItem, wEnable)

This function enables, disables, or grays a menu item.

╓┌───────────────┌─────────────────────────────┌─────────────────────────────╖
Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu           HMENU  Specifies the menu.

wIDEnableItem   WORD  Specifies the menu
                item to be checked. The
                wIDEnableItem parameter can
                specify pop-up menu items as
                well as menu items.

wEnable         WORD  Specifies the action
                to take. It can be a
Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
                to take. It can be a
                combination of MF_DISABLED,
                MF_ENABLED, or MF_GRAYED,
                with MF_BYCOMMAND or
                MF_BYPOSITION. These values
                can be combined by using the
                bitwise OR operator. These
                values have the following
                meanings:

                Value                         Meaning

                MF_BYCOMMAND                  Specifies that the
                                              wIDEnableItem  parameter
                                              gives the menu item ID
                                              (MF_BYCOMMAND is the default
                                              ID).

                MF_BYPOSITION                 Specifies that the
Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
                MF_BYPOSITION                 Specifies that the
                                              wIDEnableItem parameter
                                              gives the position of the
                                              menu item (the first item is
                                              at position zero).

                MF_DISABLED                   Menu item is disabled.

                MF_ENABLED                    Menu item is enabled.

                MF_GRAYED                     Menu item is grayed.




Return Value

The return value specifies the previous state of the menu item. The return
value is -1 if the menu item does not exist.


Comments

To disable or enable input to a menu bar, see the WM_SYSCOMMAND message.


EnableWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnableWindow(hWnd, bEnable)

This function enables or disables mouse and keyboard input to the specified
window or control. When input is disabled, input such as mouse clicks and
key presses are ignored by the window. When input is enabled, all input is
processed.

The EnableWindow function enables mouse and keyboard input to a window if
the bEnable parameter is nonzero, and disables it if bEnable is zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window to be
                                  enabled or disabled.

bEnable                           BOOL  Specifies whether the given window
                                  is to be enabled or disabled.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
window is enabled or disabled as specified. It is zero if an error occurs.


Comments

A window must be enabled before it can be activated. For example, if an
application is displaying a modeless dialog box and has disabled its main
window, the main window must be enabled before the dialog box is destroyed.
Otherwise, another window will get the input focus and be activated. If a
child window is disabled, it is ignored when Windows tries to determine
which window should get mouse messages.

Initially, all windows are enabled by default. EnableWindow must be used to
disable a window explicitly.


EndDeferWindowPos
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  EndDeferWindowPos(hWinPosInfo)

This function simultaneously updates the position and size of one or more
windows in a single screen-refresh cycle. The hWinPosInfo parameter
identifies a multiple window-position data structure that contains the
update information for the windows. The DeferWindowPos function stores the
update information in the data structure; the BeginDeferWindowPos function
creates the initial data structure used by these functions.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWinPosInfo                       HANDLE  Identifies a multiple
                                  window-position data structure that
                                  contains size and position information
                                  for one or more windows. This structure
                                  is returned by the BeginDeferWindowPos
                                  function or the most recent call to the
                                  DeferWindowPos function.



Return Value

None.


EndDialog
────────────────────────────────────────────────────────────────────────────


Syntax

  void  EndDialog(hDlg, nResult)

This function terminates a modal dialog box and returns the given result to
the DialogBox function that created the dialog box. The EndDialog function
is required to complete processing whenever the DialogBox function is used
to create a modal dialog box. The function must be used in the dialog
function of the modal dialog box and should not be used for any other
purpose.

The dialog function can call EndDialog at any time, even during the
processing of the WM_INITDIALOG message. If called during the WM_INITDIALOG
message, the dialog box is terminated before it is shown or before the input
focus is set.

EndDialog does not terminate the dialog box immediately. Instead, it sets a
flag that directs the dialog box to terminate as soon as the dialog function
ends. The EndDialog function returns to the dialog function, so the dialog
function must return control to Windows.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box to be
                                  destroyed.

nResult                           int  Specifies the value to be returned
                                  from the dialog box to the DialogBox
                                  function that created it.



Return Value

None.


EndPaint
────────────────────────────────────────────────────────────────────────────


Syntax

  void  EndPaint(hWnd, lpPaint)

This function marks the end of painting in the given window. The EndPaint
function is required for each call to the BeginPaint function, but only
after painting is complete.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window that is
                                  repainted.

lpPaint                           LPPAINTSTRUCT  Points to a PAINTSTRUCT
                                  data structure that contains the
                                  painting information retrieved by the
                                  BeginPaint function.



Return Value

None.


Comments

If the caret was hidden by the BeginPaint function, EndPaint restores the
caret to the screen.


EnumChildWindows
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnumChildWindows(hWndParent, lpEnumFunc, lParam)

This function enumerates the child windows that belong to the specified
parent window by passing the handle of each child window, in turn, to the
application-supplied callback function pointed to by the lpEnumFunc
parameter.

The EnumChildWindows function continues to enumerate windows until the
called function returns zero or until the last child window has been
enumerated.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWndParent                        HWND  Identifies the parent window whose
                                  child windows are to be enumerated.

lpEnumFunc                        FARPROC  Is the procedure-instance
                                  address of the callback function.

lParam                            DWORD  Specifies the value to be passed
                                  to the callback function for the
                                  application's use.



Return Value

The return value specifies nonzero if all child windows have been
enumerated. Otherwise, it is zero.


Comments

This function does not enumerate pop-up windows that belong to the
hWndParent parameter.

The address passed as the lpEnumFunc parameter must be created by using the
MakeProcInstance function.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  BOOL  FAR PASCAL EnumFunc(hWnd, lParam)
  HWND hWnd;
  DWORD lParam;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hWnd                              Identifies the window handle.

lParam                            Specifies the long parameter argument of
                                  the EnumChildWindows function.



Return Value

The callback function should return a nonzero value to continue enumeration;
it should return zero to stop enumeration.


EnumClipboardFormats
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  EnumClipboardFormats(wFormat)

This function enumerates the formats found in a list of available formats
that belong to the clipboard. On each call to this function, the wFormat
parameter specifies a known available format, and the function returns the
format that appears next in the list. The first format in the list can be
retrieved by setting wFormat to zero.

Parameter            Type/Description
────────────────────────────────────────────────────────────────────────────
wFormat              WORD  Specifies a known format.


Return Value

The return value specifies the next known clipboard data format. It is zero
if wFormat specifies the last format in the list of available formats. It is
zero if the clipboard is not open.


Comments

Before it enumerates the formats by using the EnumClipboardFormats function,
an application must open the clipboard by using the OpenClipboard function.


The order that an application uses for putting alternative formats for the
same data into the clipboard is the same order that the enumerator uses when
returning them to the pasting application. The pasting application should
use the first format enumerated that it can handle. This gives the donor a
chance to recommend formats that involve the least loss of data.


EnumFonts
────────────────────────────────────────────────────────────────────────────


Syntax

  int  EnumFonts(hDC, lpFacename, lpFontFunc, lpData)

This function enumerates the fonts available on a given device. For each
font having the typeface name specified by the lpFacename parameter, the
EnumFonts function retrieves information about that font and passes it to
the function pointed to by the lpFontFunc parameter. The
application-supplied callback function can process the font information as
desired. Enumeration continues until there are no more fonts or the callback
function returns zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

lpFacename                        LPSTR  Points to a null-terminated
                                  character string that specifies the
                                  typeface name of the desired fonts. If
                                  lpFacename is NULL, EnumFonts randomly
                                  selects and enumerates one font of each
                                  available typeface.

lpFontFunc                        FARPROC  Is the procedure-instance
                                  address of the callback function. See
                                  the following "Comments" section for
                                  details.

lpData                            LPSTR  Points to the
                                  application-supplied data. The data is
                                  passed to the callback function along
                                  with the font information.



Return Value

The return value specifies the last value returned by the callback function.
Its meaning is user-defined.


Comments

The address passed as the lpFontFunc parameter must be created by using the
MakeProcInstance function.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  int  FAR PASCAL FontFunc(lpLogFont, lpTextMetrics,
  nFontType, lpData)
  LPLOGFONT lpLogFont;
  LPTEXTMETRICS lpTextMetrics;
  short nFontType;
  LPSTR lpData;

FontFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
lpLogFont                         Points to a LOGFONT data structure that
                                  contains information about the logical
                                  attributes of the font.

lpTextMetrics                     Points to a TEXTMETRIC data structure
                                  that contains information about the
                                  physical attributes of the font.

nFontType                         Specifies the type of the font.

lpData                            Points to the application-supplied data
                                  passed by EnumFonts.



Return Value

The return value can be any integer.


Comments

The AND (&) operator can be used with the RASTER_FONTTYPE and
DEVICE_FONTTYPE constants to determine the font type. The RASTER_FONTTYPE
bit of the FontType parameter specifies whether the font is a raster or
vector font. If the bit is one, the font is a raster font; if zero, it is a
vector font. The DEVICE_FONTTYPE bit of FontType specifies whether the font
is a device- or GDI-based font. If the bit is one, the font is a
device-based font; if zero, it is a GDI-based font.

If the device is capable of text transformations (scaling, italicizing, and
so on) only the base font will be enumerated. The user must inquire into the
device's text-transformation abilities to determine which additional fonts
are available directly from the device. GDI can simulate the bold, italic,
underlined, and strikeout attributes for any GDI-based font.

EnumFonts only enumerates fonts from the GDI internal table. This does not
include fonts that are generated by a device, such as fonts that are
transformations of fonts from the internal table. The GetDeviceCaps function
can be used to determine which transformations a device can perform. This
information is available by using the TEXTCAPS index.

GDI can scale GDI-based raster fonts by one to five horizontally and one to
eight vertically, unless PROOF_QUALITY is being used.


EnumMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnumMetaFile(hDC, hMF, lpCallbackFunc, lpClientData)

This function enumerates the GDI calls within the metafile identified by the
hMF parameter. The EnumMetaFile function retrieves each GDI call within the
metafile and passes it to the function pointed to by the lpCallbackFunc
parameter. This callback function, an application-supplied function, can
process each GDI call as desired. Enumeration continues until there are no
more GDI calls or the callback function returns zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context
                                  associated with the metafile.

hMF                               LOCALHANDLE  Identifies the metafile.

lpCallbackFunc                    FARPROC  Is the procedure-instance
                                  callback function. See the following
                                  "Comments" section for details.

lpClientData                      BYTE FAR *  Points to the
                                  callback-function data.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
callback function enumerates all the GDI calls in a metafile; otherwise, it
returns zero.


Comments

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  int  FAR PASCAL EnumFunc(hDC, lpHTable,
  lpMFR, nObj, lpClientData)
  HDC hDC;
  LPHANDLETABLE lpHTable;
  LPMETARECORD lpMFR;
  int nObj;
  BYTE FAR * lpClientData;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hDC                               Identifies the special device context
                                  that contains the metafile.

lpHTable                          Points to a table of handles associated
                                  with the objects (pens, brushes, and so
                                  on) in the metafile.

lpMFR                             Points to a metafile record contained in
                                  the metafile.

nObj                              Specifies the number of objects with
                                  associated handles in the handle table.

lpClientData                      Points to the application-supplied data.



Return Value

The function can carry out any desired task. It must return a nonzero value
to continue enumeration, or a zero value to stop it.


EnumObjects
────────────────────────────────────────────────────────────────────────────


Syntax

  int  EnumObjects(hDC, nObjectType, lpObjectFunc, lpData)

This function enumerates the pens and brushes available on a device. For
each object that belongs to the given style, the callback function is called
with the information for that object. The callback function is called until
there are no more objects or the callback function returns zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

nObjectType                       int  Specifies the object type. It can
                                  be one of the following values:

                                  OBJ_BRUSH
                                  OBJ_PEN

lpObjectFunc                      FARPROC  Is the procedure-instance
                                  address of the application-supplied
                                  callback function. See the following
                                  "Comments" section for details.

lpData                            LPSTR  Points to the
                                  application-supplied data. The data is
                                  passed to the callback function along
                                  with the object information.



Return Value

The return value specifies the last value returned by the callback function.
Its meaning is user-defined.


Comments

The address passed as the lpObjectFunc parameter must be created by using
the MakeProcInstance function.

The callback function must use the Pascal calling convention and must be
declared FAR.


Callback Function

  int FAR PASCAL ObjectFunc(lpLogObject, lpData)
  char FAR * lpLogObject;
  char FAR * lpData;

ObjectFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
lpLogObject                       Points to a LOGPEN or LOGBRUSH data
                                  structure that contains information
                                  about the logical attributes of the
                                  object.

lpData                            Points to the application-supplied data
                                  passed to the EnumObjects function.



EnumProps
────────────────────────────────────────────────────────────────────────────


Syntax

  int  EnumProps(hWnd, lpEnumFunc)

This function enumerates all entries in the property list of the specified
window. It enumerates the entries by passing them, one by one, to the
callback function specified by lpEnumFunc. EnumProps continues until the
last entry is enumerated or the callback function returns zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window whose
                                  property list is to be enumerated.

lpEnumFunc                        FARPROC  Is the procedure-instance
                                  address of the callback function. See
                                  the following "Comments" section for
                                  details.



Return Value

The return value specifies the last value returned by the callback function.
It is -1 if the function did not find a property for enumeration.


Comments

An application can remove only those properties which it has added. It
should not remove properties added by other applications or by Windows
itself.

The following restrictions apply to the callback function:


  1.  The callback function must not yield control or do anything that might
      yield control to other tasks.

  2.  The callback function can call the RemoveProp function. However, the
      RemoveProp function can remove only the property passed to the
      callback function through the callback function's parameters.

  3.  A callback function should not attempt to add properties.


The address passed in the lpEnumFunc parameter must be created by using the
MakeProcInstance function.


Fixed Data Segments

The callback function must use the Pascal calling convention and must be
declared FAR. In applications and dynamic libraries with fixed data segments
and in dynamic libraries with moveable data segments that do not contain a
stack, the callback function must have the form shown below.


Callback Function

  int  FAR PASCAL EnumFunc(hWnd, lpString, hData)
  HWND hWnd;
  LPSTR lpString;
  HANDLE hData;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hWnd                              Identifies a handle to the window that
                                  contains the property list.

lpString                          Points to the null-terminated character
                                  string associated with the data handle
                                  when the application called the SetProp
                                  function to set the property. If the
                                  application passed an atom instead of a
                                  string to the SetProp function, the
                                  lpString parameter contains the atom in
                                  its low-order word, and the high-order
                                  word is zero.

hData                             Identifies the data handle.



Return Value

The callback function can carry out any desired task. It must return a
nonzero value to continue enumeration, or a zero value to stop it.


Moveable Data Segments

The callback function must use the Pascal calling convention and must be
declared FAR. In applications with moveable data segments and in dynamic
libraries whose moveable data segments also contain a stack, the callback
function must have the form shown below.


Callback Function

  int  FAR PASCAL EnumFunc(hWnd, nDummy,
  pString, hData)
  HWND hWnd;
  WORD nDummy;
  PSTR pString;
  HANDLE hData;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hWnd                              Identifies a handle to the window that
                                  contains the property list.

nDummy                            Specifies a dummy parameter.

pString                           Points to the null-terminated character
                                  string associated with the data handle
                                  when the application called the SetProp
                                  function to set the property. If the
                                  application passed an atom instead of a
                                  string to the SetProp function, the
                                  pString parameter contains the atom.

hData                             Identifies the data handle.



Return Value

The callback function can carry out any desired task. It should return a
nonzero value to continue enumeration, or a zero value to stop it.


Comments

The alternate form above is required since movement of the data will
invalidate any long pointer to a variable on the stack, such as the lpString
parameter. The data segment typically moves if the callback function
allocates more space in the local heap than is currently available.


EnumTaskWindows
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EnumTaskWindows(hTask, lpEnumFunc, lParam)

This function enumerates all windows associated with the hTask parameter,
which is returned by the GetCurrentTask function. (A task is any program
that executes as an independent unit. All applications are executed as tasks
and each instance of an application is a task.) The enumeration terminates
when the callback function, pointed to by lpEnumFunc, returns FALSE.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hTask                             HANDLE  Identifies the specified task.
                                  The GetCurrentTask function returns this
                                  handle.

lpEnumFunc                        FARPROC  Is the procedure-instance
                                  address of the window's callback
                                  function.

lParam                            DWORD  Specifies the 32-bit value that
                                  contains additional parameters that are
                                  sent to the callback function pointed to
                                  by lpEnumFunc.



Return Value

The return value specifies the outcome of the function. It is nonzero if all
the windows associated with a particular task are enumerated. Otherwise, it
is zero.


Comments

The callback function must use the Pascal calling convention and must be
declared FAR. The callback function must have the following form:


Callback Function

  BOOL  FAR PASCAL EnumFunc(hWnd, lParam)
  HWND hWnd;
  DWORD lParam;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter                         Description
────────────────────────────────────────────────────────────────────────────
hWnd                              Identifies a window associated with the
                                  current task.

lParam                            Specifies the same argument that was
                                  passed to the EnumTaskWindows function.



Return Value

The callback function can carry out any desired task. It must return a
nonzero value to continue enumeration, or a zero value to stop it.


EnumWindows
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL EnumWindows(lpEnumFunc, lParam)

This function enumerates all parent windows on the screen by passing the
handle of each window, in turn, to the callback function pointed to by the
lpEnumFunc parameter. Child windows are not enumerated.

The EnumWindows function continues to enumerate windows until the called
function returns zero or until the last window has been enumerated.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpEnumFunc                        FARPROC  Is the procedure-instance
                                  address of the callback function. See
                                  the following "Comments"  section for
                                  details.

lParam                            DWORD  Specifies the value to be passed
                                  to the callback function for the
                                  application's use.



Return Value

The return value specifies the outcome of the function. It is nonzero if all
windows have been enumerated. Otherwise, it is zero.


Comments

The address passed as the lpEnumFunc parameter must be created by using the
MakeProcInstance function.

The callback function must use the Pascal calling convention and must be
declared FAR. The callback function must have the following form:


Callback Function

  BOOL  FAR PASCAL EnumFunc(hWnd, lParam)
  HWND hWnd;
  DWORD lParam;

EnumFunc is a placeholder for the application-supplied function name. The
actual name must be exported by including it in an EXPORTS statement in the
application's module-definition file.

Parameter   Description
────────────────────────────────────────────────────────────────────────────
hWnd        Identifies the window handle.
lParam      Specifies the 32-bit argument of the EnumWindows function.


Return Value

The function must return a nonzero value to continue enumeration, or zero to
stop it.


EqualRect
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  EqualRect(lpRect1, lpRect2)

This function determines whether two rectangles are equal by comparing the
coordinates of their upper-left and lower-right corners. If the values of
these coordinates are equal, EqualRect returns a nonzero value; otherwise,
it returns zero.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpRect1                           LPRECT  Points to a RECT data structure
                                  that contains the upper-left and
                                  lower-right corner coordinates of the
                                  first rectangle.

lpRect2                           LPRECT  Points to a RECT data structure
                                  that contains the upper-left and
                                  lower-right corner coordinates of the
                                  second rectangle.



Return Value

The return value specifies whether the specified rectangles are equal. It is
nonzero if the two rectangles are identical. Otherwise, it is zero.


EqualRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL EqualRgn(hSrcRgn1, hSrcRgn2)

This function checks the two given regions to determine whether they are
identical.

Parameter              Type/Description
────────────────────────────────────────────────────────────────────────────
hSrcRgn1               HRGN  Identifies a region.
hSrcRgn2               HRGN  Identifies a region.


Return Value

The return value specifies whether the specified regions are equal. It is
nonzero if the two regions are equal. Otherwise, it is zero.


Escape
────────────────────────────────────────────────────────────────────────────


Syntax

  int  Escape(hDC, nEscape, nCount, lpInData, lpOutData)

This function allows applications to access facilities of a particular
device that are not directly available through GDI. Escape calls made by an
application are translated and sent to the device driver.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

nEscape                           int  Specifies the escape function to be
                                  performed. For a complete list of escape
                                  functions, see Chapter 12, "Printer
                                  Escapes," in Reference, Volume 2.

nCount                            int  Specifies the number of bytes of
                                  data pointed to by the lpInData
                                  parameter.

lpInData                          LPSTR  Points to the input data
                                  structure required for this escape.

lpOutData                         LPSTR  Points to the data structure to
                                  receive output from this escape. The
                                  lpOutData parameter should be NULL if no
                                  data are returned.



Return Value

The return value specifies the outcome of the function. It is positive if
the function is successful except for the QUERYESCSUPPORT escape, which only
checks for implementation. The return value is zero if the escape is not
implemented. A negative value indicates an error. The following list shows
common error values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
SP_ERROR                          General error.

SP_OUTOFDISK                      Not enough disk space is currently
                                  available for spooling, and no more
                                  space will become available.

SP_OUTOFMEMORY                    Not enough memory is available for
                                  spooling.

SP_USERABORT                      User terminated the job through the
                                  Print Manager.



EscapeCommFunction
────────────────────────────────────────────────────────────────────────────


Syntax

  int  EscapeCommFunction(nCid, nFunc)

This function directs the communication device specified by the nCid
parameter to carry out the extended function specified by the nFunc
parameter.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nCid        int  Specifies the
            communication device to carry
            out the extended function. The
            OpenComm function returns this
            value.
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            value.

nFunc       int  Specifies the function
            code of the extended function.
            It can be any one of the
            following values:

            Value                           Description

            CLRDTR                          Clears the data-terminal-ready
                                            (DTR) signal.

            CLRRTS                          Clears the request-to-send
                                            (RTS) signal.

            RESETDEV                        Resets the device if possible.


            SETDTR                          Sends the data-terminal-ready
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            SETDTR                          Sends the data-terminal-ready
                                            (DTR) signal.

            SETRTS                          Sends the request-to-send (RTS)
                                            signal.

            SETXOFF                         Causes transmission to act as
                                            if an XOFF character has been
                                            received.

            SETXON                          Causes transmission to act as
                                            if an XON character has been
                                            received.




Return Value

The return value specifies the result of the function. It is zero if it is
successful. It is negative if the nFunc parameter does not specify a valid
function code.


ExcludeClipRect
────────────────────────────────────────────────────────────────────────────


Syntax

  int  ExcludeClipRect(hDC, X1, Y1, X2, Y2)

This function creates a new clipping region that consists of the existing
clipping region minus the specified rectangle.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X1                                int  Specifies the logical x-coordinate
                                  of the upper-left corner of the
                                  rectangle.

Y1                                int  Specifies the logical y-coordinate
                                  of the upper-left corner of the
                                  rectangle.

X2                                int  Specifies the logical x-coordinate
                                  of the lower-right corner of the
                                  rectangle.

Y2                                int  Specifies the logical y-coordinate
                                  of the lower-right corner of the
                                  rectangle.



Return Value

The return value specifies the new clipping region's type. It can be any one
of the following values:

Value                Meaning
────────────────────────────────────────────────────────────────────────────
COMPLEXREGION        The region has overlapping borders.
ERROR                No region was created.
NULLREGION           The region is empty.
SIMPLEREGION         The region has no overlapping borders.


Comments

The width of the rectangle, specified by the absolute value of X2 - X1, must
not exceed 32,767 units. This limit applies to the height of the rectangle
as well.


ExcludeUpdateRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  int  ExcludeUpdateRgn(hDC, hWnd)

This function prevents drawing within invalid areas of a window by excluding
an updated region in the window from a clipping region.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HANDLE  Identifies the device context
                                  associated with the clipping region.

hWnd                              HWND  Identifies the window being
                                  updated.



Return Value

This value specifies the type of resultant region. It can be any one of the
following values:

Value                Meaning
────────────────────────────────────────────────────────────────────────────
COMPLEXREGION        The region has overlapping borders.
ERROR                No region was created.
NULLREGION           The region is empty.
SIMPLEREGION         The region has no overlapping borders.


ExitWindows
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  ExitWindows(dwReserved, wReturnCode)

This function initiates the standard Windows shutdown procedure. If all
applications agree to terminate, the Windows session is terminated and
control returns to DOS. Windows sends the WM_QUERYENDSESSION message to
notify all applications that a request has been made to terminate Windows.
If all applications agree to terminate, Windows sends the WM_ENDSESSION
message to all applications before exiting.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
dwReserved                        DWORD  Is reserved and should be set to
                                  zero.

wReturnCode                       WORD  Specifies the return value to be
                                  passed to DOS when Windows exits.



Return Value

The return value is FALSE if one or more applications refused to terminate.
The function does not return if all applications agree to be terminated.


ExtDeviceMode
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  ExtDeviceMode(hWnd, hDriver, lpDevModeOutput,
  lpDeviceName, lpPort, lpDevModeInput, lpProfile, wMode)

This function retrieves or modifies device initialization information for a
given printer driver, or displays a driver-supplied dialog box for
configuring the printer driver. Printer drivers that support device
initialization by applications export this ExtDeviceMode so that
applications can call it.

╓┌─────────────────┌────────────────────────────┌────────────────────────────╖
Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd              HWND  Identifies a window.
                  If the application calls
                  ExtDeviceMode to display a
                  dialog box, the specified
Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
                  dialog box, the specified
                  window is the parent of the
                  dialog box.

hDriver           HANDLE  Identifies the
                  device-driver module. The
                  GetModuleHandle function or
                  LoadLibrary function
                  returns a module handle.

lpDevModeOutput   DEVMODE FAR *  Points to a
                  DEVMODE data structure. The
                  driver writes the
                  initialization information
                  supplied in the
                  lpDevModeInput parameter to
                  this structure.

lpDeviceName      LPSTR  Points to a
Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
lpDeviceName      LPSTR  Points to a
                  null-terminated character
                  string that contains the
                  name of the printer device,
                  such as "PCL/HP LaserJet."

lpPort            LPSTR  Points to a
                  null-terminated character
                  string that contains the
                  name of the port to which
                  the device is connected,
                  such as LPT1:.

lpDevModeInput    DEVMODE FAR *  Points to a
                  DEVMODE data structure that
                  supplies initialization
                  information to the printer
                  driver.

Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────

lpProfile         LPSTR  Points to a
                  null-terminated string that
                  contains the name of the
                  initialization file which
                  initialization information
                  is recorded in and read
                  from. If this parameter is
                  NULL, WIN.INI is the
                  default.

wMode             WORD  Specifies a mask of
                  values which determine the
                  types of operations the
                  function will perform. If
                  wMode is zero,
                  ExtDeviceMode returns the
                  number of bytes required by
                  the printer device driver's
Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
                  the printer device driver's
                  DEVMODE structure.
                  Otherwise, wMode must be
                  one or more of the
                  following values:

                  Value                        Meaning

                  DM_COPY                      Writes the printer driver's
                                               current print settings to
                                               the DEVMODE data structure
                                               identified by lpDevMode-
                                               Output. The calling
                                               application must allocate a
                                               buffer sufficiently large
                                               to contain the information.
                                               If this bit is clear,
                                               lpDevModeOutput can be NULL.

Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────

                  Value                        Meaning

                  DM_MODIFY                    Changes the printer
                                               driver's current print
                                               settings to match the
                                               partial initialization data
                                               in the DEVMODE data
                                               structure identified by
                                               lpDevModeInput before
                                               prompting, copying, or
                                               updating.

                  DM_PROMPT                    Presents the printer
                                               driver's Print Setup dialog
                                               box and then changes the
                                               current print settings to
                                               those the user specifies.

Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────

                  DM_UPDATE                    Writes the printer driver's
                                               current print settings to
                                               the printer environment and
                                               the WIN.INI initialization
                                               file.




Return Value

If the wMode parameter is zero, the return value is the size of the DEVMODE
data structure required to contain the printer driver initialization data.
If the function displays the initialization dialog box, the return value is
either IDOK or IDCANCEL, depending on which button the user selected. If the
function does not display the dialog box and was successful, the return
value is IDOK. The return value is less than zero if the function failed.


Comments

The ExtDeviceMode function is actually part of the printer's device driver,
and not part of GDI. To call this function, the application must include the
DRIVINT.H file, load the printer device driver, and retrieve the address of
the function by using the GetProcAddress function. The application can then
use the address to set up the printer.

An application can set the wMode parameter to DM_COPY to obtain a DEVMODE
data structure filled in with the printer driver's initialization data. The
application can then pass this data structure to the CreateDC function to
set a private environment for the printer device context.


ExtFloodFill
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  ExtFloodFill(hDC, X, Y, crColor, wFillType)

This function fills an area of the display surface with the current brush.

If wFillType is set to FLOODFILLBORDER, the area is assumed to be completely
bounded by the color specified by the crColor parameter. The ExtFloodFill
function begins at the point specified by the X and Y parameters and fills
in all directions to the color boundary.

If wFillType is set to FLOODFILLSURFACE, the ExtFloodFill function begins at
the point specified by X and Y and continues in all directions, filling all
adjacent areas containing the color specified by crColor.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hDC         HDC  Identifies the device
            context.

X           int  Specifies the logical x
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
X           int  Specifies the logical x
            -coordinate of the point where
            filling begins.

Y           int  Specifies the logical y
            -coordinate of the point where
            filling begins.

crColor     COLORREF  Specifies the color
            of the boundary or of the area
            to be filled. The
            interpretation of crColor
            depends on the value of the
            wFillType parameter.

wFillType   WORD  Specifies the type of
            flood fill to be performed. It
            must be one of the following
            values:
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            values:

            Value                           Meaning

            FLOODFILLBORDER                 The fill area is bounded by
                                            the color specified by crColor.
                                            This style is identical to the
                                            filling performed by the
                                            FloodFill function.

            FLOODFILLSURFACE                The fill area is defined by
                                            the color specified by crColor.
                                            Filling continues outward in
                                            all directions as long as the
                                            color is encountered. This
                                            style is useful for filling
                                            areas with multicolored
                                            boundaries.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────




Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. It is zero if:


  ■   The filling could not be completed

  ■   The given point has the boundary color specified by crColor (if
      FLOODFILLBORDER was requested)

  ■   The given point does not have the color specified by crColor (if
      FLOODFILLSURFACE was requested)

  ■   The point is outside the clipping region



Comments

Only memory device contexts and devices that support raster-display
technology support the ExtFloodFill function. For more information, see the
RC_BITBLT raster capability in the GetDeviceCaps function, later in this
chapter.


ExtTextOut
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  ExtTextOut(hDC, X, Y, wOptions,
  lpRect, lpString, nCount, lpDx)

This function writes a character string, within a rectangular region on the
specified display, using the currently selected font. The rectangular region
can be opaque (filled with the current background color) and it can be a
clipping region.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X                                 int  Specifies the logical x-coordinate
                                  of the origin of the character cell for
                                  the first character in the specified
                                  string.

Y                                 int  Specifies the logical y-coordinate
                                  of the origin of the character cell for
                                  the first character in the specified
                                  string.

wOptions                          WORD  Specifies the rectangle type. It
                                  can be one or both of the following
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
                                  can be one or both of the following
                                  values, or neither:

                                  ETO_CLIPPED
                                  ETO_OPAQUE

                                  The ETO_CLIPPED value specifies that
                                  Windows will clip text to the rectangle.
                                  The ETO_OPAQUE value specifies that the
                                  current background color fills the
                                  rectangle.

lpRect                            LPRECT  Points to a RECT data structure.
                                  The lpRect parameter can be NULL.

lpString                          LPSTR  Points to the specified character
                                  string.

nCount                            int  Specifies the number of characters
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCount                            int  Specifies the number of characters
                                  in the string.

lpDx                              LPINT  Points to an array of values that
                                  indicate the distance between origins of
                                  adjacent character cells. For instance,
                                  lpDx[i] logical units will separate the
                                  origins of character cell i and
                                  character cell i + 1.




Return Value

The return value specifies whether or not the string is drawn. It is nonzero
if the string is drawn. Otherwise, it is zero.


Comments

If lpDx is NULL, the function uses the default spacing between characters.

The character-cell origins and the contents of the array pointed to by the
lpDx parameter are given in logical units. A character-cell origin is
defined as the upper-left corner of the character cell.

By default, the current position is not used or updated by this function.
However, an application can call the SetTextAlign function with the wFlags
parameter set to TA_UPDATECP to permit Windows to use and update the current
position each time the application calls ExtTextOut for a given device
context. When this flag is set, Windows ignores the X and Y parameters on
subsequent ExtTextOut calls.





FatalAppExit
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  VOID  FatalAppExit(wAction, lpMessageText)

This function displays a message containing the text specified by the
lpMessageText parameter and terminates the application when the message box
is closed. When called under the debugging version of Windows, the message
box gives the user the opportunity to terminate the application or to return
to the caller.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wAction                           WORD  Is reserved and must be set to 0.

lpMessageText                     LPSTR  Points to a character string that
                                  is displayed in the message box. The
                                  message is displayed on a single line.
                                  To accommodate low-resolution displays,
                                  the string should be no more than 35
                                  characters in length.



Return Value

None.


Comments

An application that encounters an unexpected error should terminate by
freeing all its memory and then returning from its main message loop. It
should call FatalAppExit only when it is not capable of terminating any
other way. FatalAppExit may not always free an application's memory or close
its files, and it may cause a general failure of Windows.


FatalExit
────────────────────────────────────────────────────────────────────────────


Syntax

  void  FatalExit(Code)

This function displays the current state of Windows on the debugging monitor
and prompts for instructions on how to proceed. The display includes an
error code, the Code parameter, followed by a symbolic stack trace, showing
the flow of execution up to the point of call.

An application should call this function only for debugging purposes; it
should not call the function in a retail version of the application. Calling
this function in the retail version will terminate the application.

Parameter       Type/Description
────────────────────────────────────────────────────────────────────────────
Code            int  Specifies the error code to be displayed.


Return Value

None.


Comments

The FatalExit function prompts the user to respond to an "Abort, Break or
Ignore" message. FatalExit processes the response as follows:

Response                          Description
────────────────────────────────────────────────────────────────────────────
A (Abort)                         Terminates Windows.

B (Break)                         Simulates a non-maskable interrupt (NMI)
                                  to enter the debugger.

I (Ignore)                        Returns to the caller.


The FatalExit function is for debugging only.

An application should call this function whenever the application detects a
fatal error. All input and output is received and transmitted through the
computer's auxiliary port (AUX) or through the debugger if a debugger is
installed.


FillRect
────────────────────────────────────────────────────────────────────────────


Syntax

  int FillRect(hDC, lpRect, hBrush)

This function fills a given rectangle by using the specified brush. The
FillRect function fills the complete rectangle, including the left and top
borders, but does not fill the right and bottom borders.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context.

lpRect                            LPRECT Points to a RECT data structure
                                  that contains the logical coordinates of
                                  the rectangle to be filled.

hBrush                            HBRUSH Identifies the brush used to fill
                                  the rectangle.



Return Value

Although the FillRect function return type is an integer, the return value
is not used and has no meaning.


Comments

The brush must have been created previously by using either the
CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function, or
retrieved using the GetStockObject function.

When filling the specified rectangle, the FillRect function does not include
the rectangle's right and bottom sides. GDI fills a rectangle up to, but
does not include, the right column and bottom row, regardless of the current
mapping mode.

FillRect compares the values of the top, bottom, left, and right fields of
the specified rectangle. If bottom is less than or equal to top, or if right
is less than or equal to left, the rectangle is not drawn.


FillRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  FillRgn(hDC, hRgn, hBrush)

This function fills the region specified by the hRgn parameter with the
brush specified by the hBrush parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

hRgn                              HRGN  Identifies the region to be filled.
                                  The coordinates for the given region are
                                  specified in device units.

hBrush                            HBRUSH  Identifies the brush to be used
                                  to fill the region.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. Otherwise, it is zero.


FindAtom
────────────────────────────────────────────────────────────────────────────


Syntax

  ATOM  FindAtom(lpString)

This function searches the atom table for the character string pointed to by
the lpString parameter and retrieves the atom associated with that string.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpString                          LPSTR  Points to the character string to
                                  be searched for. The string must be
                                  null-terminated.



Return Value

The return value identifies the atom associated with the given string. It is
NULL if the string is not in the table.


FindResource
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  FindResource(hInstance, lpName, lpType)

This function determines the location of a resource in the specified
resource file. The lpName and lpType parameters define the resource name and
type, respectively.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance   HANDLE  Identifies the
            instance of the module whose
            executable file contains the
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            executable file contains the
            resource.

lpName      LPSTR  Points to a
            null-terminated character
            string that represents the
            name of the resource.

lpType      LPSTR  Points to a
            null-terminated character
            string that represents the
            type name of the resource. For
            predefined resource types, the
            lpType parameter should be one
            of the following values:

            Value                           Meaning

            RT_ACCELERATOR                  Accelerator table
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            RT_ACCELERATOR                  Accelerator table

            RT_BITMAP                       Bitmap resource

            RT_DIALOG                       Dialog box

            RT_FONT                         Font resource

            RT_FONTDIR                      Font directory resource

            RT_MENU                         Menu resource

            RT_RCDATA                       User-defined resource (raw
                                            data)




Return Value

The return value identifies the named resource. It is NULL if the requested
resource cannot be found.


Comments

An application must not call FindResource and the LoadResource function to
load cursor, icon, and string resources. Instead, it must load these
resources by calling the following functions:


  ■   LoadCursor

  ■   LoadIcon

  ■   LoadString


An application can call FindResource and LoadResource to load other
predefined resource types. However, it is recommended that the application
load the corresponding resources by calling the following functions:


  ■   LoadAccelerators

  ■   LoadBitmap

  ■   LoadMenu


If the high-order word of the lpName or lpType parameter is zero, the
low-order word specifies the integer ID of the name or type of the given
resource. Otherwise, the parameters are long pointers to null-terminated
character strings. If the first character of the string is a pound sign (#),
the remaining characters represent a decimal number that specifies the
integer ID of the resource's name or type. For example, the string #258
represents the integer ID 258.

To reduce the amount of memory required for the resources used by an
application, the application should refer to the resources by integer ID
instead of by name.


FindWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  FindWindow(lpClassName, lpWindowName)

This function returns the handle of the window whose class is given by the
lpClassName parameter and whose window name, or caption, is given by the
lpWindowName parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpClassName                       LPSTR  Points to a null-terminated
                                  character string that specifies the
                                  window's class name. If lpClassName is
                                  NULL, all class names match.

lpWindowName                      LPSTR  Points to a null-terminated
                                  character string that specifies the
                                  window name (the window's text caption).
                                  If lpWindowName is NULL, all window
                                  names match.



Return Value

The return value identifies the window that has the specified class name and
window name. It is NULL if no such window is found.


FlashWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  FlashWindow(hWnd, bInvert)

This function "flashes" the given window once. Flashing a window means
changing the appearance of its caption bar as if the window were changing
from inactive to active status, or vice versa. (An inactive caption bar
changes to an active caption bar; an active caption bar changes to an
inactive caption bar.)

Typically, a window is flashed to inform the user that the window requires
attention, but that it does not currently have the input focus.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window to be
                                  flashed. The window can be either open
                                  or iconic.

bInvert                           BOOL  Specifies whether the window is to
                                  be flashed or returned to its original
                                  state. The window is flashed from one
                                  state to the other if the bInvert
                                  parameter is nonzero. If the bInvert
                                  parameter is zero, the window is
                                  returned to its original state (either
                                  active or inactive).



Return Value

The return value specifies the window's state before call to the FlashWindow
function. It is nonzero if the window was active before the call. Otherwise,
it is zero.


Comments

The FlashWindow function flashes the window only once; for successive
flashing, the application should create a system timer.

The bInvert parameter should be zero only when the window is getting the
input focus and will no longer be flashing; it should be nonzero on
successive calls while waiting to get the input focus.

This function always returns a nonzero value for iconic windows. If the
window is iconic, FlashWindow will simply flash the icon; bInvert is ignored
for iconic windows.


FloodFill
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  FloodFill(hDC, X, Y, crColor)

This function fills an area of the display surface with the current brush.
The area is assumed to be bounded as specified by the crColor parameter. The
FloodFill function begins at the point specified by the X and Y parameters
and continues in all directions to the color boundary.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X                                 int  Specifies the logical x-coordinate
                                  of the point where filling begins.

Y                                 int  Specifies the logical y-coordinate
                                  of the point where filling begins.

crColor                           COLORREF  Specifies the color of the
                                  boundary.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. It is zero if the filling could not be completed,
the given point has the boundary color specified by crColor, or the point is
outside the clipping region.


Comments

Only memory device contexts and devices that support raster-display
technology support the FloodFill function. For more information, see the
RC_BITBLT raster capability in the GetDeviceCaps function, later in this
chapter.


FlushComm
────────────────────────────────────────────────────────────────────────────


Syntax

  int FlushComm(nCid, nQueue)

This function flushes all characters from the transmit or receive queue of
the communication device specified by the nCid parameter. The nQueue
parameter specifies which queue is to be flushed.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int  Specifies the communication device
                                  to be flushed. The OpenComm function
                                  returns this value.

nQueue                            int  Specifies the queue to be flushed.
                                  If nQueue is zero, the transmit queue is
                                  flushed. If it is 1, the receive queue
                                  is flushed.



Return Value

The return value specifies the result of the function. It is zero if it is
successful. It is negative if nCid is not a valid device, or if nQueue is
not a valid queue.


FrameRect
────────────────────────────────────────────────────────────────────────────


Syntax

  int  FrameRect(hDC, lpRect, hBrush)

This function draws a border around the rectangle specified by the lpRect
parameter. The FrameRect function uses the given brush to draw the border.
The width and height of the border is always one logical unit.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context of the
                                  window.

lpRect                            LPRECT Points to a RECT data structure
                                  that contains the logical coordinates of
                                  the upper-left and lower-right corners
                                  of the rectangle.

hBrush                            HBRUSH Identifies the brush to be used
                                  for framing the rectangle.



Return Value

Although the return value type is integer, its contents should be ignored.


Comments

The brush identified by the hBrush parameter must have been created
previously by using the CreateHatchBrush, CreatePatternBrush, or
CreateSolidBrush function.

If the bottom field is less than or equal to the top field, or if right is
less than or equal to left, the rectangle is not drawn.


FrameRgn
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  FrameRgn(hDC, hRgn, hBrush, nWidth, nHeight)

This function draws a border around the region specified by the hRgn
parameter, using the brush specified by the hBrush parameter. The nWidth
parameter specifies the width of the border in vertical brush strokes; the
nHeight parameter specifies the height in horizontal brush strokes.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

hRgn                              HANDLE  Identifies the region to be
                                  enclosed in a border. The coordinates
                                  for the given region are specified in
                                  device units.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────







hBrush                            HBRUSH  Identifies the brush to be used
                                  to draw the border.

nWidth                            int  Specifies the width in vertical
                                  brush strokes (in logical units).

nHeight                           int  Specifies the height in horizontal
                                  brush strokes (in logical units).




Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. Otherwise, it is zero.


FreeLibrary
────────────────────────────────────────────────────────────────────────────


Syntax

  void  FreeLibrary(hLibModule)

This function decreases the reference count of the loaded library module by
one. When the reference count reaches zero, the memory occupied by the
module is freed.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hLibModule       HANDLE  Identifies the loaded library module.


Return Value

None.


FreeModule
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  FreeModule(hModule)

This function decreases the reference count of the loaded module by one.
When the reference count reaches zero, the memory occupied by the module is
freed.

Parameter          Type/Description
────────────────────────────────────────────────────────────────────────────
hModule            HANDLE  Identifies the loaded module.


Return Value

None.


FreeProcInstance
────────────────────────────────────────────────────────────────────────────


Syntax

  void  FreeProcInstance(lpProc)

This function frees the function specified by the lpProc parameter from the
data segment bound to it by the MakeProcInstance function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpProc                            FARPROC  Is the procedure-instance
                                  address of the function to be freed. It
                                  must have been created previously by
                                  using the MakeProcInstance function.



Return Value

None.


Comments

After freeing a procedure instance, attempts to call the function using the
freed procedure-instance address will result in an unrecoverable error.


FreeResource
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL FreeResource(hResData)

This function removes a loaded resource from memory by freeing the allocated
memory occupied by that resource.

The FreeResource function does not actually free the resource until the
reference count is zero (that is, the number of calls to the function equals
the number of times the application called the LoadResource function for
this resource). This ensures that the data remain in memory for the
application to use.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hResData                          HANDLE  Identifies the data associated
                                  with the resource. The handle is assumed
                                  to have been created by using the
                                  LoadResource function.



Return Value

The return value specifies the outcome of the function. The return value is
nonzero if the function has failed and the resource has not been freed. The
return value is zero if the function is successful.


FreeSelector
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  FreeSelector(wSelector)

This function frees a selector originally allocated by the AllocSelector or
AllocDStoCSAlias functions. After the application calls this function, the
selector is invalid and must not be used.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
wSelector        WORD  Specifies the selector to be freed.


Return Value

The return value is NULL if the function was successful. Otherwise, it is
the selector specified by the wSelector parameter.


Comments

An application should not use this function unless it is absolutely
necessary. Use of this function violates preferred Windows programming
practices.





GetActiveWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND GetActiveWindow( )

This function retrieves the window handle of the active window. The active
window is either the window that has the current input focus, or the window
explicitly made active by the SetActiveWindow function.

This function has no parameters.


Return Value

The return value identifies the active window.


GetAspectRatioFilter
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetAspectRatioFilter(hDC)

This function retrieves the setting for the current aspect-ratio filter. The
aspect ratio is the ratio formed by a device's pixel width and height.
Information about a device's aspect ratio is used in the creation,
selection, and displaying of fonts. Windows provides a special filter, the
aspect-ratio filter, to select fonts designed for a particular aspect ratio
from all of the available fonts. The filter uses the aspect ratio specified
by the SetMapperFlags function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context that
                                  contains the specfied aspect ratio.



Return Value

The return value specifies the aspect ratio used by the current aspect-ratio
filter. The x-coordinate of the aspect ratio is contained in the high-order
word, and the y-coordinate is contained in the low-order word.


GetAsyncKeyState
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetAsyncKeyState(vKey)

This function determines whether a key is up or down at the time the
function is called, and whether the key was pressed after a previous call to
the GetAsyncKeyState function. If the most significant bit of the return
value is set, the key is currently down; if the least significant bit is
set, the key was pressed after a previous call to the function.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
vKey        int  Specifies one of 256 possible virtual-key code values.


Return Value

The return value specifies whether the key was pressed since the last call
to GetAsyncKeyState and whether the key is currently up or down. If the most
significant bit is set, the key is down, and if the least significant bit is
set, the key was pressed after a preceding GetAsyncKeyState call.


GetAtomHandle
────────────────────────────────────────────────────────────────────────────


Syntax

  HMEM GetAtomHandle(wAtom)

This function retrieves a handle (relative to the local heap) of the string
that corresponds to the atom specified by the wAtom parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wAtom                             WORD Specifies an unsigned integer that
                                  identifies the atom whose handle is to
                                  be retrieved.



Return Value

The return value identifies the given atom's string. It is zero if no such
atom exists.


GetAtomName
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD GetAtomName(nAtom, lpBuffer, nSize)

This function retrieves a copy of the character string associated with the
nAtom parameter and places it in the buffer pointed to by the lpBuffer
parameter. The nSize parameter specifies the maximum size of the buffer.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nAtom                             ATOM Identifies the character string to
                                  be retrieved.

lpBuffer                          LPSTR Points to the buffer that is to
                                  receive the character string.

nSize                             int Specifies the maximum size (in bytes)
                                  of the buffer.



Return Value

The return value specifies the actual number of bytes copied to the buffer.
It is zero if the specified atom is not valid.


GetBitmapBits
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetBitmapBits(hBitmap, dwCount, lpBits)

This function copies the bits of the specified bitmap into the buffer that
is pointed to by the lpBits parameter. The dwCount parameter specifies the
number of bytes to be copied to the buffer. The GetObject function should be
used to determine the correct dwCount value for the given bitmap.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hBitmap                           HBITMAP Identifies the bitmap.

dwCount                           DWORD Specifies the number of bytes to
                                  be copied.

lpBits                            LPSTR Long pointer to the buffer that is
                                  to receive the bitmap. The bitmap is an
                                  array of bytes. The bitmap byte array
                                  conforms to a structure where horizontal
                                  scan lines are multiples of 16 bits.



Return Value

The return value specifies the actual number of bytes in the bitmap. It is
zero if there is an error.


GetBitmapDimension
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetBitmapDimension(hBitmap)

This function returns the width and height of the bitmap specified by the
hBitmap parameter. The height and width is assumed to have been set
previously by using the SetBitmapDimension function.

Parameter            Type/Description
────────────────────────────────────────────────────────────────────────────
hBitmap              HBITMAP Identifies the bitmap.


Return Value

The return value specifies the width and height of the bitmap, measured in
tenths of millimeters. The height is in the high-order word, and the width
is in the low-order word. If the bitmap width and height have not been set
by using SetBitmapDimension, the return value is zero.


GetBkColor
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetBkColor(hDC)

This function returns the current background color of the specified device.


Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC Identifies the device context.


Return Value

The return value specifies an RGB color value that names the current
background color.


GetBkMode
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetBkMode(hDC)

This function returns the background mode of the specified device. The
background mode is used with text, hatched brushes, and pen style that is
not a solid line.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC Identifies the device context.


Return Value

The return value specifies the current background mode. It can be OPAQUE or
TRANSPARENT.


GetBrushOrg
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetBrushOrg(hDC)

This function retrieves the current brush origin for the given device
context.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC Identifies the device context.


Return Value

The return value specifies the current origin of the brush. The x-coordinate
is in the low word, and the y-coordinate is in the high word. The
coordinates are assumed to be in device units.


Comments

The initial brush origin is at the coordinate (0,0).


GetBValue
────────────────────────────────────────────────────────────────────────────


Syntax

  BYTE GetBValue(rgbColor)

This macro extracts the blue value from an RGB color value.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
rgbColor                          DWORD Specifies a red, a green, and a
                                  blue color field, each specifying the
                                  intensity of the given color.



Return Value

The return value specifies a byte that contains the blue value of the
rgbColor parameter.


Comments

The value 0FFH corresponds to the maximum intensity value for a single byte;
000H corresponds to the minimum intensity value for a single byte.


GetCapture
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND GetCapture( )

This function retrieves a handle that identifies the window that has the
mouse capture. Only one window has the mouse capture at any given time; this
window receives mouse input whether or not the cursor is within its borders.


This function has no parameters.


Return Value

The return value identifies the window that has the mouse capture; it is
NULL if no window has the mouse capture.


Comments

A window receives the mouse capture when its handle is passed as the hWnd
parameter of the SetCapture function.


GetCaretBlinkTime
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD GetCaretBlinkTime( )

This function retrieves the caret blink rate. The blink rate is the elapsed
time in milliseconds between flashes of the caret.

This function has no parameters.


Return Value

The return value specifies the blink rate (in milliseconds).


GetCaretPos
────────────────────────────────────────────────────────────────────────────


Syntax

  void GetCaretPos(lpPoint)

This function retrieves the caret's current position (in screen
coordinates), and copies them to the POINT structure pointed to by the
lpPoint parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPoint                           LPPOINT Points to the POINT structure
                                  that is to receive the screen
                                  coordinates of the caret.



Return Value

None.


Comments

The caret position is always given in the client coordinates of the window
that contains the caret.


GetCharWidth
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL GetCharWidth(hDC, wFirstChar, wLastChar, lpBuffer)

This function retrieves the widths of individual characters in a consecutive
group of characters from the current font. For example, if the wFirstChar
parameter identifies the letter a and the wLastChar parameter identifies the
letter z, the GetCharWidth function retrieves the widths of all lowercase
characters. The function stores the values in the buffer pointed to by the
lpBuffer parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context.

wFirstChar                        WORD Specifies the first character in a
                                  consecutive group of characters in the
                                  current font.

wLastChar                         WORD Specifies the last character in a
                                  consecutive group of characters in the
                                  current font.

lpBuffer                          LPINT Points to a buffer that will
                                  receive the width values for a
                                  consecutive group of characters in the
                                  current font.



Return Value

The return value specifies the outcome of the function. It is nonzero if the
function is successful. Otherwise, it is zero.


Comments

If a character in the consecutive group of characters does not exist in a
particular font, it will be assigned the width value of the default
character.


GetClassInfo
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  BOOL  GetClassInfo(hInstance, lpClassName, lpWndClass)

This function retrieves information about a window class. The hInstance
parameter identifies the instance of the application that created the class,
and the lpClassName parameter identifies the window class. If the function
locates the specified window class, it copies the WNDCLASS data used to
register the window class to the WNDCLASS data structure pointed to by
lpWndClass.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance                         HANDLE  Identifies the instance of the
                                  application that created the class. To
                                  retrieve information on classes defined
                                  by Windows (such as buttons or list
                                  boxes), set hInstance to NULL.

lpClassName                       LPSTR  Points to a null-terminated
                                  string that contains the name of the
                                  class to find. If the high-order word of
                                  this parameter is NULL, the low-order
                                  word is assumed to be a value returned
                                  by the MAKEINTRESOURCE macro used when
                                  the class was created.

lpWndClass                        LPWNDCLASS  Points to the WNDCLASS
                                  structure to which the function will
                                  copy the class information.



Return Value

The return value is TRUE if the function found a matching class and
successfully copied the data; the return value is FALSE if the function did
not find a matching class.


Comments

The lpszClassName, lpszMenuName, and hInstance fields in the WNDCLASS data
structure are not returned by this function. The menu name is not stored
internally and cannot be returned. The class name is already known since it
is passed to this function. The GetClassInfo function returns all other
fields with the values used when the class was registered.


GetClassLong
────────────────────────────────────────────────────────────────────────────


Syntax

  LONG  GetClassLong(hWnd, nIndex)

This function retrieves the long value specified by the nIndex parameter
from the WNDCLASS structure of the window specified by the hWnd parameter.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND Identifies the window.

nIndex      int Specifies the byte offset
            of the value to be retrieved.
            It can also be the following
            value:

            Value                           Meaning

            GCL_WNDPROC                     Retrieves a long pointer to
                                            the window function.



Return Value

The return value specifies the value retrieved from the WNDCLASS structure.



Comments

To access any extra four-byte values allocated when the window-class
structure was created, use a positive byte offset as the index specified by
the nIndex parameter. The first four-byte value in the extra space is at
offset zero, the next four-byte value is at offset 4, and so on.


GetClassName
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetClassName(hWnd, lpClassName, nMaxCount)

This function retrieves the class name of the window specified by the hWnd
parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND Identifies the window whose class
                                  name is to be retrieved.

lpClassName                       LPSTR Points to the buffer that is to
                                  receive the class name.

nMaxCount                         int Specifies the maximum number of
                                  bytes to be stored in the lpClassName
                                  parameter. If the actual name is longer,
                                  a truncated name is copied to the buffer.



Return Value

The return value specifies the number of characters actually copied to
lpClassName. The return value is zero if the specified class name is not
valid.


GetClassWord
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD GetClassWord(hWnd, nIndex)

This function retrieves the word that is specified by the nIndex parameter
from the WNDCLASS structure of the window specified by the hWnd parameter.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND Identifies the window.

nIndex      int Specifies the byte offset
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nIndex      int Specifies the byte offset
            of the value to be retrieved.
            It can also be one of the
            following values:

            Value                           Meaning

            GCW_CBCLSEXTRA                  Tells how many bytes of
                                            additional class information
                                            you have. For information on
                                            how to access this memory, see
                                            the following "Comments"
                                            section.

            GCW_CBWNDEXTRA                  Tells how many bytes of
                                            additional window information
                                            you have. For information on
                                            how to access this memory, see
                                            the following"Comments"
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            the following"Comments"
                                            section.

            GCW_HBRBACKGROUND               Retrieves a handle to the
                                            background brush.

            GCW_HCURSOR                     Retrieves a handle to the
                                            cursor.

            GCW_HICON                       Retrieves a handle to the icon.


            GCW_HMODULE                     Retrieves a handle to the
                                            module.

            GCW_STYLE                       Retrieves the window-class
                                            style bits.




Return Value

The return value specifies the value retrieved from the WNDCLASS structure.



Comments

To access any extra two-byte values allocated when the window-class
structure was created, use a positive byte offset as the index specified by
the nIndex parameter, starting at zero for the first two-byte value in the
extra space, 2 for the next two-byte value and so on.


GetClientRect
────────────────────────────────────────────────────────────────────────────


Syntax

  void GetClientRect(hWnd, lpRect)

This function copies the client coordinates of a window's client area into
the data structure pointed to by the lpRect parameter. The client
coordinates specify the upper-left and lower-right corners of the client
area. Since client coordinates are relative to the upper-left corners of a
window's client area, the coordinates of the upper-left corner are (0,0).

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND Identifies the window associated with the client area.
lpRect      LPRECT Points to a RECT data structure.


Return Value

None.


GetClipboardData
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE GetClipboardData(wFormat)

This function retrieves data from the clipboard in the format given by the
wFormat parameter. The clipboard must have been opened previously.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wFormat                           WORD Specifies a data format. For a
                                  description of the data formats, see the
                                  SetClipboardData function, later in this
                                  chapter.



Return Value

The return value identifies the memory block that contains the data from the
clipboard. The handle type depends on the type of data specified by the
wFormat parameter. It is NULL if there is an error.


Comments

The available formats can be enumerated in advance by using the
EnumClipboardFormats function.

The data handle returned by GetClipboardData is controlled by the clipboard,
not by the application. The application should copy the data immediately,
instead of relying on the data handle for long-term use. The application
should not free the data handle or leave it locked.

Windows supports two formats for text, CF_TEXT and CF_OEMTEXT. CF_TEXT is
the default Windows text clipboard format, while Windows uses the CF_OEMTEXT
format for text in non-Windows applications. If you call GetClipboardData to
retrieve data in one text format and the other text format is the only
available text format, Windows automatically converts the text to the
requested format before supplying it to your application.

If the clipboard contains data in the CF_PALETTE (logical color palette)
format, the application should assume that any other data in the clipboard
is realized against that logical palette.


GetClipboardFormatName
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetClipboardFormatName(wFormat, lpFormatName,
  nMaxCount)

This function retrieves from the clipboard the name of the registered format
specified by the wFormat parameter. The name is copied to the buffer pointed
to by the lpFormatName parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wFormat                           WORD Specifies the type of format to be
                                  retrieved. It must not specify any of
                                  the predefined clipboard formats.

lpFormatName                      LPSTR Points to the buffer that is to
                                  receive the format name.

nMaxCount                         int  Specifies the maximum length (in
                                  bytes) of the string to be copied to the
                                  buffer. If the actual name is longer, it
                                  is truncated.



Return Value

The return value specifies the actual length of the string copied to the
buffer. It is zero if the requested format does not exist or is a predefined
format.


GetClipboardOwner
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND GetClipboardOwner( )

This function retrieves the window handle of the current owner of the
clipboard.

This function has no parameters.


Return Value

The return value identifies the window that owns the clipboard. It is NULL
if the clipboard is not owned.


Comments

The clipboard can still contain data even if the clipboard is not currently
owned.


GetClipboardViewer
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND GetClipboardViewer( )

This function retrieves the window handle of the first window in the
clipboard-viewer chain.

This function has no parameters.


Return Value

The return value identifies the window currently responsible for displaying
the clipboard. It is NULL if there is no viewer.


GetClipBox
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetClipBox(hDC, lpRect)

This function retrieves the dimensions of the tightest bounding rectangle
around the current clipping boundary. The dimensions are copied to the
buffer pointed to by the lpRect parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context.

lpRect                            LPRECT Points to the RECT data structure
                                  that is to receive the rectangle
                                  dimensions.



Return Value

The return value specifies the clipping region's type. It can be any one of
the following values:

Value              Meaning
────────────────────────────────────────────────────────────────────────────
COMPLEXREGION      Clipping region has overlapping borders.
ERROR              Device context is not valid.
NULLREGION         Clipping region is empty.
SIMPLEREGION       Clipping region has no overlapping borders.


GetCodeHandle
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetCodeHandle(lpProc)

This function determines which code segment contains the function pointed to
by the lpProc parameter.

Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
lpProc            FARPROC  Is a procedure-instance address.


Return Value

The return value identifies the code segment that contains the function.


Comments

If the code segment that contains the function is already loaded, the
GetCodeHandle function marks the segment as recently used. If the code
segment is not loaded, GetCodeHandle attempts to load it. Thus, an
application can use this function to attempt to preload one or more segments
needed to perform a particular task.


GetCodeInfo
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  void  GetCodeInfo(lpProc, lpSegInfo)

This function retrieves a pointer to an array of 16-bit values containing
information about the code segment that contains the function pointed to by
the lpProc parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpProc                            FARPROC   Is the address of the function
                                  in the segment for which information is
                                  to be retrieved. Instead of a
                                  segment:offset address, this value can
                                  also be in the form of a module handle
                                  and segment number. The GetModuleHandle
                                  function returns the handle of a named
                                  module.

lpSegInfo                         LPVOID   Points to an array of four
                                  32-bit values that will be filled with
                                  information about the code segment. See
                                  the following "Comments" section for a
                                  description of the values in this array.



Return Value

None.


Comments

The lpSegInfo parameter points to an array of four 32-bit values that
contains such information as the location and size of the segment and its
attributes. The following list describes each of these values:

╓┌───────┌─────────────────────────────────┌─────────────────────────────────╖
Offset  Description
────────────────────────────────────────────────────────────────────────────
0       Specifies the logical-sector
        offset (in bytes) to the
        contents of the segment data,
        relative to the beginning of the
        file. Zero means no file data is
        available.

2       Specifies the length of the
        segment in the file (in bytes).
        Zero means 64K.

Offset  Description
────────────────────────────────────────────────────────────────────────────

4       Contains flags which specify
        attributes of the segment. The
        following list describes these
        flags:

        Bit                               Meaning

        0-2                               Specifies the segment type. If
                                          bit 0 is set to 1, the segment
                                          is a data segment. Otherwise,
                                          the segment is a code segment.

        3                                 Specifies whether segment data
                                          is iterated. When this bit set
                                          to 1, the segment data is
                                          iterated.

        4                                 Specifies whether the segment is
Offset  Description
────────────────────────────────────────────────────────────────────────────
        4                                 Specifies whether the segment is
                                          moveable or fixed. When this bit
                                          is set to 1, the segment is
                                          moveable. Otherwise, it is fixed.

        5                                 Is not returned.

        6                                 Is not returned.

        7                                 Specifies whether the segment is
                                          a read-only data segment or an
                                          execute-only code segment. If
                                          this bit is set to 1 and the
                                          segment is a code segment, the
                                          segment is an execute-only
                                          segment. If this bit is set to
                                          zero and the segment is a data
                                          segment, it is a read-only
                                          segment.
Offset  Description
────────────────────────────────────────────────────────────────────────────
                                          segment.

        8                                 Specifies whether the segment
                                          has associated relocation
                                          information. If this bit is set
                                          to 1, the segment has relocation
                                          information. Otherwise, the
                                          segment does not have relocation
                                          information.

        9                                 Specifies whether the segment
                                          has debugging information. If
                                          this bit is set to 1, the
                                          segment has debugging
                                          information. Otherwise, the
                                          segment does not have debugging
                                          information.

        10-11                             Is not returned.
Offset  Description
────────────────────────────────────────────────────────────────────────────
        10-11                             Is not returned.

        12-15                             Is not returned.

6       Specifies the total amount of
        memory allocated for the segment.
        This amount may exceed the
        actual size of the segment. Zero
        means 65,536.




GetCommError
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetCommError(nCid, lpStat)

In case of a communications error, Windows locks the communications port
until the error is cleared by using the GetCommError function. This function
fills the status buffer pointed to by the lpStat parameter with the current
status of the communication device specified by the nCid parameter. It also
returns the error codes that have occurred since the last GetCommError call.
If lpStat is NULL, only the error code is returned. For a list of the error
codes, see Table 4.8, "Communications Error Codes."

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int Specifies the communication device
                                  to be examined. The OpenComm function
                                  returns this value.

lpStat                            COMSTAT FAR * Points to the COMSTAT
                                  structure that is to receive the device
                                  status. The structure contains
                                  information about a communication device.



Return Value

The return value specifies the error codes returned by the most recent
communications function. It can be a combination of one or more of the
values given in Table .

Table   Communications Error Codes

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
CE_BREAK                          The hardware detects a break condition.

CE_CTSTO                          Clear-to-send timeout. CTS is low for
                                  the duration specified by CtsTimeout
                                  while trying to transmit a character.

CE_DNS                            The parallel device is not selected.

Value                             Meaning
────────────────────────────────────────────────────────────────────────────

CE_DSRTO                          Data-set-ready timeout. DSR is low for
                                  the duration specified by DsrTimeout
                                  while trying to transmit a character.

CE_FRAME                          The hardware detects a framing error.

CE_IOE                            An I/O error occurs while trying to
                                  communicate with a parallel device.

CE_MODE                           Requested mode is not supported, or the
                                  nCid parameter is invalid. If set, this
                                  is the only valid error.

CE_OOP                            The parallel device signals that it is
                                  out of paper.

CE_OVERRUN                        A character is not read from the
                                  hardware before the next character
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  hardware before the next character
                                  arrives. The character is lost.

CE_PTO                            Timeout occurs while trying to
                                  communicate with a parallel device.

CE_RLSDTO                         Receive-line-signal-detect timeout. RLSD
                                  is low for the duration specified by
                                  RlsdTimeout while trying to transmit a
                                  character.



Table   Communications Error Codes (continued)

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
CE_RXOVER                         Receive queue overflow. There is either
                                  no room in the input queue or a
                                  character is received after the EofChar
                                  character is received.

CE_RXPARITY                       The hardware detects a parity error.

CE_TXFULL                         The transmit queue is full while trying
                                  to queue a character.



GetCommEventMask
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD GetCommEventMask(nCid, nEvtMask)

This function retrieves the value of the current event mask, and then clears
the mask. This function must be used to prevent loss of an event.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int Specifies the communication device
                                  to be examined. The OpenComm function
                                  returns this value.

nEvtMask                          int Specifies which events are to be
                                  enabled. For a list of the event values,
                                  see the SetCommEventMask function, later
                                  in this chapter.



Return Value

The return value specifies the current event-mask value. Each bit in the
event mask specifies whether a given event has occurred. A bit is set to 1
if the event has occurred.


GetCommState
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetCommState(nCid, lpDCB)

This function fills the buffer pointed to by the lpDCB parameter with the
device control block of the communication device specified by the nCid
parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nCid                              int Specifies the device to be examined.
                                  The OpenComm function returns this value.

lpDCB                             DCB FAR * Points to the DCB data
                                  structure that is to receive the current
                                  device control block. The structure
                                  defines the control setting for the
                                  device.



Return Value

The return value specifies the outcome of the function. It is zero if the
function was successful. If an error occurred, the return value is negative.



GetCurrentPDB
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetCurrentPDB()

This function returns the paragraph address or selector of the current DOS
Program Data Base (PDB), also known as the Program Segment Prefix (PSP).

This function has no parameters.


Return Value

The return value is the paragraph address or selector of the current PDB.


GetCurrentPosition
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetCurrentPosition(hDC)

This function retrieves the logical coordinates of the current position.

Parameter            Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                  HDC Identifies a device context.


Return Value

The return value specifies the current position. The y-coordinate is in the
high-order word; the x-coordinate is in the low-order word.


GetCurrentTask
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE GetCurrentTask( )

This function returns the handle of the currently executing task.

This function has no parameters.


Return Value

The return value identifies the task if the function is successful.
Otherwise, it is NULL.


GetCurrentTime
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetCurrentTime( )

This function retrieves the current Windows time. Windows time is the number
of milliseconds that have elapsed since the system was booted.

This function has no parameters.


Return Value

The return value specifies the current time (in milliseconds).


Comments

The GetCurrentTime and GetMessageTime functions return different times.
GetMessageTime returns the Windows time when the given message was created,
not the current Windows time.

The system timer eventually overflows and resets to zero.


GetCursorPos
────────────────────────────────────────────────────────────────────────────


Syntax

  void GetCursorPos(lpPoint)

This function retrieves the cursor's current position (in screen
coordinates), that copies them to the POINT structure pointed to by the
lpPoint parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPoint                           LPPOINT Points to the POINT structure
                                  that is to receive the screen
                                  coordinates of the cursor.



Return Value

None


Comments

The cursor position is always given in screen coordinates and is not
affected by the mapping mode of the window that contains the cursor.


GetDC
────────────────────────────────────────────────────────────────────────────


Syntax

  HDC GetDC(hWnd)

This function retrieves a handle to a display context for the client area of
the given window. The display context can be used in subsequent GDI
functions to draw in the client area.

The GetDC function retrieves a common, class, or private display context
depending on the class style specified for the given window. For common
display contexts, GetDC assigns default attributes to the context each time
it is retrieved. For class and private contexts, GetDC leaves the previously
assigned attributes unchanged.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND Identifies the window whose display
                                  context is to be retrieved.



Return Value

The return value identifies the display context for the given window's
client area if the function is successful. Otherwise, it is NULL.


Comments

After painting with a common display context, the ReleaseDC function must be
called to release the context. Class and private display contexts do not
have to be released. Since only five common display contexts are available
at any given time, failure to release a display context can prevent other
applications from accessing a display context.


GetDCOrg
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD GetDCOrg(hDC)

This function obtains the final translation origin for the device context.
The final translation origin specifies the offset used by Windows to
translate device coordinates into client coordinates for points in an
application's window. The final translation origin is relative to the
physical origin of the screen display.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context whose
                                  origin is to be retrieved.



Return Value

The return value specifies the final translation origin (in device
coordinates). The y-coordinate is in the high-order word; the x-coordinate
is in the low-order word.


GetDesktopWindow
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HWND  GetDesktopWindow()

This function returns the window handle to the Windows desktop window. The
desktop window covers the entire screen and is the area on top of which all
icons and other windows are painted.

This function has no parameters.


Return Value

The return value identifies the Windows desktop window.


GetDeviceCaps
────────────────────────────────────────────────────────────────────────────


Syntax

  int GetDeviceCaps(hDC, nIndex)

This function retrieves device-specific information about a given display
device. The nIndex parameter specifies the type of information desired.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC Identifies the device context.

nIndex                            int Specifies the item to return. It can
                                  be any one of the values given in Table
                                  .9, "GDI Information Indexes."



Return Value

The return value specifies the value of the desired item.


Comments

Table  lists the values for the nIndex parameter:

Table   GDI Information Indexes

╓┌──────────────┌──────────────────────────────────────────┌─────────────────╖
Index          Meaning
Index          Meaning
────────────────────────────────────────────────────────────────────────────
DRIVERVERSION  Version number; for example, 0x100 for
               1.0.

TECHNOLOGY     Device technology. It can be any one of
               the following values:

               Value                                      Meaning

               DT_PLOTTER                                 Vector plotter

               DT_RASDISPLAY                              Raster display

               DT_RASPRINTER                              Raster printer

               DT_RASCAMERA                               Raster camera

               DT_CHARSTREAM                              Character stream

               DT_METAFILE                                Metafile
Index          Meaning
────────────────────────────────────────────────────────────────────────────
               DT_METAFILE                                Metafile

               DT_DISPFILE                                Display file

HORZSIZE       Width of the physical display (in
               millimeters).

VERTSIZE       Height of the physical display (in
               millimeters).

HORZRES        Width of the display (in pixels).

VERTRES        Height of the display (in raster lines).

LOGPIXELSX     Number of pixels per logical inch along
               the display width.

LOGPIXELSY     Number of pixels per logical inch along
               the display height.
Index          Meaning
────────────────────────────────────────────────────────────────────────────
               the display height.

BITSPIXEL      Number of adjacent color bits for each
               pixel.

PLANES         Number of color planes.

NUMBRUSHES     Number of device-specific brushes.

NUMPENS        Number of device-specific pens.

NUMFONTS       Number of device-specific fonts.

NUMCOLORS      Number of entries in the device's color
               table.

ASPECTX        Relative width of a device pixel as used
               for line drawing.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

ASPECTY        Relative height of a device pixel as used
               for line drawing.

ASPECTXY       Diagonal width of the device pixel as
               used for line drawing.

PDEVICESIZE    Size of the PDEVICE internal data
               structure.

CLIPCAPS       Flag that indicates the clipping
               capabilities of the device. It is 1 if
               the device can clip to a rectangle, 0 if
               it cannot.

SIZEPALETTE    Number of entries in the system palette.
               This index is valid only if the device
               driver sets the RC_PALETTE bit in the
               RASTERCAPS index and is available only if
Index          Meaning
────────────────────────────────────────────────────────────────────────────
               RASTERCAPS index and is available only if
               the driver version is 3.0 or higher.



Table   GDI Information Indexes (continued)

╓┌──────────────┌─────────────────────────────┌──────────────────────────────╖
Index          Meaning
────────────────────────────────────────────────────────────────────────────
NUMRESERVED    Number of reserved entries
               in the system palette. This
               index is valid only if the
               device driver sets the
               RC_PALETTE bit in the
               RASTERCAPS index and is
               available only if the driver
               version is 3.0 or higher.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

COLORRES       Actual color resolution of
               the device in bits per pixel.
               This index is valid only if
               the device driver sets the
               RC_PALETTE bit in the
               RASTERCAPS index and is
               available only if the driver
               version is 3.0 or higher.

RASTERCAPS     Value that indicates the
               raster capabilities of the
               device, as shown in the
               following list:

               Capability                    Meaning

               RC_BANDING                    Requires banding support.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

               RC_BITBLT                     Capable of transferring
                                             bitmaps.

               RC_BITMAP64                   Capable of supporting bitmaps
                                             larger than 64K.

               RC_DI_BITMAP                  Capable of supporting
                                             SetDIBits and GetDIBits.

               RC_DIBTODEV                   Capable of supporting the
                                             SetDIBitsToDevice function.

               RC_FLOODFILL                  Capable of performing flood
                                             fills.

               RC_GDI20_OUTPUT               Capable of supporting Windows
                                             version 2.0 features.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

               RC_PALETTE                    Palette-based device.

               RC_SCALING                    Capable of scaling.

               RC_STRETCHBLT                 Capable of performing the
                                             StretchBlt function.

               RC_STRETCHDIB                 Capable of performing the
                                             StretchDIBits function.

CURVECAPS      A bitmask that indicates the
               curve capabilities of the
               device. The bits have the
               following meanings:

               Bit                           Meaning

               0                             Device can do circles.
Index          Meaning
────────────────────────────────────────────────────────────────────────────
               0                             Device can do circles.

               1                             Device can do pie wedges.

               2                             Device can do chord arcs.

               3                             Device can do ellipses.

               4                             Device can do wide borders.

               5                             Device can do styled borders.

               6                             Device can do borders that
                                             are wide and styled.

               7                             Device can do interiors.

               The high byte is 0.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

LINECAPS       A bitmask that indicates the
               line capabilities of the
               device. The bits have the
               following meanings:

               Bit                           Meaning

               0                             Reserved.

               1                             Device can do polyline.

               2                             Reserved.

               3                             Reserved.

               4                             Device can do wide lines.

               5                             Device can do styled lines.
Index          Meaning
────────────────────────────────────────────────────────────────────────────
               5                             Device can do styled lines.

               6                             Device can do lines that are
                                             wide and styled.

               7                             Device can do interiors.

               The high byte is 0.

POLYGONALCAPS  A bitmask that indicates the
               polygonal capabilities of
               the device. The bits have
               the following meanings:

               Bit                           Meaning

               0                             Device can do alternate fill
                                             polygon.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

               1                             Device can do rectangle.

               2                             Device can do winding number
                                             fill polygon.

               3                             Device can do scanline.

               4                             Device can do wide borders.

               5                             Device can do styled borders.

               6                             Device can do borders that
                                             are wide and styled.

               7                             Device can do interiors.

               The high byte is 0.

Index          Meaning
────────────────────────────────────────────────────────────────────────────

TEXTCAPS       A bitmask that indicates the
               text capabilities of the
               device. The bits have the
               following meanings:

               Bit                           Meaning

               0                             Device can do character
                                             output precision.

               1                             Device can do stroke output
                                             precision.

               2                             Device can do stroke clip
                                             precision.

               3                             Device can do 90-degree
                                             character rotation.
Index          Meaning
────────────────────────────────────────────────────────────────────────────
                                             character rotation.

               4                             Device can do any character
                                             rotation.

               5                             Device can do scaling
                                             independent of X and Y.

               6                             Device can do doubled
                                             character for scaling.

               7                             Device can do integer
                                             multiples for scaling.

               8                             Device can do any multiples
                                             for exact scaling.

               9                             Device can do double-weight
                                             characters.
Index          Meaning
────────────────────────────────────────────────────────────────────────────
                                             characters.

               10                            Device can do italicizing.

               11                            Device can do underlining.

               12                            Device can do strikeouts.

               13                            Device can do raster fonts.

               14                            Device can do vector fonts.

               15                            Reserved. Must be returned
                                             zero.

────────────────────────────────────────────────────────────────────────────



For a list of all the available abilities, see the LOGFONT data structure in
Chapter 7, "Data Types and Structures," in Reference, Volume 2.


GetDialogBaseUnits
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  LONG  GetDialogBaseUnits()

This function returns the dialog base units used by Windows when creating
dialog boxes. An application should use these values to calculate the
average width of characters in the system font.

This function has no parameters.


Return Value

The return value specifies the dialog base units. The high-order word
contains the height in pixels of the current dialog base height unit derived
from the height of the system font, and the low-order word contains the
width in pixels of the current dialog base width unit derived from the width
of the system font.


Comments

The values returned represent dialog base units before being scaled to
actual dialog units. The actual dialog unit in the x direction is 1/4 of the
width returned by GetDialogBaseUnits. The actual dialog unit in the y
direction is 1/8 of the height returned by the function.

To determine the actual height and width in pixels of a control, given the
height (x) and width (y) in dialog units and the return value
(lDlgBaseUnits) from calling GetDialogBaseUnits, use the following formula:


  (x * LOWORD(lDlgBaseUnits))/4
  (y * HIWORD(lDlgBaseUnits))/8

To avoid rounding problems, perform the multiplication before the division
in case the dialog base units are not evenly divisible by four.


GetDIBits
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetDIBits(hDC, hBitmap, nStartScan,
  nNumScans, lpBits, lpBitsInfo, wUsage)

This function retrieves the bits of the specified bitmap and copies them, in
device-independent format, into the buffer that is pointed to by the lpBits
parameter. The lpBitsInfo parameter retrieves the color format for the
device-independent bits.

╓┌────────────┌──────────────────────────────┌───────────────────────────────╖
Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hDC          HDC  Identifies the device
             context.

hBitmap      HBITMAP  Identifies the
             bitmap.

nStartScan   WORD  Specifies the first
             scan line in the destination
             bitmap to set in lpBits.

nNumScans    WORD  Specifies the number of
             lines to be copied.

lpBits       LPSTR  Points to a buffer
             that will receive the bitmap
             bits in device-independent
             format.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────

lpBitsInfo   LPBITMAPINFO  Points to a
             BITMAPINFO data structure
             that specifies the color
             format and dimension for the
             device-independent bitmap.

wUsage       WORD  Specifies whether the
             bmiColors[ ] fields of the
             lpBitsInfo parameter are to
             contain explicit RGB values
             or indexes into the currently
             realized logical palette. The
             wUsage parameter must be one
             of the following values:

             Value                          Meaning

             DIB_PAL_COLORS                 The color table is to consist
Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
             DIB_PAL_COLORS                 The color table is to consist
                                            of an array of 16-bit indexes
                                            into the currently realized
                                            logical palette.

             DIB_RGB_COLORS                 The color table is to contain
                                            literal RGB values.




Return Value

The return value specifies the number of scan lines copied from the bitmap.
It is zero if there was an error.


Comments

If the lpBits parameter is NULL, GetDIBits fills in the BITMAPINFO data
structure to which the lpBitsInfo parameter points, but does not retrieve
bits from the bitmap.

The bitmap identified by the hBitmap parameter must not be selected into a
device context when the application calls this function.

The origin for device-independent bitmaps is the bottom-left corner of the
bitmap, not the top-left corner, which is the origin when the mapping mode
is MM_TEXT.

This function also retrieves a bitmap specification formatted for Microsoft
OS/2 Presentation Manager versions 1.1 and 1.2 if the lpBitsInfo parameter
points to a BITMAPCOREINFO data structure.


GetDlgCtrlID
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetDlgCtrlID(hWnd)

This function returns the ID value of the child window identified by the
hWnd parameter.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                HWND  Identifies the child window.


Return Value

The return value is the numeric identifier of the child window if the
function is successful. If the function fails, or if hWnd is not a valid
window handle, the return value is NULL.


Comments

Since top-level windows do not have an ID value, the return value of this
function is invalid if the hWnd parameter identifies a top-level window.


GetDlgItem
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND GetDlgItem(hDlg, nIDDlgItem)

This function retrieves the handle of a control contained in the dialog box
specified by the hDlg parameter.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg         HWND  Identifies the dialog box that contains the control.
nIDDlgItem   int  Specifies the integer ID of the item to be retrieved.


Return Value

The return value identifies the given control. It is NULL if no control with
the integer ID given by the nIDDlgItem parameter exists.


Comments

The GetDlgItem function can be used with any parent-child window pair, not
just dialog boxes. As long as the hDlg parameter specifies a parent window
and the child window has a unique ID (as specified by the hMenu parameter in
the CreateWindow function that created the child window), GetDlgItem returns
a valid handle to the child window.


GetDlgItemInt
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetDlgItemInt(hDlg, nIDDlgItem, lpTranslated, bSigned)

This function translates the text of a control in the given dialog box into
an integer value. The GetDlgItemInt function retrieves the text of the
control identified by the nIDDlgItem parameter. It translates the text by
stripping any extra spaces at the beginning of the text and converting
decimal digits, stopping the translation when it reaches the end of the text
or encounters any nonnumeric character. If the bSigned parameter is nonzero,
GetDlgItemInt checks for a minus sign (-) at the beginning of the text and
translates the text into a signed number. Otherwise, it creates an unsigned
value.

GetDlgItemInt returns zero if the translated number is greater than 32,767
(for signed numbers) or 65,535 (for unsigned). When errors occur, such as
encountering nonnumeric characters and exceeding the given maximum,
GetDlgItemInt copies zero to the location pointed to by the lpTranslated
parameter. If there are no errors, lpTranslated receives a nonzero value. If
lpTranslated is NULL, GetDlgItemInt does not warn about errors.
GetDlgItemInt sends a WM_GETTEXT message to the control.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box.

nIDDlgItem                        int  Specifies the integer identifier of
                                  the dialog-box item to be translated.

lpTranslated                      BOOL FAR *  Points to the Boolean
                                  variable that is to receive the
                                  translated flag.

bSigned                           BOOL  Specifies whether the value to be
                                  retrieved is signed.



Return Value

The return value specifies the translated value of the dialog-box item text.
Since zero is a valid return value, the lpTranslated parameter must be used
to detect errors. If a signed return value is desired, it should be cast as
an int type.


GetDlgItemText
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetDlgItemText(hDlg, nIDDlgItem, lpString, nMaxCount)

This function retrieves the caption or text associated with a control in a
dialog box. The GetDlgItemText function copies the text to the location
pointed to by the lpString parameter and returns a count of the number of
characters it copies.

GetDlgItemText sends a WM_GETTEXT message to the control.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box that
                                  contains the control.

nIDDlgItem                        int  Specifies the integer identifier of
                                  the dialog-box item whose caption or
                                  text is to be retrieved.

lpString                          LPSTR  Points to the buffer to receive
                                  the text.

nMaxCount                         int  Specifies the maximum length (in
                                  bytes) of the string to be copied to
                                  lpString. If the string is longer than
                                  nMaxCount, it is truncated.



Return Value

The return value specifies the actual number of characters copied to the
buffer. It is zero if no text is copied.


GetDOSEnvironment
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  LPSTR  GetDOSEnvironment( )

This function returns a far pointer to the environment string of the
currently running task. See Microsoft MS-DOS Programmer's Reference for more
information on the format and contents of the environment string.

This function has no parameters.


Comments

Unlike an application, a dynamic-link library (DLL) does not have a copy of
the environment string. As a result, a library must call this function to
retrieve the environment string.


GetDoubleClickTime
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetDoubleClickTime( )

This function retrieves the current double-click time for the mouse. A
double-click is a series of two clicks of the mouse button, the second
occurring within a specified time after the first. The double-click time is
the maximum number of milliseconds that may occur between the first and
second click of a double-click.

This function has no parameters.


Return Value

The return value specifies the current double-click time (in milliseconds).



GetDriveType
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetDriveType(nDrive)

This function determines whether a disk drive is removeable, fixed, or
remote.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nDrive                            int  Specifies the drive for which the
                                  type is to be determined. Drive A: is 0,
                                  drive B: is 1, drive C: is 2, and so on.



Return Value

The return value specifies the type of drive. It can be one of the following
values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
DRIVE_REMOVEABLE                  Disk can be removed from the drive.

DRIVE_FIXED                       Disk cannot be removed from the drive.

DRIVE_REMOTE                      Drive is a remote (network) drive.

The return value is zero if the function cannot determine the drive type, or
1 if the specified drive does not exist.


GetEnvironment
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetEnvironment(lpPortName, lpEnviron, nMaxCount)

This function retrieves the current environment that is associated with the
device attached to the system port specified by the lpPortName parameter,
and copies it into the buffer specified by the lpEnviron parameter. The
environment, maintained by GDI, contains binary data used by GDI whenever a
device context is created for the device on the given port.

The function fails if there is no environment for the given port.

An application can call this function with the lpEnviron parameter set to
NULL to determine the size of the buffer required to hold the environment.
It can then allocate the buffer and call GetEnvironment a second time to
retrieve the environment.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPortName                        LPSTR  Points to the null-terminated
                                  character string that specifies the name
                                  of the desired port.

lpEnviron                         LPSTR  Points to the buffer that will
                                  receive the environment.

nMaxCount                         WORD  Specifies the maximum number of
                                  bytes to copy to the buffer.



Return Value

The return value specifies the number of bytes copied to lpEnviron. If
lpEnviron is NULL, the return value is the size in bytes of the buffer
required to hold the environment. It is zero if the environment cannot be
found.


Comments

The first field in the buffer pointed to by lpEnviron must be the same as
that passed in the lpDeviceName parameter of the CreateDC function. If
lpPortName specifies a null port (as defined in the WIN.INI file), the
device name pointed to by lpEnviron is used to locate the desired
environment.


GetFocus
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetFocus( )

This function retrieves the handle of the window that currently owns the
input focus.

This function has no parameters.


Return Value

The return value identifies the window that currently owns the focus if the
function is successful. Otherwise, it is NULL.


GetFreeSpace
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  DWORD  GetFreeSpace(wFlags)

This function scans the global heap and returns the number of bytes of
memory currently available.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
wFlags                            WORD  Specifies whether to scan the heap
                                  above or below the EMS bank line in
                                  large-frame and small-frame EMS systems.
                                  If it is set to GMEM_NOT_BANKED,
                                  GetFreeSpace returns the amount of
                                  memory available below the line. If
                                  wFlags is zero, GetFreeSpace returns the
                                  amount is the memory available above the
                                  EMS bank line. The wFlags parameter is
                                  ignored for non-EMS systems.



Return Value

The return value is the amount of available memory in bytes. This memory is
not necessarily contiguous; the GlobalCompact function returns the number of
bytes in the largest block of free global memory.


GetGValue
────────────────────────────────────────────────────────────────────────────


Syntax

  BYTE  GetGValue(rgbColor)

This macro extracts the green value from an RGB color value.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
rgbColor                          DWORD  Specifies a red, a green, and a
                                  blue color field, each specifying the
                                  intensity of the given color.



Return Value

The return value specifies a byte that contains the green value of the
rgbColor parameter.


Comments

The value 0FFH corresponds to the maximum intensity value for a single byte;
000H corresponds to the minimum intensity value for a single byte.


GetInputState
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  GetInputState( )

This function determines whether there are mouse, keyboard, or timer events
in the system queue that require processing. An event is a record that
describes interrupt-level input. Mouse events occur when a user moves the
mouse or clicks a mouse button. Keyboard events occur when a user presses
one or more keys. Timer events occur after a specified number of clock
ticks. The system queue is the location in which Windows stores mouse,
keyboard, and timer events.

This function has no parameters.


Return Value

The return value specifies whether mouse, keyboard or timer input occurs. It
is nonzero if input is detected. Otherwise, it is zero.


GetInstanceData
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetInstanceData(hInstance, pData, nCount)

This function copies data from a previous instance of an application into
the data area of the current instance. The hInstance parameter specifies
which instance to copy data from, pData specifies where to copy the data,
and nCount specifies the number of bytes to copy.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hInstance    HANDLE  Identifies a previous call of the application.
pData        NPSTR  Points to a buffer in the current instance.
nCount       int  Specifies the number of bytes to copy.


Return Value

The return value specifies the number of bytes actually copied.


GetKBCodePage
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetKBCodePage( )

This function determines which OEM/ANSI tables are loaded by Windows.

This function has no parameters.


Return Value

The return value specifies the code page currently loaded by Windows. It can
be one of the following values:

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
437                               Default (USA, used by most countries:
                                  indicates that there is no OEMANSI.BIN
                                  in the Windows directory)
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  in the Windows directory)

850                               International (OEMANSI.BIN = XLAT850.BIN)

860                               Portugal (OEMANSI.BIN = XLAT860.BIN)

861                               Iceland (OEMANSI.BIN = XLAT861.BIN)

863                               French Canadian (OEMANSI.BIN =
                                  XLAT863.BIN)

865                               Norway/Denmark (OEMANSI.BIN =
                                  XLAT865.BIN)




Comments

If the file OEMANSI.BIN is in the Windows directory, Windows reads it and
overwrites the OEM/ANSI translation tables in the keyboard driver.

When the user selects a language within the Setup program and the language
does not use the default code page (437), Setup copies the appropriate file
(such as XLATPO.BIN) to OEMANSI.BIN in the Windows system directory. If the
language uses the default code page, Setup deletes OEMANSI.BIN, if it
exists, from the Windows system directory.


GetKeyboardState
────────────────────────────────────────────────────────────────────────────


Syntax

  void  GetKeyboardState(lpKeyState)

This function copies the status of the 256 virtual-keyboard keys to the
buffer specified by the lpKeyState parameter. The high bit of each byte is
set to 1 if the key is down, or it is set to 0 if it is up. The low bit is
set to 1 if the key was pressed an odd number of times since startup.
Otherwise, it is set to 0.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpKeyState                        BYTE FAR *  Points to the 256-byte
                                  buffer of virtual-key codes.



Return Value

None.


Comments

An application calls the GetKeyboardState function in response to a
keyboard-input message. This function retrieves the state of the keyboard
when the input message was generated.

To obtain state information for individual keys, follow these steps:


  1.  Create an array of characters that is 265 bytes long.

  2.  Copy the contents of the buffer pointed to by the lpKeyState parameter
      into the array.

  3.  Use the virtual-key code from Appendix A, "Virtual-Key Codes," in
      Reference, Volume 2, to obtain an individual key state.



GetKeyboardType
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetKeyboardType(nTypeFlag)

This function retrieves the system-keyboard type.

Parameter  Type/Description
────────────────────────────────────────────────────────────────────────────
nTypeFlag  int  Determines whether the
           function returns a value
           indicating the type or subtype
           of the keyboard. It may be one
           of the following values:

           Value                           Meaning

           0                               Function returns the keyboard
                                           type.

           1                               Function returns the keyboard
                                           subtype.

           2                               Function returns the number of
                                           function keys on the keyboard.



Return Value

The return value indicates the type or subtype of the system keyboard or the
number of function keys on the keyboard. The subtype is an OEM-dependent
value. The type may be one of the following values:

╓┌───────────┌───────────────────────────────────────────────────────────────╖
Value       Meaning
────────────────────────────────────────────────────────────────────────────
1           IBM(R) PC/XT(tm), or compatible (83-key) keyboard
2           Olivetti(R) M24 "ICO" (102-key) keyboard
3           IBM AT(R) (84-key) or similar keyboard
4           IBM Enhanced (101- or 102-key) keyboard
5           Nokia 1050 and similar keyboards
6           Nokia 9140 and similar keyboards


The return value is zero if the nTypeFlag parameter is greater than 2 or if
the function fails.


Comments

An application can determine the number of function keys on a keyboard from
the keyboard type. The following shows the number of function keys for each
keyboard type:

╓┌───────────────────┌───────────────────────────────────────────────────────╖
Type                Number of Function Keys
────────────────────────────────────────────────────────────────────────────
1                   10
2                   12 (sometimes 18)
3                   10
4                   12
5                   10
6                   24



GetKeyNameText
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetKeyNameText(lParam, lpBuffer, nSize)

This function retrieves a string which contains the name of a key.

The keyboard driver maintains a list of names in the form of character
strings for keys with names longer than a single character. The key name is
translated according to the layout of the currently installed keyboard. The
translation is performed for the principal language supported by the
keyboard driver.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lParam                            DWORD  Specifies the 32-bit parameter of
                                  the keyboard message (such as WM_KEYDOWN)
                                  which the function is processing. Byte 3
                                  (bits 16-23) of the long parameter is a
                                  scan code. Bit 20 is the extended bit
                                  that distinguishes some keys on an
                                  enhanced keyboard. Bit 21 is a "don't
                                  care" bit; the application calling this
                                  function sets this bit to indicate that
                                  the function should not distinguish
                                  between left and right control and shift
                                  keys, for example.

lpBuffer                          LPSTR  Specifies a buffer to receive the
                                  key name.

nSize                             WORD  Specifies the maximum length in
                                  bytes of the key name, not including the
                                  terminating NULL character.



Return Value

The return value is the actual length of the string copied to lpBuffer.


GetKeyState
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetKeyState(nVirtKey)

This function retrieves the state of the virtual key specified by the
nVirtKey parameter. The state specifies whether the key is up, down, or
toggled.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nVirtKey                          int  Specifies a virtual key. If the
                                  desired virtual key is a letter or digit
                                  (A through Z, a through z, or 0 through
                                  9), nVirtKey must be set to the ASCII
                                  value of that character. For other keys,
                                  it must be one of the values listed in
                                  Appendix A, "Virtual-Key Codes," in
                                  Reference, Volume 2.



Return Value

The return value specifies the state of the given virtual key. If the
high-order bit is 1, the key is down. Otherwise, it is up. If the low-order
bit is 1, the key is toggled. A toggle key, such as the CAPSLOCK key, is
toggled if it has been pressed an odd number of times since the system was
started. The key is untoggled if the low bit is 0.


Comments

An application calls the GetKeyState function in response to a
keyboard-input message. This function retrieves the state of the key when
the input message was generated.


GetLastActivePopup
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  HWND  GetLastActivePopup(hwndOwner)

This function determines which pop-up window owned by the window identified
by the hwndOwner parameter was most recently active.

Parameter          Type/Description
────────────────────────────────────────────────────────────────────────────
hwndOwner          HWND  Identifies the owner window.


Return Value

The return value identifies the most-recently active pop-up window. The
return value will be hwndOwner if any of the following conditions are met:


  ■   The window identified by hwndOwner itself was most recently active.

  ■   The window identified by hwndOwner does not own any pop-up windows.

  ■   The window identified by hwndOwner is not a top-level window or is
      owned by another window.



GetMapMode
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetMapMode(hDC)

This function retrieves the current mapping mode. See the SetMapMode
function, later in this chapter, for a description of the mapping modes.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC  Identifies the device context.


Return Value

The return value specifies the mapping mode.


GetMenu
────────────────────────────────────────────────────────────────────────────


Syntax

  HMENU  GetMenu(hWnd)

This function retrieves a handle to the menu of the specified window.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND  Identifies the window whose menu is to be examined.


Return Value

The return value identifies the menu. It is NULL if the given window has no
menu. The return value is undefined if the window is a child window.


GetMenuCheckMarkDimensions
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  DWORD  GetMenuCheckMarkDimensions()

This function returns the dimensions of the default checkmark bitmap.
Windows displays this bitmap next to checked menu items. Before calling the
SetMenuItemBitmaps function to replace the default checkmark, an application
should call the GetMenuCheckMarkDimensions function to determine the correct
size for the bitmaps.

This function has no parameters.


Return Value

The return value specifies the height and width of the default checkmark
bitmap. The high-order word contains the height in pixels and the low-order
word contains the width.


GetMenuItemCount
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetMenuItemCount(hMenu)

This function determines the number of items in the menu identified by the
hMenu parameter. This may be either a pop-up or a top-level menu.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu        HMENU  Identifies the handle to the menu to be examined.


Return Value

The return value specifies the number of items in the menu specified by the
hMenu parameter if the function is successful. Otherwise, it is -1.


GetMenuItemID
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetMenuItemID(hMenu, nPos)

This function obtains the menu-item identifier for a menu item located at
the position defined by the nPos parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu                             HMENU  Identifies a handle to the pop-up
                                  menu that contains the item whose ID is
                                  being retrieved.

nPos                              int  Specifies the position (zero-based)
                                  of the menu item whose ID is being
                                  retrieved.



Return Value

The return value specifies the item ID for the specified item in a pop-up
menu if the function is successful; if hMenu is NULL or if the specified
item is a pop-up menu (as opposed to an item within the pop-up menu), the
return value is -1.


GetMenuState
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetMenuState(hMenu, wId, wFlags)

This function obtains the number of items in the pop-up menu associated with
the menu item specified by the wId parameter if the hMenu parameter
identifies a menu with an associated pop-up menu. If hMenu identifies a
pop-up menu, this function obtains the status of the menu item associated
with wId.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu                             HMENU  Identifies the menu.

wId                               WORD  Specifies the menu-item ID.

wFlags                            WORD  Specifies the nature of the wId
                                  parameter. If the wFlags parameter
                                  contains MF_BYPOSITION, wId specifies a
                                  (zero-based) relative position; if
                                  wFlags contains MF_BYCOMMAND, wId
                                  specifies the item ID.



Return Value

The return value specifies the outcome of the function. It is -1 if the
specified item does not exist. If the menu itself does not exist, a fatal
exit occurs. If wId identifies a pop-up menu, the return value contains the
number of items in the pop-up menu in its high-order byte, and the menu
flags associated with the pop-up menu in its low-order byte; otherwise, it
is a mask (Boolean OR) of the values from the following list (this mask
describes the status of the menu item that wId identifies):

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
MF_CHECKED                        Checkmark is placed next to item (pop-up
                                  menus only).

MF_DISABLED                       Item is disabled.

MF_ENABLED                        Item is enabled.

MF_GRAYED                         Item is disabled and grayed.

MF_MENUBARBREAK                   Same as MF_MENUBREAK, except for pop-up
                                  menus where the new column is separated
                                  from the old column by a vertical
                                  dividing line.
Value                             Meaning
────────────────────────────────────────────────────────────────────────────
                                  dividing line.

MF_MENUBREAK                      Item is placed on a new line (static
                                  menus) or in a new column (pop-up menus)
                                  without separating columns.

MF_SEPARATOR                      Horizontal dividing line is drawn
                                  (pop-up menus only). This line cannot be
                                  enabled, checked, grayed, or highlighted.
                                  The lpNewItem and wIDNewItem parameters
                                  are ignored.

MF_UNCHECKED                      Checkmark is not placed next to item
                                  (default).




GetMenuString
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetMenuString(hMenu, wIDItem, lpString,
  nMaxCount, wFlag)

This function copies the label of the specified menu item into the lpString
parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu                             HMENU  Identifies the menu.

wIDItem                           WORD  Specifies the integer identifier
                                  of the menu item (from the resource file)
                                  or the offset of the menu item in the
                                  menu, depending on the value of the
                                  wFlag parameter.

lpString                          LPSTR  Points to the buffer that is to
                                  receive the label.

nMaxCount                         int  Specifies the maximum length of the
                                  label to be copied. If the label is
                                  longer than the maximum specified in
                                  nMaxCount, the extra characters are
                                  truncated.

wFlag                             WORD  Specifies the nature of the wID
                                  parameter. If wFlags contains
                                  MF_BYPOSITION, wId specifies a
                                  (zero-based) relative position; if the
                                  wFlags parameter contains MF_BYCOMMAND,
                                  wId specifies the item ID.



Return Value

The return value specifies the actual number of bytes copied to the buffer.



Comments

The nMaxCount parameter should be one larger than the number of characters
in the label to accommodate the null character that terminates a string.





GetMessage
────────────────────────────────────────────────────────────────────────────


Syntax

  BOOL  GetMessage(lpMsg, hWnd, wMsgFilterMin, wMsgFilterMax)

This function retrieves a message from the application queue and places the
message in the data structure pointed to by the lpMsg parameter. If no
message is available, the GetMessage function yields control to other
applications until a message becomes available.

GetMessage retrieves only messages associated with the window specified by
the hWnd parameter and within the range of message values given by the
wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, GetMessage
retrieves messages for any window that belongs to the application making the
call. (The GetMessage function does not retrieve messages for windows that
belong to other applications.) If wMsgFilterMin and wMsgFilterMax are both
zero, GetMessage returns all available messages (no filtering is performed).


The constants WM_KEYFIRST and WM_KEYLAST can be used as filter values to
retrieve all messages related to keyboard input; the constants WM_MOUSEFIRST
and WM_MOUSELAST can be used to retrieve all mouse-related messages.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpMsg                             LPMSG  Points to an MSG data structure
                                  that contains message information from
                                  the Windows application queue.

hWnd                              HWND  Identifies the window whose
                                  messages are to be examined. If hWnd is
                                  NULL, GetMessage retrieves messages for
                                  any window that belongs to the
                                  application making the call.

wMsgFilterMin                     WORD  Specifies the integer value of the
                                  lowest message value to be retrieved.

wMsgFilterMax                     WORD  Specifies the integer value of the
                                  highest message value to be retrieved.



Return Value

The return value specifies the outcome of the function. It is nonzero if a
message other than WM_QUIT is retrieved. It is zero if the WM_QUIT message
is retrieved.

The return value is usually used to decide whether to terminate the
application's main loop and exit the program.


Comments

In addition to yielding control to other applications when no messages are
available, the GetMessage and PeekMessage functions also yield control when
WM_PAINT or WM_TIMER messages for other tasks are available.

The GetMessage, PeekMessage, and WaitMessage functions are the only ways to
let other applications run. If your application does not call any of these
functions for long periods of time, other applications cannot run.

When GetMessage, PeekMessage, and WaitMessage yield control to other
applications, the stack and data segments of the application calling the
function may move in memory to accommodate the changing memory requirements
of other applications. If the application has stored long pointers to
objects in the data or stack segment (that is, global or local variables),
these pointers can become invalid after a call to GetMessage, PeekMessage,
or WaitMessage. The lpMsg parameter of the called function remains valid in
any case.


GetMessagePos
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD  GetMessagePos( )

This function returns a long value that represents the cursor position (in
screen coordinates) when the last message obtained by the GetMessage
function occurred.

This function has no parameters.


Return Value

The return value specifies the x- and y-coordinates of the cursor position.
The x-coordinate is in the low-order word, and the y-coordinate is in the
high-order word. If the return value is assigned to a variable, the
MAKEPOINT macro can be used to obtain a POINT structure from the return
value; the LOWORD or HIWORD macro can be used to extract the x- or the
y-coordinate.


Comments

To obtain the current position of the cursor instead of the position when
the last message occurred, use the GetCursorPos function.


GetMessageTime
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD  GetMessageTime( )

This function returns the message time for the last message retrieved by the
GetMessage function. The time is a long integer that specifies the elapsed
time (in milliseconds) from the time the system was booted to the time the
message was created (placed in the application queue).

This function has no parameters.


Return Value

The return value specifies the message time.


Comments

Do not assume that the return value is always increasing. The return value
will "wrap around" to zero if the timer count exceeds the maximum value for
long integers.

To calculate time delays between messages, subtract the time of the second
message from the time of the first message.


GetMetaFile
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetMetaFile(lpFilename)

This function creates a handle for the metafile named by the lpFilename
parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpFilename                        LPSTR  Points to the null-terminated
                                  character string that specifies the DOS
                                  filename of the metafile. The metafile
                                  is assumed to exist.



Return Value

The return value identifies a metafile if the function is successful.
Otherwise, it is NULL.


GetMetaFileBits
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetMetaFileBits(hMF)

This function returns a handle to a global memory block that contains the
specified metafile as a collection of bits. The memory block can be used to
determine the size of the metafile or to save the metafile as a file. The
memory block should not be modified.

Parameter         Type/Description
────────────────────────────────────────────────────────────────────────────
hMF               HANDLE  Identifies the memory metafile.


Return Value

The return value identifies the global memory block that contains the
metafile. If an error occurs, the return value is NULL.


Comments

The handle used as the hMF parameter becomes invalid when the
GetMetaFileBits function returns, so the returned global memory handle must
be used to refer to the metafile.

Memory blocks created by this function are unique to the calling application
and are not shared by other applications. These blocks are automatically
deleted when the application terminates.


GetModuleFileName
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetModuleFileName(hModule, lpFilename, nSize)

This function retrieves the full pathname of the executable file from which
the specified module was loaded. The function copies the null-terminated
filename into the buffer pointed to by the lpFilename parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hModule                           HANDLE  Identifies the module or the
                                  instance of the module.

lpFilename                        LPSTR  Points to the buffer that is to
                                  receive the filename.

nSize                             int  Specifies the maximum number of
                                  characters to copy. If the filename is
                                  longer than the maximum number of
                                  characters specified by the nSize
                                  parameter, it is truncated.



Return Value

The return value specifies the actual length of the string copied to the
buffer.


GetModuleHandle
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetModuleHandle(lpModuleName)

This function retrieves the module handle of the specified module.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpModuleName                      LPSTR  Points to a null-terminated
                                  character string that specifies the
                                  module.



Return Value

The return value identifies the module if the function is successful.
Otherwise, it is NULL.


GetModuleUsage
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetModuleUsage(hModule)

This function returns the reference count of a specified module.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hModule     HANDLE  Identifies the module or an instance of the module.


Return Value

The return value specifies the reference count of the module.


GetNearestColor
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD  GetNearestColor(hDC, crColor)

This function returns the closest logical color to a specified logical color
the given device can represent.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hDC              HDC  Identifies the device context.
crColor          COLORREF  Specifies the color to be matched.


Return Value

The return value specifies an RGB color value that names the solid color
closest to the crColor value that the device can represent.


GetNearestPaletteIndex
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetNearestPaletteIndex(hPalette, crColor)

This function returns the index of the entry in a logical palette which most
closely matches a color value.

Parameter        Type/Description
────────────────────────────────────────────────────────────────────────────
hPalette         HPALETTE  Identifies the logical palette.
crColor          COLORREF  Specifies the color to be matched.


Return Value

The return value is the index of an entry in a logical palette. The entry
contains the color which most nearly matches the specified color.


GetNextDlgGroupItem
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetNextDlgGroupItem(hDlg, hCtl, bPrevious)

This function searches for the next (or previous) control within a group of
controls in the dialog box identified by the hDlg parameter. A group of
controls consists of one or more controls with WS_GROUP style.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box being
                                  searched.

hCtl                              HWND  Identifies the control in the
                                  dialog box where the search starts.

bPrevious                         BOOL  Specifies how the function is to
                                  search the group of controls in the
                                  dialog box. If the bPrevious parameter
                                  is zero, the function searches for the
                                  previous control in the group. If
                                  bPrevious is nonzero, the function
                                  searches for the next control in the
                                  group.



Return Value

The return value identifies the next or previous control in the group.


Comments

If the current item is the last item in the group and bPrevious is zero, the
GetNextDlgGroupItem function returns the window handle of the first item in
the group. If the current item is the first item in the group and bPrevious
is nonzero, GetNextDlgGroupItem returns the window handle of the last item
in the group.


GetNextDlgTabItem
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetNextDlgTabItem(hDlg, hCtl, bPrevious)

This function obtains the handle of the first control that has the
WS_TABSTOP style that precedes (or follows) the control identified by the
hCtl parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDlg                              HWND  Identifies the dialog box being
                                  searched.

hCtl                              HWND  Identifies the control to be used
                                  as a starting point for the search.

bPrevious                         BOOL  Specifies how the function is to
                                  search the dialog box. If the bPrevious
                                  parameter is zero, the function searches
                                  for the previous control in the dialog
                                  box. If bPrevious is nonzero, the
                                  function searches for the next control
                                  in the dialog box. Identifies the
                                  control to be used as a starting point
                                  for the search.



Return Value

The return value identifies the previous (or next) control that has the
WS_TABSTOP style set.


GetNextWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetNextWindow(hWnd, wFlag)

This function searches for a handle that identifies the next (or previous)
window in the window-manager's list. The window-manager's list contains
entries for all top-level windows, their associated child windows, and the
child windows of any child windows. If the hWnd parameter is a handle to a
top-level window, the function searches for the next (or previous) handle to
a top-level window; if hWnd is a handle to a child window, the function
searches for a handle to the next (or previous) child window.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND  Identifies the current
            window.

wFlag       WORD  Specifies whether the
            function returns a handle to
            the next window or to the
            previous window. It can be
            either of the following
            values:

            Value                           Meaning

            GW_HWNDNEXT                     The function returns a handle
                                            to the next window.

            GW_HWNDPREV                     The function returns a handle
                                            to the previous window.



Return Value

The return value identifies the next (or the previous) window in the
window-manager's list.


GetNumTasks
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetNumTasks( )

This function returns the number of tasks currently executing in the system.
A task is a unique instance of a Windows application.

This function has no parameters.


Return Value

The return value specifies an integer that represents the number of tasks
currently executing in the system.


GetObject
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetObject(hObject, nCount, lpObject)

This function fills a buffer with the logical data that defines the logical
object specified by the hObject parameter. The GetObject function copies the
number of bytes of data specified by the nCount parameter to the buffer
pointed to by the lpObject parameter. The function retrieves data structures
of the LOGPEN, LOGBRUSH, LOGFONT, or BITMAP type, or an integer, depending
on the logical object. The buffer must be sufficiently large to receive the
data.

If hObject specifies a bitmap, the function returns only the width, height,
and color format information of the bitmap. The actual bits must be
retrieved by using the GetBitmapBits function.

If hObject specifies a logical palette, it retrieves a two-byte value that
specifies the number of entries in the palette; it does not retrieve the
entire LOGPALETTE data structure that defines the palette. To get
information on palette entries, an application must call the
GetPaletteEntries function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hObject                           HANDLE  Identifies a logical pen, brush,
                                  font, bitmap, or palette.

nCount                            int  Specifies the number of bytes to be
                                  copied to the buffer.

lpObject                          LPSTR  Points to the buffer that is to
                                  receive the information.



Return Value

The return value specifies the actual number of bytes retrieved. It is zero
if an error occurs.


GetPaletteEntries
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetPaletteEntries(hPalette, wStartIndex,
  wNumEntries, lpPaletteEntries)

This function retrieves a range of palette entries in a logical palette.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hPalette                          HPALETTE  Identifies the logical palette.

wStartIndex                       WORD  Specifies the first entry in the
                                  logical palette to be retrieved.

wNumEntries                       WORD  Specifies the number of entries in
                                  the logical palette to be retrieved.

lpPaletteEntries                  LPPALETTEENTRY  Points to an array of
                                  PALETTEENTRY data structures to receive
                                  the palette entries. The array must
                                  contain at least as many data structures
                                  as specified by the wNumEntries
                                  parameter.



Return Value

The return value is the number of entries retrieved from the logical
palette. It is zero if the function failed.


GetParent
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetParent(hWnd)

This function retrieves the window handle of the specified window's parent
window (if any).

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window whose parent
                                  window handle is to be retrieved.



Return Value

The return value identifies the parent window. It is NULL if the window has
no parent window.


GetPixel
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD  GetPixel(hDC, X, Y)

This function retrieves the RGB color value of the pixel at the point
specified by the X and Y parameters. The point must be in the clipping
region. If the point is not in the clipping region, the function is ignored.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

X                                 int  Specifies the logical x-coordinate
                                  of the point to be examined.

Y                                 int  Specifies the logical y-coordinate
                                  of the point to be examined.



Return Value

The return value specifies an RGB color value for the color of the given
point. It is -1 if the coordinates do not specify a point in the clipping
region.


Comments

Not all devices support the GetPixel function. For more information, see the
RC_BITBLT raster capability in the GetDeviceCaps function, earlier in this
chapter.


GetPolyFillMode
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetPolyFillMode(hDC)

This function retrieves the current polygon-filling mode.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC  Identifies the device context.


Return Value

The return value specifies the polygon-filling mode. It can be any one of
the following values:

Value                    Meaning
────────────────────────────────────────────────────────────────────────────
ALTERNATE                Alternate mode
WINDING                  Winding-number mode

For a description of these modes, see the SetPolyFillMode function, later in
this chapter.


GetPriorityClipboardFormat
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetPriorityClipboardFormat(lpPriorityList, nCount)

This function returns the first clipboard format in a list for which data
exist in the clipboard.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpPriorityList                    WORD FAR *  Points to an integer array
                                  that contains a list of clipboard
                                  formats in priority order. For a
                                  description of the data formats, see the
                                  SetClipboardData function later in this
                                  chapter.

nCount                            int  Specifies the number of entries in
                                  lpPriorityList. This value must not be
                                  greater than the actual number of
                                  entries in the list.



Return Value

The return value is the highest priority clipboard format in the list for
which data exist. If no data exist in the clipboard, this function returns
NULL. If data exist in the clipboard which did not match any format in the
list, the return value is -1.


GetPrivateProfileInt
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetPrivateProfileInt(lpApplicationName, lpKeyName,
  nDefault, lpFileName)

This function retrieves the value of an integer key from the specified
initialization file.

The function searches the file for a key that matches the name specified by
the lpKeyName parameter under the application heading specified by the
lpApplicationName parameter. An integer entry in the initialization file
must have the following form:

  [application name]
  keyname = value
        .
        .
        .

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpApplicationName                 LPSTR  Points to the name of a Windows
                                  application that appears in the
                                  initialization file.

lpKeyName                         LPSTR  Points to a key name that appears
                                  in the initialization file.

nDefault                          int  Specifies the default value for the
                                  given key if the key cannot be found in
                                  the initialization file.

lpFileName                        LPSTR  Points to a string that names the
                                  initialization file. If lpFileName does
                                  not contain a path to the file, Windows
                                  searches for the file in the Windows
                                  directory.



Return Value

The return value specifies the result of the function. The return value is
zero if the value that corresponds to the specified key name is not an
integer or if the integer is negative. If the value that corresponds to the
key name consists of digits followed by nonnumeric characters, the function
returns the value of the digits. For example, if the entry KeyName=102abc is
accessed, the function returns 102. If the key is not found, this function
returns the default value, nDefault.


Comments

The GetPrivateProfileInt function is not case dependent, so the strings in
lpApplicationName and lpKeyName may be in any combination of uppercase and
lowercase letters.


GetPrivateProfileString
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetPrivateProfileString(lpApplicationName, lpKeyName,
  lpDefault, lpReturnedString, nSize, lpFileName)

This function copies a character string from the specified initialization
file into the buffer pointed to by the lpReturnedString parameter.

The function searches the file for a key that matches the name specified by
the lpKeyName parameter under the application heading specified by the
lpApplicationName parameter. If the key is found, the corresponding string
is copied to the buffer. If the key does not exist, the default character
string specified by the lpDefault parameter is copied. A string entry in the
initialization file must have the following form:

  [application name]
  keyname = string
        .
        .
        .

If lpKeyName is NULL, the GetPrivateProfileString function enumerates all
key names associated with lpApplicationName by filling the location pointed
to by lpReturnedString with a list of key names (not values). Each key name
in the list is terminated with a null character.

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpApplicationName                 LPSTR  Points to the name of a Windows
                                  application that appears in the
                                  initialization file.

lpKeyName                         LPSTR  Points to a key name that appears
                                  in the initialization file.

lpDefault                         LPSTR  Specifies the default value for
Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpDefault                         LPSTR  Specifies the default value for
                                  the given key if the key cannot be found
                                  in the initialization file.

lpReturnedString                  LPSTR  Points to the buffer that
                                  receives the character string.

nSize                             int  Specifies the maximum number of
                                  characters (including the last null
                                  character) to be copied to the buffer.

lpFileName                        LPSTR  Points to a string that names the
                                  initialization file. If lpFileName does
                                  not contain a path to the file, Windows
                                  searches for the file in the Windows
                                  directory.




Return Value

The return value specifies the number of characters copied to the buffer
identified by the lpReturnedString parameter, not including the terminating
null character. If the buffer is not large enough to contain the entire
string and lpKeyName is not NULL, the return value is equal to the length
specified by the nSize parameter. If the buffer is not large enough to
contain the entire string and lpKeyName is NULL, the return value is equal
to the length specified by the nSize parameter minus 2.


Comments

GetPrivateProfileString is not case dependent, so the strings in
lpApplicationName and lpKeyName may be in any combination of uppercase and
lowercase letters.


GetProcAddress
────────────────────────────────────────────────────────────────────────────


Syntax

  FARPROC  GetProcAddress(hModule, lpProcName)

This function retrieves the memory address of the function whose name is
pointed to by the lpProcName parameter. The GetProcAddress function searches
for the function in the module specified by the hModule parameter, or in the
current module if hModule is NULL. The function must be an exported
function; the module's definition file must contain an appropriate EXPORTS
line for the function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hModule                           HANDLE  Identifies the library module
                                  that contains the function.

lpProcName                        LPSTR  Points to the function name, or
                                  contains the ordinal value of the
                                  function. If it is an ordinal value, the
                                  value must be in the low-order word and
                                  zero must be in the high-order word. The
                                  string must be a null-terminated
                                  character string.



Return Value

The return value points to the function's entry point if the function is
successful. Otherwise, it is NULL.

If the lpProcName parameter is an ordinal value and a function with the
specified ordinal does not exist in the module, GetProcAddress can still
return a non-NULL value. In cases where the function may not exist, specify
the function by name rather than ordinal value.


Comments

Only use GetProcAddress to retrieve addresses of exported functions that
belong to library modules. The MakeProcInstance function can be used to
access functions within different instances of the current module.

The spelling of the function name (pointed to by lpProcName) must be
identical to the spelling as it appears in the source library's definition
(.DEF) file. The function can be renamed in the definition file.


GetProfileInt
────────────────────────────────────────────────────────────────────────────


Syntax

  WORD  GetProfileInt(lpAppName, lpKeyName, nDefault)

This function retrieves the value of an integer key from the Windows
initialization file, WIN.INI. The function searches WIN.INI for a key that
matches the name specified by the lpKeyName parameter under the application
heading specified by the lpAppName parameter. An integer entry in WIN.INI
must have the following form:

  [application name]
  keyname = value
  .
  .
  .

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpAppName                         LPSTR  Points to the name of a Windows
                                  application that appears in the Windows
                                  initialization file.

lpKeyName                         LPSTR  Points to a key name that appears
                                  in the Windows initialization file.

nDefault                          int  Specifies the default value for the
                                  given key if the key cannot be found in
                                  the Windows initialization file.



Return Value

The return value specifies the result of the function. The return value is
zero if the value that corresponds to the specified key name is not an
integer or if the integer is negative. If the value that corresponds to the
key name consists of digits followed by nonnumeric characters, the function
returns the value of the digits. For example, if the entry KeyName=102abc is
accessed, the function returns 102. If the key is not found, this function
returns the default value, nDefault.


GetProfileString
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetProfileString(lpAppName, lpKeyName,
  lpDefault, lpReturnedString, nSize)

This function copies a character string from the Windows initialization
file, WIN.INI, into the buffer pointed to by the lpReturnedString parameter.
The function searches WIN.INI for a key that matches the name specified by
the lpKeyName parameter under the application heading specified by the
lpAppName parameter. If the key is found, the corresponding string is copied
to the buffer. If the key does not exist, the default character string
specified by the lpDefault parameter is copied. A string entry in WIN.INI
must have the following form:

  [application name]
  keyname = value
  .
  .
  .

If lpKeyName is NULL, the GetProfileString function enumerates all key names
associated with lpAppName by filling the location pointed to by
lpReturnedString with a list of key names (not values). Each key name in the
list is terminated with a null character.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpAppName                         LPSTR  Points to a null-terminated
                                  character string that names the
                                  application.

lpKeyName                         LPSTR  Points to a null-terminated
                                  character string that names a key.

lpDefault                         LPSTR  Specifies the default value for
                                  the given key if the key cannot be found
                                  in the initialization file.

lpReturnedString                  LPSTR  Points to the buffer that
                                  receives the character string.

nSize                             int  Specifies the number of characters
                                  (including the last null character) that
                                  will be copied to the buffer.



Return Value

The return value specifies the number of characters copied to the buffer
identified by the lpReturnedString parameter, not including the terminating
null character. If the buffer is not large enough to contain the entire
string and lpKeyName is not NULL, the return value is equal to the length
specified by the nSize parameter. If the buffer is not large enough to
contain the entire string and lpKeyName is NULL, the return value is equal
to the length specified by the nSize parameter minus 2.


Comments

GetProfileString is not case-dependent, so the strings in lpAppName and
lpKeyName may be in any combination of uppercase and lowercase letters.


GetProp
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetProp(hWnd, lpString)

This function retrieves a data handle from the property list of the
specified window. The character string pointed to by the lpString parameter
identifies the handle to be retrieved. The string and handle are assumed to
have been added to the property list by using the SetProp function.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd                              HWND  Identifies the window whose
                                  property list is to be searched.

lpString                          LPSTR  Points to a null-terminated
                                  character string or an atom that
                                  identifies a string. If an atom is given,
                                  it must have been created previously by
                                  using the AddAtom function. The atom, a
                                  16-bit value, must be placed in the
                                  low-order word of the lpString
                                  parameter; the high-order word must be
                                  set to zero.



Return Value

The return value identifies the associated data handle if the property list
contains the given string. Otherwise, it is NULL.


Comments

The value retrieved by the GetProp function can be any 16-bit value useful
to the application.


GetRgnBox
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  int  GetRgnBox(hRgn, lpRect)

This function retrieves the coordinates of the bounding rectangle of the
region specified by the hRgn parameter.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hRgn                              HRGN  Identifies the region.

lpRect                            LPRECT  Points to a RECT data structure
                                  to receive the coordinates of the
                                  bounding rectangle.



Return Value

The return value specifies the region's type. It can be any of the following
values.

Value                  Meaning
────────────────────────────────────────────────────────────────────────────
COMPLEXREGION          Region has overlapping borders.
NULLREGION             Region is empty.
SIMPLEREGION           Region has no overlapping borders.

The return value is NULL if the hRgn parameter does not specify a valid
region.


GetROP2
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetROP2(hDC)

This function retrieves the current drawing mode. The drawing mode specifies
how the pen or interior color and the color already on the display surface
are combined to yield a new color.

Parameter    Type/Description
────────────────────────────────────────────────────────────────────────────
hDC          HDC  Identifies the device context for a raster device.


Return Value

The return value specifies the drawing mode. For a list of the drawing
modes, see Table 4.16, "Drawing Modes," in the SetROP2 function, later in
this chapter.


Comments

For more information about the drawing modes, see Chapter 11, "Binary and
Ternary Raster-Operation Codes," in Reference, Volume 2.


GetRValue
────────────────────────────────────────────────────────────────────────────


Syntax

  BYTE  GetRValue(rgbColor)

This macro extracts the red value from an RGB color value.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
rgbColor                          DWORD  Specifies a red, a green, and a
                                  blue color field, each specifying the
                                  intensity of the given color.



Return Value

The return value specifies a byte that contains the red value of the
rgbColor parameter.


Comments

The value 0FFH corresponds to the maximum intensity value for a single byte;
000H corresponds to the minimum intensity value for a single byte.


GetScrollPos
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetScrollPos(hWnd, nBar)

This function retrieves the current position of a scroll-bar thumb. The
current position is a relative value that depends on the current scrolling
range. For example, if the scrolling range is 0 to 100 and the thumb is in
the middle of the bar, the current position is 50.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND  Identifies a window that
            has standard scroll bars or a
            scroll-bar control, depending
            on the value of the nBar
            parameter.

nBar        int  Specifies the scroll bar
            to examine. It can be one of
            the following values:

            Value                           Meaning

            SB_CTL                          Retrieves the position of a
                                            scroll-bar control. In this
                                            case, the hWnd parameter must
                                            be the window handle of a
                                            scroll-bar control.
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            scroll-bar control.

            SB_HORZ                         Retrieves the position of a
                                            window's horizontal scroll bar.


            SB_VERT                         Retrieves the position of a
                                            window's vertical scroll bar.





Return Value

The return value specifies the current position of the scroll-bar thumb.


GetScrollRange
────────────────────────────────────────────────────────────────────────────


Syntax

  void  GetScrollRange(hWnd, nBar, lpMinPos, lpMaxPos)

This function copies the current minimum and maximum scroll-bar positions
for the given scroll bar to the locations specified by the lpMinPos and
lpMaxPos parameters. If the given window does not have standard scroll bars
or is not a scroll-bar control, then the GetScrollRange function copies zero
to lpMinPos and lpMaxPos.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND  Identifies a window that
            has standard scroll bars or a
            scroll-bar control, depending
            on the value of the nBar
            parameter.
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
            parameter.

nBar        int  Specifies an integer
            value that identifies which
            scroll bar to retrieve. It can
            be one of the following
            values:

            Value                           Meaning

            SB_CTL                          Retrieves the position of a
                                            scroll-bar control; in this
                                            case, the hWnd parameter must
                                            be the handle of a scroll-bar
                                            control.

            SB_HORZ                         Retrieves the position of a
                                            window's horizontal scroll bar.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────


            SB_VERT                         Retrieves the position of a
                                            window's vertical scroll bar.


lpMinPos    LPINT  Points to the integer
            variable that is to receive
            the minimum position.

lpMaxPos    LPINT  Points to the integer
            variable that is to receive
            the maximum position.




Return Value

None.


Comments

The default range for a standard scroll bar is 0 to 100. The default range
for a scroll-bar control is empty (both values are zero).


GetStockObject
────────────────────────────────────────────────────────────────────────────


Syntax

  HANDLE  GetStockObject(nIndex)

This function retrieves a handle to one of the predefined stock pens,
brushes, or fonts.

╓┌───────────┌───────────────────────────────┌───────────────────────────────╖
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
nIndex      int  Specifies the type of
            stock object desired. It can
            be any one of the following
            values:

            Value                           Meaning

            BLACK_BRUSH                     Black brush

            DKGRAY_BRUSH                    Dark gray brush

            GRAY_BRUSH                      Gray brush

            HOLLOW_BRUSH                    Hollow brush

            LTGRAY_BRUSH                    Light gray brush

            NULL_BRUSH                      Null brush

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────

            WHITE_BRUSH                     White brush

            BLACK_PEN                       Black pen

            NULL_PEN                        Null pen

            WHITE_PEN                       White pen

            ANSI_FIXED_FONT                 ANSI fixed system font

            ANSI_VAR_FONT                   ANSI variable system font

            DEVICE_DEFAULT_FONT             Device-dependent font

            OEM_FIXED_FONT                  OEM-dependent fixed font

            SYSTEM_FONT                     The system font. By default,
                                            Windows uses the system font
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            Windows uses the system font
                                            to draw menus, dialog-box
                                            controls, and other text. In
                                            Windows versions 3.0 and later,
                                            the system font is
                                            proportional width; earlier
                                            versions of Windows use a
                                            fixed-width system font.

            Value                           Meaning

            SYSTEM_FIXED_FONT               The fixed-width system font
                                            used in earlier versions of
                                            Windows. This stock object is
                                            available for compatibility
                                            purposes.

            DEFAULT_PALETTE                 Default color palette. This
                                            palette consists of the 20
Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
                                            palette consists of the 20
                                            static colors always present
                                            in the system palette for
                                            matching colors in the logical
                                            palettes of background
                                            windows.




Return Value

The return value identifies the desired logical object if the function is
successful. Otherwise, it is NULL.


Comments

The DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH objects should not be used as
background brushes or for any other purpose in a window whose class does not
specify CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in such
windows can lead to misalignment of brush patterns after a window is moved
or sized. Stock-brush origins cannot be adjusted (for more information, see
the SetBrushOrg function, later in this chapter).


GetStretchBltMode
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetStretchBltMode(hDC)

This function retrieves the current stretching mode. The stretching mode
defines how information is to be added or removed from bitmaps that are
stretched or compressed by using the StretchBlt function.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC  Identifies the device context.


Return Value

The return value specifies the current stretching mode. It can be
WHITEONBLACK, BLACKONWHITE, or COLORONCOLOR. For more information, see the
SetStretchBltMode function, later in this chapter.


GetSubMenu
────────────────────────────────────────────────────────────────────────────


Syntax

  HMENU  GetSubMenu(hMenu, nPos)

This function retrieves the menu handle of a pop-up menu.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hMenu                             HMENU  Identifies the menu.

nPos                              int  Specifies the position in the given
                                  menu of the pop-up menu. Position values
                                  start at zero for the first menu item.
                                  The pop-up menu's integer ID cannot be
                                  used in this function.



Return Value

The return value identifies the given pop-up menu. It is NULL if no pop-up
menu exists at the given position.


GetSysColor
────────────────────────────────────────────────────────────────────────────


Syntax

  DWORD  GetSysColor(nIndex)

This function retrieves the current color of the display element specified
by the nIndex parameter. Display elements are the various parts of a window
and the Windows display that appear on the system display screen.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nIndex                            int  Specifies the display element whose
                                  color is to be retrieved. For a list of
                                  the index values, see the SetSysColor
                                  function, later in this chapter.



Return Value

The return value specifies an RGB color value that names the color of the
given element.


Comments

System colors for monochrome displays are usually interpreted as various
shades of gray.


GetSysModalWindow
────────────────────────────────────────────────────────────────────────────


Syntax

  HWND  GetSysModalWindow( )

This function returns the handle of a system-modal window, if one is
present.

This function has no parameters.


Return Value

The return value identifies the system-modal window, if one is present. If
no such window is present, the return value is NULL.


GetSystemDirectory
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetSystemDirectory(lpBuffer, nSize)

This function obtains the pathname of the Windows system subdirectory. The
system subdirectory contains such files as Windows libraries, drivers, and
font files.

Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
lpBuffer                          LPSTR  Points to the buffer that is to
                                  receive the null-terminated character
                                  string containing the pathname.

nSize                             int  Specifies the maximum size (in
                                  bytes) of the buffer. This value should
                                  be set to at least 144 to allow
                                  sufficient room in the buffer for the
                                  pathname.



Return Value

The return value is the length of the string copied to lpBuffer, not
including the terminating null character. If the return value is greater
than nSize, the return value is the size of the buffer required to hold the
pathname. The return value is zero if the function failed.


Comments

The pathname retrieved by this function does not end with a backslash ( \ ),
unless the system directory is the root directory. For example, if the
system directory is named WINDOWS\SYSTEM on drive C:, the pathname of the
system subdirectory retrieved by this function is C:\WINDOWS\SYSTEM.


GetSystemMenu
────────────────────────────────────────────────────────────────────────────


Syntax

  HMENU  GetSystemMenu(hWnd, bRevert)

This function allows the application to access the System menu for copying
and modification.

Parameter   Type/Description
────────────────────────────────────────────────────────────────────────────
hWnd        HWND  Identifies the window
            that will own a copy of the
            System menu.

bRevert     BOOL  Specifies the action to
            be taken.

            If bRevert is:                  Description

            zero                            GetSystemMenu returns a handle
                                            to a copy of the System menu
                                            currently in use. This copy is
                                            initially identical to the
                                            System menu, but can be
                                            modified.

            nonzero                         GetSystemMenu destroys the
                                            possibly modified copy of the
                                            System menu (if there is one)
                                            that belongs to the specified
                                            window and returns a handle to
                                            the original, unmodified
                                            version of the System menu.



Return Value

The return value identifies the System menu if bRevert is nonzero and the
System menu has been modified. If bRevert is nonzero and the System menu has
not been modified, the return value is NULL. If bRevert is zero, the return
value identifies a copy of the System menu.


Comments

Any window that does not use the GetSystemMenu function to make its own copy
of the System menu receives the standard System menu.

The handle returned by the GetSystemMenu function can be used with the
AppendMenu, InsertMenu or ModifyMenu functions to change the System menu.
The System menu initially contains items identified with various ID values
such as SC_CLOSE, SC_MOVE, and SC_SIZE. Menu items on the System menu send
WM_SYSCOMMAND messages. All predefined System-menu items have ID numbers
greater than 0xF000. If an application adds commands to the System menu, it
should use ID numbers less than F000.

Windows automatically grays items on the standard System menu, depending on
the situation. The application can carry out its own checking or graying by
responding to the WM_INITMENU message, which is sent before any menu is
displayed.


GetSystemMetrics
────────────────────────────────────────────────────────────────────────────


Syntax

  int  GetSystemMetrics(nIndex)

This function retrieves the system metrics. The system metrics are the
widths and heights of various display elements of the Windows display. The
GetSystemMetrics function can also return flags that indicate whether the
current version is a debugging version, whether a mouse is present, or
whether the meaning of the left and right mouse buttons have been exchanged.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
nIndex                            int  Specifies the system measurement to
                                  be retrieved. All measurements are given
                                  in pixels. The system measurement must
                                  be one of the values listed in Table .10,
                                  "System Metric Indexes."



Return Value

The return value specifies the requested system metric.


Comments

System metrics depend on the system display and may vary from display to
display. Table  lists the system-metric values for the nIndex parameter:

Table   System Metric Indexes

╓┌────────────────┌──────────────────────────────────────────────────────────╖
Index            Meaning
────────────────────────────────────────────────────────────────────────────
SM_CXSCREEN      Width of screen.
SM_CYSCREEN      Height of screen.
SM_CXFRAME       Width of window frame that can be sized.
SM_CYFRAME       Height of window frame that can be sized.
SM_CXVSCROLL     Width of arrow bitmap on vertical scroll bar.
SM_CYVSCROLL     Height of arrow bitmap on vertical scroll bar.
SM_CXHSCROLL     Width of arrow bitmap on horizontal scroll bar.
SM_CYHSCROLL     Height of arrow bitmap on horizontal scroll bar.
SM_CYCAPTION     Height of caption.
SM_CXBORDER      Width of window frame that cannot be sized.
SM_CYBORDER      Height of window frame that cannot be sized.
SM_CXDLGFRAME    Width of frame when window has WS_DLGFRAME style.
Index            Meaning
────────────────────────────────────────────────────────────────────────────
SM_CXDLGFRAME    Width of frame when window has WS_DLGFRAME style.
SM_CYDLGFRAME    Height of frame when window has WS_DLGFRAME style.
SM_CXHTHUMB      Width of thumb box on horizontal scroll bar.
SM_CYVTHUMB      Height of thumb box on vertical scroll bar.


Table   System Metric Indexes (continued)

╓┌─────────────────────────────────┌─────────────────────────────────────────╖
Index                             Meaning
────────────────────────────────────────────────────────────────────────────
SM_CXICON                         Width of icon.

SM_CYICON                         Height of icon.

SM_CXCURSOR                       Width of cursor.

SM_CYCURSOR                       Height of cursor.

Index                             Meaning
────────────────────────────────────────────────────────────────────────────

SM_CYMENU                         Height of single-line menu bar.

SM_CXFULLSCREEN                   Width of window client area for
                                  full-screen window.

SM_CYFULLSCREEN                   Height of window client area for
                                  full-screen window (equivalent to the
                                  height of the screen minus the height of
                                  the window caption).

SM_CYKANJIWINDOW                  Height of Kanji window.

SM_CXMINTRACK                     Minimum tracking width of window.

SM_CYMINTRACK                     Minimum tracking height of window.

SM_CXMIN                          Minimum width of window.

Index                             Meaning
────────────────────────────────────────────────────────────────────────────

SM_CYMIN                          Minimum height of window.

SM_CXSIZE                         Width of bitmaps contained in the title
                                  bar.

SM_CYSIZE                         Height of bitmaps contained in the title
                                  bar.

SM_MOUSEPRESENT                   Nonzero if mouse hardware installed.

SM_DEBUG                          Nonzero if Windows debugging version.

SM_SWAPBUTTON                     Nonzero if left and right mouse buttons
                                  swapped.




GetSystemPaletteEntries
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetSystemPaletteEntries(hDC, wStartIndex,
  wNumEntries, lpPaletteEntries)

This function retrieves a range of palette entries from the system palette.


Parameter                         Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                               HDC  Identifies the device context.

wStartIndex                       WORD  Specifies the first entry in the
                                  system palette to be retrieved.

wNumEntries                       WORD  Specifies the number of entries in
                                  the system palette to be retrieved.

lpPaletteEntries                  LPPALETTEENTRY  Points to an array of
                                  PALETTEENTRY data structures to receive
                                  the palette entries. The array must
                                  contain at least as many data structures
                                  as specified by the wNumEntries
                                  parameter.



Return Value

The return value is the number of entries retrieved from the system palette.
It is zero if the function failed.


GetSystemPaletteUse
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  WORD  GetSystemPaletteUse(hDC)

This function determines whether an application has access to the full
system palette. By default, the system palette contains 20 static colors
which are not changed when an application realizes its logical palette. An
application can gain access to most of these colors by calling the
SetSystemPaletteUse function.

The device context identified by the hDC parameter must refer to a device
that supports color palettes.

Parameter           Type/Description
────────────────────────────────────────────────────────────────────────────
hDC                 HDC  Identifies the device context.


Return Value

The return value specifies the current use of the system palette. It is
either of the following values:

Value                             Meaning
────────────────────────────────────────────────────────────────────────────
SYSPAL_NOSTATIC                   System palette contains no static colors
                                  except black and white.

SYSPAL_STATIC                     System palette contains static colors
                                  which will not change when an
                                  application realizes its logical palette.



GetTabbedTextExtent
────────────────────────────────────────────────────────────────────────────

 Version 3.0 

Syntax

  DWORD  GetTabbedTextExtent(hDC, lpString, nCount,
  nTabPositions, lpnTabStopPositions)

This function computes the width and height of the line of text pointed to
by the lpString parameter. If the string contains one or more tab
characters, the width of the string is based upon the tab stops specified by
the lpnTabStopPositions parameter. The GetTabbedTextExtent function uses the
currently selected font to compute the dimensions of the string. The width
and height (in logical units) are computed without considering the current
clipping region.

Parameter                         Type/Description
─────────────────────────────────────────────────────────