A Window's Instance

When you start an application such as Notepad, you are said to have created an instance of the application. In the same way, when you declare a variable of a class, an instance of the class is created and made available to the project. The WinMain() function also allows you to create an instance of an application, referred to as the hInstance argument of the WinMain() function. The instance is created as an HINSTANCE. The CWinApp class provides a corresponding instance variable called m_hInstance. This variable can let you get a handle to the instance of your application. Alternatively, to get a handle to the instance of your application, you can call the AfxGetInstanceHandle() global function. Its syntax is:

HINSTANCE AfxGetInstanceHandle();

Even more, to get a handle to your application, you can call the Win32 API's GetWindowLong() function. Suppose you have opened Notepad to view the source code of an HTML document. This is said that you have an instance of Notepad. Imagine that you want to open a text document using Notepad without closing the first instance of Notepad. To do this, you must open another copy of Notepad. This second copy of Notepad is another instance. In this case, the first instance is referred to as a previous instance. For a Win32 application, the previous instance would be the hPrevInstance argument of the WinMain() function. For a Win32 application, the hPrevInstance argument always has the NULL value. If you want to find out whether a previous instance of an application already exists, you can call the CWnd::FindWindow() method. Its syntax is:

static CWnd* PASCAL FindWindow(LPCTSTR lpszClassName, LPCTSTR lpszWindowName);

If you created the window or if it is a window you know for sure, in which case it could be a WNDCLASS or WNDCLASSEX object, specify it as the lpszClassName argument. If you do not know its name with certainty, set this argument as NULL. The lpszWindowName argument is the possible caption of the window you are looking for. Imagine you position a button on a dialog box and you want the user to launch Notepad with that button and imagine that, if Notepad is already opened, there would be no reason to create another instance of it.

The CWinApp class provides all the basic functionality that an application needs. It is equipped with a method called InitInstance(). Its syntax is:

virtual BOOL InitInstance();

When creating an application, you must override this method in your own class. This method is used to create an application. If it succeeds, it returns TRUE or a non-zero value. If the application could not be created, the method returns FALSE or 0. Here is an example of implementing it:

class CSimpleApp : public CWinApp
{
    BOOL InitInstance() { return TRUE; }
};

Based on your knowledge of C++, keep in mind that the method could also have been implemented as:

struct CSimpleApp : public CWinApp
{
    BOOL InitInstance()
    {
 return TRUE;
    }
};

or:

struct CSimpleApp : public CWinApp
{
    BOOL InitInstance();
};

BOOL CSimpleApp::InitInstance()
{
    return TRUE;
}