CWaitCursor Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CWaitCursor Class.

Provides a one-line way to show a wait cursor, which is usually displayed as an hourglass, while you're doing a lengthy operation.

Syntax

class CWaitCursor  

Members

Public Constructors

Name	Description
CWaitCursor::CWaitCursor	Constructs a CWaitCursor object and displays the wait cursor.

Public Methods

Name	Description
CWaitCursor::Restore	Restores the wait cursor after it's been changed.

Remarks

CWaitCursor does not have a base class.

Good Windows programming practices require that you display a wait cursor whenever you're performing an operation that takes a noticeable amount of time.

To display a wait cursor, just define a CWaitCursor variable before the code that performs the lengthy operation. The object's constructor automatically causes the wait cursor to be displayed.

When the object goes out of scope (at the end of the block in which the CWaitCursor object is declared), its destructor sets the cursor to the previous cursor. In other words, the object performs the necessary clean-up automatically.

Note

Because of how their constructors and destructors work, CWaitCursor objects are always declared as local variables — they're never declared as global variables nor are they allocated with new.

If you perform an operation which might cause the cursor to be changed, such as displaying a message box or dialog box, call the Restore member function to restore the wait cursor. It is okay to call Restore even when a wait cursor is currently displayed.

Another way to display a wait cursor is to use the combination of CCmdTarget::BeginWaitCursor, CCmdTarget::EndWaitCursor, and perhaps CCmdTarget::RestoreWaitCursor. However, CWaitCursor is easier to use because you don't need to set the cursor to the previous cursor when you're done with the lengthy operation.

Note

MFC sets and restores the cursor using the CWinApp::DoWaitCursor virtual function. You can override this function to provide custom behavior.

Inheritance Hierarchy

CWaitCursor

Requirements

Header: afxwin.h

Example

BOOL SomeLengthyProcess()
{
   CWaitCursor wait;
   //Do the lengthy processing.
   Sleep(1000);

   AfxMessageBox(_T("Some result")); //This changes the cursor.
   wait.Restore(); //Restore the Wait cursor.
   //Continue Processing.
   Sleep(1000);

   //The destructor changes the cursor back to Regular cursor.
   return TRUE;         

}

CWaitCursor::CWaitCursor

To display a wait cursor, just declare a CWaitCursor object before the code that performs the lengthy operation.

CWaitCursor();

Remarks

The constructor automatically causes the wait cursor to be displayed.

When the object goes out of scope (at the end of the block in which the CWaitCursor object is declared), its destructor sets the cursor to the previous cursor. In other words, the object performs the necessary clean-up automatically.

You can take advantage of the fact that the destructor is called at the end of the block (which might be before the end of the function) to make the wait cursor active in only part of your function. This technique is shown in the second example below.

Note

Because of how their constructors and destructors work, CWaitCursor objects are always declared as local variables — they're never declared as global variables, nor are they allocated with new.

Example

// The following example illustrates the most common case
// of displaying the wait cursor during some lengthy
// processing.
void LengthyFunction()
{
   // perhaps you display a dialog box before displaying a
   // wait cursor

   CWaitCursor wait;   // display wait cursor

   // do some lengthy processing
   Sleep(1000);

}  // destructor automatically removes the wait cursor

// This example shows using a CWaitCursor object inside a block
// so the wait cursor is displayed only while the program is
// performing a lengthy operation.
void ConditionalFunction()
{
   if (SomeCondition)
   {
      CWaitCursor wait;   // display wait cursor in this block only

      // do some lengthy processing
      Sleep(1000);

   }  // at this point, the destructor removes the wait cursor
   else
   {
      // no wait cursor--only quick processing
   }
}

CWaitCursor::Restore

To restore the wait cursor, call this function after performing an operation, such as displaying a message box or dialog box, which might change the wait cursor to another cursor.

void Restore ();

Remarks

It is OK to call Restore even when the wait cursor is currently displayed.

If you need to restore the wait cursor while in a function other than the one in which the CWaitCursor object is declared, you can call CCmdTarget::RestoreWaitCursor.

Example

// This example illustrates performing an operation 
// which changes the wait cursor. You should call 
// CWaitCursor::Restore to restore the wait 
// cursor after an operation which changes the cursor.
void AnotherLengthyFunction( )
{
   CWaitCursor wait;   // display wait cursor

   // do some lengthy processing
   Sleep(1000);

   // The dialog box will normally change the cursor to
   // the standard arrow cursor.
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // It is necessary to call Restore here in order
   // to change the cursor back to the wait cursor.
   wait.Restore();

   // do some more lengthy processing
   Sleep(1000);

   // destructor automatically removes the wait cursor
}

// If the wait cursor is changed by a function called by
// the function which created the wait cursor, you 
// can call CCmdTarget::RestoreWaitCursor to restore 
// the wait cursor.
void CalledFunction()
{
   CFileDialog dlg(TRUE);
   dlg.DoModal();

   // Since CWinApp is derived from CCmdTarget, we can use a 
   // pointer to our application object to make the call to
   // CCmdTarget::RestoreWaitCursor.
   AfxGetApp()->RestoreWaitCursor();

   // Yet more lengthy processing...
   Sleep(1000);
}

See Also

Hierarchy Chart
CCmdTarget::BeginWaitCursor
CCmdTarget::EndWaitCursor
CCmdTarget::RestoreWaitCursor
CWinApp::DoWaitCursor
How Do I: Change the Mouse Cursor in an Microsoft Foundation Class Application