Run-Time Object Model Services
The classes CObject and CRuntimeClass encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from CObject inherit this functionality.
Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information isn't supported directly by the C++ language.
Serialization is the process of writing or reading an object's contents to or from a file. You can use serialization to store an object's contents even after the application exits. The object can then be read from the file when the application is restarted. Such data objects are said to be "persistent."
Dynamic object creation enables you to create an object of a specified class at run time. For example, document, view, and frame objects must support dynamic creation because the framework needs to create them dynamically.
The following table lists the MFC macros that support run-time class information, serialization, and dynamic creation.
For more information on these run-time object services and serialization, see the article CObject Class: Accessing Run-Time Class Information.
Run-Time Object Model Services Macros
| Name | Description |
|---|---|
DECLARE_DYNAMIC |
Enables access to run-time class information (must be used in the class declaration). |
DECLARE_DYNCREATE |
Enables dynamic creation and access to run-time class information (must be used in the class declaration). |
DECLARE_SERIAL |
Enables serialization and access to run-time class information (must be used in the class declaration). |
IMPLEMENT_DYNAMIC |
Enables access to run-time class information (must be used in the class implementation). |
IMPLEMENT_DYNCREATE |
Enables dynamic creation and access to run-time information (must be used in the class implementation). |
IMPLEMENT_SERIAL |
Permits serialization and access to run-time class information (must be used in the class implementation). |
RUNTIME_CLASS |
Returns the CRuntimeClass structure that corresponds to the named class. |
OLE frequently requires the dynamic creation of objects at run time. For example, an OLE server application must be able to create OLE items dynamically in response to a request from a client. Similarly, an automation server must be able to create items in response to requests from automation clients.
The Microsoft Foundation Class Library provides two macros specific to OLE.
Dynamic Creation of OLE Objects
| Name | Description |
|---|---|
AFX_COMCTL32_IF_EXISTS |
Determines whether the Common Controls library implements the specified API. |
AFX_COMCTL32_IF_EXISTS2 |
Determines whether the Common Controls library implements the specified API. |
DECLARE_OLECREATE |
Enables objects to be created through OLE automation. |
DECLARE_OLECTLTYPE |
Declares the GetUserTypeNameID and GetMiscStatus member functions of your control class. |
DECLARE_PROPPAGEIDS |
Declares that the OLE control provides a list of property pages to display its properties. |
IMPLEMENT_OLECREATE |
Enables objects to be created by the OLE system. |
IMPLEMENT_OLECTLTYPE |
Implements the GetUserTypeNameID and GetMiscStatus member functions of your control class. |
IMPLEMENT_OLECREATE_FLAGS |
Either this macro or IMPLEMENT_OLECREATE must appear in the implementation file for any class that uses DECLARE_OLECREATE. |
AFX_COMCTL32_IF_EXISTS
Determines whether the Common Controls library implements the specified API.
Syntax
AFX_COMCTL32_IF_EXISTS( proc );
Parameters
proc
Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode.
Remarks
Use this macro to determine whether the Common Controls library the function specified by proc (instead of calling GetProcAddress.
Requirements
afxcomctl32.h, afxcomctl32.inl
AFX_COMCTL32_IF_EXISTS2
Determines whether the Common Controls library implements the specified API (this is the Unicode version of AFX_COMCTL32_IF_EXISTS).
Syntax
AFX_COMCTL32_IF_EXISTS2( proc );
Parameters
proc
Pointer to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero. This parameter must be in Unicode.
Remarks
Use this macro to determine whether the Common Controls library the function specified by proc (instead of calling GetProcAddress. This macro is the Unicode version of AFX_COMCTL32_IF_EXISTS.
Requirements
afxcomctl32.h, afxcomctl32.inl
DECLARE_DYNAMIC
Adds the ability to access run-time information about an object's class when deriving a class from CObject.
DECLARE_DYNAMIC(class_name)
Parameters
class_name
The actual name of the class.
Remarks
Add the DECLARE_DYNAMIC macro to the header (.h) module for the class, then include that module in all .cpp modules that need access to objects of this class.
If you use the DECLARE_DYNAMIC and IMPLEMENT_DYNAMIC macros as described, you can then use the RUNTIME_CLASS macro and the CObject::IsKindOf function to determine the class of your objects at run time.
If DECLARE_DYNAMIC is included in the class declaration, then IMPLEMENT_DYNAMIC must be included in the class implementation.
For more information on the DECLARE_DYNAMIC macro, see CObject Class Topics.
Example
See the example for IMPLEMENT_DYNAMIC.
Requirements
Header: afx.h
DECLARE_DYNCREATE
Enables objects of CObject-derived classes to be created dynamically at run time.
DECLARE_DYNCREATE(class_name)
Parameters
class_name
The actual name of the class.
Remarks
The framework uses this ability to create new objects dynamically. For example, the new view created when you open a new document. Document, view, and frame classes should support dynamic creation because the framework needs to create them dynamically.
Add the DECLARE_DYNCREATE macro in the .h module for the class, then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation.
For more information on the DECLARE_DYNCREATE macro, see CObject Class Topics.
Note
The DECLARE_DYNCREATE macro includes all the functionality of DECLARE_DYNAMIC.
Example
See the example for IMPLEMENT_DYNCREATE.
Requirements
Header: afx.h
DECLARE_OLECTLTYPE
Declares the GetUserTypeNameID and GetMiscStatus member functions of your control class.
Syntax
DECLARE_OLECTLTYPE( class_name )
Parameters
class_name
The name of the control class.
Remarks
GetUserTypeNameID and GetMiscStatus are pure virtual functions, declared in COleControl. Because these functions are pure virtual, they must be overridden in your control class. In addition to DECLARE_OLECTLTYPE, you must add the IMPLEMENT_OLECTLTYPE macro to your control class declaration.
Requirements
Header: afxctl.h
DECLARE_PROPPAGEIDS
Declares that the OLE control provides a list of property pages to display its properties.
Syntax
DECLARE_PROPPAGEIDS( class_name )
Parameters
class_name
The name of the control class that owns the property pages.
Remarks
Use the DECLARE_PROPPAGEIDS macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_PROPPAGEIDS macro, macro entries for each of your control's property pages, and the END_PROPPAGEIDS macro to declare the end of the property page list.
For more information on property pages, see the article ActiveX Controls: Property Pages.
Requirements
Header: afxctl.h
DECLARE_SERIAL
Generates the C++ header code necessary for a CObject-derived class that can be serialized.
DECLARE_SERIAL(class_name)
Parameters
class_name
The actual name of the class.
Remarks
Serialization is the process of writing or reading the contents of an object to and from a file.
Use the DECLARE_SERIAL macro in an .h module, and then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_SERIAL is included in the class declaration, then IMPLEMENT_SERIAL must be included in the class implementation.
The DECLARE_SERIAL macro includes all the functionality of DECLARE_DYNAMIC and DECLARE_DYNCREATE.
You can use the AFX_API macro to automatically export the CArchive extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code:
#undef AFX_API
#define AFX_API AFX_EXT_CLASS
// <your class declarations here>
#undef AFX_API
#define AFX_API
For more information on the DECLARE_SERIAL macro, see CObject Class Topics.
Example
class CAge : public CObject
{
public:
void Serialize(CArchive& ar);
DECLARE_SERIAL(CAge)
// remainder of class declaration omitted
Requirements
Header: afx.h
IMPLEMENT_DYNAMIC
Generates the C++ code necessary for a dynamic CObject-derived class with run-time access to the class name and position within the hierarchy.
IMPLEMENT_DYNAMIC(class_name, base_class_name)
Parameters
class_name
The actual name of the class.
base_class_name
The name of the base class.
Remarks
Use the IMPLEMENT_DYNAMIC macro in a .cpp module, and then link the resulting object code only once.
For more information, see CObject Class Topics.
Example
class CPerson : public CObject
{
DECLARE_DYNAMIC(CPerson)
// other declarations
};
IMPLEMENT_DYNAMIC(CPerson, CObject)
Requirements
Header: afx.h
IMPLEMENT_DYNCREATE
Enables objects of CObject-derived classes to be created dynamically at run time when used with the DECLARE_DYNCREATE macro.
IMPLEMENT_DYNCREATE(class_name, base_class_name)
Parameters
class_name
The actual name of the class.
base_class_name
The actual name of the base class.
Remarks
The framework uses this ability to create new objects dynamically, for example, when it reads an object from disk during serialization. Add the IMPLEMENT_DYNCREATE macro in the class implementation file. For more information, see CObject Class Topics.
If you use the DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE macros, you can then use the RUNTIME_CLASS macro and the CObject::IsKindOf member function to determine the class of your objects at run time.
If DECLARE_DYNCREATE is included in the class declaration, then IMPLEMENT_DYNCREATE must be included in the class implementation.
Note that this macro definition will invoke the default constructor for your class. If a non-trivial constructor is explicitly implemented by the class, it must also explicitly implement the default constructor as well. The default constructor can be added to the class's private or protected member sections to prevent it from being called from outside the class implementation.
Example
class CMyDynCreateObj : public CObject
{
int m_Num;
public:
DECLARE_DYNCREATE(CMyDynCreateObj)
CMyDynCreateObj(int Num) { m_Num = Num; }
private:
CMyDynCreateObj() { m_Num = 0; } // provide default constructor only for
// dynamic creation
};
IMPLEMENT_DYNCREATE(CMyDynCreateObj, CObject)
Requirements
Header: afx.h
IMPLEMENT_OLECREATE_FLAGS
Either this macro or IMPLEMENT_OLECREATE must appear in the implementation file for any class that uses DECLARE_OLECREATE.
Syntax
IMPLEMENT_OLECREATE_FLAGS( class_name, external_name, nFlags,
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)
Parameters
class_name
The actual name of the class.
external_name
The object name exposed to other applications (enclosed in quotation marks).
nFlags
Contains one or more of the following flags:
afxRegInsertableAllows the control to appear in the Insert Object dialog box for OLE objects.afxRegApartmentThreadingSets the threading model in the registry toThreadingModel=Apartment.afxRegFreeThreadingSets the threading model in the registry toThreadingModel=Free.
You can combine the two flags afxRegApartmentThreading and afxRegFreeThreading to set ThreadingModel=Both. See InprocServer32 in the Windows SDK for more information on threading model registration.
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8
Components of the class's CLSID.
Remarks
Note
If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the nFlags parameter. If you want to support only the single-treading model, use IMPLEMENT_OLECREATE.
The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server.
The OLE class ID is a unique 128-bit identifier for the object. It consists of one long, two **WORD**s, and eight **BYTE**s, as represented by l, w1, w2, and b1 through b8 in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required.
Requirements
Header: afxdisp.h
IMPLEMENT_OLECTLTYPE
Implements the GetUserTypeNameID and GetMiscStatus member functions of your control class.
Syntax
DECLARE_OLECTLTYPE( class_name, idsUserTypeName, dwOleMisc )
Parameters
class_name
The name of the control class.
idsUserTypeName
The resource ID of a string containing the external name of the control.
dwOleMisc
An enumeration containing one or more flags. For more information on this enumeration, see OLEMISC in the Windows SDK.
Remarks
In addition to IMPLEMENT_OLECTLTYPE, you must add the DECLARE_OLECTLTYPE macro to your control class declaration.
The GetUserTypeNameID member function returns the resource string that identifies your control class. GetMiscStatus returns the OLEMISC bits for your control. This enumeration specifies a collection of settings describing miscellaneous characteristics of your control. For a full description of the OLEMISC settings, see OLEMISC in the Windows SDK.
Note
The default settings used by the ActiveX ControlWizard are: OLEMISC_ACTIVATEWHENVISIBLE, OLEMISC_SETCLIENTSITEFIRST, OLEMISC_INSIDEOUT, OLEMISC_CANTLINKINSIDE, and OLEMISC_RECOMPOSEONRESIZE.
Requirements
Header: afxctl.h
IMPLEMENT_SERIAL
Generates the C++ code necessary for a dynamic CObject-derived class with run-time access to the class name and position within the hierarchy.
IMPLEMENT_SERIAL(class_name, base_class_name, wSchema)
Parameters
class_name
The actual name of the class.
base_class_name
The name of the base class.
wSchema
A UINT "version number" that will be encoded in the archive to enable a deserializing program to identify and handle data created by earlier program versions. The class schema number must not be -1.
Remarks
Use the IMPLEMENT_SERIAL macro in a .cpp module; then link the resulting object code only once.
You can use the AFX_API macro to automatically export the CArchive extraction operator for classes that use the DECLARE_SERIAL and IMPLEMENT_SERIAL macros. Bracket the class declarations (located in the .h file) with the following code:
#undef AFX_API
#define AFX_API AFX_EXT_CLASS
// <your class declarations here>
#undef AFX_API
#define AFX_API
For more information, see the CObject Class Topics.
Example
IMPLEMENT_SERIAL(CAge, CObject, VERSIONABLE_SCHEMA | 2)
Requirements
Header: afx.h
RUNTIME_CLASS
Gets the run-time class structure from the name of a C++ class.
RUNTIME_CLASS(class_name)
Parameters
class_name
The actual name of the class (not enclosed in quotation marks).
Remarks
RUNTIME_CLASS returns a pointer to a CRuntimeClass structure for the class specified by class_name. Only CObject-derived classes declared with DECLARE_DYNAMIC, DECLARE_DYNCREATE, or DECLARE_SERIAL will return pointers to a CRuntimeClass structure.
For more information, see CObject Class Topics.
Example
CRuntimeClass* prt = RUNTIME_CLASS(CAge);
ASSERT(strcmp(prt->m_lpszClassName, "CAge") == 0);
Requirements
Header: afx.h
DECLARE_OLECREATE
Enables objects of CCmdTarget-derived classes to be created through OLE automation.
DECLARE_OLECREATE(class_name)
Parameters
class_name
The actual name of the class.
Remarks
This macro enables other OLE-enabled applications to create objects of this type.
Add the DECLARE_OLECREATE macro in the .h module for the class, and then include that module in all .cpp modules that need access to objects of this class.
If DECLARE_OLECREATE is included in the class declaration, then IMPLEMENT_OLECREATE must be included in the class implementation. A class declaration using DECLARE_OLECREATE must also use DECLARE_DYNCREATE or DECLARE_SERIAL.
Requirements
Header: afxdisp.h
IMPLEMENT_OLECREATE
Either this macro or IMPLEMENT_OLECREATE_FLAGS must appear in the implementation file for any class that uses DECLARE_OLECREATE.
IMPLEMENT_OLECREATE(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8)
Parameters
class_name
The actual name of the class.
external_name
The object name exposed to other applications (enclosed in quotation marks).
l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8
Components of the class's CLSID.
Remarks
Note
If you use IMPLEMENT_OLECREATE, by default, you support only the single threading model. If you use IMPLEMENT_OLECREATE_FLAGS, you can specify which threading model your object supports by using the nFlags parameter.
The external name is the identifier exposed to other applications. Client applications use the external name to request an object of this class from an automation server.
The OLE class ID is a unique 128-bit identifier for the object. It consists of one long, two **WORD**s, and eight **BYTE**s, as represented by l, w1, w2, and b1 through b8 in the syntax description. The Application Wizard and code wizards create unique OLE class IDs for you as required.
Requirements
Header: afxdisp.h
See also
Macros and Globals
Isolation of the MFC Common Controls Library
CLSID Key
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for