CGdiObject Class

Article
12/18/2017

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

Provides a base class for various kinds of Windows graphics device interface (GDI) objects such as bitmaps, regions, brushes, pens, palettes, and fonts.

Syntax

class CGdiObject : public CObject

Members

Public Constructors

Name	Description
CGdiObject::CGdiObject	Constructs a `CGdiObject` object.

Public Methods

Name	Description
CGdiObject::Attach	Attaches a Windows GDI object to a `CGdiObject` object.
CGdiObject::CreateStockObject	Retrieves a handle to one of the Windows predefined stock pens, brushes, or fonts.
CGdiObject::DeleteObject	Deletes the Windows GDI object attached to the `CGdiObject` object from memory by freeing all system storage associated with the object.
CGdiObject::DeleteTempMap	Deletes any temporary `CGdiObject` objects created by `FromHandle`.
CGdiObject::Detach	Detaches a Windows GDI object from a `CGdiObject` object and returns a handle to the Windows GDI object.
CGdiObject::FromHandle	Returns a pointer to a `CGdiObject` object given a handle to a Windows GDI object.
CGdiObject::GetObject	Fills a buffer with data that describes the Windows GDI object attached to the `CGdiObject` object.
CGdiObject::GetObjectType	Retrieves the type of the GDI object.
CGdiObject::GetSafeHandle	Returns `m_hObject` unless `this` is `NULL`, in which case `NULL` is returned.
CGdiObject::UnrealizeObject	Resets the origin of a brush or resets a logical palette.

Public Operators

Name	Description
CGdiObject::operator !=	Determines if two GDI objects are logically not equal.
CGdiObject::operator ==	Determines if two GDI objects are logically equal.
CGdiObject::operator HGDIOBJ	Retrieves a `HANDLE` to the attached Windows GDI object.

Public Data Members

Name	Description
CGdiObject::m_hObject	A `HANDLE` containing the `HBITMAP`, `HPALETTE`, `HRGN`, `HBRUSH`, `HPEN`, or `HFONT` attached to this object.

Remarks

You never create a CGdiObject directly. Rather, you create an object from one of its derived classes, such as CPen or CBrush.

For more information on CGdiObject, see Graphic Objects.

Inheritance Hierarchy

CObject

CGdiObject

Requirements

Header: afxwin.h

CGdiObject::Attach

Attaches a Windows GDI object to a CGdiObject object.

BOOL Attach(HGDIOBJ hObject);

Parameters

hObject
A HANDLE to a Windows GDI object (for example, HPEN or HBRUSH).

Return Value

Nonzero if attachment is successful; otherwise 0.

CGdiObject::CGdiObject

Constructs a CGdiObject object.

CGdiObject();

Remarks

You never create a CGdiObject directly. Rather, you create an object from one of its derived classes, such as CPen or Cbrush.

CGdiObject::CreateStockObject

Retrieves a handle to one of the predefined stock Windows GDI pens, brushes, or fonts, and attaches the GDI object to the CGdiObject object.

BOOL CreateStockObject(int nIndex);

Parameters

nIndex
A constant specifying the type of stock object desired. See the parameter fnObject for GetStockObject in the Windows SDK for a description of appropriate values.

Return Value

Nonzero if the function is successful; otherwise 0.

Remarks

Call this function with one of the derived classes that corresponds to the Windows GDI object type, such as CPen for a stock pen.

CGdiObject::DeleteObject

Deletes the attached Windows GDI object from memory by freeing all system storage associated with the Windows GDI object.

BOOL DeleteObject();

Return Value

Nonzero if the GDI object was successfully deleted; otherwise 0.

Remarks

The storage associated with the CGdiObject object is not affected by this call. An application should not call DeleteObject on a CGdiObject object that is currently selected into a device context.

When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently.

CGdiObject::DeleteTempMap

Called automatically by the CWinApp idle-time handler, DeleteTempMap deletes any temporary CGdiObject objects created by FromHandle.

static void PASCAL DeleteTempMap();

Remarks

DeleteTempMap detaches the Windows GDI object attached to a temporary CGdiObject object before deleting the CGdiObject object.

Example

   // DeleteTempMap() is a static member and so does not need to 
   // be called within the scope of an instantiated CGdiObject object.
   CGdiObject::DeleteTempMap();

CGdiObject::Detach

Detaches a Windows GDI object from a CGdiObject object and returns a handle to the Windows GDI object.

HGDIOBJ Detach();

Return Value

A HANDLE to the Windows GDI object detached; otherwise NULL if no GDI object is attached.

CGdiObject::FromHandle

Returns a pointer to a CGdiObject object given a handle to a Windows GDI object.

static CGdiObject* PASCAL FromHandle(HGDIOBJ hObject);

Parameters

hObject
A HANDLE to a Windows GDI object.

Return Value

A pointer to a CGdiObject that may be temporary or permanent.

Remarks

If a CGdiObject object is not already attached to the Windows GDI object, a temporary CGdiObject object is created and attached.

This temporary CGdiObject object is only valid until the next time the application has idle time in its event loop, at which time all temporary graphic objects are deleted. Another way of saying this is that the temporary object is only valid during the processing of one window message.

CGdiObject::GetObject

Fills a buffer with data that defines a specified object.

int GetObject(
    int nCount,  
    LPVOID lpObject) const;

Parameters

nCount
Specifies the number of bytes to copy into the lpObject buffer.

lpObject
Points to a user-supplied buffer that is to receive the information.

Return Value

The number of bytes retrieved; otherwise 0 if an error occurs.

Remarks

The function retrieves a data structure whose type depends on the type of graphic object, as shown by the following list:

Object	Buffer type
`CPen`	LOGPEN
`CBrush`	LOGBRUSH
`CFont`	LOGFONT
`CBitmap`	BITMAP
`CPalette`	WORD
`CRgn`	Not supported

If the object is a CBitmap object, GetObject returns only the width, height, and color format information of the bitmap. The actual bits can be retrieved by using CBitmap::GetBitmapBits.

If the object is a CPalette object, GetObject retrieves a WORD that specifies the number of entries in the palette. The function does not retrieve the LOGPALETTE structure that defines the palette. An application can get information on palette entries by calling CPalette::GetPaletteEntries.

CGdiObject::GetObjectType

Retrieves the type of the GDI object.

UINT GetObjectType() const;

Return Value

The type of the object, if successful; otherwise 0. The value can be one of the following:

OBJ_BITMAP Bitmap
OBJ_BRUSH Brush
OBJ_FONT Font
OBJ_PAL Palette
OBJ_PEN Pen
OBJ_EXTPEN Extended pen
OBJ_REGION Region
OBJ_DC Device context
OBJ_MEMDC Memory device context
OBJ_METAFILE Metafile
OBJ_METADC Metafile device context
OBJ_ENHMETAFILE Enhanced metafile
OBJ_ENHMETADC Enhanced-metafile device context

CGdiObject::GetSafeHandle

Returns m_hObject unless this is NULL, in which case NULL is returned.

HGDIOBJ GetSafeHandle() const;

Return Value

A HANDLE to the attached Windows GDI object; otherwise NULL if no object is attached.

Remarks

This is part of the general handle interface paradigm and is useful when NULL is a valid or special value for a handle.

Example

See the example for CWnd::IsWindowEnabled.

CGdiObject::m_hObject

A HANDLE containing the HBITMAP, HRGN, HBRUSH, HPEN, HPALETTE, or HFONT attached to this object.

HGDIOBJ m_hObject;

CGdiObject::operator !=

Determines if two GDI objects are logically not equal.

BOOL operator!=(const CGdiObject& obj) const;

Parameters

obj
A pointer to an existing CGdiObject.

Remarks

Determines if a GDI object on the left side is not equal to a GDI object on the right side.

CGdiObject::operator ==

Determines if two GDI objects are logically equal.

BOOL operator==(const CGdiObject& obj) const;

Parameters

obj
A reference to an existing CGdiObject.

Remarks

Determines if a GDI object on the left side is equal to a GDI object on the right side.

CGdiObject::operator HGDIOBJ

Retrieves a HANDLE to the attached Windows GDI object; otherwise NULL if no object is attached.

operator HGDIOBJ() const;

CGdiObject::UnrealizeObject

Resets the origin of a brush or resets a logical palette.

BOOL UnrealizeObject();

Return Value

Nonzero if successful; otherwise 0.

Remarks

While UnrealizeObject is a member function of the CGdiObject class, it should be invoked only on CBrush or CPalette objects.

For CBrush objects, UnrealizeObject directs the system to reset the origin of the given brush the next time it is selected into a device context. If the object is a CPalette object, UnrealizeObject directs the system to realize the palette as though it had not previously been realized. The next time the application calls the CDC::RealizePalette function for the specified palette, the system completely remaps the logical palette to the system palette.

The UnrealizeObject function should not be used with stock objects. The UnrealizeObject function must be called whenever a new brush origin is set (by means of the CDC::SetBrushOrg function). The UnrealizeObject function must not be called for the currently selected brush or currently selected palette of any display context.

CGdiObject Class

Syntax

Members

Public Constructors

Public Methods

Public Operators

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CGdiObject::Attach

Parameters

Return Value

CGdiObject::CGdiObject

Remarks

CGdiObject::CreateStockObject

Parameters

Return Value

Remarks

CGdiObject::DeleteObject

Return Value

Remarks

CGdiObject::DeleteTempMap

Remarks

Example

CGdiObject::Detach

Return Value

CGdiObject::FromHandle

Parameters

Return Value

Remarks

CGdiObject::GetObject

Parameters

Return Value

Remarks

CGdiObject::GetObjectType

Return Value

CGdiObject::GetSafeHandle

Return Value

Remarks

Example

CGdiObject::m_hObject

CGdiObject::operator !=

Parameters

Remarks

CGdiObject::operator ==

Parameters

Remarks

CGdiObject::operator HGDIOBJ

CGdiObject::UnrealizeObject

Return Value

Remarks

See Also

Additional resources