CDC::EnumObjects

Enumerates the pens and brushes available in a device context.

int EnumObjects( 
   int nObjectType, 
   int ( CALLBACK * lpfn )( LPVOID, LPARAM ), 
   LPARAM lpData 
);

Parameters

• nObjectType
  Specifies the object type. It can have the values OBJ_BRUSH or OBJ_PEN.

• lpfn
  Is the procedure-instance address of the application-supplied callback function. See the "Remarks" section below.

• lpData
  Points to the application-supplied data. The data is passed to the callback function along with the object information.

Return Value

Specifies the last value returned by the callback function. Its meaning is user-defined.

Remarks

For each object of a given type, the callback function that you pass is called with the information for that object. The system calls the callback function until there are no more objects or the callback function returns 0.

Note that new features of Microsoft Visual C++ let you use an ordinary function as the function passed to EnumObjects. The address passed to EnumObjects is a pointer to a function exported with EXPORT and with the Pascal calling convention. In protect-mode applications, you do not have to create this function with the Windows MakeProcInstance function or free the function after use with the FreeProcInstance Windows function.

You also do not have to export the function name in an EXPORTS statement in your application's module-definition file. You can instead use the EXPORT function modifier, as in

int CALLBACK EXPORT AFunction**(** LPSTR, LPSTR );

to cause the compiler to emit the proper export record for export by name without aliasing. This works for most needs. For some special cases, such as exporting a function by ordinal or aliasing the export, you still need to use an EXPORTS statement in a module-definition file.

For compiling Microsoft Foundation programs, you will normally use the /GA and /GEs compiler options. The /Gw compiler option is not used with the Microsoft Foundation classes. (If you do use the Windows function MakeProcInstance, you will need to explicitly cast the returned function pointer from FARPROC to the type needed in this API.) Callback registration interfaces are now type-safe (you must pass in a function pointer that points to the right kind of function for the specific callback).

Also note that all callback functions must trap Microsoft Foundation exceptions before returning to Windows, since exceptions cannot be thrown across callback boundaries. For more information about exceptions, see the article Exceptions.

Example

// print some info about a pen we're ready to enumerate
BOOL CALLBACK EnumObjectHandler(LPVOID lpLogObject, LPARAM /* lpData */)
{
   LOGPEN* pPen = (LOGPEN*) lpLogObject;

   switch (pPen->lopnStyle)
   {
   case PS_SOLID:
      TRACE0("PS_SOLID:      ");
      break;
   case PS_DASH:
      TRACE0("PS_DASH:       ");
      break;
   case PS_DOT:
      TRACE0("PS_DOT:        ");
      break;
   case PS_DASHDOT:
      TRACE0("PS_DASHDOT:    ");
      break;
   case PS_DASHDOTDOT:
      TRACE0("PS_DASHDOTDOT: ");
      break;
   case PS_NULL:
      TRACE0("PS_NULL:       ");
      break;
   case PS_INSIDEFRAME:
      TRACE0("PS_INSIDEFRAME:");
      break;
   default:
      TRACE0("unk style:");
   }

   TRACE2("Color: 0x%8.8X, Width: %d\n", pPen->lopnColor, pPen->lopnWidth);
   return TRUE;
}

// get the default printer and enumerate the pens it has 
void CDCView::OnEnumPens()
{
   CPrintDialog dlg(FALSE);
   dlg.GetDefaults();
   HDC hdc = dlg.GetPrinterDC();

   if (hdc != NULL)
   {
      CDC dc;
      dc.Attach(hdc);
      VERIFY(dc.EnumObjects(OBJ_PEN, EnumObjectHandler, 0));
   }
}

Requirements

Header: afxwin.h

See Also

Reference

CDC Class

Hierarchy Chart

EnumObjects