How to create a basic Window in C++

//////////////////////////////////////////
//                                      //
// SIMPLEST WINDOWS PROGRAM             //
//                                      //
// You found this at bobobobo's weblog, //
// https://bobobobo.wordpress.com        //
//                                      //
// Creation date:  Jan 31/08            //
// Last modified:  Feb 9/08             //
//                                      //
//////////////////////////////////////////

#include <windows.h>

// Function prototypes.
LRESULT CALLBACK WndProc( HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam );
int WINAPI WinMain( HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR szCmdLine, int iCmdShow );

////////////////////////////
// Introduction:
// Basic Windows Program!
//
// This package demonstrates how to build a very basic Windows application
// on a Win O/S system from Windows 3.1 to Windows XP using C++ code.
//
// * Prerequisites to understanding this program:
//     - Already understand how to create Console applications in C++.
//     - Full understanding of C FUNCTIONS, FUNCTION PARAMETERS/ARGUMENTS.
//
// If you don't know what those are, go learn what
// they are before going on reading this!
// 

///////////////////
// OVERVIEW:
// Windows applications in C++ are easy!
// To understand them, you must first see the big
// picture.  Then you can get your hands dirty 
// and get right into the code.

///////////////////
// Big picture.
//
// Windows apps are much different than console apps.
// A console app, (which you probably are used to)
// has just a single "main" function called main().

// Every Windows app has __2__ functions that are very
// important to it.

// These 2 functions are WinMain and WndProc.  WinMain
// and WndProc really form the Windows' app's heart and soul.
// 
//    A.  WinMain:  Application STARTING POINT.  REPLACES
//                  main() function that you might be used to
//                  from regular C/C++ programs.
// 
//    B.  WndProc:  A function that PROCESSES MESSAGES from
//                  the Windows O/S as they come in.
//

///////////////////
// BUT what's a MESSAGE???
//
// The idea of "messages" takes some getting used
// to, but it is really a simple concept.
//
// The Windows Operating system is like a GOVERNMENT.
//
// All of the little windows that live inside
// (the Firefox window, the MSWord window,
// and YOUR PROGRAM's window!) are people owned
// by the Windows GOVERNMENT.
// 
// So, whenever the user attempts to interact
// with ANY program window inside that Windows Government,
// either by clicking on your window, or by pressing a key
// while your program has the "input focus" (when
// your window is "selected"),
// the Windows O/S INTERCEPTS that communication FIRST.
//
// THEN, a fraction of a second later, (almost
// instantly), the Windows O/S SENDS A a "MESSAGE"
// to YOUR Window program that "HEY! THE USER
// CLICKED ON YOU AT LOCATION (22, 405), USING
// THE RIGHT MOUSE BUTTON."  or "HEY!  THE
// USER PRESSED THE 'A' KEY, AND HE WAS ALSO HOLDING
// DOWN SHIFT WHILE HE PRESSED IT."

// THAT is what a MESSAGE is.  Its a notification
// from the Windows O/S that the user has 
// done something to your program's window.

// ONCE your program receives this
// "MESSAGE", your program can THEN execute some code
// in response to that particular MESSAGE.

// The WndProc function will contain ALL of
// your "MESSAGE HANDLING CODE" -- that is,
// the code pieces that you want executed 
// when certain window events happen.

// This is called EVENT DRIVEN PROGRAMMING.
// And in most standard Windows applications, this is
// how things happen.

// Most of a basic, standard Windows application's
// time is spent WAITING for events.

// And that is what a message is!

//////////////////////////////
// OF INSTANCES AND HANDLES.
//
// There are 2 concepts you must understand intuitively first
// before diving into Windows programming.

// Those concepts are the concept of an INSTANCE,
// and the concept of a HANDLE.

///////////////
// INSTANCES:
// The first concept is the concept of an INSTANCE of a program.

// What's an INSTANCE?

// An INSTANCE of an application is just one running OCCURRENCE of it.
// If you open up 3 different NOTEPAD.exe windows, then you have
// created __3__ different, separate INSTANCE of the NOTEPAD program
// inside your Windows Kernel.

// If you're familiar with OOP, an easy explanation is this:
    // PROGRAM CODE >> like a C++ class definition.
    // ACTUALLY RUNNING PROGRAM CODE >> like an "instance" of the class, this is an INSTANCE of the program.


///////////////
// HANDLES:
// HANDLES pop up EVERYWHERE in Windows programming (and all other
// types of programming as well!)  So I'm hoping to explain the idea
// behind a HANDLE intuitively, so that you have something to "hold onto"
// whenever you see use of HANDLES in program code.

// Think about a POT of boiling water.  Inside that pot is
// some corn on the cob being cooked.

// Now, say you want to ACCESS the pot, so you can dump its
// contents out into the sink and drain the corn.

// How do you do that?  Do you GRAB THE POT DIRECTLY??? NO!!
// That would be stupid.  Instead, you grab the HANDLE TO THE POT.
// Using the HANDLE to the pot, you manipulate the pot, slowly
// dumping out the water and leaving the corn behind.  Then you
// eat the corn and it is delicious.

// Now, in programming, the idea of a HANDLE is much the same.
// A HANDLE to a WINDOW is __NOT__ the window itself in an application
// variable.  Instead, it is a POINTER TO, A REFERENCE TO the
// window itself.

// A HANDLE TO AN INSTANCE in an application variable is NOT
// the application INSTANCE itself.  Rather, it is a POINTER TO
// that application instance.  The application instance exists
// somewhere in the Windows O/S's program memory.  You use the
// programmatic HANDLE that you have as YOUR MEANS TO MANIPULATE
// AND DEAL WITH that application instance.

// The benefits of HANDLES are many!  You'll see as we go on.
// Onto WinMain()!

////////////////////////////
// In a C++ Windows app, the starting point is WinMain().
int WINAPI WinMain( HINSTANCE hInstance,    // HANDLE TO AN INSTANCE.  This is the "handle" to YOUR PROGRAM ITSELF.  More in the GLOSSARY at the bottom.
                    HINSTANCE hPrevInstance,// USELESS on modern windows (totally ignore hPrevInstance)
                    LPSTR szCmdLine,        // Command line arguments.  Explained near BOTTOM of this file.
                    int iCmdShow )          // Start window maximized, minimized, etc.
{
    // As we said before, WinMain is the application starting point.
    
    // A:  WinMain does 2 main things:
    //    1.  STARTUP STUFF:  CREATE THE WINDOW ITSELF, AND LOAD IT UP
    //        SO IT APPEARS ON THE SCREEN.
    //
    //    2.  KEEP CHECKING WITH WINDOWS O/S TO SEE IF THE USER
    //        HAS INTERACTED WITH THE APPLICATION ("MESSAGE LOOP")
    //        If the user has clicked on anything, or pressed any keys while
    //        our window is ACTIVE (our window has the "input focus")
    //        then we are to DISPATCH a MESSAGE to WndProc (make
    //        a function call to WndProc) that tells
    //        WndProc EXACTLY what the user did to our window (clicked?
    //        key pressed?), when it happened, etc.  WndProc then
    //        has the opportunity to EXECUTE SOME CODE in response
    //        to that particular user interaction.
    
    #pragma region part 1 - STARTUP STUFF
    // A.  Create WNDCLASS structure and initialize it
    // The WNDCLASS structure tells Windows WHAT KIND OF
    // WINDOW we dream of creating.
    
    // A note:  Use the TEXT() macro whenever you have a
    // string value that gets passed to a Windows
    // function.  Its good and makes life easier.
    WNDCLASS wc;
    wc.cbClsExtra = 0;  // ignore for now
    wc.cbWndExtra = 0;  // ignore for now
    wc.hbrBackground = (HBRUSH)GetStockObject( WHITE_BRUSH );   // I want the window to have a white background
    wc.hCursor = LoadCursor( NULL, IDC_ARROW );            // I want it to have an arrow for a cursor
    wc.hIcon = LoadIcon( NULL, IDI_APPLICATION );        // I want it to have that envelope like icon
    wc.hInstance = hInstance;           // INSTANCE HANDLE -- see the GLOSSARY PART of this file for an explanation of what HINSTANCE is
    wc.lpfnWndProc = WndProc;           // Give name of WndProc function here.
    wc.lpszClassName = TEXT("Philip");  // I have named it Philip.
                                        // You could name it anything
                                        // you want, but you have to
                                        // remember the name for when
                                        // you call CreateWindow().
    wc.lpszMenuName = 0;    // no menu - ignore
    wc.style = CS_HREDRAW | CS_VREDRAW; // Redraw the window
    // on BOTH horizontal resizes (CS_HREDRAW) and
    // vertical resizes (CS_VREDRAW).  There are
    // many more window class styles!

    
    // B.  Register the WNDCLASS with Windows, THEN
    //     create the window.
    RegisterClass( &wc );   // This kind of "plants" the information
                            // about the Window we "dream"
                            // of creating somewhere inside the Windows O/S...
    
    // NOW, at this next stage, WE ACTUALLY CREATE
    // the window.  The previous lines of code
    // until this point have only been PREPARATION.

    // When we call the CreateWindow() function, we will
    // make a reference to this WNDCLASS structure (BY ITS
    // NAME -- "Philip"), and the Windows government
    // will grant us our wish and a REAL LIVE WINDOW,
    // with the properties that we specified in the
    // WNDCLASS structure!

    // NOTICE that the value that is returned from
    // CreateWindow is a variable of type HWND.

    // HWND is a "handle to a window" - its a programmatic
    // reference variable to the Window.
    // The HWND is OUR MEANS BY WHICH to manipulate
    // our Window.

    // Read the schpeal near the top of this file if
    // not sure about HANDLES.

    // Most of the time, you would want to save
    // this HWND into a global variable,
    // so you wouldn't lose it later.
    HWND hwnd = CreateWindow(
        TEXT("Philip"),         // THIS IS THE LINK
                                // to the WNDCLASS structure that
                                // we created earlier.

        TEXT("window's title!"),// appears in title of window

        WS_OVERLAPPEDWINDOW,    // STYLE of window.  WS_OVERLAPPEDWINDOW just means
                                // the window we create should have a few common features
                                // like a minimize box, a maximize box, and it should
                                // be resizeable by dragging the "thick frame" around
                                // the window. There are other styles
                                // and they all start with WS_.  Check it out in the
                                // autocomplete by typing WS_ THEN PRESSING CTRL+SPACE
                                // to make the autocomplete window come up.
        10, 10,                 // x, y start coordinates of window
        200, 200,               // width, height of window
        NULL, NULL,             // nothing and nothing (ignore to start out)
        hInstance, NULL );      // hInstance -- (see glossary), nothing

    // Next, SHOW and PAINT the window!
    // You won't see the window if you DO NOT
    // call ShowWindow();
    ShowWindow(hwnd, iCmdShow );
    UpdateWindow(hwnd);
    #pragma endregion

    #pragma region part 2 - ENTER A LOOP TO CONTINUALLY KEEP CHECKING WITH WIN O/S FOR USER INTERACTION
    // first, we create the MSG structure.
    MSG msg;
    // But WTF IS A MESSAGE???
    // A MESSAGE is something that the Windows O/S
    // SENDS your application program when
    // SOMETHING HAPPENS TO YOUR WINDOW.

    // Messages can be anything from "the user
    // has moved your window", to "the user
    // has clicked at pixel location (20, 20)" or,
    // "you need to paint yourself", or, 
    // "you have been maximized".

    // YOUR CHANCE to handle those "messages"
    // that get passed to your window comes
    // IN WNDPROC.
    while( GetMessage( &msg, NULL, 0, 0 ) )
    {
        // GetMessage is a function that will not
        // return until the Windows O/S HAS A message
        // for our program.

        // Since the GetMessage() function call is
        // INSIDE the bracket for the while Loop,
        // this means that our program is essentially
        // "put on hold" or halted until the GetMessage function
        // returns.

        // If and when the user interacts with our
        // application's window, then the GetMessage()
        // function WILL return and the variable
        // msg will be filled with interesting details
        // about exactly what the user did to the window.

        TranslateMessage( &msg );   // translates 
        // the message so WndProc can process it
        // more easily.

        // Next we 'dispatch' the message, or
        // send it off to WndProc for processing.

        // Notice that there is NO EXPLICIT function
        // call to WndProc, but somehow in the bowels
        // of the Windows O/S, calling DispatchMessage
        // WILL result in a call to your WndProc function,
        // WITH the appropriate msg struct passed in
        // as well.
        
        DispatchMessage( &msg );    // this line RESULTS IN
        // a call to WndProc(), passing the message and
        // the HWND.


    }
    #pragma endregion

    return msg.wParam;    // return from WinMain
}

LRESULT CALLBACK WndProc(   HWND hwnd,      // "handle" to the window that this message is for
                            UINT message,   // TYPE of message (e.g. WM_PAINT is a message asking to paint the window)
                            WPARAM wparam,  // information about the actual message
                            LPARAM lparam ) // MORE info about the message
{
    // If WinMain was the heart of the Windows application, then
    // WndProc is the soul.

    // WndProc does just 1 thing:
    //    - Execute some bit of code in response
    //      to user interactions with our windows
    //      application.  

    // The tricky bit about WndProc is that NOWHERE IN THIS APP'S
    // CODE DO YOU EVER SEE ANY EXPLICIT FUNCTION CALLS
    // TO WndProc!!!  Does that mean WndProc never
    // gets used???

    // NO!!!  Take a look again, around where
    // we create the WNDCLASS.

    // Notice, how the WNDCLASS has lpfnWndProc = WndProc??
    // THAT is the reference to this function.

    // The WINDOWS O/S PERFORMS the function call to
    // WndProc when we call DispatchMessage().

    switch( message )
    {
    case WM_CREATE:
        // upon creation, let the speaker beep at 50Hz, for 10ms.
        Beep( 50, 10 );
        return 0;
        break;

    case WM_PAINT:
        {
            // we would place our Windows painting code here.
            HDC hdc;
            PAINTSTRUCT ps;
            hdc = BeginPaint( hwnd, &ps );

            // draw a circle and a 2 squares
            Ellipse( hdc, 20, 20, 160, 160 );
            Rectangle( hdc, 50, 50, 90, 90 );
            Rectangle( hdc, 100, 50, 140, 90 );
            
            EndPaint( hwnd, &ps );
        }
        return 0;
        break;

    case WM_DESTROY:
        PostQuitMessage( 0 ) ;
        return 0;
        break;

        
    }

    // Now, try going into Visual Studio and
    // press WM_ then press CTRL + SPACE.

    // Or go to
    // http://msdn2.microsoft.com/en-us/library/ms632595.aspx

    // See that huge listing?  Those are ALL THE EVENTS
    // that Windows could possibly throw at our application.
    // WOW!  That's a lot of events.  WE don't want to 
    // have to write code for every single one of them!
    // But our WndProc gets called whenever ANY event
    // happens to our application.  What do we do with
    // the events we don't want to handle?
    
    // Simple.  We will pass the events we DON'T want
    // to handle to DefWindowProc().  DefWindowProc()
    // knows what to do with the events we don't want
    // to handle so that our application remains stable
    // and good.
    return DefWindowProc( hwnd, message, wparam, lparam );
}



/// GLOSSARY ///
// HINSTANCE:  "Handle" to an instance.  Every running INSTANCE
// of an application has a handle to it that is YOUR MEANS
// by which to manipulate, talk about, or refer to that specific
// application instance as it exists inside the Windows O/S.

// What's an instance again?  If you have 2 copies of the same programming running
// at the same time, then you are running 2 INSTANCES
// of the same program (2 copies of Microsoft Word, for example).
// Each INSTANCE of a program has its own INSTANCE HANDLE and
// hence its PID (ProcessID - unique integer identifier
// for each program that is currently running in the Windows O/S)
// and its own entry in the Window task manager.

// TRY THIS:  Press CTRL+ALT+DEL to bring up the Windows
// Task Manager.
    // Now switch to the PROCESSES tab.
    // Click the "IMAGE NAME" column, so that everything gets organized by name of the process.
    // Now, open NOTEPAD, 3 times.  You should have 3 Notepad windows open.
    // NOW, LOOK AT the Windows Task Manager.  Try to locate __3__ entries
    // that say NOTEPAD.EXE.  Open a fourth notepad.  Open a fifth notepad.
    // every instance of notepad you open gets its own entry in that table.

// Now HINSTANCE is exactly what it sounds like . . its a "handle"
// (a means by which to access or control) the INSTANCE of your
// program.
//
// The actual INSTANCE of your application lives inside the Windows O/S.
// But you have a HANDLE TO IT, and your HANDLE to it is your means
// by which to manipulate it, refer to it, change it, or delete it.

// HWND:  HANDLE TO A WINDOW.  This is exactly the same in CONCEPT as
//        the INSTANCE HANDLE, but now, this is a handle TO THE WINDOW ITSELF.
//        The HANDLE TO THE WINDOW is your means by which to change
//        manipulate, or refer to the window that belongs to your program.
//        A single INSTANCE of an application can have MULTIPLE window
//        handles associated with it.  THAT IS WHY when you CREATE A WINDOW,
//        using the CreateWindow() function, you MUST PASS the hInstance
//        parameter.  That is so that Windows knows which application
//        INSTANCE is attached to which WINDOW.
//
// HDC:  HANDLE TO A DEVICE CONTEXT.  Hmm.  I'm not going to explain this
//       in detail here, because we're not really using the HDC much
//       in this example.  Perhaps at a later time.


///////////////////////////
// THERE, ALL DONE - CLOSING NOTES.
// Everyone knows starting Windows Programming can be a bit hard.
// There are a few things I'd like to highlight here.
//
// Now you might be wondering, "ok, if WinMain is the application
// starting point, WHERE / WHEN / HOW does WinMain accept
// PARAMETERS?"
//
// To understand this, you must start to see your "Windows program"
// as really just a FUNCTION that Windows will call, when it is
// time to start up your application.
// 
// So where do the values of hInstance, hPrevInstance, szCmdLine
// and iCmdShow come from?
// These parameters are PASSED BY the Windows O/S AT APPLICATION START TIME.
// So all of hInstance, hPrevInstance (which is always passed as NULL)
// szCmdLine and iCmdShow are passed by the Windows O/S
// to your application.

////////////////////
// Understanding what szCmdLine is and does:
//
// Do me a favor.
// Open the Windows command prompt (go to START->Run,
// then type "cmd" in the box that appears there.)
//
// You should see a black console window, like the one that your basic console C++ 
// apps run in.  In the black window, type in:
//          explorer
// then press enter.

// What should happen is your windows file explorer should pop up.

// Now go back to the command prompt and type in
//          explorer "C:\Program Files"

// Notice now that the Windows disk explorer now opens in the folder "C:\Program Files"
// In the above example, "C:\Program Files" is a command line argument that modifies
// the behaviour of the disk explorer upon its launch.

// So the explorer.exe program is a Windows program.
// And szCmdLine WOULD BE WHERE YOU TAKE that extra string
// that is passed to the program at the time the program is
// launched.

// You won't necessarily use this at all in your programming!
// But, it is good to know.


// REFERENCES:
// If you want to know more about Windows Programming
// in this CLASSIC C++ way, then you should pick
// up a copy of Charles Petzold's "Programming Windows,
// 5th Edition"
// http://www.charlespetzold.com/pw5/
// On Amazon:  http://www.amazon.com/exec/obidos/ISBN=157231995X

// "The Petzold" is THE reference that all the game
// books out there (some of which are pretty good!)
// draw on when they write their Win32 chapter (its
// obvious from the way they've written them!)

// What's annoying is, a lot of the people who write
// those books though, never acknowledge Petzold or
// mention where they derived their Win32 understanding
// from.

// So, the Petzold is where I got my initial understanding
// anyway, and its really good.  Check it out
// from your library if you haven't the $.

// More refs:
// MSDN:  "About messages and message queues"
// http://msdn2.microsoft.com/en-us/library/ms644927(VS.85).aspx

////////////////
// MORE Closing notes:
// This is sometimes called "EVENT DRIVEN
// PROGRAMMING" -- the idea is that your
// program is entirely driven by EVENTS.
// If there are no events, then your
// Windows program DOES NOTHING.

// Note that this is NOT the case with GAMES!
// GAMES CAN'T WAIT!  Games must be fast.
// For games, you would use DirectInput,
// and things like that, and you WOULD NOT
// be WAITING for messages.  Instead,
// you want to be DIRECTLY listening
// at the keyboard and mouse for user 
// interaction with those DEVICES.


///////////////////
// You MIGHT HAVE been wondering about
// the apparent RETURN TYPE of WinMain and
// WndProc.

// Looking at those function prototypes, we have:

/*

int WINAPI WinMain( HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR szCmdLine, int iCmdShow );
LRESULT CALLBACK WndProc( HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam );

*/

// For example, a question you might have might be:
// WHY is the return type of WinMain "int WINAPI"?
// That is so weird.

// The short answer, is ITS NOT!!

// The return type of WinMain is just INT.
// "WINAPI" IS NOT PART OF THE RETURN TYPE
// OF THE WinMain FUNCTION!

// The second word after the return type
// (WINAPI) is called the CALLING CONVENTION of
// the function.

// In case you're still interested, check out
// these links:
// http://support.microsoft.com/kb/100832
// http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccore98/html/_core_calling_conventions_topics.asp
// http://www.devnewz.com/devnewz-3-20050125UsingWin32CallingConventions.html

// A MSDN basic window example:
// http://msdn2.microsoft.com/en-us/library/aa383668(VS.85).aspx

// MSDN root page for a lot of windows stuff
// http://msdn2.microsoft.com/en-us/library/ms632586(VS.85).aspx

/* 
     ____   __   __      __   __  ___
    / _  \ /  / /  /    /  /  \ \/  /
   / _/ / /  / /  /    /  /    \   /
  / _/ \ /  / /  /__  /  /__   /  /
 /_____//__/ /______//______/ /__/

*/

Check out the Visual Studio project files [updated Feb 9 / 08] hosted by esnips! (Thanks esnips!)

(donation should be to bill.sherif@gmail.com)