Part D: Directions of MS-DOS
`
`2. Resource script: The resource script is an ASCII file that generally has the extension
`.RC. This file contains definitions of menus, dialog boxes, string tables, and keyboard
`accelerators used by the program. The resourcescript can also reference otherfiles
`that contain icons, cursors, bitmaps, and fonts in binary form, as well as other read-
`only data defined by the programmer. When a program is running, Windowsloads
`resources into memory only whenthey are needed and in most cases can discard
`them if additional memory spaceis required.
`SAMPLE.RC,the resource script for théSAMPLEprogram,is shown in Figure 17-12;it
`contains only the definition of the menu used in the program.
`#include "sample.h"
`
`Sample MENU
`BEGIN
`
`POPUP "&Typeface"
`BEGIN
`
`MENUITEM "&Script",
`MENUITEM “&Modern",
`MENUITEM "&Roman",
`
`IDM_SCRIPT, CHECKED
`IDMMODERN
`IDM_ROMAN
`
`END
`
`END
`
`Figure 17-12. The resource scriptfor the SAMPLEprogram.
`
`3. Header(or include) file: This file, with the extension .H, can contain definitions of
`constants or macros, as is customary in C programming. For Windowsprograms, the
`headerfile also reconciles constants used in both the resource script and the pro-
`gram source-codefile. For example, in the SAMPLE.RC resourcescript, each item in
`the pop-up menu (Script, Modern, and Roman) also includesan identifier —
`IDM_SCRIPT, IDM_.MODERN,and IDM_ROMAN,respectively. These identifiers
`are merely numbers that Windowsusesto notify the program of the user's selection
`of a menu item. The same namesare usedto identify the menuselection in the C
`source-codefile. And, because both the resource compiler and the source-code com-
`piler must have accessto these identifiers, the headerfile is included in both the
`resourcescript and the source-codefile.
`The headerfile for the SAMPLE program, SAMPLE.H,is shownin Figure 17-13.
`#define IDM_SCRIPT 1
`#define IDM_MODERN 2
`#define IDM_ROMAN
`3
`
`Figure 17-13. The SAMPLE.H headerfile.
`
`4. Module-definition file: The module-definition file generally has a .DEF extension.
`The Windowslinkerusesthis file in creating the executable .EXEfile. The module-
`definition file specifies various attributes of the program’s code and data segments,
`andit lists all imported and exported functionsin the source-cadefile. In large pro-
`gramsthat are divided into multiple code segments, the module-definitionfile allows
`the programmerto specify different attributes for each code segment.
`
`516
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 526/1582
`
`OLYMPUS EX. 1010 - 526/1582
`
`

`

` Article 17: Windows
`
`The module-definition file for the SAMPLE program is named SAMPLE.DEFandis
`shownin Figure 17-14.
`NAME
`SAMPLE
`DESCRIPTION ,
`'Demonstration Windows Program'
`STUB
`'WINSTUB. EXE"
`CODE
`MOVABLE
`DATA
`MOVABLE MULTIPLE
`HEAPSIZE
`1024
`STACKSIZE
`4096
`EXPORTS
`WndProc
`
`Figure 17-14. The SAMPLE.DEF module-definitionfile.
`
`Makefile: To facilitate construction of the executable file from these different com-
`ponents, Windows programmersoften use the MAKEprogram to compile only those
`files that have changedsince the last time the program waslinked. To do this, the
`programmerfirst creates an ASCIItext file called a makefile. By convention, the
`makefile has no extension.
`
`The makefile for the SAMPLE program is named SAMPLEand is shownin Figure
`17-15. The programmercan create the SAMPLE.EXE executable file by executing
`C>MAKE SAMPLE <Enter>
`
`sample.obj
`
`: sample.c sample.h
`
`If either or both the SAMPLE.C and SAMPLE.Hfiles have a later creation time than
`SAMPLE.OB], then MAKErunsthe program or programslisted immediately below.
`In the case of the SAMPLE makefile, the program is the C compiler, and it compiles
`the SAMPLE.C source code:
`
`cl -c -Gsw -W2 -Zdp sample.c
`
`Thus,if the programmer changesonly oneof the severalfiles used in the develop-
`ment of SAMPLE,then running MAKEensuresthat the executable file is brought up
`to date, while carrying out only the required steps.
`
`: sample.c sample.h
`sample.obj
`cl -c -Gsw -W2 -Zdp sample.c
`
`sample.res : sample.rc sample.h
`re -r sample.rc
`
`sample.exe : sample.obj sample.def sample.res
`link4 sample,
`/align:16,
`/map /line, slibw, sample
`re sample.res
`mapsym sample
`
`Figure 17-15. The makefilefor the SAMPLEprogram.
`
`Section Il: Programming in theMS-DOS Environment
`
`517
`
`OLYMPUS EX. 1010 - 527/1582
`
`Amakefile often contains several sections, each beginning withatarget filename,
`followed by a colon and one or more dependentfilenames, such as
`
`
`
`OLYMPUS EX. 1010 - 527/1582
`
`

`

`Part D: Directions of MS-DOS
`
`Construction of a Windows program
`
`The makefile shows the steps that create a program’s .EXEfile from the various
`components:
`
`1. Compiling the source-codefile:
`cl -c -Gsw -W2 -Zdp sample.c
`
`This step uses the CL_EXE C compiler to create a .OBJ object-modulefile. The com-
`mandline switches are
`— -c: Compiles the program but doesnot link it. Windows programs must be linked —
`with Windows’ LINK4linker, rather than with the LINK program the C compiler
`would normally invoke.
`~ -Gsw: Includes two switches, -Gs and -Gw. The-Gs switch removes stack checks
`from the program. The -Gw switch inserts special prologue and epilogue code in
`all far functions defined in the program. This special code is required for Win-
`dows’ memory management.
`— -W2: Compiles with warninglevel 2. This is the highest warning level, andit causes
`the compiler to display messages for conditions that may be acceptable in normal C
`programsbutthat can cause serious errors in a Windows program.
`— -Zdp: Includes two switches, -Zd and -Zp. The -Zd switch includes line numbers
`in the .OBJ file — helpful for debugging at the source-codelevel. The -Zp switch
`packsstructures on byte boundaries. The -Zp switch is required, because data
`structures used within Windowsare in a packed format.
`2. Compiling the resourcescript:
`
`re ~r sample.rc
`
`This step runs the resource compiler and converts the ASCII .RC resourcescript into a
`binary .RES form. The -r switch indicates that the resource script should be compiled
`but the resources should not yet be added to the program’s .EXEfile.
`Linking the program:
`
`3.
`
`link4 sample,
`
`/align:16,
`
`/map /line, slibw, sample
`
`This step uses the special Windowslinker, LINK4. Thefirst parameterlisted is the
`nameofthe .OBJ file. The /align:16 switch instructs LINK4 to align segmentsin the
`.EXEfile on 16-byte boundaries. The /map and /line switches cause LINK4to create a
`MAPfile that contains program line numbers — again, useful for debugging source
`code. Next,slibw is a reference to the SLIBW.LIB file, which is an importlibrary that
`contains module names and ordinal numbers for all Windowsfunctions. The last
`parameter, sample, is the program’s module-definition file, SAMPLE.DEF.
`4, Adding the resources to the .EXEfile:
`
`re sample.res
`
`518
`
`The MS-DOSEncyclopedia
`
`
`
`OLYMPUS EX. 1010 - 528/1582
`
`OLYMPUS EX. 1010 - 528/1582
`
`

`

`
`
`
`
`
`
`
`Object module
`(OBJ)
`
`Compiled resources
`
`Article 17: Windows
`
`This step runs the resource compiler a secondtime, using the compiled resourcefile,
`SAMPLE.RES. This time, the resource compiler adds the resourcesto the .EXEfile.
`
`
`Module
`Header or
`
`
`
`
`Program
`
`include files
`definition file
`source code
`Resource script
`
`
`
`
`(.RC)
`(.H or .INC)
`(.DEF)
`
`
`
`<.C, .PAS, or .ASM)
`
`
`Cor Pascal
`
`
`RC.EXE
`
`Compiler or
`
`
`
`Resource compiler
`Macro Assembler
`
`(.RES) LINK4.EXE
`(.MAP)
`(SYM)
`Resource compiler
`
`Windowlinker
`
`Mapfile
`
` Executable
`
`without resources
`(EXE)
`
`MAPSYM.EXE
`Converts mapfile
`to symbolfile
`
`RC.EXE
`
`
`
`
`Symbolfile
`
`Executable
`
`(.EXE)
`
`
`
`Figure 17-16. A block diagram showing the creation ofa Windows .EXEfile.
`
`Section HU: Programming in the MS-DOSEnvironment
`
`519
`
`OLYMPUS EX. 1010 - 529/1582
`
`OLYMPUS EX. 1010 - 529/1582
`
`

`

`Part D: Directions of MS-DOS
`
`5, Creating a symbol (SYM)file from the linker’s map (MAP)file:
`mMapsym sample
`
`This step is required for symbolic debugging with SYMDEB.
`
`Figure 17-16 on the preceding page shows how the various components of a Windowspro-
`gram fit into the creation of a .EXEfile.
`,
`Program initialization
`The SAMPLE.C program shownin Figure 17-11 contains some codethat appears in almbst
`every Windows program. The statement
`#include <windows.h>
`
`appearsat the top of every Windows source-codefile written in C. The WINDOWSHfile,
`provided with the Microsoft Windows Software DevelopmentKit, contains templates for
`all Windowsfunctions, structure definitions, and #define statements for many mnemonic
`identifiers.
`
`Someof the variable names in SAMPLE.C may look unusual to C programmers because
`they begin with a prefix notation that denotes the data type of the variable. Windows
`programmers are encouraged to use this type of notation. Some of the more common
`prefixes are
`
`Prefix
`
`DataType
`
`iorn
`w
`|
`dw
`h
`SZ
`Ipsz
`Ipfn
`
`——s
`
`Integer (16-bit signed integer)
`Word (16-bit unsigned integer)
`Long (32-bit signed integer)
`Doubleword (32-bit unsigned integer)
`Handle (16-bit unsigned integer)
`Null-terminated string
`Longpointer to null-terminatedstring
`Long pointerto a function
`
`The program’s entry point (following some startup code) is the WinMain function,
`whichis passed the following parameters: a handle to the current instance of the
`program (hinstance), a handle to the most recent previous instance of the program
`(hPrevInstance), a long pointerto the program’s command line (ipszCmdLine), and a
`number (nCmdShow)thatindicates whether the program should initially be displayed as a
`normally sized window oras an icon.
`Thefirst job SAMPLE performsin the WinMain function is to register a window class—a
`structure that describes characteristics of the windowsthat will be created in the class.
`These characteristics include backgroundcolor, the type of cursor to be displayed in the
`window, the window’s initial menu andicon, and the window function (the structure
`membercalled IpfnWndProc).
`
`520
`
`The MS-DOSEncyclopedia
`
`
`
`OLYMPUS EX. 1010 - 530/1582
`
`OLYMPUS EX. 1010 - 530/1582
`
`

`

`Article 17: Windows
`
`Multiple instances of a program can share the same window class, so SAMPLEregisters the
`window class only forthe first instance of the program:
`
`if (!hPrevInstance}
`
`;
`;
`
`{ w
`
`= CS_HREDRAW | CS_VREDRAW ;
`ndclass.style
`= WndProc ;
`wndclass.lpfnWndProc
`=0;
`wndclass.cbClsExtra
`=0;
`wndclass.cbWndExtra
`= hiInstance ;
`wndclass.hInstance
`.
`= NULL ;
`wndclass.hicon
`IDC_ARROW)
`(NULL,
`= LoadCursor
`:
`wndclass.hCursor
`wndclass-.hbrBackground = GetStockObject
`(WHITE_BRUSH)
`wndclass.lpszMenuName
`= szAppName ;
`wndclass.lpszClassName = szAppName ;
`
`RegisterClass (&wndclass)
`}
`
`;
`
`The SAMPLE program then creates a window using the CreateWindow call, displaysit to
`the screen by calling ShowWindow,and updatesthe client area by calling UpdateWindow:
`
`hWnd = CreateWindow (szAppName, "Demonstration Windows Program",
`WS_OVERLAPPEDWINDOW,
`:
`(int) CW_USEDEFAULT, 0,
`(int) CW_USEDEFAULT, 0,
`NULL, NULL, hInstance, NULL)
`ShowWindow (hWnd, nCmdShow)
`;
`UpdateWindow (hWnd)
`;
`
`;
`
`The first parameter to CreateWindow is the name of the window class. The second param-
`eter is the actual text that appears in the window’stitle bar. The third parameteris the style
`of the window — in this case, the WINDOWS.Hidentifier WS_OVERLAPPEDWINDOW.
`The WS_OVERLAPPEDWINDOWis the most common windowstyle. The fourth through
`seventh parameters specify the initial position and size of the window.Theidentifier
`CW_USEDEFAULTtells Windowsto position and size the window accordingto the default
`rules.
`
`After creating and displaying a Window, the SAMPLE program enters a piece of code
`called the message loop:
`
`while (GetMessage (&msg, NULL, 0, 0))
`
`;
`
`;
`
`{ T
`
`ranslateMessage (&msg)
`DispatchMessage (&msg)
`}
`return msg.wParam ;
`
`This loop continues to execute until the GetMessagecall returns zero. When that happens,
`the program instance terminates and the memoryrequired for the instanceis freed.
`
`Section II: Programming in the MS-DOS Environment
`
`521
`
`OLYMPUS EX. 1010 - 531/1582
`
`
`
`OLYMPUS EX. 1010 - 531/1582
`
`

`

`
`
`Part D: Directions of MS-DOS
`
`The Windows messaging system
`Interactive programswritten for the normal MS-DOS environment generally obtain user
`input only from the keyboard, using either an MS-DOSor a ROM BIOSsoftware interrupt
`to check for keystrokes. Whenthe user types something, such programsact on the key-
`stroke and then return to wait for the next keystroke.
`
`.
`
`Programs written for Windows, however, can receive user input from a variety of sources,
`including the keyboard, the mouse, the Windowstimer, menus,scroll bars, and controls,
`such as buttons andedit boxes.
`
`Moreover, a Windows program must be informedof other events occurring within the
`system. For instance, the user of a Windows program might choose to make its window
`smalleror larger. Windows must make the program aware of this change so thatthe pro-
`gram can adjust its screen outputto fit the new window size. Thus, for example, if a Win-
`dows program is minimized as an icon and the user maximizes its windowtofill the full
`screen, Windows must inform the program that the size of the client area has changed
`and needsto be re-created.
`
`Windowscarries out this job of keeping a program informed of other events through the
`use of formatted messages. In effect, Windows sends these messages to the program. The
`Windows program receives and acts upon the messages.
`
`This messaging makesthe relationship between Windows and a Windows program much
`different from the relationship between MS-DOSand an MS-DOSprogram. Whereas
`MS-DOSdoesnotprovide information until a program requests it through an MS-DOS
`function call, Windows must continually notify a program ofall the events thataffectits
`window.
`
`Window messages can be separated into two major categories: queued and nonqueued.
`
`Queued messages are similar to the keyboard information an MS-DOS program obtains
`from MS-DOS. When the Windowsuser presses a key on the keyboard, moves the mouse,
`or presses one of the mouse buttons, Windowssaves information about the event (in the
`form of a data structure) in the system message queue. Each message is destined for a par-
`ticular window in a particular instance of a Windows program. Windowstherefore deter-
`mines which window should get the information and then places the message in the
`instance’s Own message queue.
`
`A Windows program retrieves information from its queue in the message loop:
`while (GetMessage (&msg, NULL, 0, 0))
`
`{ T
`
`ranslateMessage (&msg)
`DispatchMessage (&msg)
`}
`
`;
`
`;
`
`The msg variable is a structure. During the GetMessagecall, Windowsfills in the fields of
`this structure with information about the message. Thefields are as follows:
`
`522
`
`The MS-DOS Encyclopedia
`
`  
`
`

 


`
`OLYMPUS EX. 1010 - 532/1582
`
`OLYMPUS EX. 1010 - 532/1582
`
`

`

`Article 17: Windows
`
`©
`©
`
`hwnd: The handle for the windowthatis to receive the message.
`iMessage: A numeric code identifying the type of message(for example, kéyboard
`or mouse).
`@ wParam: A 16-bit value containing information specific to the message. See The
`‘Windows Messages below.
`/Param: A 32-bit value containing information specific to the message.
`time: Thetime, in milliseconds, that the message was placed in the queue. The time
`is a 32-bit value relative to the time at which the current Windowssession began.
`pt.x: The horizontal coordinate of the mouse cursorat the time the event occurred.
`pty: The vertical coordinate of the mouse cursorat the time the event occurred.
`
`e
`®
`
`®
`©
`
`GetMessage always returns a nonzero value except whenit receives a quit message. The
`quit message causes the message loop to end. The program should then terminate and
`return control to Windows.
`
`Within the message loop, the TranslateMessage function translates physical keystrokes into
`character-code messages. Windowsplaces these translated messages into the program’s
`message queue.
`The DispatchMessage function essentially makes a call to the window functionofthe win-
`dow specified by the hwndfield. This window function (WndProc in SAMPLE)is indicated
`in the lpfnWndProcfield of the windowclassstructure.
`
`When DispatchMessage passes the message to the window function, Windowsuses the
`first four fields of the message structure as parameters to the function. The window func-
`tion can then process the message. In SAMPLE,for instance, the four fields passed to
`WndProc are hwnd (the handle to the window), iMessage (the numeric message iden-
`tifier), wParam, and [Param. Although Windowsdoesnot pass the time and mouse-
`position information fields as parameters to the window function,this information is
`available through the Windowsfunctions GetMessageTime and GetMessagePos.
`
`A Windows program obtains only a few specific types of messages through its message
`queue. These are keyboard messages, mouse messages, timer messages, the paint message
`that tells the program it must re-create the client area of its window, and the quit message
`that tells the program it is being terminated.
`
`In addition to the queued messages, however, a program’s window function also receives
`many nonqueued messages. Windows sends these nonqueued messages by bypassing the
`message loop and calling the program’s window function directly.
`
`Manyof these nonqueued messagesare derived from queued messages. For example,
`whenthe userclicks the mouse onthe menu bar, a mouse-click messageis placed in the
`program’s message queue. The GetMessage function retrieves the message and the Dis-
`patchMessagefunction sendsit to the program’s window function. However, because this
`mouse message affects a nonclient area of the window (an area outside the window’s cli-
`ent area), the window function normally doesnot processit. Instead, the function passes
`the message back to Windows. In this example, the message tells Windowsto invoke a
`pop-up menu. Windowscalls up the menu and then sends the window function several
`nonqueued messagesto inform the program ofthis action.
`
`Section Il: Programming in theMS-DOSEnvironment
`
`523
`
`OLYMPUS EX. 1010 - 533/1582
`
`|
`
`OLYMPUS EX. 1010 - 533/1582
`
`

`

`
`
`;
`
`Part D: Directions of MS-DOS
`
`,
`
`A Windows program is thus message driven. Once a program reaches the message loop,
`it acts only when the window function receives a message. And, although a program
`receives many messagesthat affect the window, the program usually processes only some
`of them, sending the rest to Windowsfor normal default processing.
`
`The Windows messages
`
`Windows can send a window function more than 100 different messages. The
`WINDOWS.H headerfile includesidentifiersfor all these messages so that C programmers
`do not have to rememberthe message numbers. Some of the more common messages and
`the meanings of the wParam and [Param parametersare discussed here:
`
`WM_CREATE. Windows sends a window function this nonqueued message while pro-
`cessing the CreateWindow call. The Param parameteris a pointerto a creation structure.
`A window function can perform some programinitialization during the WM_CREATE|
`message.
`
`WM_MOVE. Windows sends a windowfunction the nonqueued WM_MOVEmessage
`whenthe window has been movedto anotherpart of the display. The /Param parameter
`gives the new coordinates of the window relative to the upperleft corner of the screen.
`
`WM_SIZE. This nonqueued messageindicates that the size of the window has been
`changed. The new size is encoded in the (Param parameter. Programsoften save this
`windowsize forlater use.
`
`WM_PAINT. This queued message indicates that a region in the window’sclient area
`needs repainting. (The message queue can contain only one WM_ PAINT message.)
`
`WM_COMMAND.This nonqueued message signals a program that a user has selected a
`menu item or has triggered a keyboard accelerator. Child-window controls also use
`WM_COMMANDto send messagesto the parent window.
`
`WM_KEYDOWN. The wParam parameterof this queued messageis a virtual key code
`that identifies the key being pressed. The /Param parameterincludes flags that indicate
`the previous key state and the numberof keypresses the message represents.
`
`WM_KEYUP. This queued messagetells a window function that a key has been released.
`The wParam parameteris a virtual key code.
`
`WM_CHAR. This queued message is generated from WM_KEYDOWN messages during
`the TranslateMessage call. The wParam parameter is the ASCII code of a keyboard key.
`
`WM_MOUSEMOVE. Windowsusesthis queued messagetotell a program about mouse
`movement. The /Param parameter contains the coordinates of the mouserelative to the -
`upperleft cornerof the client area of the window. The wParam parametercontainsflags
`that indicate whether any mouse buttonsor the Shift or Ctri keys are currently pressed.
`
`WM_xBUTTONDOWN. This queued messagetells a program that a button on the mouse
`was depressed while the mouse was in the window'sclient area. The xcan beeitherL, R,
`or M fortheleft, right, or middle mouse button. The wParam and lParam parameters are
`the same as for WM_MOUSEMOVE.
`
`524
`
`The MS-DOSEncyclopedia
`
`OLYMPUS EX. 1010 - 534/1582
`
`OLYMPUS EX. 1010 - 534/1582
`
`

`

`Article 17: Windows
`
`WM_xBUTTONUP. This queued message tells a program that the user has released a
`mouse button.
`
`WM_xBUTTONDBLCLK. Whenthe user double-clicks a mouse button, Windows
`generates a WM_xBUTTONDOWN messageforthefirst click and a queued
`WM_.xBUTTONDBLCLK messagefor the secondclick.
`
`WM_TIMER. When a Windows program sets a timer with the SetTimer function,
`Windows places a WM_TIMER message in the message queueat periodic intervals.
`The wParam parameteris a timer ID. (if the message queue already contains a
`WM_TIMER message, Windows doesnot add another one to the queue.)
`
`WM_VSCROLL. A Windows program that includesa vertical scroll bar in its window
`receives nonqueued WM_VSCROLLmessagesindicating various typesof scroll-bar
`manipulation.
`
`WM_.HSCROLL. This nonqueued message indicates a user is manipulating a horizontal
`scroll bar.
`
`WM_CLOSE. Windows sends a window function this nonqueued message whenthe user
`has selected Close from the window’s system menu. A program can query the userto de-
`termine whetherany action, such as savingafile to disk, is needed before the program
`is terminated.
`
`_WM_.QUERYENDSESSION. This nonqueued messageindicates that the useris shutting
`down Windowsbyselecting Close from the MS-DOSExecutive system menu. A program
`can request the userto verify that the program should be ended. If the window function —
`returns a zero value from the message, Windowsdoesnot end the session.
`
`WM_. DESTROY. This nonqueued messageis the last message a window function receives
`before the program ends. A window function can perform somelast-minute cleanup while
`processing WM_ DESTROY.
`
`WM_OQUIT. This is a queued message that never reachesthe window function becauseit
`causes GetMessageto return a zero value that causes the program to exit the message loop.
`
`Message processing
`
`Programmers can chooseto process some messages and ignore others in the window
`function. Messages that are ignored are generallypassed on to the function
`Def WindowProcfor default processing within Windows.
`
`Because Windows eventually has access to messages that a window function does not
`process,it can send a program messages that might otherwise be regarded as pertaining to
`system functions — for example, mouse messagesthat occur in a nonclient area of the win-
`dow, or system keyboard messagesthat affect the menu. Unless these messages are passed
`on to Def WindowProc, the menu and other system functions do not work properly.
`
`A program can, however, trap someofthese messagesto override Windows’ default pro-
`cessing. For example, when Windowsneedsto repaint the nonclient area of a window (the
`title bar, system-menubox, andscroll bars), it sends the window function a WM_NCPAINT
`
`Section I Programming in the MS-DOSEnvironment
`
`525
`
`OLYMPUS EX. 1010 - 535/1582
`
`OLYMPUS EX. 1010 - 535/1582
`
`

`

`Part D: Directions of MS-DOS
`
`(nonclient paint) message. The window function normally passes this message to
`Def WindowProc, which then calls routines to update the nonclient areas of the window.
`The program can, however, choose to process the WM_.NCPAINT message andpaint the
`nonclientarea itself. A program that doesthis can, for example, draw its own scroll bars.
`
`The Windowsmessaging system also notifies a program of important events occurring
`outside its window. For example,if the MS-DOS Executive were simply to end the Win-
`dowssession whenthe userselects the Close option from its system menu,then applica-
`tions that were still running would not haVe a chanceto save changedfiles to disk. Instead,
`whenthe user selects Close from thelast instance of the MS-DOS Executive’s system
`menu, the MS-DOSExecutive sends a WM_QUERYENDSESSION messageto each cur-
`rently running application.If any application responds by returning a zero value, the MS-
`DOSExecutive does not end the Windowssession.
`
`Before responding, an application can process the WM_QUERYENDSESSION message
`and display a message box askingtheuserif a file should be saved. The message box
`should include three buttons labeled Yes, No, and Cancel. If the user answers Yes, the pro-
`gram can savethe file and then return a nonzero value to the WM_QUERYENDSESSION
`message. If the user answers No, the program can return a nonzero value without saving
`the file. But if the user answers Cancel, the program should return a zero value so that
`the Windowssession will not be ended.If a program does not process the
`WM_QUERYENDSESSION message, Def WindowProc returns a nonzero value.
`
`;
`
`When a userselects Close from the system menuofa particular instance of an application,
`tather than from the MS-DOSExecutive’s menu, Windows sends the window function a
`WM_CLOSE message. If the program has an unsavedfile loaded, it can query the user with
`a message box —— possibly the same one displayed when WM_QUERYENDSESSIONis
`processed. If the user responds Yes to the query, the program cansavethefile and then
`call DestroyWindow. If the user responds No, the program can call DestroyWindow
`without saving the file. If the user responds Cancel, the window function doesnotcall
`DestroyWindow and the program will not be terminated.If a program does not process
`WM._CLOSE messages, Def WindowProc calls DestroyWindow.
`
`Finally, a window function can send messages to other window functions,either within
`the same program or in other programs, with the Windows SendMessage function. This
`function returns control to the calling program after the message has been processed. A
`program can also place messages in a program’s message queue with the PostMessage
`function. This function returns control immediately after posting the message.
`
`For example, when a program makes changesto the WIN.INIfile.(a file containing
`Windowsinitialization information), it can notify all currently running instancesof these
`changes by sending them a WM_WININICHANGEmessage:
`
`SendMessage (-1, WM_WININICHANGE, 0, OL)
`
`;
`
`The -1 parameterindicates that the messageis to be sent to all window functions of
`all currently running instances. Windowscalls the window functions with the
`WM_WININICHANGEmessage and then returns control to the program that sent the
`message.
`,
`
`526
`
`The MS-DOSEncyclopedia
`
`
`
`OLYMPUS EX. 1010 - 536/1582
`
`OLYMPUS EX. 1010 - 536/1582
`
`

`

`Article 17; Windows
`
`SAMPLE’s message processing
`
`The SAMPLE program shownin Figure 17-11 processesonly four messages:
`WM_COMMAND, WM_SIZE, WM_ PAINT, and WM_ DESTROY. All other messages are
`passed to Def WindowProc.Asis typical with most Windows programswrittenin C,
`SAMPLEusesa switch and case construction for processing messages.
`The WM_COMMANDmessagesignals the program that the user has selected a new font
`from the menu. SAMPLEfirst obtains a handle to the menu and removes the checkmark
`from the previously selected font:
`
`;
`hMenu = GetMenu (hWnd)
`CheckMenuitem (hMenu, nCurrentFont, MF_UNCHECKED)
`
`;
`
`The value of wParam inthe WM_COMMANDmessageis the menu ID of the newly
`selected font. SAMPLE saves thatvalue in a static variable (nCurrent Font) and then places a
`checkmark on the new menu choice:
`
`nCurrentFont = wParam ;
`CheckMenuItem (hMenu, nCurrentFont, MF_CHECKED)
`
`;
`
`Because the typeface has changed, SAMPLE mustrepaintits display. The program does
`not repaint it immediately, however. Instead,it calls the InvalidateRect function:
`
`InvalidateRect
`(hWnd, NULL, TRUE)
`;
`This causes a WM_.PAINT messageto be placed in the program’s message queue. The
`NULLparameterindicates that the entire client area should be repainted. The TRUE
`parameterindicates that the background should be erased.
`
`
`
`The WM_SIZE message indicates that the size of SAMPLE’s client area has changed.
`SAMPLEsimply saves the new dimensionsof the client area in twostatic variables:
`xClient
`yClient
`
`LOWORD (lParam)
`HIWORD (lParam)
`
`;
`;
`
`The LOWORD and HIWORD macrosare defined in WINDOWS.H.
`
`Windowsalso places a WM_ PAINT message in SAMPLE’s message queue whenthesize
`of the client area has changed.Asis the case with WM_COMMAND,,the program does
`not have to repaint the client area immediately, because the WM_ PAINT messageis in the
`message queue.
`
`SAMPLEcan receive a WM_PAINT message for many reasons. Thefirst WM_PAINT mes-
`sage it receives results from calling UpdateWindowin the WinMain function.Later, if the
`currentfont is changed from the menu, the program itself causes a WM_ PAINT message
`to be placed in the message queuebycalling InvalidateRect. Windows also sends a win-
`dow function a WM__PAINT message wheneverthe user changesthesize of the window
`or whenpart of the window previously covered by another window is uncovered.
`
`Programs begin processing WM_ PAINT messagesby calling Begin Paint:
`
`BeginPaint
`
`(hWnd, &ps)
`
`;
`
`apma
`
`Section II: Programming in the MS-DOSEnvironment—527
`
`OLYMPUS EX. 1010 - 537/1582
`
`OLYMPUS EX. 1010 - 537/1582
`
`

`

`Part D: Directions of MS-DOS
`
`The SAMPLEprogram thencreates a font based on the currentsize of the client area and
`the current typeface selected from the menu:
`
`hFont = CreateFont
`
`(yClient, xClient / 8,
`0, 0, 400, 0, 0,. 0, OBM_CHARSET,
`OUT_STROKE_PRECIS, OUT._STROKE_PRECIS,
`DRAFT_QUALITY,
`(BYTE) VARIABLE_PITCH |
`cFamily [nCurrentFont - IDMSCRIPT],
`szFace
`{nCurrentFont - IDM_SCRIPT])
`
`;
`
`The fontis selected into the device context (a data structure internal to Windowsthat
`describes the characteristics of the output device); the program also savesthe original
`device-context font:
`
`hFont = SelectObject
`
`(ps.hdc, hFont)
`
`And the word Windows is displayed:
`
`TextOut
`
`(ps.hdc, 0, 0,
`
`"Windows", 7)
`
`;
`
`;
`
`Theoriginal font in the device context is then selected, and the font that was createdis
`now deleted:
`
`DeleteObject
`
`(SelectObject
`
`(ps.hdc, hFont))
`
`;
`
`Finally, SAMPLEcalls EndPaint to signal Windowsthat the client area is now updated and
`valid:
`
`EndPaint
`
`(hWnd, &ps)
`
`;
`
`,
`
`Although the processing of the WM_ PAINT message in this program is simple, the
`method used is commonto all Windows programs. The Begin Paint and End Paint func-
`tions always Occurin pairs, first to get information aboutthe area that needs repainting
`and then to mark that area as valid.
`
`SAMPLE will display this text even when the program is minimized to be displayed as an
`icon at the bottom of the screen. Although most Windowsprogramsuse a customized icon
`for this purpose, the window-class structure in SAMPLEindicates that the program’s icon
`is NULL, meaning that the program is responsible for drawing its own icon. SAMPLE does
`not, however, make any special provisions for drawing the icon. To it, the icon is simply
`a small client area. As a result, SAMPLE displays the word Windowsinits “icon,” using a
`smallfont size.
`
`Windows sends the window function the WM_DESTROY messageas a result of the
`DestroyWindow function that DefWindowProc calls when processing a WM_.CLOSE
`message. The standard processing involves placing a WM_QUIT message in the message
`queue:
`
`PostQuitMessage (0)
`
`;
`
`When the GetMessage function retrieves WM_QUIT from the message queue, GetMessage
`returns 0. This terminates the message loop and the program.
`
`528
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 538/1582
`
`OLYMPUS EX. 1010 - 538/1582
`
`

`

`Article 17: Windows
`
`Forall other messages, SAMPLE calls DefWindowProcand exits the window function by
`returning the value from thecall:
`
`return DefWindowProc (hWnd,
`
`iMessage, wParam, 1Param)
`
`;
`
`This allows Windowsto perform default processing on the messages SAMPLEignores.
`Windows’ multitasking
`
`Most operating systems or operating environmentsthat allow multitasking use whatis
`called a preemptive scheduler. Generally, the procedure involves use of the computer’s
`clock to switch rapidly between programsand allow each a small timeslice. When
`switching between programs,the operating system must preserve the machinestate.
`
`Windowsis different. It is a nonpreemptive multitasking envi