DrawStateA function (winuser.h)

  • Article

The DrawState function displays an image and applies a visual effect to indicate a state, such as a disabled or default state.

Syntax

BOOL DrawStateA(
  [in] HDC           hdc,
  [in] HBRUSH        hbrFore,
  [in] DRAWSTATEPROC qfnCallBack,
  [in] LPARAM        lData,
  [in] WPARAM        wData,
  [in] int           x,
  [in] int           y,
  [in] int           cx,
  [in] int           cy,
  [in] UINT          uFlags
);

Parameters

[in] hdc

A handle to the device context to draw in.

[in] hbrFore

A handle to the brush used to draw the image, if the state specified by the fuFlags parameter is DSS_MONO. This parameter is ignored for other states.

[in] qfnCallBack

A pointer to an application-defined callback function used to render the image. This parameter is required if the image type in fuFlags is DST_COMPLEX. It is optional and can be NULL if the image type is DST_TEXT. For all other image types, this parameter is ignored. For more information about the callback function, see the DrawStateProc function.

[in] lData

Information about the image. The meaning of this parameter depends on the image type.

[in] wData

Information about the image. The meaning of this parameter depends on the image type. It is, however, zero extended for use with the DrawStateProc function.

[in] x

The horizontal location, in device units, at which to draw the image.

[in] y

The vertical location, in device units, at which to draw the image.

[in] cx

The width of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the width of the image.

[in] cy

The height of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the height of the image.

[in] uFlags

The image type and state. This parameter can be one of the following type values.

Value (type) Meaning
DST_BITMAP
 The image is a bitmap. The lData parameter is the bitmap handle. Note that the bitmap cannot already be selected into an existing device context.
DST_COMPLEX
 The image is application defined. To render the image, DrawState calls the callback function specified by the lpOutputFunc parameter.
DST_ICON
 The image is an icon. The lData parameter is the icon handle.
DST_PREFIXTEXT
 The image is text that may contain an accelerator mnemonic. DrawState interprets the ampersand (&) prefix character as a directive to underscore the character that follows. The lData parameter is a pointer to the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
DST_TEXT
 The image is text. The lData parameter is a pointer to the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
 

This parameter can also be one of the following state values.

Value (state) Meaning
DSS_DISABLED
 Embosses the image.
DSS_HIDEPREFIX
 Ignores the ampersand (&) prefix character in the text, thus the letter that follows will not be underlined. This must be used with DST_PREFIXTEXT.
DSS_MONO
 Draws the image using the brush specified by the hbr parameter.
DSS_NORMAL
 Draws the image without any modification.
DSS_PREFIXONLY
 Draws only the underline at the position of the letter after the ampersand (&) prefix character. No text in the string is drawn. This must be used with DST_PREFIXTEXT.
DSS_RIGHT
 Aligns the text to the right.
DSS_UNION
 Dithers the image.
 

For all states except DSS_NORMAL, the image is converted to monochrome before the visual effect is applied.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Note

The winuser.h header defines DrawState as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll

See also

DrawStateProc

Painting and Drawing Functions

Painting and Drawing Overview