General Control Reference

This section contains reference information about programming elements that apply to multiple controls, not just to a specific control. There are functions, macros, messages, notifications, and structures that most controls support. For example, most controls use the NM_HOVER notifications to process mouse clicks.

Overviews

Topic Contents
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 Windows operating system.
Common Controls FAQ This FAQ provides answers to some common questions about the common controls.

Functions

Topic Contents
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

Topic Contents
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

Topic Contents
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

Topic Contents
NM_CHAR The NM_CHAR notification code is sent by a control when a character key is processed. This notification code is sent in the form of a WM_NOTIFY message.
NM_CUSTOMDRAW Notifies a control's parent window about custom drawing operations. This notification code is sent in the form of a WM_NOTIFY message.
NM_CUSTOMTEXT Notifies a control's parent window about custom text operations. This notification code 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 code 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 that make up the split button. This notification code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code 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 code is sent in the form of a WM_NOTIFY message.

Structures

Topic Contents
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 codes.
NMTOOLTIPSCREATED Contains information used with NM_TOOLTIPSCREATED notification code.
READERMODEINFO Contains information required to initialize the DoReaderMode function.

Constants

Topic Contents
CDRF Constants These constants are used as return values by a control in response to an NM_CUSTOMDRAW notification code.
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.