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. |