DOC: STATIC_DOWNCAST and DYNAMIC_DOWNCAST

ID: Q192099

The information in this article applies to:

Microsoft Visual C++, 32-bit Editions, versions 4.0, 5.0

SUMMARY

The following provides supplemental information to the documentation on STATIC_DOWNCAST:

   STATIC_DOWNCAST( class_name, pobject )

Parameters:

   class_name

      The name of the class you want to cast to.

   pobject

      The pointer to be cast to a pointer to a class_name object.

Remarks:

   This macro casts pobject to a pointer to a class_name object. pobject
   must either be NULL, or point to an object of a class which is derived
   directly, or indirectly, from class_name. In builds of your application
   with the _DEBUG preprocessor symbol defined, the macro will ASSERT if
   pobject is not NULL and if it points to an object that is not a "kind
   of" the class_name (see definition for the CObject::IsKindOf). In non-
   _DEBUG builds, the macro performs the cast without any type checking.

   class_name must be derived from CObject and use the DECLARE_DYNAMIC and
   IMPLEMENT_DYNAMIC, the DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE, or the
   DECLARE_SERIAL and IMPLEMENT_SERIAL macros explained in the Help topic
   "CObject Class: Deriving a Class from Cobject."

   For example, you might cast a pointer to CYourDocument, called pYourDoc,
   to a pointer to CDocument using the following expression:

      CDocument* pDoc = STATIC_DOWNCAST(CDocument, pYourDoc);

   If pYourDoc does not point to an object derived directly or indirectly
   from CDocument, the macro will ASSERT.

   Similarly, the documentation on DYNAMIC_DOWNCAST should be supplemented
   by saying that class_name must be derived from CObject and use the
   DECLARE_DYNAMIC and IMPLEMENT_DYNAMIC, the DECLARE_DYNCREATE and
   IMPLEMENT_DYNCREATE, or the DECLARE_SERIAL and IMPLEMENT_SERIAL macros.

   If you leave out the pair of DECLARE_... and IMPLEMENT_... macros from
   your code, trying to cast the class pointer using STATIC_DOWNCAST or
   DYNAMIC_DOWNCAST gives compiler errors like the following:

      error C2039: 'classCMyClass' : is not a member of 'CMyClass'
      error C2065: 'classCMyClass' : undeclared identifier

MORE INFORMATION

Following is additional information on related subjects:

1. The documentation on CObject::IsKindOf should also include:

      This function works only for classes declared with the
      DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL macros.

2. The documentation on DECLARE_DYNCREATE should also include:

      The DECLARE_DYNCREATE macro includes all the functionality of
      DECLARE_DYNAMIC.

3. You may also want to see the topics on the static_cast and dynamic_cast

   operators in the Visual C++ documentation. Please note that the
   STATIC_DOWNCAST and DYNAMIC_DOWNCAST macros suggest an action that is
   contrary to the common usage of the term "downcast". The term "downcast"
   is commonly used to signify the movement of an object down a class
   hierarchy, from a given class to a class derived from it. This may be
   confusing when you consider that the STATIC_DOWNCAST and
   DYNAMIC_DOWNCAST macros perform the action of "upcasting". The term
   "upcast" is commonly used to signify the movement of an object up the
   class hierarchy, from a derived class to a class it is derived from.

REFERENCES

ARTICLE-ID: Q151070

TITLE     : FIX: DYNAMIC_DOWNCAST & STATIC_DOWNCAST Causes Stack Overflow

Additional query words: DECLARE_DYNAMIC IMPLEMENT_DYNAMIC DECLARE_DYNCREATE IMPLEMENT_DYNCREATE DECLARE_SERIAL IMPLEMENT_SERIAL IsKindOf

Keywords          : kberrmsg kbMFC kbDocs kbVC400 kbVC500 
Version           : WINNT:4.0,5.0
Platform          : winnt
Issue type        : kbinfo

Last Reviewed: September 2, 1998