Update common control function documentation.

dlls/comctl32/commctrl.c

@@ -131,7 +131,9 @@ static const WORD wPattern55AA[] =
 
 
 /***********************************************************************
- * DllMain [Internal] Initializes the internal 'COMCTL32.DLL'.
+ * DllMain [Internal]
+ *
+ * Initializes the internal 'COMCTL32.DLL'.
  *
  * PARAMS
  *     hinstDLL    [I] handle to the 'dlls' instance
@@ -223,6 +225,9 @@ BOOL WINAPI DllMain(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved)
 /***********************************************************************
  * MenuHelp [COMCTL32.2]
  *
+ * Handles the setting of status bar help messages when the user
+ * selects menu items.
+ *
  * PARAMS
  *     uMsg       [I] message (WM_MENUSELECT) (see NOTES)
  *     wParam     [I] wParam of the message uMsg
@@ -378,6 +383,8 @@ ShowHideMenuCtl (HWND hwnd, UINT uFlags, LPINT lpInfo)
 /***********************************************************************
  * GetEffectiveClientRect [COMCTL32.4]
  *
+ * Calculates the coordinates of a rectangle in the client area.
+ *
  * PARAMS
  *     hwnd   [I] handle to the client window.
  *     lpRect [O] pointer to the rectangle of the client window
@@ -536,7 +543,9 @@ CreateStatusWindowA (LONG style, LPCSTR text, HWND parent, UINT wid)
 
 
 /***********************************************************************
- * CreateStatusWindowW [COMCTL32.@] Creates a status bar control
+ * CreateStatusWindowW [COMCTL32.@]
+ *
+ * Creates a status bar control
  *
  * PARAMS
  *     style  [I] window style
@@ -560,7 +569,9 @@ CreateStatusWindowW (LONG style, LPCWSTR text, HWND parent, UINT wid)
 
 
 /***********************************************************************
- * CreateUpDownControl [COMCTL32.16] Creates an up-down control
+ * CreateUpDownControl [COMCTL32.16]
+ *
+ * Creates an up-down control
  *
  * PARAMS
  *     style  [I] window styles
@@ -711,7 +722,9 @@ InitCommonControlsEx (LPINITCOMMONCONTROLSEX lpInitCtrls)
 
 
 /***********************************************************************
- * CreateToolbarEx [COMCTL32.@] Creates a tool bar window
+ * CreateToolbarEx [COMCTL32.@]
+ *
+ * Creates a toolbar window.
  *
  * PARAMS
  *     hwnd
@@ -794,12 +807,14 @@ CreateToolbarEx (HWND hwnd, DWORD style, UINT wID, INT nBitmaps,
 /***********************************************************************
  * CreateMappedBitmap [COMCTL32.8]
  *
+ * Loads a bitmap resource using a colour map.
+ *
  * PARAMS
- *     hInstance  [I]
+ *     hInstance  [I] Handle to the module containing the bitmap.
- *     idBitmap   [I]
+ *     idBitmap   [I] The bitmap resource ID.
- *     wFlags     [I]
+ *     wFlags     [I] CMB_MASKED for using bitmap as a mask or 0 for normal.
- *     lpColorMap [I]
+ *     lpColorMap [I] Colour information needed for the bitmap or NULL (uses system colours).
- *     iNumMaps   [I]
+ *     iNumMaps   [I] Number of COLORMAP's pointed to by lpColorMap.
  *
  * RETURNS
  *     Success: handle to the new bitmap
@@ -900,7 +915,9 @@ CreateMappedBitmap (HINSTANCE hInstance, INT idBitmap, UINT wFlags,
 
 
 /***********************************************************************
- * CreateToolbar [COMCTL32.7] Creates a tool bar control
+ * CreateToolbar [COMCTL32.7]
+ *
+ * Creates a toolbar control.
  *
  * PARAMS
  *     hwnd
@@ -969,6 +986,12 @@ COMCTL32_DllGetVersion (DLLVERSIONINFO *pdvi)
 
 /***********************************************************************
  *		DllInstall (COMCTL32.@)
+ *
+ * Installs the ComCtl32 DLL.
+ *
+ * RETURNS
+ *     Success: S_OK
+ *     Failure: A HRESULT error
  */
 HRESULT WINAPI COMCTL32_DllInstall(BOOL bInstall, LPCWSTR cmdline)
 {
@@ -1011,9 +1034,10 @@ _TrackMouseEvent (TRACKMOUSEEVENT *ptme)
 /*************************************************************************
  * GetMUILanguage [COMCTL32.@]
  *
- * FIXME: "Returns the language currently in use by the common controls
+ * Returns the user interface language in use by the current process.
- * for a particular process." (MSDN)
  *
+ * RETURNS
+ *      Language ID in use by the current process.
  */
 LANGID WINAPI GetMUILanguage (VOID)
 {
@@ -1024,11 +1048,11 @@ LANGID WINAPI GetMUILanguage (VOID)
 /*************************************************************************
  * InitMUILanguage [COMCTL32.@]
  *
- * FIXME: "Enables an application to specify a language to be used with
+ * Sets the user interface language to be used by the current process.
- * the common controls that is different than the system language." (MSDN)
  *
+ * RETURNS
+ *      Nothing.
  */
-
 VOID WINAPI InitMUILanguage (LANGID uiLang)
 {
    COMCTL32_uiLang = uiLang;

dlls/comctl32/draglist.c

@@ -19,7 +19,6 @@
  *
  * NOTES
  *   This is just a dummy control. An author is needed! Any volunteers?
- *   I will only improve this control once in a while.
  *     Eric <ekohl@abo.rhein-zeitung.de>
  *
  * TODO:
@@ -43,6 +42,12 @@ static DWORD dwLastScrollTime = 0;
 
 /***********************************************************************
  *		MakeDragList (COMCTL32.13)
+ *
+ * Makes a normal ListBox into a DragList by subclassing it.
+ *
+ * RETURNS
+ *      Success: Non-zero
+ *      Failure: Zero
  */
 BOOL WINAPI MakeDragList (HWND hwndLB)
 {
@@ -54,6 +59,11 @@ BOOL WINAPI MakeDragList (HWND hwndLB)
 
 /***********************************************************************
  *		DrawInsert (COMCTL32.15)
+ *
+ * Draws insert arrow by the side of the ListBox item in the parent window.
+ *
+ * RETURNS
+ *      Nothing.
  */
 VOID WINAPI DrawInsert (HWND hwndParent, HWND hwndLB, INT nItem)
 {
@@ -64,6 +74,12 @@ VOID WINAPI DrawInsert (HWND hwndParent, HWND hwndLB, INT nItem)
 
 /***********************************************************************
  *		LBItemFromPt (COMCTL32.14)
+ *
+ * Gets the index of the ListBox item under the specified point,
+ * scrolling if bAutoScroll is TRUE and pt is outside of the ListBox.
+ *
+ * RETURNS
+ *      The ListBox item ID if pt is over a list item or -1 otherwise.
  */
 INT WINAPI LBItemFromPt (HWND hwndLB, POINT pt, BOOL bAutoScroll)
 {
@@ -128,6 +144,3 @@ DRAGLIST_WindowProc (HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
     return FALSE;
 }
 #endif
-
-
-

dlls/comctl32/flatsb.c

@@ -53,8 +53,15 @@ typedef struct
 /***********************************************************************
  *		InitializeFlatSB (COMCTL32.@)
  *
- *	returns nonzero if successful, zero otherwise
+ * Initializes flat scroll bars for the specified window.
  *
+ * RETURNS
+ *     Success: Non-zero
+ *     Failure: Zero
+ *
+ * NOTES
+ *     Subclasses specified window so that flat scroll bars may be drawn
+ *     and used.
  */
 BOOL WINAPI InitializeFlatSB(HWND hwnd)
 {
@@ -65,11 +72,16 @@ BOOL WINAPI InitializeFlatSB(HWND hwnd)
 /***********************************************************************
  *		UninitializeFlatSB (COMCTL32.@)
  *
- *	returns:
+ * Uninitializes flat scroll bars for the specified window.
+ *
+ * RETURNS
  *	E_FAIL		if one of the scroll bars is currently in use
- *	S_FALSE		if InitializeFlatSB was never called on this hwnd
+ *	S_FALSE		if InitializeFlatSB() was never called on this hwnd
  *	S_OK		otherwise
  *
+ * NOTES
+ *     Removes any subclassing on the specified window so that regular
+ *     scroll bars are drawn and used.
  */
 HRESULT WINAPI UninitializeFlatSB(HWND hwnd)
 {
@@ -80,10 +92,12 @@ HRESULT WINAPI UninitializeFlatSB(HWND hwnd)
 /***********************************************************************
  *		FlatSB_GetScrollProp (COMCTL32.@)
  *
- *	Returns nonzero if successful, or zero otherwise. If index is WSB_PROP_HSTYLE,
+ * Retrieves flat-scroll-bar-specific properties for the specified window.
- *	the return is nonzero if InitializeFlatSB has been called for this window, or
- *	zero otherwise.
  *
+ * RETURNS
+ *     nonzero if successful, or zero otherwise. If index is WSB_PROP_HSTYLE,
+ *     the return is nonzero if InitializeFlatSB has been called for this window, or
+ *     zero otherwise.
  */
 BOOL WINAPI
 FlatSB_GetScrollProp(HWND hwnd, INT propIndex, LPINT prop)
@@ -94,6 +108,12 @@ FlatSB_GetScrollProp(HWND hwnd, INT propIndex, LPINT prop)
 
 /***********************************************************************
  *		FlatSB_SetScrollProp (COMCTL32.@)
+ *
+ * Sets flat-scroll-bar-specific properties for the specified window.
+ *
+ * RETURNS
+ *     Success: Non-zero
+ *     Failure: Zero
  */
 BOOL WINAPI
 FlatSB_SetScrollProp(HWND hwnd, UINT index, INT newValue, BOOL flag)
@@ -120,6 +140,8 @@ FlatSB_SetScrollProp(HWND hwnd, UINT index, INT newValue, BOOL flag)
 
 /***********************************************************************
  *		FlatSB_EnableScrollBar (COMCTL32.@)
+ *
+ * See EnableScrollBar.
  */
 BOOL WINAPI
 FlatSB_EnableScrollBar(HWND hwnd, int nBar, UINT flags)
@@ -129,6 +151,8 @@ FlatSB_EnableScrollBar(HWND hwnd, int nBar, UINT flags)
 
 /***********************************************************************
  *		FlatSB_ShowScrollBar (COMCTL32.@)
+ *
+ * See ShowScrollBar.
  */
 BOOL WINAPI
 FlatSB_ShowScrollBar(HWND hwnd, int nBar, BOOL fShow)
@@ -138,6 +162,8 @@ FlatSB_ShowScrollBar(HWND hwnd, int nBar, BOOL fShow)
 
 /***********************************************************************
  *		FlatSB_GetScrollRange (COMCTL32.@)
+ *
+ * See GetScrollRange.
  */
 BOOL WINAPI
 FlatSB_GetScrollRange(HWND hwnd, int nBar, LPINT min, LPINT max)
@@ -147,6 +173,8 @@ FlatSB_GetScrollRange(HWND hwnd, int nBar, LPINT min, LPINT max)
 
 /***********************************************************************
  *		FlatSB_GetScrollInfo (COMCTL32.@)
+ *
+ * See GetScrollInfo.
  */
 BOOL WINAPI
 FlatSB_GetScrollInfo(HWND hwnd, int nBar, LPSCROLLINFO info)
@@ -156,6 +184,8 @@ FlatSB_GetScrollInfo(HWND hwnd, int nBar, LPSCROLLINFO info)
 
 /***********************************************************************
  *		FlatSB_GetScrollPos (COMCTL32.@)
+ *
+ * See GetScrollPos.
  */
 INT WINAPI
 FlatSB_GetScrollPos(HWND hwnd, int nBar)
@@ -165,6 +195,8 @@ FlatSB_GetScrollPos(HWND hwnd, int nBar)
 
 /***********************************************************************
  *		FlatSB_SetScrollPos (COMCTL32.@)
+ *
+ * See SetScrollPos.
  */
 INT WINAPI
 FlatSB_SetScrollPos(HWND hwnd, int nBar, INT pos, BOOL bRedraw)
@@ -174,6 +206,8 @@ FlatSB_SetScrollPos(HWND hwnd, int nBar, INT pos, BOOL bRedraw)
 
 /***********************************************************************
  *		FlatSB_SetScrollInfo (COMCTL32.@)
+ *
+ * See SetScrollInfo.
  */
 INT WINAPI
 FlatSB_SetScrollInfo(HWND hwnd, int nBar, LPSCROLLINFO info, BOOL bRedraw)
@@ -183,6 +217,8 @@ FlatSB_SetScrollInfo(HWND hwnd, int nBar, LPSCROLLINFO info, BOOL bRedraw)
 
 /***********************************************************************
  *		FlatSB_SetScrollRange (COMCTL32.@)
+ *
+ * See SetScrollRange.
  */
 INT WINAPI
 FlatSB_SetScrollRange(HWND hwnd, int nBar, INT min, INT max, BOOL bRedraw)

dlls/comctl32/imagelist.c

@@ -33,6 +33,7 @@
  *  TODO:
  *    - Add support for ILD_PRESERVEALPHA, ILD_SCALE, ILD_DPISCALE
  *    - Add support for ILS_GLOW, ILS_SHADOW, ILS_SATURATE, ILS_ALPHA
+ *    - Thread-safe locking
  *
  *  FIXME:
  *    - Hotspot handling still not correct. The Hotspot passed to BeginDrag
@@ -530,7 +531,9 @@ ImageList_Copy (HIMAGELIST himlDst, INT iDst,	HIMAGELIST himlSrc,
 
 
 /*************************************************************************
- * ImageList_Create [COMCTL32.@]  Creates a new image list.
+ * ImageList_Create [COMCTL32.@]
+ *
+ * Creates a new image list.
  *
  * PARAMS
  *     cx       [I] image height
@@ -543,7 +546,6 @@ ImageList_Copy (HIMAGELIST himlDst, INT iDst,	HIMAGELIST himlSrc,
  *     Success: Handle to the created image list
  *     Failure: NULL
  */
-
 HIMAGELIST WINAPI
 ImageList_Create (INT cx, INT cy, UINT flags,
 		  INT cInitial, INT cGrow)
@@ -960,7 +962,9 @@ ImageList_DragShowNolock (BOOL bShow)
 
 
 /*************************************************************************
- * ImageList_Draw [COMCTL32.@] Draws an image.
+ * ImageList_Draw [COMCTL32.@]
+ *
+ * Draws an image.
  *
  * PARAMS
  *     himl   [I] handle to image list
@@ -1041,7 +1045,7 @@ ImageList_DrawEx (HIMAGELIST himl, INT i, HDC hdc, INT x, INT y,
 /*************************************************************************
  * ImageList_DrawIndirect [COMCTL32.@]
  *
- * Draws an image using ...
+ * Draws an image using various parameters specified in pimldp.
  *
  * PARAMS
  *     pimldp [I] pointer to IMAGELISTDRAWPARAMS structure.
@@ -1207,7 +1211,9 @@ cleanup:
 
 
 /*************************************************************************
- * ImageList_Duplicate [COMCTL32.@] Duplicates an image list.
+ * ImageList_Duplicate [COMCTL32.@]
+ *
+ * Duplicates an image list.
  *
  * PARAMS
  *     himlSrc [I] source image list handle
@@ -1247,7 +1253,7 @@ ImageList_Duplicate (HIMAGELIST himlSrc)
 
 
 /*************************************************************************
- * ImageList_EndDrag [COMCTL32.@] Finishes a drag operation.
+ * ImageList_EndDrag [COMCTL32.@]
  *
  * Finishes a drag operation.
  *
@@ -1333,6 +1339,14 @@ ImageList_GetDragImage (POINT *ppt, POINT *pptHotspot)
 /*************************************************************************
  * ImageList_GetFlags [COMCTL32.@]
  *
+ * Gets the flags of the specified image list.
+ *
+ * PARAMS
+ *     himl [I] Handle to image list
+ *
+ * RETURNS
+ *     Image list flags.
+ *
  * BUGS
  *    Stub.
  */
@@ -2019,7 +2033,9 @@ HIMAGELIST WINAPI ImageList_Read (LPSTREAM pstm)
 
 
 /*************************************************************************
- * ImageList_Remove [COMCTL32.@] Removes an image from an image list
+ * ImageList_Remove [COMCTL32.@]
+ *
+ * Removes an image from an image list
  *
  * PARAMS
  *     himl [I] image list handle
@@ -2444,6 +2460,15 @@ ImageList_SetFilter (HIMAGELIST himl, INT i, DWORD dwFilter)
 /*************************************************************************
  * ImageList_SetFlags [COMCTL32.@]
  *
+ * Sets the image list flags.
+ *
+ * PARAMS
+ *     himl  [I] Handle to image list
+ *     flags [I] Flags to set
+ *
+ * RETURNS
+ *     Old flags?
+ *
  * BUGS
  *    Stub.
  */

dlls/comctl32/propsheet.c

@@ -2477,6 +2477,15 @@ static void PROPSHEET_CleanUp(HWND hwndDlg)
 /******************************************************************************
  *            PropertySheet    (COMCTL32.@)
  *            PropertySheetA   (COMCTL32.@)
+ *
+ * Creates a property sheet in the specified property sheet header.
+ *
+ * RETURNS
+ *     Modal property sheets: Positive if successful or -1 otherwise.
+ *     Modeless property sheets: Property sheet handle.
+ *     Or:
+ *| ID_PSREBOOTSYSTEM - The user must reboot the computer for the changes to take effect.
+ *| ID_PSRESTARTWINDOWS - The user must restart Windows for the changes to take effect.
  */
 INT WINAPI PropertySheetA(LPCPROPSHEETHEADERA lppsh)
 {
@@ -2522,6 +2531,8 @@ INT WINAPI PropertySheetA(LPCPROPSHEETHEADERA lppsh)
 
 /******************************************************************************
  *            PropertySheetW   (COMCTL32.@)
+ *
+ * See PropertySheetA.
  */
 INT WINAPI PropertySheetW(LPCPROPSHEETHEADERW lppsh)
 {
@@ -2568,6 +2579,16 @@ INT WINAPI PropertySheetW(LPCPROPSHEETHEADERW lppsh)
 /******************************************************************************
  *            CreatePropertySheetPage    (COMCTL32.@)
  *            CreatePropertySheetPageA   (COMCTL32.@)
+ *
+ * Creates a new property sheet page.
+ *
+ * RETURNS
+ *     Success: Handle to new property sheet page.
+ *     Failure: NULL.
+ *
+ * NOTES
+ *     An application must use the PSM_ADDPAGE message to add the new page to
+ *     an existing property sheet.
  */
 HPROPSHEETPAGE WINAPI CreatePropertySheetPageA(
                           LPCPROPSHEETPAGEA lpPropSheetPage)
@@ -2601,6 +2622,8 @@ HPROPSHEETPAGE WINAPI CreatePropertySheetPageA(
 
 /******************************************************************************
  *            CreatePropertySheetPageW   (COMCTL32.@)
+ *
+ * See CreatePropertySheetA.
  */
 HPROPSHEETPAGE WINAPI CreatePropertySheetPageW(LPCPROPSHEETPAGEW lpPropSheetPage)
 {
@@ -2638,6 +2661,14 @@ HPROPSHEETPAGE WINAPI CreatePropertySheetPageW(LPCPROPSHEETPAGEW lpPropSheetPage
 
 /******************************************************************************
  *            DestroyPropertySheetPage   (COMCTL32.@)
+ *
+ * Destroys a property sheet page previously created with
+ * CreatePropertySheetA() or CreatePropertySheetW() and frees the associated
+ * memory.
+ *
+ * RETURNS
+ *     Success: TRUE
+ *     Failure: FALSE
  */
 BOOL WINAPI DestroyPropertySheetPage(HPROPSHEETPAGE hPropPage)
 {

dlls/comctl32/smoothscroll.c

@@ -63,10 +63,14 @@ typedef struct tagSMOOTHSCROLLSTRUCT {
  *
  * Lots of magic for smooth scrolling windows.
  *
- * Currently only scrolls ONCE. The comctl32 implementation uses GetTickCount
+ * RETURNS
- * and what else to do smooth scrolling.
+ *     Success: TRUE
+ *     Failure: FALSE
+ *
+ * BUGS
+ *     Currently only scrolls ONCE. The comctl32 implementation uses GetTickCount
+ *     and what else to do smooth scrolling.
  */
-
 BOOL WINAPI SmoothScrollWindow( SMOOTHSCROLLSTRUCT *smooth ) {
    LPRECT	lpupdaterect = smooth->lpupdaterect;
    HRGN		hrgnupdate = smooth->hrgnupdate;