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

Public Methods

Public Operators

Public Data Members

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:

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.

See also

Hierarchy Chart
CBitmap Class
CBrush Class
CFont Class
CPalette Class
CPen Class
CRgn Class