This section contains information about programming elements used with all controls including the updated common controls delivered in Windows XP.

Overviews

About Common Controls

The common controls are a set of windows that are implemented by the common control library, which is a DLL included with the Microsoft Windows operating system.

Common Controls FAQ

This FAQ provides answers to some common questions about the common controls.

Functions

DoReaderMode

Enables reader mode in a window.

DPA_Clone

Duplicates a dynamic pointer array (DPA).

DPA_Create

Creates a DPA.

DPA_CreateEx

Creates a DPA using a given specified size and heap location.

DPA_DeleteAllPtrs

Removes all items from a DPA and shrinks the DPA accordingly.

DPA_DeletePtr

Removes an item from a DPA. The DPA shrinks if necessary to accommodate the removed item.

DPA_Destroy

Frees a Dynamic Pointer Array (DPA).

DPA_DestroyCallback

Calls pfnCB on each element of the DPA, then frees the DPA.

DPA_EnumCallback

Iterates through the Dynamic Pointer Array (DPA) and calls pfnCB on each item.

DPA_GetPtr

Gets an item from a DPA.

DPA_GetPtrIndex

Gets the index of a matching item found in a DPA.

DPA_GetSize

Gets the size of a DPA.

DPA_Grow

Changes the number of pointers in a DPA.

DPA_InsertPtr

Inserts a new item at a specified position in a DPA. If neccessary, the DPA expands to accommodate the new item.

DPA_LoadStream

Loads the DPA from a stream by calling the specified callback function to read each element.

DPA_Merge

Combines the contents of two DPAs.

DPA_SaveStream

Saves the DPA to a stream by writing out a header, and then calling the specified callback function to write each element.

DPA_Search

Finds an item in a DPA.

DPA_SetPtr

Assigns a value to an item in a DPA.

DPA_Sort

Sorts the items in a Dynamic Pointer Array (DPA).

DrawShadowText

Draws text that has a shadow.

DrawTextExPrivWrap

Draws formatted text in the specified rectangle. This function wraps a call to DrawTextEx.

DrawTextWrap

Draws formatted text in the specified rectangle. It formats the text according to the specified method (expanding tabs, justifying characters, breaking lines, and so on). This function wraps a call to DrawText.

DSA_Clone

Duplicates a dynamic structure array (DSA).

DSA_Create

Creates a DSA.

DSA_DeleteAllItems

Deletes all items from a DSA.

DSA_DeleteItem

Deletes an item from a DSA.

DSA_Destroy

Frees a DSA.

DSA_DestroyCallback

Iterates through a DSA, calling a specified callback function on each item. Upon reaching the end of the array, the DSA is freed.

DSA_EnumCallback

Iterates through the DSA and calls pfnCB on each item.

DSA_GetItem

Gets an element from a DSA.

DSA_GetItemPtr

Gets a pointer to an element from a DSA.

DSA_GetSize

Gets the size of the DSA.

DSA_InsertItem

Inserts a new item into a DSA. If necessary, the DSA expands to accommodate the new item.

DSA_SetItem

Sets the contents of an element in a DSA.

DSA_Sort

Sorts the items in a DSA.

ExtTextOutWrap

Draws text using the currently selected font, background color, and text color. You can optionally provide dimensions to be used for clipping, opacity, or both. This function wraps a call to ExtTextOut.

GetEffectiveClientRect

Calculates the dimensions of a rectangle in the client area that contains all the specified controls.

GetMUILanguage

Gets the language currently in use by the common controls for a particular process.

GetTextExtentPoint32Wrap

Computes the width and height of the specified string of text. This function wraps a call to GetTextExtentPoint .

InitCommonControls

Registers and initializes certain common control window classes. This function is obsolete. New applications should use the InitCommonControlsEx function.

InitCommonControlsEx

Registers specific common control classes from the common control DLL.

InitMUILanguage

Enables an application to specify a language to be used with the common controls that is different from the system language.

LoadIconMetric

Loads a specified icon resource with a client-specified system metric.

LoadIconWithScaleDown

Loads an icon. If the icon is not a standard size, this function scales down a larger image instead of scaling up a smaller image.

MirrorIcon

Reverses (mirrors) icons so that they are displayed correctly on a mirrored device context.

PFNDACOMPARE

Defines the prototype for the compare function used by DSA_Sort.

PFNDACOMPARECONST

Defines the prototype for the compare function used by DSA_Sort when the items being compared are constant objects.

PFNDAENUMCALLBACK

Defines the prototype for the callback function used by DSA and DPA functions.

PFNDAENUMCALLBACKCONST

Defines the prototype for the callback function used by DSA and DPA functions when the items involved are pointers to constant data.

PFNDPACOMPARE

Defines the prototype for the compare function used by DPA_Sort and DPA_Search.

PFNDPACOMPARECONST

Defines the prototype for the compare function used by DPA_Sort or DPA_Search when the items being compared are constant objects.

PFNDPAENUMCALLBACK

Defines the prototype for the callback function used by DPA_EnumCallback.

PFNDPAMERGE

Defines the prototype for the merge function used by DPA_Merge.

PFNDPAMERGECONST

Defines the prototype for the merge function used by DPA_Merge, using constant values.

PFNDPASTREAM

Defines the prototype for the callback function used by DPA_LoadStream and DPA_SaveStream.

PFNDSAENUMCALLBACK

Defines the prototype for the callback function used by DSA_DestroyCallback.

ReaderScroll

An application-defined callback function used when the mouse pointer is moved within the portion of the reader mode window that has been declared as the active scrolling area.

ShowHideMenuCtl

Sets or removes the specified menu item's check mark attribute and shows or hides the corresponding control. The function adds a check mark to the specified menu item if it does not have one and then displays the corresponding control. If the menu item already has a check mark, the function removes the check mark and hides the corresponding control.

Str_GetPtr

Copies a string from one buffer to another.

Str_SetPtrW

Sets ppszCurrent to a copy of pszNew and frees the previous value, if necessary.

TranslateDispatch

Used by the client of the DoReaderMode function to intercept and explicitly handle any windows messages targeted for the scrolling area of the reader mode window. This is an application-defined callback function.

Macros

DPA_AppendPtr

Inserts a new item at the end of a DPA.

DPA_FastDeleteLastPtr

Deletes the last pointer from a DPA.

DPA_FastGetPtr

Gets the value of the specified pointer in the DPA.

DPA_GetPtrCount

Gets the number of pointers in a DPA.

DPA_GetPtrPtr

Gets the pointer to the internal pointer array of a DPA.

DPA_SetPtrCount

Sets the number of pointers in a DPA.

DPA_SortedInsertPtr

Inserts a new item before or after a specified existing item.

DSA_AppendItem

Appends a new item to the end of a DSA.

DSA_GetItemCount

Gets the number of items in a DSA.

FORWARD_WM_NOTIFY

Sends or posts the WM_NOTIFY message.

HANDLE_WM_NOTIFY

Calls a function that processes the WM_NOTIFY message.

INDEXTOSTATEIMAGEMASK

Prepares the index of a state image so that a tree-view control or list-view control can use the index to retrieve the state image for an item.

Messages

CCM_DPISCALE

Enables automatic high dots per inch (dpi) scaling in Tree-View controls, List-View controls, ComboBoxEx controls, Header controls, Buttons, Toolbar controls, Animation controls, and Image Lists.

CCM_GETUNICODEFORMAT

Gets the Unicode character format flag for the control.

CCM_GETVERSION

Gets the version number for a control set by the most recent CCM_SETVERSION message.

CCM_SETUNICODEFORMAT

Sets the Unicode character format flag for the control. This message enables you to change the character set used by the control at run time rather than having to re-create the control.

CCM_SETVERSION

This message is used to inform the control that you are expecting a behavior associated with a particular version.

CCM_SETWINDOWTHEME

Sets the visual style of a control.

WM_NOTIFY

Sent by a common control to its parent window when an event has occurred or the control requires some information.

WM_NOTIFYFORMAT

Determines if a window accepts ANSI or Unicode structures in the WM_NOTIFY notification message. WM_NOTIFYFORMAT messages are sent from a common control to its parent window and from the parent window to the common control.

Notifications

NM_CHAR

The NM_CHAR notification message is sent by a control when a character key is processed. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW

Notifies a control's parent window about custom drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMTEXT

Notifies a control's parent window about custom text operations. This notification is sent in the form of a WM_NOTIFY message.

NM_FONTCHANGED

Sent by a list-view control when the control has changed a font. This notification is sent in the form of a WM_NOTIFY message.

NM_GETCUSTOMSPLITRECT

Sent by a button control to its parent to get measurements for the two rectangles comprising the split button. This notification is sent in the form of a WM_NOTIFY message.

NM_HOVER

Sent by a control when the mouse hovers over an item. This notification is sent in the form of a WM_NOTIFY message.

NM_KEYDOWN

Sent by a control when the control has the keyboard focus and the user presses a key. This notification is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS

Notifies a control's parent window that the control has lost the input focus. This notification is sent in the form of a WM_NOTIFY message.

NM_LDOWN

Notifies a control's parent window that the left mouse button has been pressed. This notification is sent in the form of a WM_NOTIFY message.

NM_NCHITTEST

Sent by a rebar control when the control receives a WM_NCHITTEST message. This notification is sent in the form of a WM_NOTIFY message.

NM_OUTOFMEMORY

Notifies a control's parent window that the control could not complete an operation because there was not enough memory available. This notification is sent in the form of a WM_NOTIFY message.

NM_RDOWN

Not currently supported.

NM_RELEASEDCAPTURE

Notifies a control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RETURN

Notifies a control's parent window that the control has the input focus and that the user has pressed the ENTER key. This notification is sent in the form of a WM_NOTIFY message.

NM_SETCURSOR

Notifies a control's parent window that the control is setting the cursor in response to a NM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS

Notifies a control's parent window that the control has received the input focus. This notification is sent in the form of a WM_NOTIFY message.

NM_THEMECHANGED

Notifies a control's parent window that the theme has changed. This notification is sent in the form of a WM_NOTIFY message.

NM_TOOLTIPSCREATED

Notifies a control's parent window that the control has created a tooltip control. This notification is sent in the form of a WM_NOTIFY message.

NM_TVSTATEIMAGECHANGING

Sent by a tree-view control to its parent window that the state image is changing. This notification is sent in the form of a WM_NOTIFY message.

Structures

COLORSCHEME

Contains information for the drawing of buttons in a toolbar or rebar.

DPASTREAMINFO

Contains a stream item used by the PFNDPASTREAM callback function.

INITCOMMONCONTROLSEX

Carries information used to load common control classes from the dynamic-link library (DLL). This structure is used with the InitCommonControlsEx function.

NMCHAR

Contains information used with character notification messages.

NMCUSTOMSPLITRECTINFO

Contains information about the two rectangles of a split button. Sent with the NM_GETCUSTOMSPLITRECT notification.

NMCUSTOMTEXT

Contains information used with custom text notification.

NMHDR

Contains information about a notification message.

NMKEY

Contains information used with key notification messages.

NMMOUSE

Contains information used with mouse notification messages.

NMOBJECTNOTIFY

Contains information used with the TBN_GETOBJECT, TCN_GETOBJECT, and PSN_GETOBJECT notification messages.

NMTOOLTIPSCREATED

Contains information used with NM_TOOLTIPSCREATED notification messages.

READERMODEINFO

Contains information required to initialize the DoReaderMode function.

Constants

CDRF Constants

These constants are used as return values by a control in response to an NM_CUSTOMDRAW notification.

Styles

This section lists common control styles. Except where noted, these styles apply to header controls, toolbar controls, and status windows.

Window Classes

This section lists the window class names provided by the common control library.