1.6.2 Display Context Types

There are four types of display contexts: common, class, private, and window. The common, class, and private display contexts permit drawing in the client area of a given window. The window display context permits drawing anywhere in the window. When a window is created, Windows assigns a common, class, or private display context to it, based on the type of display context specified in that window's class style.

Common Display Context

A common display context is the default context for all windows. Windows assigns a common display context to the window if a display-context type is not explicitly specified in the window's class style.

A common display context permits drawing in a window's client area, but it is not immediately available for use by a window. A common display context must be retrieved from a cache of display contexts before a window can carry out any drawing in its client area. The GetDC or BeginPaint function retrieves the display context and returns a handle to the context. The handle can be used with GDI functions to draw in the client area of the given window. After drawing is complete, the context must be returned to the cache by using the ReleaseDC or EndPaint function. After the context is released, drawing cannot occur until another display context is retrieved.

When a common display context is retrieved, Windows gives it default selections for pen, brush, font, clipping area, and other attributes. These attributes define the tools currently available to carry out the actual drawing. Table 1.4 lists the default selections for a common display context:

Table 1.4 Defaults for a Display Context

Attribute Default
Background color White
Background mode OPAQUE
Bitmap No default

Table 1.4 Defaults for a Display Context (continued)

Attribute Default
Brush WHITE_BRUSH
Brush origin (0,0)
Clipping region Entire client area with the update region clipped as appropriate. Child and pop-up windows in the client area may also be clipped.
Color palette DEFAULT_PALETTE
Current pen position (0,0)
Device origin Upper-left corner of client area.
Drawing mode R2_COPYPEN
Font SYSTEM_FONT (SYSTEM_FIXED_FONT for applications written to run with Windows versions prior to 3.0)
Intercharacter spacing 0
Mapping mode MM_TEXT
Pen BLACK_PEN
Polygon-filling mode ALTERNATE
Relative-absolute flag ABSOLUTE
Stretching mode BLACKONWHITE
Text color Black
Viewport extent (1,1)
Viewport origin (0,0)
Window extents (1,1)
Window origin (0,0)

An application can modify the attributes of the display context by using the selection functions and display-context attribute functions. For example, applications typically change the selected pen, brush, and font.

When a common display context is released, the current selections, such as mapping mode and clipping area, are lost. Windows does not preserve the previous selections of a common display context since these contexts are shared and Windows has no way to guarantee that the next window to use a given common display context will be the last window to use that context. Applications that modify the attributes of a common display context must do so each time another context is retrieved.

Class Display Context

A window has a class display context if the window class specifies the CS_CLASSDC style. A class display context is shared by all windows in a given class. A class display context is not part of the display context cache. Instead, Windows specifically allocates a class context for sole use by the window class.

A class display context must be retrieved before it can be used, but it does not have to be released after use. As long as only one window from the class uses the context, the class display context can be kept and reused. If another window in the class needs to use the context, that window must retrieve it before any drawing occurs. Retrieving the context sets the correct origin and clipping for the new window and ensures that the context will be applied to the correct window. A handle to the class display context can be retrieved by using the GetDC or BeginPaint function. The ReleaseDC and EndPaint functions have no effect on the class display context.

A class display context is given the same default selections as a common display context when the first window of the class is created (see Table 1.4, “Defaults for a Display Context”). These selections can be modified at any time. Windows preserves all new selections made for the class display context, except for the clipping region and device origin, which are adjusted for the current window when the context is retrieved. Otherwise, all other attributes remain unchanged. This means a change made by one window applies to all windows that subsequently use the context.

NOTE:

Changing the mapping mode of a class display context may have an undesirable effect on how a window's background is erased. For more information, see Section 1.6.7, “Window Background,” and Section 2.5, “Mapping Functions.”

Private Display Context

A window has a private display context if the window class specifies the CS_OWNDC style. A private display context is used exclusively by a given window. A private display context is not part of the display context cache. Instead, Windows specifically allocates the context for sole use by the window.

A private display context needs to be retrieved only once. Thereafter, it can be kept and used any number of times by the window. Windows automatically updates the context to reflect changes to the window, such as moving or sizing. A handle to a private display context can be retrieved by using the GetDC or BeginPaint function. The ReleaseDC and EndPaint functions have no effect on the private display context.

A private display context is given the same default selections as a common display context when the window is created (see Table 1.4, “Defaults for a Display Context”). These selections can be modified at any time. Windows preserves any new selections made for the context. New selections, such as clipping region and brush, remain selected until the window specifically makes a change.

NOTE:

Changing the mapping mode of a private display context may have an undesirable effect on how the window's background is erased. For more information, see Section 1.6.7, “Window Background,” and Section 2.5, “Mapping Functions.”

Window Display Context

A window display context permits painting anywhere in a window, including the caption bar, menus, and scroll bars. Its origin is the upper-left corner of the window, instead of the upper-left corner of the client area.

The GetWindowDC function retrieves a window display context from the same cache as it does common display contexts. Therefore, a window that uses a window display context must release it with the ReleaseDC function immediately after drawing.

Windows always sets the current selections of a window display context to the same default selections as a common display context and does not preserve any change the window may have made to these selections (see Table 1.4, “Defaults for a Display Context”). Windows does not allow private or class window display contexts, so CS_OWNDC and CS_CLASSDC class styles have no effect on the window display context.

A window display context is intended to be used for special painting within a window's nonclient area. Since painting in nonclient areas of overlapped windows is not recommended, most applications reserve a display context for designing custom child windows. For example, an application may use the display context to draw a custom border around the window. In such cases, the window usually processes the WM_NCPAINT message instead of passing it on to the DefWindowProc function. For applications that do not process WM_NCPAINT messages but still wish to paint in the nonclient area, the GetSystemMetrics function can be used to retrieve the dimensions of various parts of the nonclient area, such as the caption bar, menu bar, and scroll bars.