Lesson 1 Introducing Windows Programming

Ivan Mois

March 27, 2007

[email protected]

Contents

Contents
1 Introduction of the Windows architecture 1.1 Application and operating system overview . . . . . . . . . . . . . . . 2 Create a window 2.1 Main window program . . 2.2 Note of the code . . . . . . 2.2.1 WinMain . . . . . 2.2.2 Window class . . . 2.2.3 Create the window 3 Conclusion 3 3 5 5 7 7 7 9 11

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

Ivan Mois

DirectX World

1 Introduction of the Windows architecture

1 Introduction of the Windows architecture

To use DirectX API (application programming interface) is important to build a main window where we render our 3D scene. A main window has several aspects inside its code coming from the Windows architecture. So, in this section, it is necessary introduce the reader to the Windows architecture. The goal is to understand how a Windows application and the OS (operating system) communicate with each other. The next chapter covers all the aspects hidden in the code to build a main window.

1.1 Application and operating system overview

When a programmer build a main window, he has to take care of various aspects coming from the way in which Windows and the application communicate. Windows follows an event-driven programming model. This means that the application, when theres nothing to do, it waits for an event. An event can be generated in various ways (keypressed, windows creation, mouse click, etc). When an event occur, Windows send a message to the application. So, the application has a queue where Windows put its messages, this is the message queue. The application constantly checks the presence of messages inside the queue. When it nds a message the application send it to a particular function. The function is the Window Procedure. The Window Procedure manage all the messages sent by Windows to the application. To say the true, the Window Procedure is associated with a Window Class. The Window Class describes the window features. So all the windows deriving from the same Window Class have the same Window Procedure. We can have multiple Window Procedure for each application. One for each Window Class dened in the application. The Figure 1 shows the event-driven programming mode.

Ivan Mois

DirectX World

1 Introduction of the Windows architecture

Figure 1: Event-driven programming mode.

Ivan Mois

DirectX World

2 Create a window

2 Create a window
This lesson explain how to write programs for Windows, expecially how to create a main window, upon which we render our 3D scenes. To accomplish this job, we introduce the Win32 API (Application Programming Interface) to create the main window. For a computer programmer view, the Win32 API are a set of low-level functions and structures exposed to us in the C programming language that enables our application and the Windows OS to communicate with each other.

2.1 Main window program

Below, the Code 1 shows how to create a main window using the Win32 API. The next section explain a little bit the code. The code is listed in the lesson1.cpp le that you downloaded with this lesson. I reccomend you to create a project for this le following the instructions at the internet address : http://directxworld.altervista.org/index.php?link=support Click on the Create Project link and follow the instruction step by step. Now, lets have a look to the code:
Listing 1: Main window code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

/ / F i l e : mainWindow . cpp / / A u t h o r : I v a n Moise (C ) A l l R i g h t s R e s e r v e d // / / T h i s a p p l i c a t i o n c r e a t e s a main window . / / T h i s i s t h e Windows h e a d e r f i l e . T h i s f i l e i n c l u d e s o t h e r h e a d e r f i l e s , s u c h a s : / / WINDEF . H b a s i c t y p e s and s t r u c t u r e s / / WINNT . H t y p e s t o s u p p o r t Unicode / / WINBASE . H K e r n e l f u n c t i o n s / / WINUSER . H User I n t e r f a c e f u n c t i o n s / / WINGDI . H GDI f u n c t i o n s # i n c l u d e <windows . h> / / T h i s i s t h e h a n d l e o f t h e main window . The h a n d l e i s an i d . T h i s i d i s u s e d by / / t h e a p p l i c a t i o n t o r e f e r t o t h e window . HWND hMainWindow = 0 ; / / The window p r o c e d u r e , i t h a n d l e s t h e m e s s a g e s r e c e i v e d f o r o u r window . LRESULT CALLBACK WndProc (HWND hWnd , UINT msg , WPARAM wParam , LPARAM l P a r a m ) ; / / Windows e q u i v a l a n t t o main ( ) i n t WINAPI WinMain ( HINSTANCE h I n s t a n c e , HINSTANCE h P r e v I n s t a n c e , PSTR pCmdLine , i n t nShowCmd ) { WNDCLASS wc ; / / i t s a s t r u c t u r e used t o d e f i n e t h e c h a r a c t e r i s t i c o f our / / window MSG msg ; / / T h i s i s a m e s s a g e . We u s e i t t o s t o r e t h e m e s s a g e s s e n t by / / Windows structure . = CS_HREDRAW | CS_VREDRAW; = WndProc ; = 0; = 0; = hInstance ; = : : L o a d I c o n ( 0 , IDI_APPLICATION ) ; = : : L o a d C u r s o r ( 0 , IDC_ARROW ) ; = s t a t i c _ c a s t <HBRUSH> ( : : G e t S t o c k O b j e c t (WHITE_BRUSH ) ) ; = NULL ;

/ / We f i l l i n t h e wc . s t y l e wc . l p f n W n d P r o c wc . c b C l s E x t r a wc . cbWndExtra wc . h I n s t a n c e wc . h I c o n wc . h C u r s o r wc . h b r B a c k g r o u n d wc . lpszMenuName

Ivan Mois

DirectX World

2 Create a window

41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109

wc . l p s z C l a s s N a m e = "MainWindow" ; / / We r e g i s t e r o u r window d e f i n i t i o n . Once t h e c l a s s i s r e g i t e r e d / / we can c r e a t e a window b a s e d o f t h i s c l a s s . i f ( ! R e g i s t e r C l a s s (&wc ) ) { MessageBox ( 0 , "RegisterClass - Failed" , 0 , 0 ) ; return 0; } / / Now , we can c r e a t e t h e window w i t h t h e CreateWindow f u n c t i o n . / / T h i s f u n c t i o n r e t u r n t h e h a n d l e o f t h e window . hMainWindow = CreateWindow ( "MainWindow" , "Main Window" , WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, 0, 0, hInstance , 0); i f ( hMainWindow == 0 ) { : : MessageBox ( 0 , "CreateWindow - Failed" , 0 , 0 ) ; return 0; } / / We show and u p d a t e t h e window . N o t e t h e h a n d l e o f t h e window p a s s e d t o t h e / / f u n c t i o n s . I n t h i s manner , t h e f u n c t i o n s know w h i c h window r e f e r . ShowWindow ( hMainWindow , nShowCmd ) ; UpdateWindow ( hMainWindow ) ; / / T h i s i s t h e m e s s a g e l o o p . Here , t h e a p p l i c a t i o n c h e c k i f t h e r e a r e m e s s a g e s / / i n s i d e t h e message queue . w h i l e ( GetMessage (&msg , 0 , 0 , 0 ) ) { / / I f t h e r e i s a message , t r a n s l a t e t h e message , and t h e n d i s p a t c h i t / / t o t h e a p p r o p r i a t e window p r o c e d u r e . : : T r a n s l a t e M e s s a g e (&msg ) ; : : D i s p a t c h M e s s a g e (&msg ) ; } return 0; } LRESULT CALLBACK WndProc (HWND windowHandle , UINT msg , WPARAM wParam , LPARAM l P a r a m ) { / / Handle some m e s s a g e s : s w i t c h ( msg ) { / / P r e s s i n g t h e ESC b u t t o n we d e s t r o y t h e window . c a s e WM_KEYDOWN: i f ( wParam == VK_ESCAPE ) DestroyWindow ( MainWindowHandle ) ; return 0; / / I n c a s e o f a d e s t r o y message , t h e a p p l i c a t i o n s e n d a WM_QUIT m e s s a g e / / to terminate the application . c a s e WM_DESTROY: PostQuitMessage ( 0 ) ; return 0; }

Ivan Mois

DirectX World

2 Create a window

110 111 112 113

/ / P r o c e s s i n a s t a n d a r d way t h e m e s s a g e s n o t p r o c e s s e d by t h e / / window p r o c e d u r e . r e t u r n DefWindowProc ( windowHandle , msg , wParam , l P a r a m ) ; }

2.2 Note of the code

In this section i give you some explanation about the Code 1 above. 2.2.1 WinMain WinMain is the entry point of the program. WINAPI is a calling convention for Win32 API function, this options determine: The order in which function arguments are pushed onto the stack. Whether the caller function or called function removes the arguments from the stack at the end of the call. The parameters are : hInstance : It is the handle of the instance. So it is an id used for identify the application. hPrevInstance : It is always 0. This parameter is used in the old version of Windows to recognize if other requests of the same application were in execution. pCmdLine : It is the command line used to execute the application. nShowCmd : Species how the window is to be shown. 2.2.2 Window class An application must register a window class before it can create a window of that class. Registering a window class associates a window procedure, class styles, and other class attributes with a class name. A window class denes the attributes of a window, such as its style, icon, cursor, menu, and window procedure. The rst step in registering a window class is to ll in a WNDCLASS structure with the window class information. The elements of a window class dene the default behavior of windows belonging to the class. The window class elements are as shown in the following Table 1.

Ivan Mois

DirectX World

2 Create a window

Class Name Window Procedure

Instance Handle Class Cursor Class Icons Class Background Brush Class Menu Class Styles

Extra Class Memory

Extra Window Memory

Distinguishes the class from other registered classes. Address Pointer to the function that processes all messages sent to windows in the class and denes the behavior of the window. Identies the application or .dll that registered the class. Denes the mouse cursor that the system displays for a window of the class. Denes the large icon and the small icon (Windows 95/98/Me, Windows NT 4.0 and later). Denes the color and pattern that ll the client area when the window is opened or painted. Species the default menu for windows that do not explicitly dene a menu. Denes how to update the window after moving or resizing it, how to process double-clicks of the mouse, how to allocate space for the device context, and other aspects of the window. Species the amount of extra memory, in bytes, that the system should reserve for the class. All windows in the class share the extra memory and can use it for any application-dened purpose. The system initializes this memory to zero. Species the amount of extra memory, in bytes, that the system should reserve for each window belonging to the class. The extra memory can be used for any application-dened purpose. The system initializes this memory to zero.
Table 1: window class elements.

Ivan Mois

DirectX World

2 Create a window

2.2.3 Create the window The CreateWindow function creates an overlapped, pop-up, or child window. The window class elements are as shown in the following Table 2.

Ivan Mois

DirectX World

2 Create a window

10

lpClassName

lpWindowName dwStyle

nWidth nHeight hWndParent hMenu hInstance lpParam

[in] Pointer to a null-terminated string or a class atom created by a previous call to the RegisterClass or RegisterClassEx function. The class name can also be any of the predened system class names. [in] Pointer to a null-terminated string that species the window name. [in] Species the style of the window being created. This parameter can be a combination of window styles. [in] Species the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the windows upper-left corner, in screen coordinates. For a child window, x is the xcoordinate of the upper-left corner of the window relative to the upper-left corner of the parent windows client area. [in] Species the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the windows upper-left corner, in screen coordinates. For a child window, y is the initial ycoordinate of the upper-left corner of the child window relative to the upper-left corner of the parent windows client area. [in] Species the width, in device units, of the window. [in] Species the height, in device units, of the window. [in] Handle to the parent or owner window of the window being created. [in] Handle to a menu. [in] Handle to the instance of the module to be associated with the window. [in] Creation parameters.
Table 2: CreateWindow elements.

Ivan Mois

DirectX World

3 Conclusion

11

3 Conclusion
In this lesson we concentrate our attention to the creation of a Window. We saw a bit of the Windows architecture to understand the inner workings of this OS. My last recommendation is to play with the application just to understand each little part. In the next lesson well create the DirectX object and well see how to modify the queue loop to be ready for our purpose.

Ivan Mois

DirectX World